Web components Identifier: Pre-alpha

[amyleadem]

Summary

• Design a markup structure for the light and shadow DOM
• Design component variants, props, parts, slots, and vars

Research and planning tasks

• Gather code samples from the landscape
  • Note: Use the Landscape analysis code samples template to collect relevant code samples from across the landscape
• Identify and document the component’s critical content
  • Document the component content that is critical for end-user understanding. Note: This critical content should always appear on the page, even in non-JS environments.
• Design and document the structure for the light DOM
• Design and document the structure for the shadow DOM
• Design and document the expected component customization methods
  • List and define the proposed component variants
  • List and define props
  • List and define slots
  • List and define CSS Parts
  • List and define CSS Variables
  • List any component content that will need to be translated into other languages

[amyleadem]

Identifier component design plan

Landscape analysis

Identifier code samples from the landscape analysis (Google docs 🔒)

Proposed component structure

Critical content

Element	Required attributes	Content

Sample default implementation:

<usa-identifier 
  lang="en" 
  domainName="domain.gov"
  parentAgencyLogo="https://designsystem.digital.gov/assets/img/circle-gray-20.svg"
  parentAgencyUrl="javascipt:void(0)"
  parentAgencyName="[Parent agency]"
  parentAgencyShortname="[AAA]"
  aboutURL="javascipt:void(0)" 
  accessibilityURL="javascipt:void(0)" 
  foiaURL="javascipt:void(0)" 
  noFearURL="javascipt:void(0)"
  oigURL="javascipt:void(0)" 
  performanceURL="javascipt:void(0)" 
  privacyURL="javascipt:void(0)"
>
</usa-identifier>

Sample default implementation with pre-programmed language (in this example, Spanish):

<usa-identifier 
  lang="es" 
  domainName="domain.gov"
  parentAgencyLogo="https://designsystem.digital.gov/assets/img/circle-gray-20.svg"
  parentAgencyUrl="javascipt:void(0)"
  parentAgencyName="[Parent agency]"
  parentAgencyShortname="[AAA]"
  aboutURL="javascipt:void(0)" 
  accessibilityURL="javascipt:void(0)" 
  foiaURL="javascipt:void(0)" 
  noFearURL="javascipt:void(0)"
  oigURL="javascipt:void(0)" 
  performanceURL="javascipt:void(0)" 
  privacyURL="javascipt:void(0)"
>
</usa-identifier>

Sample complex implementation with custom language strings (French) and multiple logo0s:

<usa-identifier 
  taxpayerDisclaimer=true
  disclaimerIntroText="Un site officiel du"
  disclaimerConjunctionText="et"
  taxpayerText="Produit et publié aux frais des contribuables."
  ariaLabel="Identifiant de l'agence"
  domainName="domain.gov"
  parentAgencyLogo="https://designsystem.digital.gov/assets/img/circle-gray-20.svg"
  parentAgencyUrl="javascipt:void(0)"
  parentAgencyName="[Parent agency]"
  parentAgencyShortname="[AAA]"
  secondaryParentAgencyLogo="https://designsystem.digital.gov/assets/img/circle-gray-20.svg"
  secondaryParentAgencyUrl="javascipt:void(0)"
  secondaryParentAgencyName="[Parent agency]"
  aboutURL="javascipt:void(0)" 
  aboutText="À propos"
  accessibilityURL="javascipt:void(0)" 
  accessibilityText="Déclaration d'accessibilité"
  foiaURL="javascipt:void(0)" 
  foiaText="Solicitud a través de FOIA"
  noFearURL="javascipt:void(0)"
  noFearText="Datos de la ley No FEAR"
  oigURL="javascipt:void(0)" 
  oigText="Bureau de l'Inspecteur général"
  performanceURL="javascipt:void(0)" 
  performanceText="Rapports de performances"
  privacyURL="javascipt:void(0)"
  privacyText="Politique de confidentialité"
  usagovText="Vous recherchez des informations et des services du gouvernement américain?"
  usagovLinkText="Visitez usa.gov"
  usagovUrl="https://www.usa.gov/"
>
</usa-identifier>

Shadow DOM

Same as USWDS 3, with some small exceptions:

• Replace the wrapping .usa-identifier <div> with a <section> - this makes it a landmark region
• Use only one aria-label for the component - remove aria-labels from nested sections

<section class="usa-identifier" aria-label="Agency identifier">
  <section class="usa-identifier__section usa-identifier__section--masthead">
    <div class="usa-identifier__container">
      <div class="usa-identifier__logos" part="logo-wrapper">
        <a href="javascipt:void(0)" class="usa-identifier__logo" part="logo">
          <img src="https://designsystem.digital.gov/assets/img/circle-gray-20.svg" alt="[Parent agency] logo" class="usa-identifier__logo-img" part="logo-image">
        </a>
      </div>
      <section class="usa-identifier__identity">
        <p slot="domain" class="usa-identifier__identity-domain" part="domain">[domain.gov]</p>
        <p class="usa-identifier__identity-disclaimer" part="disclaimer">
          An official website of the <a agency-shortname="[Agency shortname]" href="javascipt:void(0)" part="disclaimer-link">[Parent agency]</a>
        </p>
      </section>
    </div>
  </section>
       
  <nav class="usa-identifier__section usa-identifier__section--required-links">
    <div class="usa-identifier__container">
      <ul class="usa-identifier__required-links-list">
        <li class="usa-identifier__required-links-item">
          <a class="usa-identifier__required-link usa-link" part="required-link" href="javascipt:void(0)">About [Agency shortname]</a>
        </li>
        <li class="usa-identifier__required-links-item">
          <a class="usa-identifier__required-link usa-link" part="required-link" href="javascipt:void(0)">Accessibility statement</a>
        </li>
        <li class="usa-identifier__required-links-item">
          <a class="usa-identifier__required-link usa-link" part="required-link" href="javascipt:void(0)">FOIA requests</a>
        </li>
        <li class="usa-identifier__required-links-item">
          <a class="usa-identifier__required-link usa-link" part="required-link" href="javascipt:void(0)">No FEAR Act data</a>
        </li>
        <li class="usa-identifier__required-links-item">
          <a class="usa-identifier__required-link usa-link" part="required-link" href="javascipt:void(0)">Office of the Inspector General</a>
        </li>
        <li class="usa-identifier__required-links-item">
          <a class="usa-identifier__required-link usa-link" part="required-link" href="javascipt:void(0)">Performance reports</a>
        </li>
        <li class="usa-identifier__required-links-item">
          <a class="usa-identifier__required-link usa-link" part="required-link" href="javascipt:void(0)">Privacy policy</a>
        </li>
      </ul>
    </div>
  </nav>
  <section class="usa-identifier__section usa-identifier__section--usagov">
    <div class="usa-identifier__container">
      <p class="usa-identifier__usagov-description" part="usagov">
        Looking for U.S. government information and services?
        <a class="usa-link" href="https://www.usa.gov/">Visit USA.gov</a>
      </p>
    </div>
  </section>
</section>

Variants

Current variants

USWDS 3 variant	Web components variant	Description	Defined via

Proposed additional variants

USWDS 3 variant	Web components variant	Description	Defined via

Props

Current variants

Property	Description	Expected values

Proposed additional variants

Property	Description	Expected values

Slots

Unnamed slot

CSS Parts

Part name	Element

CSS Variables

Current settings

USWDS 3 setting	CSS custom property	Description
$theme-identifier-background-color	--usa-theme-identifier-background-color	The background color of the identifier. Use a color of grade 80 or higher, darker than the section that precedes it.
$theme-identifier-font-family	--usa-theme-identifier-font-family	The font family of the identifier.
$theme-identifier-identity-domain-color	--	The color of your domain text in the identifier masthead. This should be grade 20-30 in the same family as the $theme-identifier-background-color.
$theme-identifier-max-width	--usa-theme-identifier-max-width	The maximum width of the content within the identifier. Use the same max-width as your site footer.
$theme-identifier-primary-link-color	--	The color of the links in the masthead section. Default uses either the standard or reverse link color set with $theme-link-color and $theme-link-reverse-color.
$theme-identifier-secondary-link-color	--usa-theme-identifier-link-list-color	The color of the links in the required links section. This should be grade 20-30 in a gray family.

Proposed additional setting

USWDS 3 setting	CSS custom property	Description
--	--usa-theme-identifier-text-color	Text color used in the disclaimer and USA.gov statement
--	--usa-theme-identifier-secondary-text-color	Link color used in the disclaimer and USA.gov statement

Translatable content