From 90b757bdee6b568540712658a3709591360c5db3 Mon Sep 17 00:00:00 2001 From: amyleadem Date: Tue, 14 Jan 2025 13:21:10 -0700 Subject: [PATCH 1/7] Add identifier pre-alpha --- web-components/identifier.md | 252 +++++++++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 web-components/identifier.md diff --git a/web-components/identifier.md b/web-components/identifier.md new file mode 100644 index 0000000..2b2cf9b --- /dev/null +++ b/web-components/identifier.md @@ -0,0 +1,252 @@ +# Identifier component design plan + +## Landscape analysis + +[Identifier code samples from the landscape analysis](https://docs.google.com/document/d/1umaVv9KFNHhO1L1MQ-25ttTERxC6dlD-qrZd5vfptYE/edit?tab=t.0#heading=h.fa3sv1ray42g) (Google docs :lock:) + +> [!Note] +> Identifier is a unique component, which means there are very few comparable components in the landscape. + +## Proposed component structure + +### Critical content + +N/A. Proposing that none of the content inside the identifier meets the criteria for critical content. + +### Light DOM + +Sample default implementation: + +```html + + +``` + +Sample default implementation with pre-programmed language (in this example, Spanish): + +```html + + +``` + +Sample complex implementation with custom language strings (French) and multiple logos: + +```html + + +``` + +### Shadow DOM + +_Same as USWDS 3, with some proposed tweaks:_ + +- Replace the wrapping `.usa-identifier` `
` with a `
` + - This makes it a landmark region which should improve accessibility +- Use only one aria-label for the component - remove aria-labels from nested sections + +```html +
+
+
+
+ +
+
+

[domain.gov]

+

+ An official website of the [Parent agency] +

+
+
+
+ + +
+
+

+ Looking for U.S. government information and services? + Visit USA.gov +

+
+
+
+``` + +### Variants + +#### Current variants +| USWDS 3 variant | Description | Defined via | +|--------|--------|--------| +| Default | | | +| Multiple parents and logos | Allows the user to name two parent agencies and two logos | `secondaryParentAgencyLogo`, `secondaryParentAgencyUrl`, `secondaryParentAgencyName` | +| No logos | Aligns content when there is no parent agency logo | Undefined/empty value for `parentAgencyLogo` | +| Taxpayer disclaimer | Adds "Produced and published at taxpayer expense" copy | `taxpayerDisclaimer: true` | +| Spanish (all variants) | Translates content for all variants into Spanish | `lang="es"` | + +#### Proposed additional variants +For ease of implementation, recommend we offer additional common translations in the component that can be defined with the `lang` attribute. + +### Props + +#### Current variants +| Property | Type | Description | Required? | +|--------|--------|--------|--------| +| `label` | string | Set a custom aria label for the identifier component. Default value: "Agency identifier" | No | +| `lang` | string | Set the language for the default component text. Expected values: "en", "es". Default value is "en". | No | +| `taxpayerDisclaimer` | boolean | Include the "Produced and published at taxpayer expense" text. A custom value can be set with `taxpayerText` attribute. | No | +| `taxpayerText` | string | Set a custom value for the taxpayer disclaimer text. Default value: "Produced and published at taxpayer expense" | No | +| `domainName` | string | Domain name for the website | Yes | +| `parentAgencyLogo` | string | The url for the parent agency logo image | No | +| `parentAgencyUrl` | string | The url for the parent agency's home page | Yes | +| `parentAgencyName` | string | The full name of the parent agency | Yes | +| `parentAgencyShortname` | string | The shortname or acronym of the parent agency. This will be added to the "About [Agency shortname]" link text. | No | +| `secondaryParentAgencyLogo` | string | The url for the secondary parent agency logo image | No | +| `secondaryParentAgencyUrl` | string | The url for the secondary parent agency's home page | No | +| `secondaryParentAgencyName` | string | The full name of the secondary parent agency | No | +| `aboutURL` | string | The url for the parent agency's "About" page | Yes | +| `aboutText` | string | Custom text for the "About us" link | No | +| `accessibilityURL` | string | The url for the parent agency's "Accesibility statement" page | Yes | +| `accessibilityText` | string | Custom text for the "Accessibility statement" link | No | +| `foiaURL` | string | The url for the parent agency's "FOIA requests" page | Yes | +| `foiaText` | string | Custom text for the "FOIA requests" link | No | +| `noFearURL` | string | The url for the parent agency's "No FEAR Act data" page | Yes | +| `noFearText` | string | Custom text for the "No FEAR Act data" link | No | +| `oigURL` | string | The url for the parent agency's "Office of the inspector general" page | Yes | +| `oigText` | string | Custom text for the "Office of the inspector general" link | No | +| `performanceURL` | string | The url for the parent agency's "Performance reports" page | Yes | +| `performanceText` | string | Custom text for the "Performance reports" link | No | +| `privacyURL` | string | The url for the parent agency's "Privacy policy" page | Yes | +| `privacyText` | string | Custom text for the "Privacy policy" link | No | +| `usagovText` | string | Custom text for the usa gov intro. Default value: "Looking for U.S. government information and services?" | No | +| `usagovLinkText` | string | Custom text for "Visit USA.gov" link. Default value for Spanish translations: "Visite USAGov en Español" | No | +| `usagovUrl | string | Custom url for usa.gov. Default values: "https://www.usa.gov/` for English translations, "https://www.usa.gov/es/" for Spanish Translations. | No | + +#### Proposed additional variants + +Same as current, but with more available values for the `lang` attribute + +### Slots + +N/A + +### CSS Parts + +| Part name | Element | +|--------|--------| +| `base` | Component wrapper | +| `disclaimer` | The `

` element that wraps the "An official website of the..." disclaimer text | +| `disclaimer-link` | The `` element inside the disclaimer text | +| `domain` | The `

` element that wraps your site's domain name | +| `logo-image` | The agency logo `` element | +| `logo-wrapper` | The `

` element that wraps all logos | +| `logo` | The `` elements that wrap each logo | +| `required-link` | The `` elements in the required links list | +| `usagov` | The `

` element that wraps the USA.gov text | +| `usagov-link` | The `` element inside the usagov text | + +### 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 | From 7d1ea72d48527c4c1e7abe8f6dac551303347928 Mon Sep 17 00:00:00 2001 From: Amy Leadem <93996430+amyleadem@users.noreply.github.com> Date: Tue, 14 Jan 2025 13:43:47 -0700 Subject: [PATCH 2/7] Update prop descriptions with spanish defaults --- web-components/identifier.md | 40 ++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/web-components/identifier.md b/web-components/identifier.md index 2b2cf9b..f55413c 100644 --- a/web-components/identifier.md +++ b/web-components/identifier.md @@ -1,17 +1,14 @@ -# Identifier component design plan +# Identifier web component design ## Landscape analysis [Identifier code samples from the landscape analysis](https://docs.google.com/document/d/1umaVv9KFNHhO1L1MQ-25ttTERxC6dlD-qrZd5vfptYE/edit?tab=t.0#heading=h.fa3sv1ray42g) (Google docs :lock:) -> [!Note] -> Identifier is a unique component, which means there are very few comparable components in the landscape. - ## Proposed component structure ### Critical content -N/A. Proposing that none of the content inside the identifier meets the criteria for critical content. +None. Proposing that none of the content inside the identifier meets the criteria for critical content. ### Light DOM @@ -36,7 +33,7 @@ Sample default implementation: ``` -Sample default implementation with pre-programmed language (in this example, Spanish): +Default Spanish implementation: ```html Date: Tue, 14 Jan 2025 13:50:29 -0700 Subject: [PATCH 3/7] Tweak prop descriptions --- web-components/identifier.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/web-components/identifier.md b/web-components/identifier.md index f55413c..3acd09c 100644 --- a/web-components/identifier.md +++ b/web-components/identifier.md @@ -177,11 +177,11 @@ For ease of implementation, recommend we offer additional common translations in | Property | Type | Description | Required? | |--------|--------|--------|--------| | `lang` | string | Set the language for the default component text. Expected values: "en", "es". Default value is "en". | No | -| `label` | string | Set a custom aria label for the identifier component. Default value for English translations: "Agency identifier", Default value for Spanish translations: "Descripción de la agencia" | No | -| `disclaimerText` | string | Custom text for the "official website" intro text. Default value for English translations: "An official website of the", Default value for Spanish translations: "Un sitio web oficial de" | No | -| `disclaimerConjunctionText` | string | Custom text for the conjunction in the "official website" intro text when there are multiple parent agencies. Default value for English translations: "and", Default value for Spanish translations: "y" | No | +| `label` | string | Set a custom aria label for the identifier component. Default values: "Agency identifier" for English translations, "Descripción de la agencia" for Spanish translations | No | +| `disclaimerText` | string | Custom text for the "official website" intro text. Default values: "An official website of the" for English translations, "Un sitio web oficial de" for Spanish translations. | No | +| `disclaimerConjunctionText` | string | Custom text for the conjunction in the "official website" intro text when there are multiple parent agencies. Default values: "and" for English translations: "y" for Spanish translations. | No | | `taxpayerDisclaimer` | boolean | Include the taxpayer disclaimer. A custom value can be set with `taxpayerText` attribute. | No | -| `taxpayerText` | string | Set a custom value for the taxpayer disclaimer text. Default value for English translations: "Produced and published at taxpayer expense.", Default value for Spanish translations: "Producido y publicado con dinero de los contribuyentes de impuestos." | No | +| `taxpayerText` | string | Set a custom value for the taxpayer disclaimer text. Default values: "Produced and published at taxpayer expense.", "Producido y publicado con dinero de los contribuyentes de impuestos." for Spanish translations | No | | `domainName` | string | Domain name for the website | Yes | | `parentAgencyLogo` | string | The url for the parent agency logo image | No | | `parentAgencyUrl` | string | The url for the parent agency's home page | Yes | @@ -191,21 +191,21 @@ For ease of implementation, recommend we offer additional common translations in | `secondaryParentAgencyUrl` | string | The url for the secondary parent agency's home page | No | | `secondaryParentAgencyName` | string | The full name of the secondary parent agency | No | | `aboutURL` | string | The url for the parent agency's "About" page | Yes | -| `aboutText` | string | Custom text for the "About" link. Default value for English translations: "About [Agency shortname or agency name], Default value for Spanish translations: "Acerca de [Agency shortname or agency name]" | No | +| `aboutText` | string | Custom text for the "About" link. Default values: "About [Agency shortname or agency name] for English translations, "Acerca de [Agency shortname or agency name]" for Spanish translations. | No | | `accessibilityURL` | string | The url for the parent agency's "Accesibility statement" page | Yes | -| `accessibilityText` | string | Custom text for the "Accessibility statement" link. Default value for English translations: "Accessibility statement", Default value for Spanish translations: "Declaración de accesibilidad" | No | +| `accessibilityText` | string | Custom text for the "Accessibility statement" link. Default values: "Accessibility statement" for English translations: "Declaración de accesibilidad" for Spanish translations. | No | | `foiaURL` | string | The url for the parent agency's "FOIA requests" page | Yes | -| `foiaText` | string | Custom text for the "FOIA requests" link. Default value for English translations: "FOIA requests", Default value for Spanish translations: "Solicitud a través de FOIA" | No | +| `foiaText` | string | Custom text for the "FOIA requests" link. Default values: "FOIA requests" for English translations, "Solicitud a través de FOIA" for Spanish translations. | No | | `noFearURL` | string | The url for the parent agency's "No FEAR Act data" page | Yes | -| `noFearText` | string | Custom text for the "No FEAR Act data" link. Default value for English translations: "No FEAR Act data", Default value for Spanish translations: "Datos de la ley No FEAR" | No | +| `noFearText` | string | Custom text for the "No FEAR Act data" link. Default values: "No FEAR Act data" for English translations, "Datos de la ley No FEAR" for Spanish translations. | No | | `oigURL` | string | The url for the parent agency's "Office of the inspector general" page | Yes | -| `oigText` | string | Custom text for the "Office of the inspector general" link. Default value for English translations: "Office of the inspector general", Default value for Spanish translations: "Oficina del Inspector General" | No | +| `oigText` | string | Custom text for the "Office of the inspector general" link. Default values: "Office of the inspector general" for English translations, "Oficina del Inspector General" for Spanish translations. | No | | `performanceURL` | string | The url for the parent agency's "Performance reports" page | Yes | -| `performanceText` | string | Custom text for the "Performance reports" link. Default value for English translations: "Performance reports", Default value for Spanish translations: "Informes de desempeño" | No | +| `performanceText` | string | Custom text for the "Performance reports" link. Default values: "Performance reports" for English translations, "Informes de desempeño" for Spanish translations. | No | | `privacyURL` | string | The url for the parent agency's "Privacy policy" page | Yes | -| `privacyText` | string | Custom text for the "Privacy policy" link. Default value for English translations: "Privacy policy", Default value for Spanish translations: "Política de privacidad" | No | -| `usagovText` | string | Custom text for the usa gov intro. Default value for English translations: "Looking for U.S. government information and services?", Default value for Spanish translations: "¿Necesita información y servicios del Gobierno?" | No | -| `usagovLinkText` | string | Custom text for "Visit USA.gov" link. Default value for English translations: "Visit USA.gov", Default value for Spanish translations: "Visite USAGov en Español" | No | +| `privacyText` | string | Custom text for the "Privacy policy" link. Default values: "Privacy policy" for English translations, "Política de privacidad" for Spanish translations. | No | +| `usagovText` | string | Custom text for the usa gov intro. Default values: "Looking for U.S. government information and services?" for English translations, "¿Necesita información y servicios del Gobierno?" for Spanish translations. | No | +| `usagovLinkText` | string | Custom text for "Visit USA.gov" link. Default values: "Visit USA.gov" for English translations, "Visite USAGov en Español" for Spanish translations. | No | | `usagovUrl` | string | Custom url for usa.gov. Default values: "https://www.usa.gov/` for English translations, "https://www.usa.gov/es/" for Spanish Translations. | No | #### Proposed additional variants From 5854ae00a6a377b8370bfc29c41daa0a9166c566 Mon Sep 17 00:00:00 2001 From: Amy Leadem <93996430+amyleadem@users.noreply.github.com> Date: Tue, 14 Jan 2025 13:52:19 -0700 Subject: [PATCH 4/7] Remove lang="en" from default sample --- web-components/identifier.md | 1 - 1 file changed, 1 deletion(-) diff --git a/web-components/identifier.md b/web-components/identifier.md index 3acd09c..392d828 100644 --- a/web-components/identifier.md +++ b/web-components/identifier.md @@ -16,7 +16,6 @@ Sample default implementation: ```html Date: Tue, 14 Jan 2025 13:54:41 -0700 Subject: [PATCH 5/7] Tweak prop structure for complex code sample --- web-components/identifier.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/web-components/identifier.md b/web-components/identifier.md index 392d828..f9954b6 100644 --- a/web-components/identifier.md +++ b/web-components/identifier.md @@ -58,9 +58,9 @@ Sample complex implementation with custom language strings (French) and multiple ```html Date: Tue, 14 Jan 2025 13:56:56 -0700 Subject: [PATCH 6/7] Update "proposed additional variants" summary --- web-components/identifier.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/web-components/identifier.md b/web-components/identifier.md index f9954b6..c7cc700 100644 --- a/web-components/identifier.md +++ b/web-components/identifier.md @@ -168,7 +168,7 @@ _Same as USWDS 3, with some proposed tweaks:_ | Spanish (all variants) | Translates content for all variants into Spanish | `lang="es"` | #### Proposed additional variants -For ease of implementation, recommend we offer additional common translations in the component that can be defined with the `lang` attribute. +For ease of implementation and consistency across sites, I recommend that we offer additional pre-built translations for commonly used languages. Then the user would just need to set the single `lang` attribute to automatically receive approved translations for this component. ### Props From 5f7d8dd306931df7beaf0c4f0671bfb61b4197d5 Mon Sep 17 00:00:00 2001 From: Amy Leadem <93996430+amyleadem@users.noreply.github.com> Date: Tue, 14 Jan 2025 14:00:17 -0700 Subject: [PATCH 7/7] Update identifier.md --- web-components/identifier.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/web-components/identifier.md b/web-components/identifier.md index c7cc700..fa6657c 100644 --- a/web-components/identifier.md +++ b/web-components/identifier.md @@ -233,6 +233,8 @@ N/A ### CSS Variables #### Current settings +> [!note] +> In this table, strikethrough styling conveys changes to the [existing settings documentation](https://designsystem.digital.gov/documentation/settings/#identifier). | USWDS 3 setting | CSS custom property | Description | |--------|--------|--------|