diff --git a/_components/date-picker/guidance/accessibility.md b/_components/date-picker/guidance/accessibility.md index 1b4ee615f..793834212 100644 --- a/_components/date-picker/guidance/accessibility.md +++ b/_components/date-picker/guidance/accessibility.md @@ -1,2 +1,8 @@ - **Customize form controls accessibly.** If you customize this component, ensure that it continues to meet the [accessibility requirements that apply to all form controls]({{ site.baseurl }}/components/form). -- **Avoid auto-submission.** Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Auto-submission disrupts screen readers because they select each option as they read them. \ No newline at end of file +- **Avoid auto-submission.** Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Auto-submission disrupts screen readers because they select each option as they read them. +- **Instructions for keyboard navigation** You can navigate this component using the following commands (Mac-equivalent commands are in parentheses): + - Days use left and right arrows + - Weeks use up and down arrows + - Months by using page up (fn + up arrow) and page down (fn + down arrow) + - Years by using shift + page up (shift + fn + up arrow) and shift + page down (shift + fn + down arrow) + - Home (fn + left arrow) and End (fn + right arrow) keys navigate to the beginning and end of a week diff --git a/_components/icon/guidance/accessibility.md b/_components/icon/guidance/accessibility.md index f280cafa4..5872120f8 100644 --- a/_components/icon/guidance/accessibility.md +++ b/_components/icon/guidance/accessibility.md @@ -1,4 +1,4 @@ -- **Hide decorative icons from screen readers.** Use the `aria-hidden="true"` and `role="img"` if the icon is redundant and used solely as visual progressive enhancement. +- **Hide decorative icons from screen readers.** Use the `aria-hidden="true"` and `role="img"` attributes if the icon is redundant and used solely as visual progressive enhancement as in the following code: ```html ``` -- **Provide descriptive text if a standalone icon has semantic meaning.** If you need to expose an icon to screen readers, remove the `aria-hidden="true"` attribute and add a `aria-labelledby` attribute with a value that matches the `id` of a `` element added inside the svg. +- **Provide descriptive text if a standalone icon has semantic meaning.** If you need to expose an icon to screen readers, remove the `aria-hidden="true"` attribute and add an `aria-labelledby` attribute with a value that matches the `id` of a `<title>` element added inside the SVG as in the following code: ```html <a href="https://twitter.com/uswds"> <svg aria-labelledby="twitter-title" role="img"> @@ -16,4 +16,4 @@ </svg> </a> ``` -- **Place icons inside links.** If icons accompany a text link, place the icon inside the link to prevent the screen reader from announcing the link twice. \ No newline at end of file +- **Place icons inside links.** If icons accompany a text link, place the icon inside the link to prevent the screen reader from announcing the link twice. diff --git a/_components/icon/guidance/implementation.md b/_components/icon/guidance/implementation.md index 262b1311c..9c772e6b6 100644 --- a/_components/icon/guidance/implementation.md +++ b/_components/icon/guidance/implementation.md @@ -2,4 +2,4 @@ - **Active icons are found in `dist/img/usa-icons`.** The icons in this directory will be packaged into an SVG sprite. The complete set of available icons are located in two directories: `dist/img/material-icons` and `dist/img/uswds-icons`. Copy icons into a `usa-icons` directory within your project images directory, and rebuild the SVG sprite using [uswds-compile](https://github.com/uswds/uswds-compile/). - **Using color in icons.** Icons use `currentColor`, so the color of the icon will be the text color of its parent element. Change colors with the [color utility](https://designsystem.digital.gov/utilities/color/). - **Relative to font size.** By default, icons will scale with font size. If you want to specify an icon size, use one of the component’s size variants. -- **Icon names are identifiers.** To use an individual, simply change the identifier after the pound sign in the sprite path to the icon name. For example, to use the `accessibility_new` icon, the path will be `<use xlink:href="/path/to/sprite.svg#accessibility_new">` or to use the `info` icon, the path will be `<use xlink:href="/path/to/sprite.svg#info">`. +- **Icon names are identifiers.** To use an individual, simply change the identifier after the pound sign in the sprite path to the icon name. For example, to use the `accessibility_new` icon, the path will be `<use xlink:href="/path/to/sprite.svg#accessibility_new">`, or to use the `info` icon, the path will be `<use xlink:href="/path/to/sprite.svg#info">`. diff --git a/_components/icon/guidance/when-to-use.md b/_components/icon/guidance/when-to-use.md index 5f46b5db3..d4ab66a95 100644 --- a/_components/icon/guidance/when-to-use.md +++ b/_components/icon/guidance/when-to-use.md @@ -1,3 +1,3 @@ -- **To draw attention to actions.** Icons are helpful when combined with text to inform users about performing an action. The icon should directly relate to the text it accompanies. -- **To help readers find key information.** Use icons as scannable, easy-to-understand visual indicators for key information like a phone number or email address. -- **To enhance an actionable target.** Icons make great touch or click targets. Use an icon for common actions like opening a menu or sharing an article. \ No newline at end of file +- **To draw attention to actions.** Icons are helpful, when combined with text, to inform users about performing an action. The icon should directly relate to the text it accompanies. +- **To help readers find key information.** Use icons as scannable, easy-to-understand visual indicators for key information, like a phone number or email address. +- **To enhance an actionable target.** Icons make great touch or click targets. Use an icon for common actions, like opening a menu or sharing an article. diff --git a/_components/prose/guidance/implementation.md b/_components/prose/guidance/implementation.md index 716d9d66c..8c3c792d8 100644 --- a/_components/prose/guidance/implementation.md +++ b/_components/prose/guidance/implementation.md @@ -4,6 +4,6 @@ - `p` - `ul` and `ol`, _plus_ child `li` - `table`, _plus_ child `thead`, `th`, `td`, and `caption` -- You can change the measure of elements styled with `usa-prose` in `_uswds-theme-typography.scss` with the following variables. Each accepts a measure token: +- Customize line-length by changing the value of `$theme-text-measure` and `$theme-lead-measure` in your [USWDS settings configuration]({{ site.baseurl }}/documentation/settings). Each setting accepts a [measure token]({{ site.baseurl }}/design-tokens/typesetting/measure/). - `$theme-text-measure` - - `$theme-lead-measure` \ No newline at end of file + - `$theme-lead-measure` diff --git a/_config.yml b/_config.yml index a60d5de47..27b959faf 100644 --- a/_config.yml +++ b/_config.yml @@ -2,7 +2,7 @@ title: U.S. Web Design System (USWDS) description: USWDS makes it easier to build accessible, mobile-friendly government websites. google_analytics_ua: UA-48605964-43 -uswds_version: 3.3.0 +uswds_version: 3.4.1 uswds_email: uswds@gsa.gov federalist_base: "https://federalist-3b6ba08e-0df4-44c9-ac73-6fc193b0e19c.sites.pages.cloud.gov/preview/uswds/uswds" federalist_component_preview: "iframe.html?id=" @@ -41,7 +41,7 @@ jekyll_get: json: "https://api.github.com/repos/uswds/uswds/contents/SECURITY.md" decode_content: true - data: hash - json: "https://api.github.com/repos/uswds/uswds/contents/security/uswds-3.3.0-zip-hash.txt?ref=main" + json: "https://api.github.com/repos/uswds/uswds/contents/security/uswds-3.4.1-zip-hash.txt?ref=main" decode_content: true repos: diff --git a/_data/changelogs/_CHANGELOG-README.md b/_data/changelogs/_CHANGELOG-README.md index f56291391..49b4bd84c 100644 --- a/_data/changelogs/_CHANGELOG-README.md +++ b/_data/changelogs/_CHANGELOG-README.md @@ -17,6 +17,7 @@ | affectsContent | Change affects content in the component itself | yes | boolean | true, false | yes | | affectsGuidance | Change affects component guidance| yes | boolean | true, false | yes | | affectsAssets | Change affects assets related to a component, like images | yes | boolean | true, false | yes | +| affectsSettings | Change affects settings | yes | boolean | true, false | yes | | githubPr | Pull request number | no | number| N/A | yes | | githubRepo | Pull request repo name | no | string| uswds, uswds-site | yes | | versionUswds | USWDS Version Number | no | number| N/A | yes | diff --git a/_data/changelogs/component-alert.yml b/_data/changelogs/component-alert.yml index 52a6c7031..fb9985eea 100644 --- a/_data/changelogs/component-alert.yml +++ b/_data/changelogs/component-alert.yml @@ -2,6 +2,13 @@ title: Alert type: component changelogURL: items: + - date: 2023-03-09 + summary: Updated padding settings to accept any valid spacing token. + summaryAdditional: + affectsStyles: true + githubPr: 5076 + githubRepo: uswds + versionUswds: 3.4.0 - date: 2022-10-19 summary: Updated the alignment of alert content to visually match banner content. summaryAdditional: The site alert component was also updated. @@ -47,4 +54,4 @@ items: affectsStyles: true githubPr: 4079 githubRepo: uswds - versionUswds: 2.11.0 \ No newline at end of file + versionUswds: 2.11.0 diff --git a/_data/changelogs/component-banner.yml b/_data/changelogs/component-banner.yml index c3f53bd43..b6db237a7 100644 --- a/_data/changelogs/component-banner.yml +++ b/_data/changelogs/component-banner.yml @@ -2,6 +2,27 @@ title: Banner type: component changelogURL: items: + - date: 2023-03-09 + summary: Improved display of focus outline on mobile. + summaryAdditional: Now the focus outline is visible all around the banner on mobile devices. + affectsStyles: true + githubPr: 5013 + githubRepo: uswds + versionUswds: 3.4.0 + - date: 2023-03-09 + summary: Updated padding settings to accept any valid spacing token. + summaryAdditional: + affectsStyles: true + githubPr: 5076 + githubRepo: uswds + versionUswds: 3.4.0 + - date: 2023-03-09 + summary: Removed grid dependency from Banner. + summaryAdditional: Banner no longer needs the `usa-layout-grid` package resulting in a much smaller package size. + affectsStyles: true + githubPr: 5000 + githubRepo: uswds + versionUswds: 3.4.0 - date: 2022-10-09 summary: Updated the aria-label in English versions of banner. summaryAdditional: When read out on a screen reader, the statement "An official website of the United States government" can sound like "Unofficial website of the United States government". To minimize confusion, we updated the component's `aria-label` to instead read "Official website of the United States government". diff --git a/_data/changelogs/component-date-picker.yml b/_data/changelogs/component-date-picker.yml index 649ae45e6..c842c6402 100644 --- a/_data/changelogs/component-date-picker.yml +++ b/_data/changelogs/component-date-picker.yml @@ -2,6 +2,13 @@ title: Date picker type: component changelogURL: items: + - date: 2023-03-09 + summary: Updated documentation for accessibility guidance. + summaryAdditional: Added instructions for keyboard navigation. + affectsAccessibility: + affectsStyles: + githubPr: 1695 + githubRepo: uswds-site - date: 2022-08-05 summary: Styled aria-disabled to match disabled. summaryAdditional: Now disabled styling is applied whether you use `disabled` (disabled and hidden from screen readers) or `aria-disabled` (disabled and visible to screen readers). @@ -51,7 +58,6 @@ items: githubPr: 4610 githubRepo: uswds versionUswds: 2.13.3 - affectsAccessibility: true - date: 2022-01-20 summary: Fixed date picker input bug in Safari. summaryAdditional: We fixed a bug where date picker selections would not propagate into the input field in Safari. diff --git a/_data/changelogs/component-footer.yml b/_data/changelogs/component-footer.yml index 8fa1d4ab8..9a2d1213e 100644 --- a/_data/changelogs/component-footer.yml +++ b/_data/changelogs/component-footer.yml @@ -2,6 +2,15 @@ title: Footer type: component changelogURL: items: + - date: 2023-03-09 + summary: Footer now accepts any heading level for primary link headers. + summaryAdditional: Use any heading level for `.usa-footer__primary-link` without it reverting to an `h4` when the JavaScript rebuilds the element for mobile. + affectsAccessibility: true + affectsJavascript: true + affectsMarkup: true + githubPr: 5044 + githubRepo: uswds + versionUswds: 3.4.0 - date: 2022-08-29 summary: Added documentation for `$theme-footer-max-width`. affectsGuidance: true diff --git a/_data/changelogs/component-form.yml b/_data/changelogs/component-form.yml index 669ccc425..68dfaa0a3 100644 --- a/_data/changelogs/component-form.yml +++ b/_data/changelogs/component-form.yml @@ -2,6 +2,14 @@ title: Form type: component changelogURL: items: + - date: 2023-03-13 + summary: Fixed invisible link text for links styled as buttons within forms. + summaryAdditional: Now link text does not match the primary button color when nested inside of a form and the `usa-button` class is present. + isBreaking: false + affectsStyles: true + githubPr: 5112 + githubRepo: uswds + versionUswds: 3.4.1 - date: 2022-04-28 summary: Updated to Sass module syntax and new package structure. isBreaking: true @@ -10,4 +18,4 @@ items: affectsStyles: true githubPr: 4656 githubRepo: uswds - versionUswds: 3.0.0 \ No newline at end of file + versionUswds: 3.0.0 diff --git a/_data/changelogs/component-header.yml b/_data/changelogs/component-header.yml index 36c28fefc..bce6e3564 100644 --- a/_data/changelogs/component-header.yml +++ b/_data/changelogs/component-header.yml @@ -2,6 +2,31 @@ title: Header type: component changelogURL: items: + - date: 2023-03-13 + summary: Logo text width setting now works as expected. + summaryAdditional: Now the design system respects the value passed to `$theme-header-logo-text-width`. + isBreaking: false + affectsStyles: true + githubPr: 5008 + githubRepo: uswds + versionUswds: 3.4.1 + - date: 2023-03-09 + summary: Secondary nav is now read properly on screen readers. + summaryAdditional: The separator between nav elements is no longer read on screen readers. + isBreaking: false + affectsAccessibility: true + affectsStyles: true + githubPr: 4963 + githubRepo: uswds + versionUswds: 3.4.0 + - date: 2023-03-09 + summary: Allow full-page width for header. + summaryAdditional: You can now set a value of `"none"` for any `max-width` setting, including `$theme-header-max-width`. + isBreaking: false + affectsStyles: true + githubPr: 5072 + githubRepo: uswds + versionUswds: 3.4.0 - date: 2022-08-05 summary: Added `type="button"` to all non-form buttons to prevent default submit behaviors. summaryAdditional: This allowed us to remove `preventDefault()` from the relevant component JavaScript. diff --git a/_data/changelogs/component-in-page-navigation.yml b/_data/changelogs/component-in-page-navigation.yml index bb3dff4ea..64c43cedb 100644 --- a/_data/changelogs/component-in-page-navigation.yml +++ b/_data/changelogs/component-in-page-navigation.yml @@ -2,6 +2,16 @@ title: In-page navigation type: component changelogURL: items: + - date: 2023-03-13 + summary: URL in address bar is updated when navigating component. + summaryAdditional: Users can now see the proper anchor link in the address bar when navigating from the in-page navigation. + affectsGuidance: + affectsJavascript: true + affectsMarkup: + affectsStyles: true + githubRepo: uswds + githubPr: 5170 + versionUswds: 3.4.1 - date: 2022-11-14 summary: Component released. affectsGuidance: true diff --git a/_data/changelogs/component-link.yml b/_data/changelogs/component-link.yml index 0390dc2fa..2a48cc7b4 100644 --- a/_data/changelogs/component-link.yml +++ b/_data/changelogs/component-link.yml @@ -2,6 +2,12 @@ title: Link type: component changelogURL: items: +- date: 2023-03-09 + summary: External link icons and link text now wrap as expected. + affectsStyles: true + githubPr: 5046 + githubRepo: uswds + versionUswds: 3.4.0 - date: 2022-04-28 summary: Updated to Sass module syntax and new package structure. isBreaking: true diff --git a/_data/changelogs/component-modal.yml b/_data/changelogs/component-modal.yml index 2bac98e00..f958a303c 100644 --- a/_data/changelogs/component-modal.yml +++ b/_data/changelogs/component-modal.yml @@ -2,6 +2,14 @@ title: Modal type: component changelogURL: items: +- date: 2023-03-09 + summary: Fixed the display of interactive form elements (like Date Picker) in modal windows. + summaryAdditional: Now any element in a modal should work as expected. + isBreaking: false + affectsJavascript: true + githubPr: 5049 + githubRepo: uswds + versionUswds: 3.4.0 - date: 2022-08-05 summary: Styled aria-disabled to match disabled. summaryAdditional: Now disabled styling is applied whether you use `disabled` (disabled and hidden from screen readers) or `aria-disabled` (disabled and visible to screen readers). diff --git a/_data/changelogs/component-site-alert.yml b/_data/changelogs/component-site-alert.yml index 55f6ad7e6..50a4f7f26 100644 --- a/_data/changelogs/component-site-alert.yml +++ b/_data/changelogs/component-site-alert.yml @@ -2,6 +2,13 @@ title: Site alert type: component changelogURL: items: + - date: 2023-03-09 + summary: Updated padding settings to accept any valid spacing token. + summaryAdditional: + affectsStyles: true + githubPr: 5076 + githubRepo: uswds + versionUswds: 3.4.0 - date: 2022-09-26 summary: Added guidance for using ARIA roles and ARIA labels. affectsGuidance: true diff --git a/_data/changelogs/component-step-indicator.yml b/_data/changelogs/component-step-indicator.yml index 08b663a3b..6637eb4ff 100644 --- a/_data/changelogs/component-step-indicator.yml +++ b/_data/changelogs/component-step-indicator.yml @@ -4,6 +4,16 @@ type: component changelogURL: items: + # 3.4.0 release + - date: 2023-03-09 + summary: Improved contrast on pending items. + summaryAdditional: Graphical elements related to pending items now meet accessibility standards for contrast ratio. + isBreaking: false + affectsAccessibility: true + affectsStyles: true + githubPr: 5048 + githubRepo: uswds + versionUswds: 3.4.0 # 3.0 release - date: 2022-04-28 summary: Updated to Sass module syntax and new package structure. diff --git a/_data/changelogs/component-typography.yml b/_data/changelogs/component-typography.yml index a97f13e19..79123f89c 100644 --- a/_data/changelogs/component-typography.yml +++ b/_data/changelogs/component-typography.yml @@ -4,6 +4,20 @@ type: component changelogURL: items: + # 3.4.0 release + - date: 2023-03-09 + summary: Use only `woff2` in our `@font-face` declarations. + summaryAdditional: Since modern browsers only need the `woff2` font format, we now only output `woff2` fonts in our `@font-face` rules. If you need `woff` and `ttf` for IE11 compatibility, set `$theme-font-browser-compatibility` to `true` in settings. + affectsAccessibility: + affectsAssets: + affectsSettings: true + affectsGuidance: true + affectsJavascript: + affectsMarkup: + affectsStyles: + githubPr: 5108 + githubRepo: uswds + versionUswds: 3.4.0 # 3.0 release - date: 2022-04-28 summary: Updated to Sass module syntax and new package structure. diff --git a/_data/changelogs/docs-implementations.yml b/_data/changelogs/docs-implementations.yml index b5e8fe019..aba7df322 100644 --- a/_data/changelogs/docs-implementations.yml +++ b/_data/changelogs/docs-implementations.yml @@ -2,6 +2,18 @@ title: Implementations type: documentation changelogURL: items: + - date: 2023-03-09 + summary: Added entry for "sam.gov" implementations. + summaryAdditional: + isBreaking: + affectsAccessibility: + affectsAssets: + affectsGuidance: true + affectsJavascript: + affectsMarkup: + affectsStyles: + githubPr: 1714 + githubRepo: uswds-site - date: 2022-10-11 summary: Added entry for "ngx-uswds". summaryAdditional: diff --git a/_data/changelogs/docs-settings.yml b/_data/changelogs/docs-settings.yml index cf7ef7875..a9b21b827 100644 --- a/_data/changelogs/docs-settings.yml +++ b/_data/changelogs/docs-settings.yml @@ -2,17 +2,38 @@ title: Settings type: utility changelogURL: items: - - date: 2023-03-08 + - date: 2023-03-20 summary: Updated settings information to match what is found in USWDS 3.3.0. summaryAdditional: affectsAccessibility: affectsAssets: + githubPr: 2016 + githubRepo: uswds-site + - date: 2023-03-09 + summary: Added `$theme-font-browser-compatibility` setting. + summaryAdditional: We now only output `woff2` fonts in our `@font-face` rules. If you need `woff` and `ttf` for IE11 compatibility, set this new setting to `true`. + affectsAccessibility: + affectsAssets: + affectsSettings: true affectsGuidance: true affectsJavascript: affectsMarkup: affectsStyles: - githubPr: 2016 - githubRepo: uswds-site + githubPr: 5108 + githubRepo: uswds + versionUswds: 3.4.0 + - date: 2023-03-09 + summary: Removed `woff` and `ttf` file format requirements from custom font source settings. + summaryAdditional: + affectsAccessibility: + affectsAssets: true + affectsGuidance: true + affectsJavascript: + affectsMarkup: + affectsStyles: + githubPr: 5108 + githubRepo: uswds + versionUswds: 3.4.0 - date: 2022-09-16 summary: Fixed typos in `primary-vivid` and `secondary-vivid` variable names. summaryAdditional: diff --git a/_data/changelogs/pattern-user-profile-gender-identity-and-sex.yml b/_data/changelogs/pattern-user-profile-gender-identity-and-sex.yml index 0126e4b85..ce12c2b61 100644 --- a/_data/changelogs/pattern-user-profile-gender-identity-and-sex.yml +++ b/_data/changelogs/pattern-user-profile-gender-identity-and-sex.yml @@ -2,8 +2,63 @@ title: Gender identity and sex type: pattern changelogURL: items: + - date: 2023-03-09 + summary: Added new White House report. + summaryAdditional: Added new White House report on collection of Sexual Orientation and Gender Identity (SOGI) information for statistical purposes. + affectsGuidance: true + githubPr: 1994 + githubRepo: uswds-site + - date: 2023-03-09 + summary: Added information on how some states collect sex data. + summaryAdditional: Added information and a reference link for how some states collect sex data on birth certificates and other legal documents. + affectsGuidance: true + githubPr: 1994 + githubRepo: uswds-site + - date: 2023-03-09 + summary: Added more detail supporting specific use cases for collecting sex data. + summaryAdditional: Added more detail about the most common use cases — matching an original birth certificate ("Sex listed at birth") or matching current legal documents ("Legal sex"). + affectsGuidance: true + githubPr: 1994 + githubRepo: uswds-site + - date: 2023-03-09 + summary: Added Sex pattern safety and transparency guidance. + summaryAdditional: Added additional guidance to promote using tested translations on multilingual forms, and providing helper text to explain data usage and sharing. + affectsGuidance: true + githubPr: 1994 + githubRepo: uswds-site + - date: 2023-03-09 + summary: Updated usage of "gender identity" and "sex" to be more consistent throughout. + affectsGuidance: true + githubPr: 1994 + githubRepo: uswds-site + - date: 2023-03-09 + summary: Updated usage for "sex listed at birth." + summaryAdditional: Updated our use of "sex listed at birth" to refer to original birth certificate information specifically. + affectsGuidance: true + githubPr: 1994 + githubRepo: uswds-site + - date: 2023-03-09 + summary: Updated description of documented pattern use cases. + summaryAdditional: Updated our background section to focus on documented use cases for collecting gender identity and sex data. + affectsGuidance: true + githubPr: 1994 + githubRepo: uswds-site + - date: 2023-03-09 + summary: Updated information on Form DS-11. + summaryAdditional: Added more detail about how the Department of State collects gender information on Form DS-11 and displays this information on passports. + affectsGuidance: true + githubPr: 1994 + githubRepo: uswds-site + - date: 2023-03-09 + summary: Updated Sex pattern preview. + summaryAdditional: Show the most common use cases of matching documents — either an original birth certificate ("Sex listed at birth") or current legal documents ("Legal sex") — and include explanation of why and how the data is used in the hint text. + affectsGuidance: true + githubPr: 1994 + githubRepo: uswds-site - date: 2022-11-14 summary: Pattern published. affectsGuidance: true githubRepo: uswds-site versionUswds: 3.3.0 + + diff --git a/_data/changelogs/template-404.yml b/_data/changelogs/template-404.yml index 441046c9c..446ebf659 100644 --- a/_data/changelogs/template-404.yml +++ b/_data/changelogs/template-404.yml @@ -1,6 +1,19 @@ title: 404 page type: template items: + - date: 2023-03-09 + summary: Updated template copy to follow parallel structure and use active voice. + summaryAdditional: + isBreaking: + affectsAccessibility: + affectsAssets: + affectsGuidance: + affectsJavascript: + affectsMarkup: true + affectsStyles: + githubPr: 5045 + githubRepo: uswds + versionUswds: - date: 2021-06-16 summary: Added Spanish variant. summaryAdditional: @@ -25,5 +38,4 @@ items: affectsMarkup: true affectsStyles: githubPr: 4003 - githubRepo: uswds - versionUswds: 2.11.0 + githubRepo: uswds \ No newline at end of file diff --git a/_data/changelogs/utilities.yml b/_data/changelogs/utilities.yml index ffbad8a91..770e1fb79 100644 --- a/_data/changelogs/utilities.yml +++ b/_data/changelogs/utilities.yml @@ -2,6 +2,19 @@ title: Utilities type: utility changelogURL: items: + - date: 2023-03-09 + summary: Outline utility and mixin now accept the 05 token. + summaryAdditional: Now, the `.outline-05` utility class and the `u-outline('05')` mixin should work as expected. + isBreaking: + affectsAccessibility: + affectsAssets: + affectsGuidance: true + affectsJavascript: + affectsMarkup: + affectsStyles: true + githubPr: 5079 + githubRepo: uswds + versionUswds: 3.4.0 - date: 2022-05-04 summary: Added `margin-horizontal` and `margin-vertical` utility modules. summaryAdditional: diff --git a/_data/implementations.yml b/_data/implementations.yml index 5a30ae117..65d848734 100644 --- a/_data/implementations.yml +++ b/_data/implementations.yml @@ -6,6 +6,22 @@ url: https://github.com/gsa notes: "This package provides Angular integration with USWDS." +- name: Sam-Prototypes + distribution: Angular + url: https://github.com/GSA/sam-prototypes + author: + name: SAM.gov + url: https://github.com/GSA + notes: "A test application that incorporates sam-styles and sam-design-system components with real-world examples." + +- name: Sam-Design-System + distribution: Angular + url: https://github.com/GSA/sam-design-system + author: + name: SAM.gov + url: https://github.com/GSA + notes: "Common Angular components integrated with sam-styles css framework." + - name: django-designstandards distribution: Django url: https://github.com/department-of-veterans-affairs/django-designstandards @@ -57,6 +73,14 @@ url: https://www.drupal.org/u/smustgrave notes: "USWDS components as paragraph bundles. Includes accordion, card, alert, process list, summary box, step indicator, and layout grid options." +- name: Sam-Styles + distribution: Fractal + url: https://github.com/GSA/sam-styles + author: + name: SAM.gov + url: https://github.com/GSA + notes: "A Fractal build that generates an interactive component library for sam-styles." + - name: uswds-jekyll distribution: Jekyll url: https://github.com/18f/uswds-jekyll diff --git a/_data/settings/typography.yml b/_data/settings/typography.yml index 9f284e51f..d12934ae0 100644 --- a/_data/settings/typography.yml +++ b/_data/settings/typography.yml @@ -36,6 +36,11 @@ contents: var: $theme-font-path default: '"../fonts"' type: path + - name: Browser compatibility mode + description: Output additional font formats (`woff` and `ttf`) to support IE11. + var: $theme-font-browser-compatibility + default: false + type: boolean - name: Custom typeface tokens description: Add custom typeface tokens. @@ -282,7 +287,7 @@ contents: description: | If you want USWDS to generate additional `@font-face` declarations, add your font data to the following variables as a map with these keys. - You must include fonts saved as `.ttf`, `.woff`, and `.woff2`. Instructions can be found on the [font-family](https://designsystem.digital.gov/design-tokens/typesetting/font-family/#adding-a-self-hosted-font) page. + You must include fonts saved as `.woff2`. You must include `.ttf` and `.woff` fonts if `$theme-font-browser-compatibility` is set to `true`. Instructions can be found on the [font-family](https://designsystem.digital.gov/design-tokens/typesetting/font-family/#adding-a-self-hosted-font) page. var: $theme-font-[family]-custom-src default: type: map diff --git a/_includes/changelog-table.html b/_includes/changelog-table.html index 1edaec4dc..511a9d480 100644 --- a/_includes/changelog-table.html +++ b/_includes/changelog-table.html @@ -58,6 +58,9 @@ {% if item.affectsStyles %} <li><span class="output-neutral">Styles</span></li> {% endif %} + {% if item.affectsSettings %} + <li><span class="output-neutral">Settings</span></li> + {% endif %} </ul> </td> <td data-title="{{ col4Title }}" class="{{ col4Classes }}"> diff --git a/_includes/patterns/biological-sex.html b/_includes/patterns/biological-sex.html deleted file mode 100644 index f4e086705..000000000 --- a/_includes/patterns/biological-sex.html +++ /dev/null @@ -1,17 +0,0 @@ -<form class="usa-form usa-form--large"> - <fieldset class="usa-fieldset"> - <legend class="usa-legend usa-legend">Sex listed at birth</legend> - <div class="usa-radio"> - <input class="usa-radio__input" id="male" type="radio" name="biological-sex" value="male" /> - <label class="usa-radio__label" for="male">Male</label> - </div> - <div class="usa-radio"> - <input class="usa-radio__input" id="female" type="radio" name="biological-sex" value="female" /> - <label class="usa-radio__label" for="female">Female</label> - </div> - <div class="usa-radio"> - <input class="usa-radio__input" id="x" type="radio" name="biological-sex" value="x" /> - <label class="usa-radio__label" for="x">X (intersex or unspecified)</label> - </div> - </fieldset> -</form> \ No newline at end of file diff --git a/_includes/patterns/gender.html b/_includes/patterns/gender-identity.html similarity index 89% rename from _includes/patterns/gender.html rename to _includes/patterns/gender-identity.html index b987a1abd..1f44c818e 100644 --- a/_includes/patterns/gender.html +++ b/_includes/patterns/gender-identity.html @@ -4,5 +4,5 @@ <div class="usa-checkbox"> <input class="usa-checkbox__input" id="prefer-not-to-answer" type="checkbox" name="prefer-not-to-answer" value="prefer-not-to-answer" /> - <label class="usa-checkbox__label" for="prefer-not-to-answer">Prefer not to share my gender</label> + <label class="usa-checkbox__label" for="prefer-not-to-answer">Prefer not to share my gender identity</label> </div> \ No newline at end of file diff --git a/_includes/patterns/sex.html b/_includes/patterns/sex.html new file mode 100644 index 000000000..a852a78aa --- /dev/null +++ b/_includes/patterns/sex.html @@ -0,0 +1,76 @@ +<h3 class="site-preview-heading">Matching an original birth certificate</h3> + +<form class="usa-form usa-form--large"> + <fieldset class="usa-fieldset"> + <legend class="usa-legend usa-legend">Sex listed at birth</legend> + <span class="usa-hint" id="slabHint">Please enter the sex that appears on your original birth certificate. Use “X” for a sex listed on your birth certificate that is neither male nor female. <a href="#sex-data-transparency-statement" aria-controls="sex-data-transparency-statement" data-open-modal>Why do we ask for sex information?</a></span> + <div class="usa-radio"> + <input class="usa-radio__input" id="slab-male" type="radio" name="sex-listed-at-birth" value="male" /> + <label class="usa-radio__label" for="slab-male">Male</label> + </div> + <div class="usa-radio"> + <input class="usa-radio__input" id="slab-female" type="radio" name="sex-listed-at-birth" value="female" /> + <label class="usa-radio__label" for="slab-female">Female</label> + </div> + <div class="usa-radio"> + <input class="usa-radio__input" id="slab-x" type="radio" name="sex-listed-at-birth" value="x" /> + <label class="usa-radio__label" for="slab-x">X</label> + </div> + </fieldset> +</form> + +<h3 class="site-preview-heading">Matching any qualifying legal document</h3> + +<form class="usa-form usa-form--large"> + <fieldset class="usa-fieldset"> + <legend class="usa-legend usa-legend">Legal sex</legend> + <span class="usa-hint" id="lsHint">Please enter the sex that appears on your driver's license, state ID, passport, or passport card. Use “X” for a sex listed on your ID that is neither male nor female. <a href="#sex-data-transparency-statement" aria-controls="sex-data-transparency-statement" data-open-modal>Why do we ask for sex information?</a></span> + <div class="usa-radio"> + <input class="usa-radio__input" id="ls-male" type="radio" name="legal-sex" value="male" /> + <label class="usa-radio__label" for="ls-male">Male</label> + </div> + <div class="usa-radio"> + <input class="usa-radio__input" id="ls-female" type="radio" name="legal-sex" value="female" /> + <label class="usa-radio__label" for="ls-female">Female</label> + </div> + <div class="usa-radio"> + <input class="usa-radio__input" id="ls-x" type="radio" name="legal-sex" value="x" /> + <label class="usa-radio__label" for="ls-x">X</label> + </div> + </fieldset> +</form> + +<div +class="usa-modal" +id="sex-data-transparency-statement" +aria-labelledby="sex-data-transparency-statement-heading" +aria-describedby="sex-data-transparency-statement-description" +> + <div class="usa-modal__content"> + <div class="usa-modal__main"> + <h4 class="usa-modal__heading" id="sex-data-transparency-statement-heading"> + Why do we ask for [type] information? + </h4> + <div class="usa-prose"> + <p id="sex-data-transparency-statement-description"> + Include a description of why your service collects [type] information and how this data will be shared. + </p> + </div> + <div class="usa-modal__footer"> + <button type="button" class="usa-button" data-close-modal> + Return to the form + </button> + </div> + </div> + <button + type="button" + class="usa-button usa-modal__close" + aria-label="Close this window" + data-close-modal + > + <svg class="usa-icon" aria-hidden="true" focusable="false" role="img"> + <use xlink:href="{{ site.baseurl }}/assets/img/sprite.svg#close"></use> + </svg> + </button> + </div> +</div> diff --git a/_includes/utilities/output-control.html b/_includes/utilities/output-control.html index 7feaa7c28..51831d795 100644 --- a/_includes/utilities/output-control.html +++ b/_includes/utilities/output-control.html @@ -1,6 +1,6 @@ <section class="utilities-section margin-top-6" id="output-control"> <h3 class="utilities-section-title">Output control</h3> - <p class="utility-text">Control whether or not to output any USWDS utility family by setting the value of the <code>$[utility_family]-settings.output</code> variable found in <code>_uswds-theme-utilities.scss</code>.</p> + <p class="utility-text">Control whether or not to output any USWDS utility family by setting the value of the <code>$[utility_family]-settings.output</code> variable in your <a href="{{ site.baseurl }}/documentation/settings" class="">USWDS settings configuration</a>.</p> <p class="utility-text">A value of <code>true</code> will output the utility family and any variants. A value of <code>false</code> prevents the output of the family and any variants.</p> <table class="usa-table--borderless site-table-responsive site-table-simple"> diff --git a/_includes/utilities/responsive-variants.html b/_includes/utilities/responsive-variants.html index 062695a1d..9c2b314a3 100644 --- a/_includes/utilities/responsive-variants.html +++ b/_includes/utilities/responsive-variants.html @@ -14,7 +14,7 @@ <h4 class="font-lang-2xs margin-top-2 margin-bottom-05">Output</h4> } </pre> </div> - <p class="utility-text margin-top-4">Set which breakpoints are available to USWDS utilities with the <code>$theme_output_breakpoints</code> variable found in <code>_uswds-theme-utilities.scss</code>.</p> + <p class="utility-text margin-top-4">Set up which breakpoints are available to USWDS utilities by setting the <code>$theme-utility-breakpoints</code> variable in your <a href="{{ site.baseurl }}/documentation/settings" class="">USWDS settings configuration</a>.</p> {% assign breakpoint = site.data.tokens.spacing.positive %} {% assign all-breakpoints = @@ -63,7 +63,22 @@ <h4 class="font-lang-2xs margin-top-2 margin-bottom-05">Output</h4> </tbody> </table> - <p class="utility-text margin-top-4">Set whether a utility family outputs with responsive variants by setting the value of <code>$[utility_family]-settings.responsive</code> in <code>_uswds-theme-utilities.scss</code>.</p> + <p class="utility-text margin-top-4">Set whether a utility family outputs with responsive variants by setting the value of <code>$[utility_family]-settings.responsive</code> in your <a href="{{ site.baseurl }}/documentation/settings">USWDS settings configuration</a>. When modifying any settings stored as a map, you need to set <em>all</em> elements of the map, not just the element you wish to change.</p> + + <div class="example border-left-05 border-secondary-light padding-left-105 margin-top-2 margin-bottom-2"> + <pre class=" font-mono-xs margin-0 padding-0 bg-transparent"> +@use "uswds-core" with ( + $background-color-settings: ( + output: true, + responsive: false, + active: false, + focus: false, + hover: true, + visited: false, + ) +); +</pre> + </div> <table class="usa-table--borderless site-table-responsive site-table-simple"> <thead> diff --git a/_includes/utilities/state-variants.html b/_includes/utilities/state-variants.html index bf0bcfc9e..d49acadf1 100644 --- a/_includes/utilities/state-variants.html +++ b/_includes/utilities/state-variants.html @@ -10,7 +10,22 @@ <h4 class="font-lang-2xs margin-top-2 margin-bottom-05">Output</h4> </pre> </div> - <p class="utility-text margin-top-4">Set whether a utility outputs a specific state variant by setting the value of the <code>$[utility_family]-settings.[state]</code> variable in <code>_uswds-theme-utilities.scss</code>.</p> +<p class="utility-text margin-top-4">Set whether a utility outputs a specific state variant by setting the value of the <code>$[utility_family]-settings.[state]</code> variable in your <a href="{{ site.baseurl }}/documentation/settings" class="">USWDS settings configuration</a>. When modifying any settings stored as a map, you need to set <em>all</em> elements of the map, not just the element you wish to change.</p> + + <div class="example border-left-05 border-secondary-light padding-left-105 margin-top-2 margin-bottom-2"> + <pre class=" font-mono-xs margin-0 padding-0 bg-transparent"> +@use "uswds-core" with ( + $background-color-settings: ( + output: true, + responsive: false, + active: false, + focus: false, + hover: true, + visited: false, + ) +); +</pre> + </div> <table class="usa-table--borderless site-table-responsive site-table-simple"> <thead> diff --git a/_includes/utilities/values-intro.html b/_includes/utilities/values-intro.html index 5851351be..36445b529 100644 --- a/_includes/utilities/values-intro.html +++ b/_includes/utilities/values-intro.html @@ -1,5 +1,5 @@ <h3 class="utilities-section-title">Custom values</h3> -<p class="utility-text">By default, USWDS utilities output the standard values listed in the documentation above. Customize and refine any utility family’s specific values by editing the <code>$[utility_family]-manual-values</code> and <code>$[utility_family]-palettes</code> variables in <code>_uswds-theme-utilities.scss</code>.</p> +<p class="utility-text">By default, USWDS utilities output the standard values listed in the <a href="#utilities-section">standard output table</a>. Customize and refine any utility family’s specific values by editing the <code>$[utility_family]-manual-values</code> and <code>$[utility_family]-palettes</code> variables in your <a href="{{ site.baseurl }}/documentation/settings">USWDS settings configuration</a>.</p> <h3 class="font-lang-4 margin-bottom-0">Manual values</h3> <p class="utility-text margin-top-1">Specify manual values as unique <code>key:value</code> pairs using the <code>$[utility_family]-manual-values</code> map, where the <code>key</code> is the utility’s value suffix, and the <code>value</code> is what the utility will output.</p> @@ -18,4 +18,4 @@ <h4 class="font-lang-2xs margin-top-2 margin-bottom-05">Output</h4> </div> <h3 class="font-lang-4 margin-bottom-0">Palettes</h3> -<p class="utility-text margin-top-1">Palettes are predefined groups of values. Add palettes to the <code>$[utility_family]-palettes</code> list variable in <code>_uswds-theme-utilities.scss</code> to add those values to the utility family.</p> +<p class="utility-text margin-top-1">Palettes are predefined groups of values. Add palettes to the <code>$[utility_family]-palettes</code> list variable in your <a href="{{ site.baseurl }}/documentation/settings">USWDS settings configuration</a> to add those values to the utility family.</p> diff --git a/_templates/page-templates/404/404.md b/_templates/page-templates/404/404.md index 7d4d1b623..8cf2b81f3 100644 --- a/_templates/page-templates/404/404.md +++ b/_templates/page-templates/404/404.md @@ -4,8 +4,8 @@ component: package: false dependencies: image: - - /assets/img/templates/layout--404.jpeg - - /assets/img/templates/layout--404-lang-es.jpeg + - /assets/img/templates/layout--404.webp + - /assets/img/templates/layout--404-lang-es.webp demo: - pages-error--page-not-found - pages-error--page-not-found-spanish diff --git a/_utilities/border.md b/_utilities/border.md index 16a2f2601..3ed8e8731 100644 --- a/_utilities/border.md +++ b/_utilities/border.md @@ -97,7 +97,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} diff --git a/_utilities/color.md b/_utilities/color.md index 56607e4c6..954ab029f 100644 --- a/_utilities/color.md +++ b/_utilities/color.md @@ -52,7 +52,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} @@ -299,7 +299,7 @@ $background-color-palettes: ( </div> <h4 class="font-lang-2xs margin-top-4 margin-bottom-0">Global color palettes</h4> - <p class="utility-text margin-top-05">Any palette added to the <code>$global-color-palettes</code> list in <code>_uswds-theme-utilities.scss</code> will output in the background color, text color, border color, and text decoration color utilities.</p> + <p class="utility-text margin-top-05">Any palette added to the <code>$global-color-palettes</code> list in your your <a href="{{ site.baseurl }}/documentation/settings" class="">USWDS settings configuration</a> will output in the background color, text color, border color, and text decoration color utilities.</p> {% include utilities/color-palettes.html %} diff --git a/_utilities/display.md b/_utilities/display.md index 9502a6266..d4524810c 100644 --- a/_utilities/display.md +++ b/_utilities/display.md @@ -138,7 +138,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} <section class="utility" id="utility-display"> diff --git a/_utilities/flex.md b/_utilities/flex.md index 5d5b2d162..93caa67b3 100644 --- a/_utilities/flex.md +++ b/_utilities/flex.md @@ -203,7 +203,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} <section class="utility" id="utility-flex"> diff --git a/_utilities/float.md b/_utilities/float.md index 63e78d069..24b72f4c4 100644 --- a/_utilities/float.md +++ b/_utilities/float.md @@ -30,7 +30,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} diff --git a/_utilities/font-size-and-family.md b/_utilities/font-size-and-family.md index 7a3518378..71244294d 100644 --- a/_utilities/font-size-and-family.md +++ b/_utilities/font-size-and-family.md @@ -44,7 +44,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} diff --git a/_utilities/height-and-width.md b/_utilities/height-and-width.md index 418c9c4cf..c4baa4b42 100644 --- a/_utilities/height-and-width.md +++ b/_utilities/height-and-width.md @@ -184,7 +184,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} <section class="utility" id="height"> diff --git a/_utilities/layout-grid.md b/_utilities/layout-grid.md index 7ac6faabf..5243397a2 100644 --- a/_utilities/layout-grid.md +++ b/_utilities/layout-grid.md @@ -69,8 +69,8 @@ The following sections break the layout grid down and describe how it works. {:.usa-content-list} - **Containers:** `grid-container` centers the container and gives it a maximum width of `desktop` (1024px). If you would like the grid to span the full width of the page, do not use `grid-container`. - - `grid-container` can also accept any breakpoint width, like `grid-container-tablet-lg` or `grid-container-widescreen`. Set the default max width with `$theme-grid-container-max-width` in `uswds-theme-spacing.scss`. - - By default, `grid-container`s have padding-x of [2 units]({{ site.baseurl }}/design-tokens/spacing-units/){:.token}, with a padding-x of [4 units]({{ site.baseurl }}/design-tokens/spacing-units/){:.token} at `desktop` and wider. Control these values with the values of `$theme-site-margins-mobile-width`, `$theme-site-margins-width` and `$theme-site-margins-breakpoint` in `uswds-theme-spacing.scss`. + - `grid-container` can also accept any breakpoint width, like `tablet-lg` or `widescreen`. Set the default max width with `$theme-grid-container-max-width` in your [USWDS settings configuration]({{ site.baseurl }}/documentation/settings) using [unit tokens]({{ site.baseurl }}/design-tokens/spacing-units/). + - By default, `grid-container` has a `padding-x` of [2 units]({{ site.baseurl }}/design-tokens/spacing-units/){:.token} at narrow widths, and a padding-x of [4 units]({{ site.baseurl }}/design-tokens/spacing-units/){:.token} at `desktop` and wider. Control these values by customizing `$theme-site-margins-mobile-width`, `$theme-site-margins-width` and `$theme-site-margins-breakpoint` in your [USWDS settings configuration]({{ site.baseurl }}/documentation/settings) using [unit tokens]({{ site.baseurl }}/design-tokens/spacing-units/). - **Rows:** Columns must have a `grid-row` as a parent. - **Columns:** `grid-col-[1-12]` indicates the number of columns the item spans out of a possible 12 per row. So, if you want three equal-width columns across, use `grid-col-4` for each item. @@ -508,9 +508,9 @@ Add `grid-gap` to a grid row to add a gap (or gutter) between each column in the When generating your CSS from USWDS source files, you have the option of customizing many system defaults by modifying project theme variables. USWDS also provides grid mixins for adding grid functionality to custom semantic component CSS. ### Variables -Variables and maps determine the number of columns, gutter width, and media-query point at which to begin floating columns. We use variables to generate the predefined grid classes documented on this page, as well as for the custom mixins noted under USWDS-theme-spacing.scss and USWDS-theme-utilities.scss. +Variables and maps determine the number of columns, gutter width, and media-query point at which to begin floating columns. We use variables to generate the predefined grid classes documented on this page, as well as for the custom mixins noted under [Spacing settings](#spacing-settings) and [Utilities settings](#utilities-settings). -#### uswds-theme-spacing.scss +#### Spacing settings {% highlight scss %} // Values are set as units tokens. @@ -526,7 +526,7 @@ $theme-site-margins-width: 4; $theme-site-margins-mobile-width: 2; {% endhighlight %} -#### uswds-theme-utilities.scss +#### Utilities settings {% highlight scss %} // Turn on or off breakpoints diff --git a/_utilities/margin-and-padding.md b/_utilities/margin-and-padding.md index 6fc282946..8642de003 100644 --- a/_utilities/margin-and-padding.md +++ b/_utilities/margin-and-padding.md @@ -130,7 +130,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} diff --git a/_utilities/outline.md b/_utilities/outline.md index 9cd240f10..e0cecb8fd 100644 --- a/_utilities/outline.md +++ b/_utilities/outline.md @@ -50,7 +50,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} diff --git a/_utilities/paragraph-styles.md b/_utilities/paragraph-styles.md index b05442c33..1b3a84ff2 100644 --- a/_utilities/paragraph-styles.md +++ b/_utilities/paragraph-styles.md @@ -141,7 +141,7 @@ vals_negative: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} diff --git a/_utilities/shadow.md b/_utilities/shadow.md index c528570d0..86ed957f7 100644 --- a/_utilities/shadow.md +++ b/_utilities/shadow.md @@ -29,7 +29,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} <section class="utility" id="box-shadow"> diff --git a/_utilities/text-styles.md b/_utilities/text-styles.md index 18b329554..ab432b22e 100644 --- a/_utilities/text-styles.md +++ b/_utilities/text-styles.md @@ -125,7 +125,7 @@ utilities: </div> </div> -<section class="utilities-section"> +<section id="utilities-section" class="utilities-section"> {% include utilities/utilities-section-title-bar.html %} diff --git a/css/settings/_uswds-theme-typography.scss b/css/settings/_uswds-theme-typography.scss index a3dd707db..6fd596d34 100644 --- a/css/settings/_uswds-theme-typography.scss +++ b/css/settings/_uswds-theme-typography.scss @@ -226,10 +226,7 @@ EXAMPLE - dir: Directory relative to $theme-font-path - This directory should include fonts saved as - .eot, .ttf, .woff, and .woff2 - ExampleSerif-Normal.eot - ExampleSerif-Normal.ttf - ExampleSerif-Normal.woff + .woff2 ExampleSerif-Normal.woff2 $theme-font-serif-custom-src: ( diff --git a/files/monthly-calls/uswds-monthly-call-march-2023--distro.pptx.zip b/files/monthly-calls/uswds-monthly-call-march-2023--distro.pptx.zip new file mode 100644 index 000000000..849e4d56f Binary files /dev/null and b/files/monthly-calls/uswds-monthly-call-march-2023--distro.pptx.zip differ diff --git a/img/templates/layout--404-lang-es.jpeg b/img/templates/layout--404-lang-es.jpeg deleted file mode 100644 index a470c8dae..000000000 Binary files a/img/templates/layout--404-lang-es.jpeg and /dev/null differ diff --git a/img/templates/layout--404-lang-es.webp b/img/templates/layout--404-lang-es.webp new file mode 100644 index 000000000..e8e239bd9 Binary files /dev/null and b/img/templates/layout--404-lang-es.webp differ diff --git a/img/templates/layout--404.jpeg b/img/templates/layout--404.jpeg deleted file mode 100644 index f0ee8ec2f..000000000 Binary files a/img/templates/layout--404.jpeg and /dev/null differ diff --git a/img/templates/layout--404.webp b/img/templates/layout--404.webp new file mode 100644 index 000000000..c912fdd65 Binary files /dev/null and b/img/templates/layout--404.webp differ diff --git a/package-lock.json b/package-lock.json index 98486d3be..7d89be49e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,7 +8,7 @@ "license": "SEE LICENSE IN LICENSE.md", "dependencies": { "@uswds/compile": "^1.0.0-beta.3", - "@uswds/uswds": "^3.3.0" + "@uswds/uswds": "^3.4.1" }, "devDependencies": { "@18f/identity-stylelint-config": "^1.0.0", @@ -474,9 +474,9 @@ } }, "node_modules/@uswds/uswds": { - "version": "3.3.0", - "resolved": "https://registry.npmjs.org/@uswds/uswds/-/uswds-3.3.0.tgz", - "integrity": "sha512-qiugkbwrO+eIIwi4lbEdH15LCHuAjfUMDRQNBBujakR99Ka3iqmrLpPllffdKaJJnnYkt75v0lltnJ5Nnd/obQ==", + "version": "3.4.1", + "resolved": "https://registry.npmjs.org/@uswds/uswds/-/uswds-3.4.1.tgz", + "integrity": "sha512-eLYbWUqf9eWUa2P6CO3ckIjtQyM3AylrIOHxN5gYG3P62TDd3FzRDyoACfvOe6CNk0w0PqXWJnuPzxpNoOgWNA==", "dependencies": { "classlist-polyfill": "1.0.3", "object-assign": "4.1.1", @@ -6459,9 +6459,9 @@ "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==" }, "node_modules/json5": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/json5/-/json5-1.0.1.tgz", - "integrity": "sha512-aKS4WQjPenRxiQsC93MNfjx+nbF4PAdYzmd/1JIj8HYzqfbu86beTuNgXDzPknWk0n0uARlyewZo4s++ES36Ow==", + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/json5/-/json5-1.0.2.tgz", + "integrity": "sha512-g1MWMLBiz8FKi1e4w0UyVL3w+iJceWAFBAaBnnGKOpNa5f8TLktkbre1+s6oICydWAm+HRUGTmI+//xv2hvXYA==", "dev": true, "dependencies": { "minimist": "^1.2.0" @@ -12701,9 +12701,9 @@ } }, "@uswds/uswds": { - "version": "3.3.0", - "resolved": "https://registry.npmjs.org/@uswds/uswds/-/uswds-3.3.0.tgz", - "integrity": "sha512-qiugkbwrO+eIIwi4lbEdH15LCHuAjfUMDRQNBBujakR99Ka3iqmrLpPllffdKaJJnnYkt75v0lltnJ5Nnd/obQ==", + "version": "3.4.1", + "resolved": "https://registry.npmjs.org/@uswds/uswds/-/uswds-3.4.1.tgz", + "integrity": "sha512-eLYbWUqf9eWUa2P6CO3ckIjtQyM3AylrIOHxN5gYG3P62TDd3FzRDyoACfvOe6CNk0w0PqXWJnuPzxpNoOgWNA==", "requires": { "classlist-polyfill": "1.0.3", "object-assign": "4.1.1", @@ -17375,9 +17375,9 @@ "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==" }, "json5": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/json5/-/json5-1.0.1.tgz", - "integrity": "sha512-aKS4WQjPenRxiQsC93MNfjx+nbF4PAdYzmd/1JIj8HYzqfbu86beTuNgXDzPknWk0n0uARlyewZo4s++ES36Ow==", + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/json5/-/json5-1.0.2.tgz", + "integrity": "sha512-g1MWMLBiz8FKi1e4w0UyVL3w+iJceWAFBAaBnnGKOpNa5f8TLktkbre1+s6oICydWAm+HRUGTmI+//xv2hvXYA==", "dev": true, "requires": { "minimist": "^1.2.0" diff --git a/package.json b/package.json index 55a088e98..52ffe38ff 100644 --- a/package.json +++ b/package.json @@ -41,7 +41,7 @@ "federalist": "npx gulp build", "lint": "npx gulp lintJS lintSass && npm run prettier:scss", "prestart": "npx gulp build", - "proof": "bundle exec htmlproofer --allow-hash-href=true --enforce-https=false --allow-missing-href=true --ignore-empty-alt=true --ignore-status-codes 0,403,429,503,302 --swap-urls 'https\\://designsystem.digital.gov/:/' --ignore-files \"\/\/select-a-language\/\/,\/\/2017\/\/,\/\/2018\/\/,\/\/2019\/\/\" ./_site", + "proof": "bundle exec htmlproofer --allow-hash-href=true --enforce-https=false --allow-missing-href=true --ignore-empty-alt=true --ignore-status-codes 0,403,429,503,302 --swap-urls 'https\\://designsystem.digital.gov/:/' --ignore-files \"//select-a-language//,//2017//,//2018//,//2019//\" ./_site", "serve": "npm run build:all-assets && bundle exec jekyll serve --drafts --future --incremental --livereload --host=localhost", "serve:package": "npm run build:uswds && npm run serve", "serve:local": "export LIBRARY_BASE_URL=\"http://localhost:3000\" && npm run serve", @@ -98,6 +98,6 @@ "snyk": true, "dependencies": { "@uswds/compile": "^1.0.0-beta.3", - "@uswds/uswds": "^3.3.0" + "@uswds/uswds": "^3.4.1" } } diff --git a/pages/design-tokens/overview.md b/pages/design-tokens/overview.md index 415849073..20f40f3a7 100644 --- a/pages/design-tokens/overview.md +++ b/pages/design-tokens/overview.md @@ -53,7 +53,7 @@ We can't include tokens, like `max-width: 1`, directly in our Sass. Rather, we u ### Example: Tokens in settings and component Sass -Tokens can be expressed as variables, which is how most Design System theme settings work. For instance, the following is an example of theme settings from `_uswds-theme-spacing.scss` showing settings variables assigned spacing unit tokens: +Tokens can be expressed as variables, which is how most Design System theme settings work. For instance, the following is an example of theme settings in your [USWDS settings configuration]({{ site.baseurl }}/documentation/settings). This example shows spacing unit tokens assigned to settings variables: ``` $theme-grid-container-max-width: 'desktop'; diff --git a/pages/design-tokens/typesetting/font-size.md b/pages/design-tokens/typesetting/font-size.md index b80d44c0b..e3e15c5b8 100644 --- a/pages/design-tokens/typesetting/font-size.md +++ b/pages/design-tokens/typesetting/font-size.md @@ -20,7 +20,7 @@ subnav: Please see the [Typesetting]({{ site.baseurl }}/design-tokens/typesetting){:.text-ink.text-bold} section for more about font size normalization and how USWDS uses tokens for typesetting. The documentation below displays a value in pixels, rather than the actual final output, which will be normalized depending on the typeface and output in `rem` customized to your project settings. ## Theme tokens -The following chart shows the USWDS default settings for the nine theme size tokens. Customize the output to your project needs in `$uswds-theme-typography.scss` by setting the variables listed below. If your project requires more than nine sizes, use [system size tokens](#system-tokens) as needed. +The following chart shows the USWDS default settings for the nine theme size tokens. Customize the output to your project needs in [USWDS settings configuration]({{ site.baseurl }}/documentation/settings) by setting the variables listed in the default settings chart. If your project requires more than nine sizes, use [system size tokens](#system-tokens) as needed. <div class="site-table-wrapper"> <table class="usa-table--borderless site-table-responsive"> diff --git a/pages/design-tokens/typesetting/font-weight.md b/pages/design-tokens/typesetting/font-weight.md index 0d97e3579..2730e3cdd 100644 --- a/pages/design-tokens/typesetting/font-weight.md +++ b/pages/design-tokens/typesetting/font-weight.md @@ -19,7 +19,7 @@ subnav: ## Theme tokens Font weight theme tokens use common names. Most projects will use only 2-4 of these tokens, with the majority set to `false`. -Customize [theme](#theme-tokens){:.token} font weight tokens in your project's theme settings with available [system](#system-tokens){:.token} font weight tokens. All typography-related settings are in `_uswds-theme-typography.scss`. +Customize [theme](#theme-tokens){:.token} font weight tokens in your project's theme settings with available [system](#system-tokens){:.token} font weight tokens. All typography-related settings can be found in [USWDS settings]({{ site.baseurl }}/documentation/settings/#typography-settings). <div class="site-table-wrapper overflow-hidden"> <table class="usa-table--borderless site-table-responsive width-full"> diff --git a/pages/design-tokens/typesetting/overview.md b/pages/design-tokens/typesetting/overview.md index f3a227bee..17d14c4b6 100644 --- a/pages/design-tokens/typesetting/overview.md +++ b/pages/design-tokens/typesetting/overview.md @@ -477,7 +477,7 @@ The individual design token sections go into this in more detail, but here's a s </div> ### Family, size, and line height together -The `typeset()` mixin outlined below accepts the tokens listed as well as a special `null` value. If either of the three properties get `null` instead of a token, the system will use a default value from `$uswds-theme-typography`: either `$theme-body-font-family`, `$theme-body-font-size`, or `$theme-body-line-height` depending on the property passed the `null` value. +The `typeset()` mixin allows you to set family, size, and line height all in one line. It accepts the tokens listed as well as a special `null` value. If either of the three properties get `null` instead of a token, the system will use a default value from [typography settings]({{ site.baseurl }}/documentation/settings/#typography-settings): either `$theme-body-font-family`, `$theme-body-font-size`, or `$theme-body-line-height` depending on the property passed the `null` value. We use the `typeset()` mixin on all our components to get the effect of default `<body>` element styling without having to explicitly style the `<body>` element. @@ -606,18 +606,23 @@ We use the `typeset()` mixin on all our components to get the effect of default </table> </div> + +See this example: + {:.margin-top-4} #### Example: Settings and typesetting ```scss -// in _uswds-theme-typography: - -$theme-respect-user-font-size: true; -$theme-font-type-sans: 'public-sans'; -$theme-font-role-ui: $theme-font-sans; -$theme-type-scale-sm: 5; -$theme-body-font-size: 'sm'; -$theme-body-line-height: 5; +// In your settings configuration: + +@use "uswds-core" with ( + $theme-respect-user-font-size: true, + $theme-font-type-sans: "public-sans", + $theme-font-role-ui: $theme-font-sans, + $theme-type-scale-sm: 5, + $theme-body-font-size: "sm", + $theme-body-line-height: 5 +); // in component code: diff --git a/pages/patterns/create-a-profile/gender-identity-and-sex.md b/pages/patterns/create-a-profile/gender-identity-and-sex.md index d6acf2803..53bc311f9 100644 --- a/pages/patterns/create-a-profile/gender-identity-and-sex.md +++ b/pages/patterns/create-a-profile/gender-identity-and-sex.md @@ -15,26 +15,29 @@ changelog: ### Background -Gender is a social construct. Gender identity is an expression of a user’s identity and is integral to their sense of self. Gendered experiences are complex and vary widely. +Services collect gender identity information to let individuals tell us who they are: how they should be identified and how they wish to interact with the world. Gendered experiences are complex and vary widely. Gender is a social construct and gender identity can be an integral expression of a person's sense of self. -Sex assigned at birth is a biological attribute. In the digital space, male and female are often the only provided options, but there are instances where an individual’s biological sex is not unambiguously male or female. +Services collect sex information to match documents for identity proofing purposes, on certain statistical surveys, and to provide biological information in a clinical context. “Sex listed at birth” or “sex assigned at birth” is what it says on a person's original birth certificate. “Legal sex” is what it says on any qualifying legal document. “Non-binary” is typically used when referring to gender identity, but many states now allow terms like `non-binary`, `X`, or `unspecified` on birth certificates. -Historically, the federal government has asked people to choose between male and female based on the sex they were assigned at birth. Recently, agencies and programs have been moving toward providing more options, reflecting the fact that biological sex is not always unambiguously male or female, and that an individual’s gender identity may not reflect the sex they were assigned at birth. +While the sex listed on a person's birth certificate or driver's license is often used as part of validating their identity, gender identity is generally more important for ensuring respectful and inclusive policies, interactions, and communication. -In April 2022, the U.S. Department of State began allowing people to specify “X,” along with “male” or “female” on their passports. (Note: “non-binary” is generally used only when referring to gender identity. It is being used by the Department of State’s changes in their recording of sex, defining `X` as `Unspecified or another gender identity` including non-binary, intersex, and gender non-conforming individuals.) While sex listed at birth is often used as part of validating identity, gender identity is generally more important for ensuring respectful communication. +Historically, the federal government has asked people to choose between male and female. Recently, agencies and programs have been moving toward providing more options, reflecting the fact that a person's gender identity may not reflect the sex they were assigned at birth, and that sex is not always unambiguously male or female. -The White House's [Office of Management and Budget](https://www.whitehouse.gov/omb/), [Federal Committee on Statistical Methodology](https://www.fcsm.gov/) interagency committee, and [Centers for Disease Control and Prevention](https://www.cdc.gov/) are just some of the federal agencies and programs working to define a meaningful, inclusive way to collect gender identity and sex information when it is needed. We were especially interested in the way CDC's [HIV Nexus Clinician Resources](https://www.cdc.gov/hiv/clinicians/transforming-health/health-care-providers/collecting-sexual-orientation.html) articulates the importance of asking two separate questions to ensure healthcare providers can provide patient-centered, high quality care: `current gender identity`, and `sex listed at birth`. +As one example, in April 2022, the U.S. Department of State updated [Form DS-11](https://eforms.state.gov/Forms/ds11.pdf) and began allowing people to self-attest and specify `M` (male), `F` (female), or `X` on their passports. The Department of State defines `X` as “Unspecified or another gender identity” on Form DS-11. The form collects this information as `Gender` but it is displayed on a passport as `Sex`. More recently, [Executive Order 14075](https://www.whitehouse.gov/briefing-room/presidential-actions/2022/06/15/executive-order-on-advancing-equality-for-lesbian-gay-bisexual-transgender-queer-and-intersex-individuals/) Advancing Equality for Lesbian, Gay, Bisexual, Transgender, Queer, and Intersex Individuals makes specific calls for improved, responsible collection of sexual orientation and gender identity information. -This is an evolving space, and language recommendations are also evolving. In this pattern we've used the term `gender identity` to capture the way a person wishes to be represented, vs. gender as a construct. We've also used the term `sex` vs. `biological sex`, `sex assigned at birth`, or `sex listed at birth`. This term, in particular, should be evaluated for your specific program needs. +The White House's [Office of Management and Budget](https://www.whitehouse.gov/omb/), [Federal Committee on Statistical Methodology](https://www.fcsm.gov/) interagency committee, and [Centers for Disease Control and Prevention](https://www.cdc.gov/) are just some of the federal agencies and programs working to define a meaningful, inclusive way to collect gender identity and sex information when it is needed. We were especially interested in the way CDC's [HIV Nexus Clinician Resources](https://www.cdc.gov/hiv/clinicians/transforming-health/health-care-providers/collecting-sexual-orientation.html) articulates the importance of asking two separate questions to ensure healthcare providers can provide patient-centered, high quality care: `current gender identity`, and `sex listed at birth`. A multi-question approach is also advocated for in [Recommendations on the best practices for the collection of +sexual orientation and gender identity data on federal statistical surveys](https://www.whitehouse.gov/wp-content/uploads/2023/01/SOGI-Best-Practices.pdf) released in January 2023. + +This is an evolving space, and language recommendations are also evolving. In this pattern we've used the term `gender identity` to capture the way a person wishes to be represented, vs. gender as a construct. We've also used the term `sex`. For specific use cases, a more specific label may be correct, like `Sex listed at birth` or `Legal sex`. This language, in particular, should be evaluated for your specific program needs. ### What problems do these patterns solve? -Gender and sex are often used synonymously. Many users struggle to provide gender information that best represents them. An overwhelming number of choices for gender identity can be as alienating as too limited a set of provided options. +Gender and sex are often used synonymously. Many users struggle to provide gender identity information that best represents them. An overwhelming number of choices for gender identity can be as alienating as too limited a set of provided options. {:.site-component-name#gender-identity-section} ## Gender identity ### When to use this pattern -Follow this pattern when you are collecting gender identity for your service or program. Only ask for gender if you need it. Sometimes it’s more prudent to skip collecting this information altogether. +Follow this pattern when you are collecting gender identity for your service or program. Only ask for gender identity if you need it. Sometimes it’s more prudent to skip collecting this information altogether. ### What's the solution? Present the user with the tools to accurately depict their gender identity. @@ -52,11 +55,16 @@ Present the user with the tools to accurately depict their gender identity. </h4> <div class="do-dont__content"> <ul> + <li>Do collect gender identity data when you are collecting other general demographic information like race, ethnicity, or disability status.</li> <li>Do support long text fields for gender identity. The language behind gender identity is constantly evolving.</li> + <li>Do include a "prefer not to answer" option.</li> <li>Do consider safety implications of the information provided. Regional and state laws are highly variable and may not adequately protect individuals from disclosure.</li> + <li>Do provide helper text that explains why you are asking for this data and who it will be shared with.</li> <li>Do be transparent about what you are asking for (for example, gender identity or sex).</li> <li>Do use inclusive language. Consider using “they” or “you” instead of “he” or “she.”</li> <li>Do use clear hint text to help users understand what type of information should be provided.</li> + <li>When collecting both gender identity and sex, gender identity should precede sex.</li> + <li>Use tested translations for labels and hint text when delivering multilingual surveys or forms.</li> </ul> </div> </div> @@ -73,7 +81,8 @@ Present the user with the tools to accurately depict their gender identity. <ul> <li>Do not assume gender identity based on sex.</li> <li>Do not use <code>other</code> as a gender option. Instead use an open-ended text field.</li> - <li>Do not limit the user's choice of gender. Not everyone will fit into a specific classification determined by the form designer.</li> + <li>Do not limit the user's choice of gender identity. Not everyone will fit into a specific classification determined by the form designer.</li> + <li>Do not combine gender identity and sex into a single question.</li> </ul> </div> </div> @@ -84,29 +93,29 @@ Present the user with the tools to accurately depict their gender identity. <div class="usa-accordion usa-accordion--bordered site-accordion-code site-component-preview margin-top-2"> <button class="usa-accordion__button" aria-controls="accordion-preview-02" aria-expanded="true"><h4 id="pattern-preview-gender">Pattern preview</h4></button> <div id="accordion-preview-02" class="usa-accordion__content"> - {% include patterns/gender.html %} + {% include patterns/gender-identity.html %} </div> </div> <div class="usa-accordion usa-accordion--bordered site-accordion-code site-component-preview"> <button class="usa-accordion__button" aria-controls="accordion-code-02" aria-expanded="false"><h4 id="pattern-code-gender">Pattern code</h4></button> <div id="accordion-code-02" class="usa-accordion__content highlight-code"> <div class="usa-sr-only"> - {% highlight text%}{% include patterns/gender.html %}{% endhighlight %} + {% highlight text%}{% include patterns/gender-identity.html %}{% endhighlight %} </div> - {% highlight html%}{% include patterns/gender.html %}{% endhighlight %} + {% highlight html%}{% include patterns/gender-identity.html %}{% endhighlight %} </div> </div> #### Considerations {:.usa-content-list} -- <strong>Confirm you need this information.</strong> As with all personal information, consider whether you need to collect it at all. Clearly explain the reason for asking for the information and what will be done to secure the user’s privacy. -- <strong>Avoid using a controlled vocabulary.</strong> If you don’t need to enforce a controlled vocabulary of gender options, strongly consider letting the user self-identify using a single text field. +- <strong>Confirm you need this information.</strong> As with all personal information, consider whether you need to collect it at all. Clearly explain the reason for asking for the information and what will be done to secure the user’s privacy and safety. +- <strong>Avoid using a controlled vocabulary.</strong> If you don’t need to enforce a controlled vocabulary of gender identity options, strongly consider letting the user self-identify using a single text field. #### Usability guidance {:.usa-content-list} -- <strong>Provide clear hint text.</strong> Some users may be unfamiliar with this question and unsure how to answer. Provide clear hint text, such as, "For example, man, woman, non-binary). Do allow users to opt out with a "Prefer not to answer" option. +- <strong>Provide clear hint text.</strong> Some users may be unfamiliar with this question and unsure how to answer. Provide clear hint text, such as, "For example, man, woman, non-binary." Do allow users to opt out with a "Prefer not to answer" option. - This pattern uses checkboxes. See [usability guidance for checkboxes]({{ site.baseurl }}/components/checkbox/#usability-guidance-checkbox). #### Accessibility @@ -121,10 +130,10 @@ Present the user with the tools to accurately depict their gender identity. ## Sex ### When to use this pattern -Follow this pattern when you are collecting sex listed at birth as part of your service. Only ask for this information if you need it. Sometimes it’s more prudent to skip collecting this information altogether. +Services collect sex information to match documents for identity proofing purposes, on certain statistical surveys, and to provide biological information in a clinical context. Only ask for this information if you need it. Even for identity proofing, sex data is not always needed. Asking for gender identity instead of sex is generally more important for ensuring respectful communication. ### What's the solution? -Present the user with a controlled vocabulary to accurately depict sex listed at birth. +Know what information you need and ask for it with specificity. If you are collecting sex information to match documents for identity proofing, be clear about whether you need the sex marker listed on an original birth certificate (“Sex listed at birth”) or the sex marker listed on any qualifying legal document (“Legal sex”). {:.site-component-section-title} ### Guidance @@ -139,11 +148,12 @@ Present the user with a controlled vocabulary to accurately depict sex listed at </h4> <div class="do-dont__content"> <ul> - <li>Do determine if you need to collect sex listed at birth and only use if the information is essential to the user's experience.</li> - <li>Do provide a controlled vocabulary when asking for sex listed at birth (<code>male</code>, <code>female</code>, and <code>X</code>). </li> - <li>Do be clear about why you are asking for the information.</li> - <li>Do be transparent about what you are asking for. To some people gender and sex are synonymous, so ensure you use clear language.</li> + <li>Do determine if you need to collect sex data and only use if the information is essential to the user's experience. Services collect sex information to match documents for identity proofing purposes, on certain statistical surveys, or to provide biological information in a clinical context.</li> + <li>Do provide a controlled vocabulary when asking for sex listed at birth or legal sex (<code>Male</code>, <code>Female</code>, and <code>X</code>). Use helper text to explain that <code>X</code> should be used for any marker that is neither male nor female.</li> + <li>Do provide helper text that explains why you are asking for this data and who it will be shared with.</li> + <li>Do be transparent about what you are asking for. To some people gender and sex are synonymous, so use clear language.</li> <li>Do use fieldset and legend to group related radio buttons together, and clear labels and attributes on these form elements.</li> + <li>When collecting both gender identity and sex, gender identity should precede sex.</li> </ul> </div> </div> @@ -159,7 +169,7 @@ Present the user with a controlled vocabulary to accurately depict sex listed at <div class="do-dont__content"> <ul> <li>Do not assume gender identity based on the user's sex.</li> - <li>Do not include "prefer not to answer." If you are considering adding this option, then consider whether the question is needed at all.</li> + <li>Do not include “prefer not to answer.” If you are considering adding this option, then consider whether the question is needed at all.</li> <li>Do not combine gender identity and sex into a single question.</li> </ul> </div> @@ -169,26 +179,26 @@ Present the user with a controlled vocabulary to accurately depict sex listed at </div> <div class="usa-accordion usa-accordion--bordered site-accordion-code site-component-preview margin-top-2"> - <button class="usa-accordion__button" aria-controls="accordion-preview-01" aria-expanded="true"><h4 id="pattern-preview-biological-sex">Pattern preview</h4></button> + <button class="usa-accordion__button" aria-controls="accordion-preview-01" aria-expanded="true"><h4 id="pattern-preview-sex">Pattern preview</h4></button> <div id="accordion-preview-01" class="usa-accordion__content"> - {% include patterns/biological-sex.html %} + {% include patterns/sex.html %} </div> </div> <div class="usa-accordion usa-accordion--bordered site-accordion-code site-component-preview"> - <button class="usa-accordion__button" aria-controls="accordion-code-01" aria-expanded="false"><h4 id="pattern-code-biological-sex">Pattern code</h4></button> + <button class="usa-accordion__button" aria-controls="accordion-code-01" aria-expanded="false"><h4 id="pattern-code-sex">Pattern code</h4></button> <div id="accordion-code-01" class="usa-accordion__content"> <div class="usa-sr-only"> - {% highlight text%}{% include patterns/biological-sex.html %}{% endhighlight %} + {% highlight text%}{% include patterns/sex.html %}{% endhighlight %} </div> - {% highlight html%}{% include patterns/biological-sex.html %}{% endhighlight %} + {% highlight html%}{% include patterns/sex.html %}{% endhighlight %} </div> </div> #### Considerations {:.usa-content-list} -- <strong>Confirm you need this information.</strong> As with all personal information, consider whether you need to collect it at all. Clearly explain the reason for asking for the information and what will be done to secure the user’s privacy. -- <strong>Be specific about the information you are requesting.</strong> Clearly state the context, such as, "Please enter your sex as it appears on your birth certificate." so that users can successfully provide the information required. Because gender and sex are often used synonymously, users have difficulty determining which information is being requested. +- <strong>Confirm you need this information.</strong> As with all personal information, consider whether you need to collect it at all. Clearly explain the reason for asking for the information and what will be done to secure the user’s privacy and safety. +- <strong>Be specific about the information you are requesting.</strong> Clearly state the context, such as, “Please enter the sex that appears on your driver's license, state ID, passport, or passport card.” so that users can successfully provide the information required. #### Accessibility @@ -218,12 +228,15 @@ Present the user with a controlled vocabulary to accurately depict sex listed at - Federal Interagency Working Group on Improving Measurement of Sexual Orientation and Gender Identity in Federal Surveys (IWG). Why Do Federal Agencies Ask About Sexual Orientation and Gender Identity (SOGI) on Surveys? FCSM-21-01. (June 2021) Retrieved on October 31, 2022, from [https://www.fcsm.gov/assets/files/docs/FCSM%2021%2001%20062221.pdf](https://www.fcsm.gov/assets/files/docs/FCSM%2021%2001%20062221.pdf) - Gender or sex. (n.d.) Retrieved on July 15, 2022 from [https://design-system.service.gov.uk/patterns/gender-or-sex/](https://design-system.service.gov.uk/patterns/gender-or-sex/) - Gender terms you may not know. (June 17, 2022) Retrieved on July 15, 2022, from [https://www.dictionary.com/e/gender-terms-you-may-not-know/](https://www.dictionary.com/e/gender-terms-you-may-not-know/) +- ID documents center. (November 2021) Retrieved on December 9, 2022, from [https://transequality.org/documents](https://transequality.org/documents) - Interagency Technical Working Group on Sexual Orientation and Gender Identity Items in the Household Pulse Survey: Report and Recommendations. (May 25, 2021) Retrieved on October 31, 2022, from [https://omb.report/icr/202106-0607-003/doc/112605500](https://omb.report/icr/202106-0607-003/doc/112605500) - Nonbinary airline passenger tickets. (June 22, 2022) Retrieved on July 15, 2022, from [https://www.nytimes.com/2022/06/22/travel/nonbinary-airline-passengers-tickets.html](https://www.nytimes.com/2022/06/22/travel/nonbinary-airline-passengers-tickets.html) - Patient centered care for transgender people: recommended practices for health care settings. (n.d.) Retrieved on November 4, 2022, from [https://www.cdc.gov/hiv/clinicians/transforming-health/health-care-providers/affirmative-care.html](https://www.cdc.gov/hiv/clinicians/transforming-health/health-care-providers/affirmative-care.html) +- Recommendations on the best practices for the collection of +sexual orientation and gender identity data on federal statistical surveys. (January 2023) Retrieved on January 27, 2023, from [https://www.whitehouse.gov/wp-content/uploads/2023/01/SOGI-Best-Practices.pdf](https://www.whitehouse.gov/wp-content/uploads/2023/01/SOGI-Best-Practices.pdf) - Social Security implements self-attestation of sex marker in Social Security Number records. (October 19, 2022) Retrieved on October 24, 2022, from [https://www.ssa.gov/news/press/releases/2022/#10-2022-3](https://www.ssa.gov/news/press/releases/2022/#10-2022-3) - X gender marker available on U.S. Passports starting April 11. (March 31, 2022) Retrieved on July 20, 2022, from [https://www.state.gov/x-gender-marker-available-on-u-s-passports-starting-april-11/](https://www.state.gov/x-gender-marker-available-on-u-s-passports-starting-april-11/) {:.site-component-section-title} ## Disclaimer -Links to nongovernment sources are made for educational or source citation purposes only, and do not represent an endorsement of the organizations by the General Services Administration. The General Services Administration does not assume any responsibility for the content, operation, or policies of other entities' websites. \ No newline at end of file +Links to nongovernment sources are made for educational or source citation purposes only, and do not represent an endorsement of the organizations by the General Services Administration. The General Services Administration does not assume any responsibility for the content, operation, or policies of other entities' websites.