About
Release notes
USWDS is an ever-evolving product. We’ve been listening to your feedback and using it as a basis for improvements and additions.
Here you’ll find our release notes — summaries of bug fixes, new features, and other updates introduced in each release.
Have suggestions for a new feature or bug fix? Open an issue in our repo.
Version USWDS 3.6.0
August 23, 2023
# What's new in USWDS 3.6.0
## Features
Package | A11y | Breaking | Description
:-- | :-- | :-- | :--
`usa-in-page-navigation` | No | No | **Updated JavaScript to exclude hidden headers from the in-page navigation link list.** Any header with a style of `display:none` or `visibility:hidden` will now be excluded from the list of links in the component. (https://github.com/uswds/uswds/pull/5393)
`usa-in-page-navigation` | No | No | **Added the optional `data-main-content-selector` attribute to the in-page navigation component.** This attribute allows users to designate which element they want the component to pull headers from. If the attribute is not defined, the component will pull headers from the `<main>` element. (https://github.com/uswds/uswds/pull/5387)
`usa-select` | No | No | **Added ellipses to overflow text in the multiple variant of the select component.** This provides a clear indication to users that there is text that extends beyond the select width. (https://github.com/uswds/uswds/pull/5268)
## Bug fixes
Package | A11y | Breaking | Description
:-- | :-- | :-- | :--
`usa-button`, `usa-checkbox`, `usa-combo-box`, `usa-file-input`, `usa-input`, `uswds-core` | Yes | Yes | **Updated default disabled color settings values.** This change also fixed configuration errors with disabled color settings, added `$theme-color-disabled-lighter` and `$theme-color-disabled-darker` settings, and added `disabled-lighter` and `disabled-darker` tokens. <br/><br/>⚠️ The names and values of disabled settings and tokens have changed and will need to be updated if they are customized in your project. See the "Breaking changes" section below for more details. (https://github.com/uswds/uswds/pull/5402)
`usa-pagination` | Yes | Potentially | **Updated the ellipsis color to meet color contrast requirements.** Additionally, this change updated styles to respect the value added to `$theme-pagination-background-color`. Users should confirm that project pagination colors display as expected. (https://github.com/uswds/uswds/pull/5358)
`usa-card`, `uswds-core` | No | No | **Fixed a bug that prevented `$theme-card-border-width` from accepting `0` or string tokens.** (https://github.com/uswds/uswds/pull/5325)
`usa-combo-box`, `usa-input`, `usa-input-prefix-suffix`, `usa-range`, `usa-select`, `usa-textarea`, `uswds-core` | Yes | No | **Fixed a bug that caused standard text input variants to show disabled styles in forced colors mode.** Now the disabled border color only shows when the element is disabled. (https://github.com/uswds/uswds/pull/5397)
`usa-icon-list` | No | No | **Updated icon list styles to allow `$theme-body-font-size` to accept `2xs` and `3xs` size tokens.** (https://github.com/uswds/uswds/pull/5363)
`usa-input-mask` | Yes | No | **Fixed a bug in input mask that caused the hover state to show disabled styling.** This change also improved the legibility of the component in forced colors mode. (https://github.com/uswds/uswds/pull/5378)
`usa-memorable-date` | Yes | No | **Updated memorable date styles to allow elements to wrap to multiple lines at narrow browser widths.** (https://github.com/uswds/uswds/pull/5372)
`uswds-utilities` | No | No | **Fixed a bug that caused `font-[family]-[size]` utility classes to not generate font-family rules.** (https://github.com/uswds/uswds/pull/5388)
## Breaking changes
> [!WARNING]
> **Disabled theme settings.** This release updates USWDS disabled color settings and tokens to conform to our standard naming convention. If your project configures disabled color settings or uses disabled color tokens, you probably need to update your code. Here is a table showing how we reassigned disabled color values:
>
> Default value | Previously assigned to: | Now assigned to:
> -- | -- | --
> "gray-20" | $theme-color-disabled | $theme-color-disabled-lighter
> "gray-40" | $theme-color-disabled-text-reverse | $theme-color-disabled-light
> "gray-50" | $theme-color-disabled-text | $theme-color-disabled
> "gray-70" | $theme-color-text-on-disabled | $theme-color-disabled-dark
>
> All references to the previous settings have been replaced with references to their corresponding new settings. This means that if you previously customized `$theme-color-disabled`, you should now instead assign that custom value to `$theme-color-disabled-lighter`. Additionally, all references to the `“disabled”` color token in your Sass should now be replaced with `“disabled-lighter”`.
>
> Please note that all disabled states are now expected to meet minimum color contrast requirements for text (4.5:1). If you have customized any of the disabled color values, please confirm that your disabled elements meet these contrast standards.
## Dependencies and security
| Dependency name | Previous version | New version |
| :---------------------------- | :--------------: | :---------: |
| @18f/identity-stylelint-config | 1.0.0 | 2.0.0 |
| postcss | 8.4.0 | 8.4.19 |
| stylelint | 14.13.0 | 15.10.1 |
---
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install @uswds/uswds`)
`4 moderate, 29 high` vulnerabilities in devDependencies (development dependencies)
---
**Release TGZ SHA-256 hash:** `a6c303c350063a1f42baa0de8f1c860d91b06fd85f330b947209a8886f0e290a`
Version USWDS 3.5.0
June 09, 2023
# What's new in USWDS 3.5.0
## Features
Package | A11y | Breaking | Description
--- | --- | --- | ---
`usa-button`, `usa-dark-background`, `uswds-core` | — | — | **Stopped using font smoothing.** No longer use font smoothing for dark backgrounds and disabled buttons. (https://github.com/uswds/uswds/pull/5250)
`usa-button`, `usa-checkbox`, `usa-date-picker`, `usa-pagination`, `usa-radio`, `usa-range`, `usa-search`, `uswds-core` | Yes | — | **Improved legibility of buttons in forced colors mode.** Added a consistent border in forced colors mode. (https://github.com/uswds/uswds/pull/5147)
`usa-button`, `usa-checkbox`, `usa-combo-box`, `usa-date-picker`, `usa-date-range-picker`, `usa-file-input`, `usa-input`, `usa-input-mask`, `usa-input-prefix-suffix`, `usa-radio`, `usa-range`, `usa-select`, `usa-textarea`, `uswds-core` | Yes | — | **Improved consistency of disabled styles in forced colors mode.** (https://github.com/uswds/uswds/pull/5295)
`usa-button`, `usa-checkbox`, `usa-combo-box`, `usa-date-picker`, `usa-date-range-picker`, `usa-file-input`, `usa-input`, `usa-input-prefix-suffix`, `usa-radio`, `usa-range`, `usa-select`, `usa-textarea`, `usa-time-picker`, `uswds-core` | Yes | — | **Improved consistency and visibility of disabled styles.** Disabled form inputs now use a consistent gray background. (https://github.com/uswds/uswds/pull/5063)<br/><br/>:warning: We don't consider this a breaking change, but teams should check disabled form elements to assure that the new styles are working in their layouts.
`usa-link`, `uswds-core` | Yes | — | **Labeled external links for screen readers.** Added a label for screen readers that identifies external links and if they open in a new tab. (https://github.com/uswds/uswds/pull/5166)
`uswds-core` | Yes | — | **Added settings for announcing external links.** Added `$theme-external-link-sr-label-tab-same` and `$theme-external-link-sr-label-tab-new` to control how screen readers announce external links. (https://github.com/uswds/uswds/pull/5166)
`usa-content`, `usa-paragraph`, `usa-prose`, `uswds-core` | — | Yes | **Removed `usa-prose-` mixins and placeholders from Sass.** Users should instead use `typeset-` mixins in their place. This is a breaking change only if your project Sass uses `usa-prose-` mixins and placeholders. It does not affect the look of any `usa-prose`–styled element.(https://github.com/uswds/uswds/pull/5158)
`uswds-core` | — | — | **Added `$theme-heading-margin-top` and `$theme-paragraph-margin-top` system variables.** (https://github.com/uswds/uswds/pull/5158)
`uswds-core` | — | Yes | **Updated individual Sass map settings without affecting defaults.** Now adjusting a single Sass map setting will no longer set all other values in the map to `false`. Users can now update only the map values they wish to change. This is a breaking change only if your project deactivated mapped settings by not declaring them. (https://github.com/uswds/uswds/pull/5216)
`usa-accordion`, `usa-banner`, `usa-nav`, `uswds-core` | — | — | **Added two new settings to customize accordion background colors.** You can now customize accordion button and content background colors with `$theme-accordion-button-background-color` and `$theme-accordion-background-color`. (https://github.com/uswds/uswds/pull/5269)
## Bug fixes
Package | A11y | Breaking | Description
--- | --- | --- | ---
`usa-header` | — | — | **Removed the `id` attribute from the `usa-logo` element.** (https://github.com/uswds/uswds/pull/5319)
`usa-header` | — | — | **Fixed a bug that caused inaccurate megamenu template markup.** The markup in megamenu code examples now accurately includes the `usa-megamenu` class. (https://github.com/uswds/uswds/pull/5311)
`usa-table` | Yes | — | **Fixed a typo in the sortable table JavaScript that caused the aria-label in table headers to have an unnecessary single quote.** (https://github.com/uswds/uswds/pull/5280)
`uswds-core`, `uswds-utilities` | — | — | **Removed unused utility builder comments from compiled CSS.** This update significantly reduces the compiled file size. (https://github.com/uswds/uswds/pull/5209)
`usa-tooltip` | — | — | **Fixed a bug that removed default positioning.** If the `data-position` attribute is not specified, the tooltip position will now default to "top". (https://github.com/uswds/uswds/pull/5228)
`usa-in-page-navigation` | — | — | **Fixed a bug that prevented links that start with a number from scrolling when clicked.** (https://github.com/uswds/uswds/pull/5200)
`usa-alert` | — | — | **Removed redundant and invalid height declaration.** (https://github.com/uswds/uswds/pull/5187)
`usa-button` | Yes | — | **Fixed a bug that caused button `type` attribute to render empty.** (https://github.com/uswds/uswds/pull/5247)
`usa-button` | Yes | — | **Added spacebar trigger to links styled as buttons.** Now any item that looks like a button will trigger with the spacebar, even if the element is a link. (https://github.com/uswds/uswds/pull/4385)
`usa-card` | Yes | Yes | **Replaced `button` elements with links styled as buttons.**<br/><br/>:warning: This is marked as a breaking change because it changes the recommended card component markup to include `<a href="#" class="usa-button"></a>` for the call to action instead of a `button` element. (https://github.com/uswds/uswds/pull/4385)
`usa-pagination` | Yes | Yes | **Improved accessible markup of overflow ellipses.** We replaced the `role="presentation"` with `aria-label="ellipsis indicating non-visible pages"` for `usa-pagination__overflow` items to better conform to WCAG 2.0 and 2.1.<br/><br/>:warning: This is marked as a breaking change because it changes the recommended component markup. In the `usa-pagination__overflow` element, use `aria-label="ellipsis indicating non-visible pages"` instead of `role="presentation"`. (https://github.com/uswds/uswds/pull/5197)
`usa-file-input` | — | — | **Fixed an issue with large file previews.** Now adding large files no longer results in an infinite spinner. Adding large files should now result in an accurate preview. (https://github.com/uswds/uswds/pull/5114)
`usa-file-input` | Yes | — | **Improved the file input experience for voice command and screen reader users.** Voice command users can now interact with the component by speaking the visible instructions text. Additionally, screen reader users now have access to both the instructions text and the file selection status. (https://github.com/uswds/uswds/pull/5213)
`usa-combo-box` | Yes | — | **Improved consistency of keyboard actions.** Users can now to use <kbd>Tab</kbd> to escape the Combo box selection without making a choice, and <kbd>Space</kbd> to select the current highlighted option when within the dropdown menu. (https://github.com/uswds/uswds/pull/5160)
`usa-accordion`, `usa-banner`, `usa-nav` | Yes | — | **Adjusted forced colors mode styles to ensure visibility and increase consistency.** Forced colors mode styles will now override the background color and display the button outline. The open/close icons now dynamically adjust to `ButtonText` colors. (https://github.com/uswds/uswds/pull/5286)
`usa-identifier` | — | Yes | **Updated Accessibility statement link text.** Updated the identifier to use the text "Accessibility statement" (EN) / "Declaración de accesibilidad" (ES) for the required link to an accessibility statement.<br/><br/>:warning: This is a breaking change because it changes the content of the identifier. Earlier versions of the identifier will continue to work as expected. (https://github.com/uswds/uswds/pull/5278)
Guidance | Yes | — | **Updated guidance to suggest identifying required and optional fields.** We added a new section on identifying required fields and now suggest labeling required fields with a red asterisk and optional fields with the word optional. (https://github.com/uswds/uswds-site/pull/1834)
## Dependencies and security
| Dependency name | Previous version | New version |
| ---------------------------- | :--------------: | :---------: |
| @chanzuckerberg/axe-storybook-testing | 5.0.1 | 6.3.0 |
| axe-core | 4.3.4 | 4.6.3 |
| extract-loader | 5.1.0 | — |
| webpack | 5.58.1 | 5.76.0 |
---
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install @uswds/uswds`)
`1 moderate 29 high` vulnerabilities in devDependencies (development dependencies)
---
**Release TGZ SHA-256 hash:** `e0dbab25bffaaf02b3b7317690939d9e0e63bc5c824046e778de8f4c15227a9c`
Version USWDS 2.14.0
April 07, 2023
# Long-term archive of Version 2
As we noted when we released Version 3.0, [we will support Version 2 through May 2023](https://designsystem.digital.gov/documentation/developers/#long-term-support-of-v2x). As a part of our long-term archive support for Version 2.x, we're releasing USWDS 2.14.0. This release has no functional changes, but it strips all nonessential development dependencies from the codebase. This will allow both the design system and long-term users of 2.x to treat this and any subsequent 2.x release as a long-term archival release, with a limited security vulnerability footprint.
If you use USWDS 2.13.3 and will not be upgrading to 3.0, consider updating to USWDS 2.14.0.
## Details
This release removes all dependencies, except those required to build and release. There were no vulnerabilities in the standard dependencies, but there were critical vulnerabilities in a few development dependencies:
- Component library
- `@frctl/fractal`
- `@frctl/mandelbrot`
- `@frctl/nunjucks`
- Testing
- `mocha`
- `gulp-spawn-mocha`
- Compiling
- `nswatch`: Legacy watch task, wasn't used.
- `gulp-svg-sprite`: Added compiled SVG to repo.
- `handlebars` and `handlebars-helpers`: Used in generating formatted tokens
in SASS
We removed all these dependencies and committed any necessary static assets to the package. We've committed an archival version of the Fractal site in GitHub, but it is not included in the package.
Finally, we added an `overrides` field to `package.json` to handle the last remaining vulnerability in `gulp`.
## Security and dependencies
- 37 total dependency changes
- 19 dependencies removed
| Dependency name | Previous version | New version |
| ---------------------------- | :--------------: | :---------: |
| classlist-polyfill | 1.0.3 | 1.2.0 |
| @babel/preset-env | 7.15.8 | 7.20.2 |
| @frctl/fractal | 1.5.11 | - |
| @frctl/mandelbrot | 1.10.1 | - |
| @frctl/nunjucks | 2.0.13 | - |
| @types/node | 16.11.6 | 18.15.5 |
| ansi-colors | 4.1.1 | 4.1.3 |
| autoprefixer | 10.3.7 | 10.4.14 |
| axe-core | 4.3.4 | - |
| chrome-launcher | 0.15.0 | - |
| chrome-remote-interface | 0.31.0 | - |
| eslint | 8.4.1 | 8.36.0 |
| eslint-config-prettier | 8.3.0 | 8.8.0 |
| eslint-plugin-import | 2.52.2 | 2.27.5 |
| eslint-plugin-no-unsanitized | 4.0.1 | 4.0.2 |
| glob-parent ― **Note:** added via NPM `overrides` | - | 6.0.2 (last updated 2 years ago) |
| gulp-replace | 1.1.1 | 1.1.4 |
| gulp-spawn-mocha | 6.0.0 | - |
| gulp-svg-sprite | 1.5.0 | - |
| handlebars | 4.7.7 | - |
| handlebars-helpers | 0.10.0 | - |
| jsdom | 19.0.0 | - |
| jsdom-global | 3.0.2 | - |
| mocha | 6.2.3 | - |
| node-notifier | 10.0.0 | 10.0.1 |
| nswatch | 0.2.0 | - |
| nyc | 15.1.0 | - |
| postcss | 8.3.11 | 8.4.21 |
| postcss-csso | 6.0.0 | 6.0.1 |
| prettier | 2.4.1 | 2.8.6 |
| resemblejs | 4.0.0 | - |
| sass | 1.43.4 | 1.59.3 |
| sass-true | 6.0.1 | - |
| sinon | 12.0.1 | - |
| snyk | 1.746.0 | 1.1123.0 |
| stylelint | 14.1.0 | 14.9.1 |
| typescript | 4.4.4 | 5.0.2 |
| yargs | 17.2.1 | - |
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with npm install uswds) from `npm audit`
Internal only: `0` vulnerabilities in devDependencies (development dependencies) from `npm audit`
Release ZIP SHA-256 hash: `8fb2fc84bcb73f3e7155fcacd35b2f96ae3be872716a91118b69991c6e0bb44b`
Version USWDS 3.4.1
March 13, 2023
# What's new in USWDS 3.4.1
There were a couple features and bug fixes that we intended to include in USWDS 3.4.0, but inadvertently omitted from that release.
## Features and bug fixes
Type | Package | A11y | Breaking | Description
--- | --- | --- | --- | ---
Feature | `usa-in-page-navigation` | — | — | **Update the URL in the address bar when navigating from the In-Page Navigation.** Now users can see the proper anchor link in the address bar when navigating. Thanks @aduth! (https://github.com/uswds/uswds/pull/5068)
Bug | `usa-form` | — | — | **Fixed invisible link text for links styled as buttons within forms.** Now link text does not match the primary button color when nested inside of a form and the `usa-button` class is present. (https://github.com/uswds/uswds/pull/5112)
Bug | `usa-header` | — | — | **Logo text width setting now works as expected.** Now the design system respects the value passed to `$theme-header-logo-text-width`. Thanks @RSD-accessboard! (https://github.com/uswds/uswds/pull/5008)
## Dependencies and security
_No dependency changes_
---
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`1 moderate 33 high` vulnerabilities in devDependencies (development dependencies)
**Release TGZ SHA-256 hash:** `af1cd42c60b73fbbfa9c27b8ee52fb735b1a2234c6b3aa17de5bbf8a9190ca62`
Version USWDS 3.4.0
March 09, 2023
# What’s new in USWDS 3.4.0
## Features and bug fixes
Type | Package | A11y | Breaking | Description
--- | --- | --- | --- | ---
Feature | `usa-banner` | — | — | **Remove grid dependency from Banner package.** Now you no longer need to use the `usa-layout-grid` package with `usa-banner` resulting in a much smaller package size. (https://github.com/uswds/uswds/pull/5000)
Feature | `uswds-core` | — | Maybe | **Output only the modern woff2 font format, unless you need compatibility.** Now we output _only_ the `woff2` webfont format with our default settings. Since we no longer support IE11 and other old browsers, we no longer need to serve the `woff` and `ttf` formats. Teams that need this support can activate it with a new setting: `$theme-font-browser-compatibility: true`. _This is only a breaking change if your project needs to support IE11._ (https://github.com/uswds/uswds/pull/5108)
Feature | `usa-header` | — | — | **Allow full-page width for the header.** You can now set a value of `"none"` for any `max-width` setting, including `$theme-header-max-width.` (https://github.com/uswds/uswds/pull/5072)
Feature | `usa-in-page-navigation` | — | — | **Update the URL in the address bar when navigating from the In-Page Navigation.** Now users can see the proper anchor link in the address bar when navigating. Thanks @aduth! (https://github.com/uswds/uswds/pull/5068)
Bug fix | `usa-alert` `uswds-core` | — | — | **Set padding to any valid spacing token.** Now you can use valid values like `1.5` for `$theme-alert-padding-y`. Thanks @aduth! (https://github.com/uswds/uswds/pull/5076)
Bug fix | `usa-banner` | Yes | — | **Improved display of focus outline on mobile.** Now the focus outline is visible all around the banner on mobile devices. Thanks @jhancock532! (https://github.com/uswds/uswds/pull/5013)
Bug fix | `usa-footer` | Yes | — | **Use any heading level for the primary links header.** Now if you use any heading level for `.usa-footer__primary-link` without it reverting to an `h4` when the JavaScript rebuilds the element for mobile. Thanks @paulathevalley! (https://github.com/uswds/uswds/pull/5044)
Bug fix | `usa-header` | Yes | — | **Secondary nav is now read properly on screen readers.** The separator between nav elements is no longer read on screen readers. (https://github.com/uswds/uswds/pull/4963)
Bug fix | `usa-link` | — | — | **External link icons and link text now wrap as expected.** Now external links break over wrapped lines as expected in any browser. (https://github.com/uswds/uswds/pull/5046)
Bug fix | `usa-modal` | — | — | **Interactive form elements like Date Picker now work properly in a modal window.** Now any element in a modal should work as expected. (https://github.com/uswds/uswds/pull/5049)
Bug fix | `usa-step-indicator` | **Yes** | — | **More legible contrast on pending items.** Graphical elements related to pending items now meet accessibility standards for contrast ratio. (https://github.com/uswds/uswds/pull/5048)
Bug fix | `uswds-utilities` `uswds-core` | — | — | **Outline utility and mixin now accept the `05` token.** Now, the `.outline-05` utility class and the `u-outline('05')` mixin should work as expected. (https://github.com/uswds/uswds/pull/5079)
Content | — | — | — | **Improved copy in 404 template.** We updated the 404 page template copy to follow parallel structure and use active voice. Thanks @ybom for the Spanish translation! (https://github.com/uswds/uswds/pull/5045)
Guidance | — | — | — | **Expanded and improved our Gender Identity and Sex patterns.** We've made updates to our pattern guidance and our pattern previews to help provide more practical use cases and up-to-date guidance for these patterns. For more details, see https://github.com/uswds/uswds-site/pull/1994
## Dependencies and security
Dependency | Old version | New version
--- | --- | ---
`gulp-dart-scss` | 1.1.0 | Removed
`gulp-mocha` | — | 8.0.0
`mocha` | 6.2.3 | 10.2.0
`sass-embedded` | 1.53.0 | 1.58.3
`snyk` | 1.966.0 | 1.1064.0
---
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`1 moderate 33 high` vulnerabilities in devDependencies (development dependencies)
**Release TGZ SHA-256 hash:** `7b0336d95fa6e9f31b27a27424f3a53e84b415e09b5bbff5d9ec8a398fb406d7`
Version USWDS 3.3.0
November 14, 2022
# What’s new in USWDS 3.3.0
## New components
We have three new components (and component packages) in this release. Learn more about each of them on our website:
- **[In-page navigation](https://designsystem.digital.gov/components/in-page-navigation):** In-page navigation allows navigation to specific sections on a lengthy content page. Package name: `usa-in-page-navigation`
- **[Input mask](https://designsystem.digital.gov/components/input-mask):** An input mask is a string expression that constrains input to support valid input values. Package name: `usa-input-mask`
- **[Language selector](https://designsystem.digital.gov/components/language-selector):** A language selector helps users find and access content in the language of their choice. Package name: `usa-language-selector`
## Updated components
- **[Memorable date](https://designsystem.digital.gov/components/memorable-date):** Based on our usability research, we updated the memorable date component to include a dropdown `select` for month.
## Updated templates
We have four updated components in this release. Learn more about each of them on our website:
- **[Address template](https://designsystem.digital.gov/templates/form-templates/address-form/):** Based on our usability research, we've made the following changes:
- Replaced the `State, territory, or military post` combo box with a dropdown `select`.
- Replaced the `Unit type` combo box and the `Unit number` input field with a single `Street address line 2` input field.
- Added an optional `Urbanization` input field for addresses in Puerto Rico.
- **[Name](https://designsystem.digital.gov/templates/form-templates/name-form/):** Based on our usability research, we've made a number of changes to support a variety of name entry preferences. See the page on our website for more details.
These template and component updates are in support of our new [Patterns](https://designsystem.digital.gov/patterns/) guidance section. For more information on using our pattern guidance to support inclusive interactions, please see our [Inclusive Patterns Report](https://designsystem.digital.gov/together/) and the pattern guidance itself.
## Other updated packages
- `uswds-form-controls`: Added `usa-input-mask`.
- `uswds-components`: Added `usa-in-page-navigation`, `usa-input-mask`, and `usa-language-selector`
## Dependencies and security
_No package updates._
---
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`29 high` vulnerabilities in devDependencies (development dependencies)
**Release TGZ SHA-256 hash:** `01994f2a02cad085a0fabb9bb2a238b94e3e03f587e241348731063b80e4308c`
Version USWDS 3.2.0
October 19, 2022
# What's new in USWDS 3.2.0
This release contains markup changes and potentially breaking changes. A ⚠️ icon indicates where we've made a change that might be a breaking change for your project.
## Package updates
### usa-alert
Updated the alignment of the Alert and Site alert component content to visually match alignment with banner content. (#4922)
### usa-banner
We made a number of small changes to the banner to improve how screen readers read its content. None of these changes are breaking chances, but they are all improvements teams should make to their banner component. (#4925)
⚠️ **Updated the `aria-label` in English versions of usa-banner.** 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". Thanks @AmandaD-USDS! (#4925)
```diff
- <section class="usa-banner" aria-label="Official government website">
+ <section class="usa-banner" aria-label="Official website of the United States government">
```
```diff
- <div class="grid-col-fill tablet:grid-col-auto">
+ <div class="grid-col-fill tablet:grid-col-auto" aria-hidden="true">
<p class="usa-banner__header-text">An official website of the United States government</p>
- <p class="usa-banner__header-action" aria-hidden="true">Here’s how you know</p>
+ <p class="usa-banner__header-action">Here’s how you know</p>
```
⚠️ **Added `aria-hidden` attribute to the flag icon in the banner component.** The flag icon in the banner component is purely decorative and we can safely remove it from the screen reader readout. (#4925)
```diff
- <img class="usa-banner__header-flag" src="[your flag path]" alt="U.S. flag">
+ <img class="usa-banner__header-flag" aria-hidden="true" src="[your flag path]" alt="">
```
⚠️ **Simplified ARIA label in the lock SVG.** We simplified the way we're using `aria-labelledby` in the lock SVG to streamline screenreader vocalization. (#4925)
```diff
- <svg xmlns="http://www.w3.org/2000/svg" width="52" height="64" viewBox="0 0 52 64" class="usa-banner__lock-image" role="img" aria-labelledby="banner-lock-title banner-lock-description" focusable="false">
+ <svg xmlns="http://www.w3.org/2000/svg" width="52" height="64" viewBox="0 0 52 64" class="usa-banner__lock-image" role="img" aria-labelledby="banner-lock-description" focusable="false">
```
```diff
- <desc id="vUSWDS 3.2.0-banner-lock-description">A locked padlock</desc>
+ <desc id="vUSWDS 3.2.0-banner-lock-description">Locked padlock</desc>
```
### usa-character-count
**Improved screen reader experience.** The character counter now includes a brief pause after input before announcing how many characters remain. Announcing the input no longer prevents the character counter from reading. Thanks @davidc-gds! (#4976)
### usa-icon
**Fixed potential incompatibility with ARM-based Macs.** We updated our SVG sprite compiler. This should resolve potential dependency incompatibilities on computers with ARM processors. (#4665)
### usa-identifier
:warning: **Use valid element for identity's aria label.** We updated the identity section of the Identifier to use a `section` instead of a `div` so it's `aria-label` will apply to a valid element. (#4964)
```diff
- <div class="usa-identifier__identity" aria-label="Agency identifier">
+ <section class="usa-identifier__identity" aria-label="Agency identifier">
...
- </div>
+ </section>
```
### usa-site-alert
Updated the alignment of the Alert and Site alert component content to visually match alignment with banner content. (#4922)
### usa-tooltip
**Tooltip allows for dynamic initialization.** Tooltip now initializes on first interaction and checks if it has been initialized before toggling. If it hasn't initialized properly then it will call a setup attributes function. (#4955)
### usa-validation
**Updated the validation component so that users of assistive technologies can receive status updates about the completion of each validation requirement.** This was done by adding a script that generates appropriate ARIA attributes. (#4914)
## Dependency updates
Dependency | Old | New
--- | --- | ---
`@storybook/addon-a11y` | 6.5.5 | 6.5.12
`@storybook/addon-essentials` | 6.5.5 | 6.5.12
`@storybook/addon-links` | 6.5.5 | 6.5.12
`@storybook/builder-webpack5` | 6.5.5 | 6.5.12
`@storybook/html` | 6.5.5 | 6.5.12
`@storybook/manager-webpack5` | 6.5.5 | 6.5.12
`gulp-svg-sprite` | 1.5.0 | REMOVED
`gulp-svgstore` | — | 9.0.0
`handlebars-helpers` | 0.10.0 | 0.9.8
`react-dom` | — | 17.0.2
`sass` | 1.45.2 | REMOVED
`sass-embedded` | — | 1.53.0
`snyk` | 1.817.0 | 1.966.0
`stylelint` | 14.1.0 | 14.13.0
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
Internal only: `26 high` vulnerabilities in devDependencies (development dependencies)
Release TGZ SHA-256 hash: `2cf071fe6af1d337c0a2bfe3fd930ea9396dae1130b7e3a7bafbfafb98e2492f`
Version USWDS 3.1.0
August 05, 2022
# What's new in USWDS 3.1.0
This release contains markup changes and potentially breaking changes. A ⚠️ icon indicates where we've made a change that might be a breaking change for your project.
## Package updates
### usa-button
**Style `aria-disabled` to match `disabled`.** Now disabled styling is applied whether you use `disabled` (disabled and hidden from screen readers) or `aria-disabled` (disabled and visible to screen readers). (https://github.com/uswds/uswds/pull/4783)
This also affects these dependent or related packages:
- `usa-button-group`
- `usa-card`
- `usa-modal`
⚠️ **Added `type="button"` to all non-form buttons to prevent default `submit` behaviors.** This allowed us to remove `preventDefault()` from the relevant component JS.
This is a potentially breaking change. Teams should update all non-form buttons to include `type="button"` in their markup. `<button>` elements that do not receive a defined `type` attribute will inherit `type="submit"` behaviors by default. This can cause unintended and undesired behavior in our buttons. Resource: [Details on button types (Mozilla)](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-type) (https://github.com/uswds/uswds/pull/4695)
This also affects these dependent or related packages:
- `usa-accordion`
- `usa-banner`
- `usa-card`
- `usa-header`
- `usa-navbar`
- `usa-modal`
- `usa-nav`
- `usa-sidenav`
### usa-button-group
**Unstyled buttons in a button group now have proper baseline alignment.** (https://github.com/uswds/uswds/pull/4812)
### usa-checkbox
**Style `aria-disabled` to match `disabled`.** Now disabled styling is applied whether you use `disabled` (disabled and hidden from screen readers) or `aria-disabled` (disabled and visible to screen readers). (https://github.com/uswds/uswds/pull/4783)
### usa-date-picker
**Style `aria-disabled` to match `disabled`.** Now disabled styling is applied whether you use `disabled` (disabled and hidden from screen readers) or `aria-disabled` (disabled and visible to screen readers). (https://github.com/uswds/uswds/pull/4783)
### usa-date-range-picker
**Updated documentation to properly show how to disable dates.** Our documentation provided incorrect information about where to add `data-min-date` and `data-max-date` attributes to the date range picker component. Add these attributes to the `usa-date-range-picker` element. (https://github.com/uswds/uswds-site/pull/1605)
**Style `aria-disabled` to match `disabled`.** Now disabled styling is applied whether you use `disabled` (disabled and hidden from screen readers) or `aria-disabled` (disabled and visible to screen readers). (https://github.com/uswds/uswds/pull/4783)
### usa-header
**Fixed mobile menu appearance for different CSS layouts.** The menu now appears properly on layouts using flex or CSS grid. (https://github.com/uswds/uswds/pull/4817)
### usa-hero
**Optimize hero image.** We replaced our default hero image (644 KB PNG) with an optimized image (147 KB JPG), saving 477 KB. We've also provided a next-generation image format version of the image (105 KB WEBP) as an example.
⚠️ This changes the value of `$theme-hero-image`. If your project uses this default hero image, you'll need to make sure to move the new asset (`hero.jpg`) to your project images directory.
Setting | Old default | New default
--- | --- | ---
`$theme-hero-image` | `"#{general.$theme-image-path}/hero.png"` | `"#{general.$theme-image-path}/hero.jpg"`
### usa-icon
**Added LinkedIn icon.** We now have a LinkedIn icon included in our default icon sprite as `linkedin`.
⚠️ **Use unmodified social media icons.** We now provide simpler social media icons, and removed any decoration not in the original icon. This means that the new icons are not in an enclosing circle unless the original icon is enclosed in a circle. (https://github.com/uswds/uswds/pull/4872)
This also affects these dependent or related packages:
- `usa-footer`
### usa-password
⚠️ **Updated markup in the `usa-password` package to use a `<button>` element instead of an anchor element.** This markup is more semantically appropriate for the related on-page user interaction.
This is not a breaking change. The old markup is still supported, but teams should consider updating to the new markup for improved semantics. (https://github.com/uswds/uswds/pull/4847)
#### Old
```
<p class="usa-form__note">
<a href="#" class="usa-show-multipassword" aria-controls="password confirmPassword"
data-hide-text="Hide my typing">Show my typing</a>
</p>
```
#### New
```
<button type="button"
class="usa-show-password usa-button usa-button--unstyled"
aria-controls="password confirmPassword"
data-hide-text="Hide my typing">Show my typing</button>
```
### usa-radio
**Style `aria-disabled` to match `disabled`.** Now disabled styling is applied whether you use `disabled` (disabled and hidden from screen readers) or `aria-disabled` (disabled and visible to screen readers). (https://github.com/uswds/uswds/pull/4783)
### usa-select
**Improved styling for `select` when the `multiple` attribute is present.** According to the HTML5 standard, a `select` element whose `multiple` attribute is present is "expected to render as an inline-block box whose height is the height necessary to contain as many rows for items as given by the element's display size, or four rows if the [size] attribute is absent." Our `select` now conforms to this guidance. (https://github.com/uswds/uswds/pull/4766)
### uswds-core
**Style `aria-disabled` to match `disabled`.** Now disabled styling is applied whether you use `disabled` (disabled and hidden from screen readers) or `aria-disabled` (disabled and visible to screen readers). (https://github.com/uswds/uswds/pull/4783)
### uswds-utilities
**Integrated the CSS `aspect-ratio` property into our `add-aspect` utility and mixins.** This change aligns us more closely with expected CSS behavior, while also extending the capabilities of `add-aspect`. Users can now apply `add-aspect` directly to media and media wrappers — without the need to use `.usa-embed-container`. This update is backwards compatible and was written to preserve previous behavior for browsers that do not support the CSS `aspect-ratio` property. (https://github.com/uswds/uswds/pull/4811)
## Dependency updates
_No dependency updates._
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
Internal only: `3 moderate, 32 high` vulnerabilities in devDependencies (development dependencies)
Release TGZ SHA-256 hash: `727a1883badb336f67f6f355e8fdf7ace9af871ca8af7dbb231b2e3cc7649a9b`
Version USWDS 3.0.2
June 17, 2022
# What's new in USWDS 3.0.2
## Improvements and bug fixes
- **uswds-init is better at suppressing FOUC.** We updated the `uswds-init` script's event listener to target `window` from `document`. This assures that the page's JavaScript is fully loaded before we remove the `loadingClass` that suppresses the open banner. The banner should no longer flash open. (https://github.com/uswds/uswds/pull/4676)
- **Improved Date Picker display at very narrow widths.** We improved the display of the date picker at very narrow widths so there are no UX inconsistencies when the date picker is in a form at less than 320px width. This assures that Date Picker conforms to WCAG 2.1. (https://github.com/uswds/uswds/pull/4770)
- **Custom background colors no longer can cause compile failures.** We updated some of our custom icons so setting a custom `$theme-body-background-color` value no longer throw an error with some colors. (https://github.com/uswds/uswds/pull/4686)
- **More accurate automatic contrast checking for custom colors.** We made our contrast checker more sophisticated so it can more accurately assess the luminance of custom colors, particularly those approximately grade 45. (https://github.com/uswds/uswds/pull/4694)
- **Improved form group error state display.** We improved the styling of form groups so that the margin is the same whether or not the form group is in an error state. (https://github.com/uswds/uswds/pull/4751)
- **High resolution flag for the Banner.** We updated the flag icon in the banner so it appears at a high resolution. (https://github.com/uswds/uswds/pull/4792)
- **Megamenu always stays within the viewport.** We improved the styling of the header megamenu so it resizes properly when trying to capture screenshots. (https://github.com/uswds/uswds/pull/4757)
- **Improved display of dropdown menus in an error state.** Text descenders in a dropdown menu are no longer cut off in the error state. (https://github.com/uswds/uswds/pull/4709)
- **Improved target area for header dropdown links.** Links in dropdown menus are now formatted as block elements to provide a larger selectable surface. (https://github.com/uswds/uswds/pull/4708)
- **Table border setting works as expected.** Theme table settings are now consistently applied to table styles. (https://github.com/uswds/uswds/pull/4712)
- **Added a Fax icon to the default set.** (https://github.com/uswds/uswds/pull/4797)
- **Added a Remove Circle icon to the default set.** (https://github.com/uswds/uswds/pull/4791)
- **Fixed precedence of normalize.** When either the `$theme-global-content-styles` or `$theme-global-paragraph-styles` settings are set to true, styles from normalize.css no longer take precedence over some USWDS global typography styles. (https://github.com/uswds/uswds/pull/4726)
- **Navigate_far icons now accept custom color.** We fixed the `navigate_far_before` and `navigate_far_next` icons to allow a customColor fill. (https://github.com/uswds/uswds/pull/4780)
Thanks @mahoneycm for your time on USWDS Core! 👏
## Dependency updates
dependency | old | new
--- | --- | ---
`chanzuckerberg/axe-storybook-testing` | 5.0.0 | 5.0.1
`@material-design-icons/svg` | — | 0.11.1
`@storybook/addon-a11y` | 6.4.18 | 6.5.5
`@storybook/addon-essentials` | — | 6.5.5
`@storybook/addon-links` | 6.4.18 | 6.5.5
`@storybook/builder-webpack5` | — | 6.5.5
`@storybook/html` | 6.4.18 | 6.5.5
`@storybook/manager-webpack5` | 6.4.18 | 6.5.5
`svgo` | — | 2.8.0
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
Internal only: `3 moderate, 31 high` vulnerabilities in devDependencies (development dependencies)
Release TGZ SHA-256 hash: `c760b8287f4fdc15652df6eb9cc8790eb1f931bac53a5141a5a3ac328980dee0`
Version USWDS 3.0.1
May 06, 2022
# What's new in USWDS 3.0.1
## Improvements and bug fixes
- **Fixed errors when building from new theme files.** We updated our distributed theme files so teams building from these files can compile without errors. (https://github.com/uswds/uswds/pull/4669)
## Dependency updates
dependency | old | new
--- | --- | ---
`@storybook/addon-actions` | 6.4.18 | Removed
`@storybook/addon-postcss` | 2.0.0 | Removed
`storybook-addon-html-document` | 1.0.1 | Removed
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
Internal only: `8 moderate, 27 high` vulnerabilities in devDependencies (development dependencies)
Release ZIP SHA-256 hash: `75bcd83f886b4a3515bec16e34229521b82a5472b231d073cc32bc086e28caf1`
Version USWDS 3.0.0
April 28, 2022
## USWDS 3.0: A more modular design system, incrementally
USWDS 3.0 is an important major design system update that's easy to apply to an existing USWDS 2 project. USWDS 3.0 allows teams to update their projects to modern Sass syntax, improve performance, and reduce the size of project CSS. Where USWDS 2.0 introduced a new design language and changed the way we built our components from the ground up, USWDS 3.0 adds important incremental improvements without fundamentally changing how the design system works.
For most USWDS 2 projects, migrating to USWDS 3.0 should only require changing a few lines of project code. We've developed this new version to be a simple, straightforward migration. We want teams to start using USWDS 3.0, and we'll be there to help you do it.
For migration assistance, start with our [USWDS 3.0 Migration Guide](https://designsystem.digital.gov/documentation/migration) →
If you have any questions or feedback let us know at the [USWDS Public Slack](https://gsa-tts.slack.com/archives/uswds-public), [GitHub Discussions](https://github.com/uswds/uswds/discussions), or [uswds@gsa.gov](mailto:uswds@gsa.gov).
If you aren't a member of the USWDS Public Slack, [sign up here](https://chat.18f.gov/) by "Joining a TTS Chat Room" — then select "U.S. Web Design System" as your chat topic.
## What's new in USWDS 3.0?
USWDS 3.0 takes a modular, component-centered approach to the design system. We've rebuilt our codebase with a component focus so teams can more effectively integrate the design system incrementally and use only the USWDS components needed in their projects.
### Update to modern Sass syntax
USWDS 3.0 stylesheets use the most modern version of the Sass module syntax. The Sass language that we use to write our stylesheets updated its syntax in 2020 and the old syntax (using `@import`) is now deprecated. Sass will no longer support the old syntax starting in October 2022. We want teams to use source code with reliable support throughout the life of their project, and USWDS 3.0 allows teams to migrate to Sass modules and maintain support.
[Read more about the Sass module syntax](https://sass-lang.com/blog/the-module-system-is-launched) →
### Improve performance and reduce the size of your project CSS
Unbundle the design system with USWDS 3.0. Using USWDS 3.0 with Sass module syntax allows teams to unbundle their implementations of USWDS and use only the components and code that they need on their project. Depending on your project, this could mean significant reduction of CSS code you ship. This means faster load times, better scores in performance evaluation tools, and a better developer experience.
[Read more about USWDS Packages](https://designsystem.digital.gov/components/packages/) →
### Simplify your project settings
USWDS is a highly customizable design system, but that doesn't mean that our settings files need to be long and complicated. Starting in USWDS 3.0, projects will use settings files that include only the settings you've changed in your project. This means fewer project settings to manage, and a clearer vision of your project's customizations.
[Read more about USWDS settings](https://designsystem.digital.gov/documentation/settings) →
### Stay up-to-date with minimal hassle
We want teams to benefit from the most current version of USWDS. Many projects should be able to migrate from USWDS 2 to USWDS 3.0 in about an hour or less. This new version makes no markup or style changes from USWDS 2.13.3. If you already use USWDS 2.13.0 or later, you should be able to update to USWDS 3.0 in a matter of minutes. Additionally, the under-the-hood changes we're introducing in USWDS 3.0 will make it easier to stay up-to-date with USWDS over time. An incremental update now will make subsequent updates simpler as well.
## Support changes in USWDS 3.0
As we move forward to USWDS 3.0 and beyond, we're making some changes to the browsers and functionality our design system supports, consistent with our 2% support threshold and modern development practices.
### No longer explicitly support IE11
IE11 has fallen below our 2% support threshold as monitored by analytics.usa.gov. While we have not removed any existing IE11 support from our codebase, we may make changes and add functionality that no longer supports IE11 as we move forward. When we do make any changes like this, we'll be sure to note it in our release notes.
[USWDS browser support (2% rule)](https://designsystem.digital.gov/documentation/developers/#browser-support) →
[See current analytics from analytics.usa.gov](https://analytics.usa.gov/) →
### Support some Javascript-required functionality
We believe that JavaScript-disabled environments fall below our 2% support threshold, and that we may require JavaScript for some design system functionality. While we have not made any changes to our codebase that affect how we use JavaScript with our components, we may make changes that require JavaScript for some functionality as we move forward. When we do make any changes like this, we'll be sure to note it in our release notes.
### Support USWDS 2 with maintenance and security patches for one year
In addition to supporting active development on USWDS 3, we will continue to support the USWDS 2 branch for one year of maintenance and security patches (until April 2023). The current LTS version of USWDS 2 is [USWDS 2.13.3](https://github.com/uswds/uswds/releases/tag/v2.13.3).
[Long-term support of version 2.x](https://designsystem.digital.gov/documentation/developers/#long-term-support-of-v2x) →
## Dependencies and security
Dependency | Old | New
--- | --- | ---
`@babel/core` | — | `7.16.7`
`@babel/preset-env` | `7.15.8` | `7.16.7`
`@chanzuckerberg/axe-storybook-testing` | — | `5.0.0`
`@frctl/fractal` | `1.5.11` | removed
`@frctl/nunjucks` | `2.0.13` | removed
`@storybook/addon-a11y` | — | `6.4.18`
`@storybook/addon-actions` | — | `6.4.18`
`@storybook/addon-essentials` | — | `6.4.18`
`@storybook/addon-links` | — | `6.4.18`
`@storybook/addon-postcss` | — | `2.0.0`
`@storybook/builder-webpack5` | — | `6.4.18`
`@storybook/html` | — | `6.4.18`
`@storybook/manager-webpack5` | — | `6.4.18`
`@types/node` | `16.11.6` | `16.11.19`
`@whitespace/storybook-addon-html` | — | `5.0.0`
`autoprefixer` | `10.3.7` | `10.4.1`
`babel-loader` | — | `8.2.2`
`chrome-launcher` | `0.15.0` | removed
`chrome-remote-interface` | `0.31.0` | removed
`css-loader` | — | `6.2.0`
`eslint-plugin-import` | `2.25.2` | `2.25.4`
`extract-loader` | — | `5.1.0`
`file-loader` | — | `6.2.0`
`gulp-filter` | `7.0.0` | removed
`gulp-replace` | `1.1.1` | `1.1.3`
`gulp-sass` | — | `5.1.0`
`html-webpack-plugin` | — | `5.4.0`
`lodash.merge` | — | `4.6.2`
`node-notifier` | `10.0.0` | removed
`nswatch` | `0.2.0` | removed
`nyc` | `15.1.0` | removed
`path` | — | `0.12.7`
`postcss` | `8.3.11` | `8.4.0`
`resemblejs` | `4.0.0` | removed
`sass` | `1.43.4` | `1.45.2`
`sass-loader` | — | `12.1.0`
`snyk` | `1.746.0` | `1.817.0`
`storybook-addon-html-document` | — | `1.0.1`
`style-loader` | — | `3.3.0`
`twig-html-loader` | — | `0.1.9`
`twigjs-loader` | — | `1.0.2`
`webpack` | — | `5.58.1`
`webpack-cli` | — | `4.9.1`
`yargs` | `17.2.1` | removed
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install @uswds/uswds`)
Internal only: `2 low, 9 moderate, 30 high` vulnerabilities in devDependencies (development dependencies)
Release package SHA-256 hash: `a98c4b4fc5974f5e335c2fc9d9a0416c236dd73e53dac62c0cc0031adfa5bb03`
Version USWDS 3.0.0 Beta 5
April 18, 2022
# What's new in 3.0.0 Beta 5
This release builds on [Beta 4](https://github.com/uswds/uswds/releases/tag/v3.0.0-beta.4) and is up-to-date with [USWDS 2.13.3](https://github.com/uswds/uswds/releases/tag/v2.13.3). This is probably the last Beta release before USWDS 3.0.0.
- - -
**Fixed bug where Sass placeholders caused compile errors.** We replaced table-related placeholders with mixins to prevent compile errors related to Sass Modules and placeholders.
**Fix bug in Identifier links.** Fixes a bug in identifier links that could show the wrong link color when the `usa-link` package is included after `usa-identifier`.
⚠️ **Use a simpler setting for utilities uselist.** We're deprecating the `$output-all-utilities` setting which overrides all utilities settings and outputs all utilities. Instead, we're using a utility module uselist, defined in a new `$output-these-utilities` setting. The default for `$output-these-utilities` is `default` — which outputs all utilities. Otherwise, you can pass a list of utility modules, and the utility builder will output only those utilities.
For example, the following settings will output only the `background-color`, `color`, `display`, `margin`, and `padding`. It also shows how you can further customize the `color` utility with custom settings and palettes.
```
@use "uswds-core" with (
$output-these-utilities:(
"background-color",
"color"
"display",
"margin",
"padding",
),
$color-settings: (
"output": true
"responsive": false
"active": false
"focus": false
"hover": false
"visited": false
),
$color-palettes: (
"palette-color-theme"
),
);
```
### Utility module names
add-aspect
add-list-reset
align-items
align-self
background-color
border
border-color
border-radius
border-style
border-width
bottom
box-shadow
circle
clearfix
color
cursor
display
flex
flex-direction
flex-wrap
float
font
font-family
font-feature
font-style
font-weight
height
justify-content
left
letter-spacing
line-height
margin
max-height
max-width
measure
min-height
min-width
opacity
order
outline
outline-color
overflow
padding
pin
position
right
square
text-align
text-decoration
text-decoration-color
text-indent
text-transform
top
vertical-align
whitespace
width
z-index
- - -
⚠️ **Use a more concise syntax for exports.** We're updating our exports to use a simpler, more concise syntax. Component JS and Sass should point to the required package. Packages typically are in the format `usa-[component-name]`, like `usa-accordion`.
Type | Old | New | Example
--- | --- | --- | ---
JS (all; backward compatibility) | `./src/js/components` | `./src/js/components` | `@uswds/uswds/src/js/components`
JS (all) | `./src/js/components` | `./js` | `@uswds/uswds/js`
JS (component) | `./src/js/components/*` | `./js/*` | `@uswds/uswds/js/usa-accordion`
CSS (compiled) | `./css/*` | `./css/*` | `@uswds/uswds/css/uswds.min.css`
Sass (compiled) | `./scss/*` | `./scss/*` | `@uswds/uswds/scss/usa-accordion`
Images | `./img/*` | `./img/*` | `@uswds/uswds/img/usa-icons/add.svg`
Images | `./fonts/*` | `./fonts/*` | `@uswds/uswds/fonts/public-sans`
### Packages
usa-accordion
usa-alert
usa-banner
usa-breadcrumb
usa-button
usa-button-group
usa-card
usa-character-count
usa-checkbox
usa-checklist
usa-collection
usa-combo-box
usa-content
usa-dark-background
usa-date-picker
usa-date-range-picker
usa-display
usa-embed-container
usa-error-message
usa-fieldset
usa-file-input
usa-footer
usa-form
usa-form-group
usa-graphic-list
usa-header
usa-hero
usa-hint
usa-icon
usa-icon-list
usa-identifier
usa-input
usa-input-prefix-suffix
usa-intro
usa-label
usa-layout-docs
usa-layout-grid
usa-legend
usa-link
usa-list
usa-media-block
usa-memorable-date
usa-modal
usa-nav
usa-pagination
usa-paragraph
usa-process-list
usa-prose
usa-radio
usa-range
usa-search
usa-section
usa-select
usa-sidenav
usa-site-alert
usa-site-title
usa-skipnav
usa-step-indicator
usa-summary-box
usa-table
usa-tag
usa-textarea
usa-time-picker
usa-tooltip
usa-validation
uswds
uswds-elements
uswds-fonts
uswds-form-controls
uswds-global
uswds-helpers
uswds-typography
uswds-utilities
## Updating from stable or previous betas
Install on your project with `npm install --save @uswds/uswds`
## Security
### Package updates
We're now pinning our dependencies to exact version to be more intentional about which dependency versions we support.
Dependency name | Old | New
--- | --- | ---
`express` | 4.17.2 | removed
`lodash.debounce` | 4.0.7 | removed
`lodash.merge` | 4.6.2 | moved to dev dependencies
`browser-sync` | 2.27.3 | removed
`chrome-launcher` | 0.15.0 | removed
`chrome-remote-interface` | 0.31.0 | removed
`gulp-filter` | 7.0.0 | removed
`gulp-run-command` | 0.0.10 | removed
`raw-loader` | 4.0.2 | removed
`twig-loader` | 0.5.5 | removed
`url-loader` | 4.1.1 | removed
NOTE: We're now releasing the binary as a tarball created from `npm pack` for consistency with the npm-distributed release.
0 vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
Internal only: `41 vulnerabilities (2 low, 9 moderate, 30 high)` in devDependencies (development dependencies)
Release TGZ SHA-256 hash: `827982ca2b6da828aa3d49eb189e42e27d4fb705385d38ee411e09ece55bf5ac`
Version USWDS 2.13.3
April 11, 2022
# What's new in USWDS 2.13.3
## Improvements and bug fixes
- **All components support High Contrast Mode and forced colors.** All our components now support proper display when users have a forced colors mode set in their operating system. (https://github.com/uswds/uswds/pull/4610)
- **Big Footer includes more accessible disclosure buttons.** Now the Big Footer variant uses more accessible disclosure buttons for showing and hiding submenus at mobile widths. Thanks @mherchel! (https://github.com/uswds/uswds/pull/4476)
- **Allow default `value` in Time Picker.** If the enhanced Time Picker input has a `value`, the value is now respected during initialization. Thanks @aduth! (https://github.com/uswds/uswds/pull/4488)
## Dependency updates
dependency | old | new
--- | --- | ---
`mocha` | 6.2.0 | 6.2.3
**Note:** We're now pinning our dependencies to exact versions to be more intentional about the dependencies we use.
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
Internal only: `4 low, 8 moderate, 19 high, 1 critical` vulnerabilities in devDependencies (development dependencies)
Release ZIP SHA-256 hash: `ee183c713841b49f13e6ca7082b81cfd4b75ceff4d8ee4d6ea2cc61241139e68`
Version USWDS 3.0.0 Beta 4
March 16, 2022
# What's new in 3.0.0 Beta 4
This release builds on [Beta 3](https://github.com/uswds/uswds/releases/tag/v3.0.0-beta.3) and is up-to-date with [USWDS 2.13.1](https://github.com/uswds/uswds/releases/tag/v2.13.1).
This release is the second Sass Module release on the 3.0 Beta Branch.
- Updating package structure
- ⚠️ Starting with this Beta release, the `uswds` package is now publishing to the `@uswds` organization scope in npm, as `@uswds/uswds`
**Note that there is no ZIP release with this beta. If you wish to use the Beta 4 release, you'll need to install it via npm.**
- - -
**Use package structure for all USWDS code.** Reorganizes USWDS source code into a common package structure in a `./packages` directory. Sass now uses common [load paths](https://sass-lang.com/documentation/at-rules/use#load-paths) to USWDS source packages (like `@use "uswds-core"`) instead of relative paths (like `@use "../../../uswds-core/src/styles"`). Package structure and load paths will allow downstream users to more easily define, customize, and optimize their USWDS implementation and load individual component packages if desired.
⚠️ To work properly, the Sass compiler needs this package's `packages` directory as a [load path](https://sass-lang.com/documentation/at-rules/use#load-paths), for instance by including something like `includePaths: ["./node_modules/@uswds/uswds/packages"]` as part of your gulp implementation of `sass`, or via `sass-loader` in webpack.
Gulp
```
.pipe(
sass.sync(
{ includePaths: [
"./node_modules/@uswds/uswds/packages"
]}
)
```
Webpack
```
loader: "sass-loader",
options: {
sassOptions: {
includePaths: [
"./node_modules/@uswds/uswds/packages"
],
},
}
```
The [most current Beta release](https://github.com/uswds/uswds-compile/releases/tag/v1.0.0-beta.1) of [USWDS Compile](https://github.com/uswds/uswds-compile) is made for the USWDS 3.0 Beta. Check it out if you want to simplify compiling with USWDS 3.0.
## Updating from stable or previous betas
Install on your project with `npm install --save @uswds/uswds@beta`
If you're using `includePaths` in Sass, you'll need to update the paths as shown above:
```js
// OLD
.pipe(
sass({
includePaths: [
`node_modules/uswds/scss`,
`node_modules/uswds/scss/packages`,
],
})
)
// NEW
.pipe(
sass({
includePaths: [
`node_modules/@uswds/uswds/scss`,
`node_modules/@uswds/uswds/packages`,
],
})
)
```
### ⚠️ Breaking changes
##### From any Stable or Beta release
We changed the organization scope of our npm package and the file structure within the package. Teams need to update their project load paths (`includePaths`) to point to the new package and its stylesheets.
##### From Stable
**Updated package names**
Only affects those using USWDS packages. The `required` package is now called `uswds-core` and the `global` package is now `uswds-global`. The packages location is `./packages` in this new release. If you use `node_modules/@uswds/uswds/packages` in your project's `includePaths`, you no longer need to prefix your package `@include`s (or `@use`s) with `packages/`.
For example:
```scss
@import 'packages/required';
@import 'packages/global';
```
Required and global SCSS packages have been updated to:
```scss
@import 'uswds-core';
@import 'uswds-global';
```
## Security
0 vulnerabilities in regular dependencies (dependencies for USWDS projects installed with npm install uswds)
Internal only: `51 vulnerabilities (20 moderate, 31 high)` in devDependencies (development dependencies)
Release ZIP SHA-256 hash: `NO ZIP RELEASE WITH USWDS 3.0.0 BETA 4`
Version USWDS 3.0.0 Beta 3
March 08, 2022
# What's new in 3.0.0 Beta 3
This release builds on [Beta 2](https://github.com/uswds/uswds/releases/tag/v3.0.0-beta.2) and is up-to-date with [USWDS 2.13.1](https://github.com/uswds/uswds/releases/tag/v2.13.1).
This release is the first Sass Module release on the 3.0 Beta Branch.
- Components now use SASS module syntax
- Old import style still works
- ⚠️ Updating shouldn't require any changes from user. `@import` syntax should still work as expected.
## Updated package names
`packages/required` → `packages/uswds-core`
## What's in this release
- [x] Drop support for IE11 [COMPLETE]
- [x] Reorganize internal directory structure [COMPLETE]
- [x] Use Sass Module Syntax [COMPLETE]
- [ ] ~Publish component packages~ [Coming in a later release]
## Updating from stable
Install on your project with `npm install --save uswds@beta`
If you're using `includePaths` in sass, you'll need to update the path from `./node_modules/uswds/dist/scss` to ` /node_modules/uswds/dist/scss/stylesheets`.
Example using USWDS-Gulp:
```js
// OLD
.pipe(
sass({
includePaths: [
`sass/styles.scss`,
`${uswds}/scss`,
`${uswds}/scss/packages`,
],
})
)
// NEW
.pipe(
sass({
includePaths: [
`sass/styles.scss`,
`${uswds}/scss/stylesheets`,
`${uswds}/scss/stylesheets/packages`,
],
})
)
```
### ⚠️ Breaking changes
##### From Beta 1
_None_
##### From Stable
**Updated package names**
Only affects those using USWDS packages. The `required` package is not called `uswds-core` and the `global` package is now `uswds-global`.
For example:
```scss
@import 'packages/required';
@import 'packages/global';
```
Required and global SCSS packages have been updated to:
```scss
@import 'packages/uswds-core';
@import 'packages/uswds-global';
```
## Security
0 vulnerabilities in regular dependencies (dependencies for USWDS projects installed with npm install uswds)
Internal only: `54 vulnerabilities (2 low, 21 moderate, 31 high)` in devDependencies (development dependencies)
Release ZIP SHA-256 hash: `c7aea4cbccae675b5a43d8d32c38538ffecc3fa5f12ddf86c117541c4ee7b403`
Version USWDS 2.13.2
March 07, 2022
# What's new in USWDS 2.13.2
## Improvements and bug fixes
- **Fixed GitHub icon to prevent CSP flag.** Resolves an error which can occur when using the USWDS Icon component SVG sprite in combination with a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), where the presence of an inline style tag within the GitHub icon can violate most common CSPs which do not include the unsafe-inline style-src directive. Thanks @aduth! (https://github.com/uswds/uswds/pull/4487)
- **Fixed Big Footer expanded display.** Fixes an issue where the Big Footer variant does not show the proper expanded display at exactly 480px. Thanks @jkjustjoshing! (https://github.com/uswds/uswds/pull/4525, https://github.com/uswds/uswds/pull/4531, and https://github.com/uswds/uswds/pull/4551)
- **Add proper aria-controls to Combo Box.** Now the Combo Box input gets the expected `aria-controls` property when it's initialized. (https://github.com/uswds/uswds/pull/4483)
## Dependency updates
dependency | old | new
--- | --- | ---
`postcss-csso` | 5.0.1 | 6.0.0
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
Internal only: `4 low, 17 moderate, 22 high, 1 critical` vulnerabilities in devDependencies (development dependencies)
Release ZIP SHA-256 hash: `c869a7b5d0ebc5b8f44645782bad39faccdb272b1e38a077586ce94e2b09c4cd`
Version USWDS 2.13.1
January 20, 2022
# What's new in USWDS 2.13.1
## Improvements and bug fixes
- **Fix Date Picker input bug in Safari.** We fixed a bug where date picker selections would not propagate into the input field in Safari. (https://github.com/uswds/uswds/pull/4456)
- **Fix external link icon display bug in Safari.** We fixed a bug that resulted in colored bars on the top and bottom of external link icons in Safari. (https://github.com/uswds/uswds/pull/4439)
- **Prevent infinite loops in `divide` function.** We improved the logic of the `divide` function to abort immediately on an attempt to divide by zero. Thanks @aduth! (https://github.com/uswds/uswds/pull/4438)
- **Optimize performance of luminance function.** We used a simple look-up table for single-channel luminance values to dramatically improve the performance of luminance calculations. Thanks @aduth! (https://github.com/uswds/uswds/pull/4437)
- **Improve package exports to allow importing in Webpack 5.** We added explicit exports to USWDS assets so Webpack 5 can access them. Thanks @tyduptyler13 and @pearl-truss! (https://github.com/uswds/uswds/pull/4461, https://github.com/uswds/uswds/pull/4468)
- **Fix Dropdown chevron display in Windows high contrast mode.** We updated the Dropdown styles to allow the chevron to appear in any forced color mode. Thanks @trimspa! (https://github.com/uswds/uswds/pull/4457)
## Dependency updates
None
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
Internal only: `2 low, 22 moderate, 19 high, 1 critical` vulnerabilities in devDependencies (development dependencies)
Release ZIP SHA-256 hash: `c048e4958cbc51a5512d89e321bc7bb90aa3bec00539330042125d6b2c0a0c45`
Version USWDS 3.0.0 Beta 2
January 07, 2022
# What's new in 3.0.0 Beta 2
This release builds on [Beta 1](https://github.com/uswds/uswds/releases/tag/v3.0.0-beta.1) and is up-to-date with [USWDS 2.12.2](https://github.com/uswds/uswds/releases/tag/v2.12.2).
This release is focused on component lifecycles for any component enhanced with JavaScript (like Combo Box, Date Picker, and Modal). So, if you integrate these components into a JavaScript application and have been looking for some more flexibility with component initialization, check it out.
JavaScript components now allow for references other than` document.body` to be referenced with initialization. This makes make the JavaScript-enhanced components more flexible and easy to use, especially in scenarios where components are rendered after initial page load + USWDS init, as with Angular, React, jQuery, vanilla JavaScript, etc.
For example, passing a selector to the Modal that is _not_ `document.body`:
```
const modalRef = useRef()
useEffect(() => {
const modalElement = modalRef.current;
modal.on(modalElement)
return () => {
modal.off(modalElement)
}
}, [modalRef])
```
## What's in this release
- [x] Drop support for IE11 [IN PROGRESS]
- [x] Reorganize internal directory structure [IN PROGRESS]
- [ ] ~Use Sass Module Syntax~ [Coming in a later release]
- [ ] ~Publish component packages~ [Coming in a later release]
## Updating from stable
Install on your project with `npm install --save uswds@beta`
If you're using `includePaths` in sass, you'll need to update the path from `./node_modules/uswds/dist/scss` to ` /node_modules/uswds/dist/scss/stylesheets`.
Example using USWDS-Gulp:
```js
// OLD
.pipe(
sass({
includePaths: [
`sass/styles.scss`,
`${uswds}/scss`,
`${uswds}/scss/packages`,
],
})
)
// NEW
.pipe(
sass({
includePaths: [
`sass/styles.scss`,
`${uswds}/scss/stylesheets`,
`${uswds}/scss/stylesheets/packages`,
],
})
)
```
### ⚠️ Breaking changes
##### From Beta 1
_None_
##### From Stable
**Updated package names**
Only affects those using USWDS packages. The required and global partials are now prefixed with `uswds-`.
For example:
```scss
@import 'packages/required';
@import 'packages/global';
```
Required and global SCSS packages have been updated to:
```scss
@import 'packages/uswds-required';
@import 'packages/uswds-global';
```
## Security
0 vulnerabilities in regular dependencies (dependencies for USWDS projects installed with npm install uswds)
Internal only: 53 vulnerabilities (2 low, 27 moderate, 22 high, 2 critical) in devDependencies (development dependencies)
Release ZIP SHA-256 hash: 55ffc38b87c619c9b0e6cc0d6d7bbd03b3729122f1dbc60d326ae406503dd368
Version USWDS 2.13.0
December 14, 2021
# What's new in USWDS 2.13.0
## Breaking changes
⚠️ **Note: This release contains a couple accessibility-related updates that require a manual markup change.**
⚠️ **Improved resilience of icon-only functionality.** We updated a couple components that use icon-only buttons so that they provide a text equivalent if the image path is broken and does not load. Specifically, this applies to two specific components:
- **The `small` variant of the Search button:** The button that includes an image of a magnifying glass
- **The social icons in the Footer:** This includes the Facebook, Twitter, YouTube, Instagram, and RSS buttons.
If you use these components, they will require a markup change.
### Small search button
#### Old markup
```
<button class="usa-button" type="submit">
<span class="usa-sr-only">Search</span>
</button>
```
#### New markup as of 2.13.0
```
<button class="usa-button" type="submit">
<img src="{{ your uswds image path }}/usa-icons-bg/search--white.svg" class="usa-search__submit-icon" alt="Search">
</button>
```
### Footer social buttons
#### Old markup
```
<a class="usa-social-link usa-social-link--facebook" href="{{ link }}">
<span>Facebook</span>
</a>
<a class="usa-social-link usa-social-link--twitter" href="{{ link }}">
<span>Twitter</span>
</a>
<a class="usa-social-link usa-social-link--youtube" href="{{ link }}">
<span>YouTube</span>
</a>
<a class="usa-social-link usa-social-link--instagram" href="{{ link }}">
<span>Instagram</span>
</a>
<a class="usa-social-link usa-social-link--rss" href="{{ link }}">
<span>RSS</span>
</a>
```
#### New markup as of 2.13.0
```
<a class="usa-social-link" href="{{ link }}">
<img class="usa-social-link__icon" src="{{ your uswds image path }}/usa-icons/facebook.svg" alt="Facebook">
</a>
<a class="usa-social-link" href="{{ link }}">
<img class="usa-social-link__icon" src="{{ your uswds image path }}/usa-icons/twitter.svg" alt="Twitter">
</a>
<a class="usa-social-link" href="{{ link }}">
<img class="usa-social-link__icon" src="{{ your uswds image path }}/usa-icons/youtube.svg" alt="YouTube">
</a>
<a class="usa-social-link" href="{{ link }}">
<img class="usa-social-link__icon" src="{{ your uswds image path }}/usa-icons/instagram.svg" alt="Instagram">
</a>
<a class="usa-social-link" href="{{ link }}">
<img class="usa-social-link__icon" src="{{ your uswds image path }}/usa-icons/rss_feed.svg" alt="RSS">
</a>
```
## Other improvements and bug fixes
**Fixed deprecation workings in our Sass compilation.** Refactored our code to avoid division! (https://github.com/uswds/uswds/pull/4314) And avoid instances of unquoted string interpolation. (https://github.com/uswds/uswds/pull/4380) Thanks @aduth!
**File upload confirms files to screenreaders.** Now File Input will tell screenreaders the total number of files and the names of files added to the component. (https://github.com/uswds/uswds/pull/4415)
**Mobile navigation now makes background content inert.** When the mobile navigation is active, all other non-nav content is hidden. This prevents accidentally leaving the focus of the active mobile menu. (https://github.com/uswds/uswds/pull/4411)
⚠️ **Improve screenreader experience of Date Picker.** Now screen readers can better describe the label and description of a date picker `input`. Thanks @mahoneycm! (https://github.com/uswds/uswds/pull/4414)
This one needs a manual markup change:
**Old Date Picker:** Two IDs in `aria-describedby`
```
<label class="usa-label" id="vUSWDS 2.13.0-{{ label ID }}" for="{{ input ID }}">{{ label text }}</label>
<div class="usa-hint" id="vUSWDS 2.13.0-{{ hint ID }}">{{ hint text }}</div>
<div class="usa-date-picker">
<input
class="usa-input"
id="vUSWDS 2.13.0-{{ input ID }}"
name="{{ input ID }}"
type="text"
aria-describedby="{{ label ID }} {{ hint ID }}"
>
</div>
```
**New Date Picker:** Label ID in `aria-labelledby` and hint ID in `aria-describedby`
```
<label class="usa-label" id="vUSWDS 2.13.0-{{ label ID }}" for="{{ input ID }}">{{ label text }}</label>
<div class="usa-hint" id="vUSWDS 2.13.0-{{ hint ID }}">{{ hint text }}</div>
<div class="usa-date-picker">
<input
class="usa-input"
id="vUSWDS 2.13.0-{{ input ID }}"
name="{{ input ID }}"
type="text"
aria-labelledby="{{ label ID }}"
aria-describedby="{{ hint ID }}"
>
</div>
```
## Dependencies
| Package | Old | New |
| :-------------------------------- | :------ | :------ |
| @18f/identity-stylelint-config | — | 1.0.0 |
| chrome-launcher | 0.14.1 | 0.15 |
| eslint | 7.32.0 | 8.4.1 |
| eslint-config-airbnb-base | 14.2.1 | 15.0.0 |
| eslint-plugin-no-unsanitized | 3.2.0 | 4.0.1 |
| gulp-eslint | 6.0.0 | removed |
| gulp-stylelint | 13.0.0 | removed |
| jsdom | 17.0.0 | 19.0.0 |
| mocha | 9.1.3 | 6.2.0 |
| sinon | 11.1.2 | 12.0.1 |
| stylelint | 13.13.0 | 14.1.0 |
| stylelint-config-prettier | 8.0.2 | removed |
| stylelint-config-recommended-scss | 4.3.0 | removed |
| stylelint-prettier | 1.2.0 | removed |
| stylelint-scss | 3.21.0 | removed |
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
**Internal only:** `8 low, 17 moderate, 12 high, 1 critical` vulnerabilities in devDependencies (development dependencies)
**Release ZIP SHA-256 hash:** `34a951034e07288c6a23c2db3b9e54d6b5f11bec13b1484ca8a8ca8f3b013fbf`
Version USWDS 3.0.0 Beta 1
November 04, 2021
## What's new in 3.0.0 Beta 1
This release is up-to-date with USWDS 2.12.2 and incorporates more of our new directory structure and some of the Pattern Lab → Storybook migration.
### What's in this release
- [x] Drop support for IE11 [IN PROGRESS]
- [x] Reorganize internal directory structure [IN PROGRESS]
- [ ] ~Use Sass Module Syntax~ [Coming in a later release]
- [ ] ~Publish component packages~ [Coming in a later release]
## Updating from stable
Install on your project with `npm install --save uswds@beta`
If you're using `includePaths` in sass, you'll need to update the path from `./node_modules/uswds/dist/scss` to ` /node_modules/uswds/dist/scss/stylesheets`.
Example using USWDS-Gulp:
```js
// OLD
.pipe(
sass({
includePaths: [
`sass/styles.scss`,
`${uswds}/scss`,
`${uswds}/scss/packages`,
],
})
)
// NEW
.pipe(
sass({
includePaths: [
`sass/styles.scss`,
`${uswds}/scss/stylesheets`,
`${uswds}/scss/stylesheets/packages`,
],
})
)
```
### ⚠️ Breaking changes
**Updated package names**
Only affects those using USWDS packages. The required and global partials are now prefixed with `uswds-`.
For example:
```scss
@import 'packages/required';
@import 'packages/global';
```
Required and global SCSS packages have been updated to:
```scss
@import 'packages/uswds-required';
@import 'packages/uswds-global';
```
## Security
0 vulnerabilities in regular dependencies (dependencies for USWDS projects installed with npm install uswds)
Internal only: 93 vulnerabilities (26 moderate, 65 high, 2 critical) in devDependencies (development dependencies)
Release ZIP SHA-256 hash: 4226f63ef09f7064bff4e169b3bda8d94f1da2ce866592302bca7b84bf91018f
Version USWDS 2.12.2
November 01, 2021
# What's new in USWDS 2.12.2
## Improvements and bug fixes
- **Fixed a duplicate-file bug in File Input.** If a file with the same name was uploaded in two separate file input fields, the preview spinner would spin indefinitely. We now assign each upload an individual ID, and the image preview loads properly. (https://github.com/uswds/uswds/pull/4313) Thanks @mahoneycm!
- **Added ability to add a custom error message for wrong file type error in File Upload.** Add the data attribute `data-errorMessage` to `usa-file-input` to include a custom error message. (https://github.com/uswds/uswds/pull/3890) Thanks @hilvitzs!
- **Fixed external link icon color.** We resolved an issue with visited links where the icon color may not match the color of the link. (https://github.com/uswds/uswds/pull/4297) Thanks @aduth!
- **Removed extraneous `href` from Collection calendar.** The `usa-collection__calendar-date` should not include an `href`, so we removed it. (https://github.com/uswds/uswds/pull/4308) Thanks @mahoneycm!
## Security and dependencies
- **Added automatic sanitizing.** The design system now automatically sanitizes content in elements we compose with JavaScript. This means that components like Combobox, Tooltip, File Input, and Date Picker will sanitize any content passed to them. This helps protect any design system implementation against malicious XSS attacks through these components. (https://github.com/uswds/uswds/pull/4329)
## Dependencies
| Package | Old | New |
| :----------------------------------- | :--------- | :--------- |
| @babel/preset-env | 7.15.0 | 7.15.8 |
| @types/node | 16.6.1 | 16.11.6 |
| autoprefixer | 10.3.1 | 10.3.7 |
| axe-core | 4.3.2 | 4.3.4 |
| chrome-launcher | 0.14.0 | 0.14.1 |
| eslint-plugin-import | 2.24.0 | 2.25.2 |
| eslint-plugin-no-unsanitized | 3.1.5 | 3.2.0 |
| gulp-postcss | 9.0.0 | 9.0.1 |
| mocha | 9.0.3 | 9.1.3 |
| postcss | 8.3.6 | 8.3.11 |
| prettier | 2.3.2 | 2.4.1 |
| sass | 1.38.0 | 1.43.4 |
| snyk | 1.683.0 | 1.746.0 |
| stylelint-scss | 3.20.1 | 3.21.0 |
| typescript | 4.3.5 | 4.4.4 |
| yargs | 17.1.1 | 17.2.1 |
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
**Internal only:** `2 low, 12 moderate, 14 high, 1 critical` vulnerabilities in devDependencies (development dependencies)
**Release ZIP SHA-256 hash:** `2c4a794c11dca65db04d6552312241ae6c397b7fd4ea5c8094698461d8d3f687`
Version USWDS 2.12.1
August 18, 2021
# What's new in USWDS 2.12.1
## Improvements and bug fixes
- **Improved whitespace sensitivity of radio and checkbox tiles.** Now radio and checkbox tiles will display consistently whether or not there's extra whitespace in the markup. Thanks @aduth! (https://github.com/uswds/uswds/pull/4286)
- **Header dropdown menus close with escape or focus out.** Now `esc` or focusing out will close dropdown menus in the header. (https://github.com/uswds/uswds/pull/4275)
- **Minimized images.** We optimized our PNGs. Thanks @mgifford! (https://github.com/uswds/uswds/pull/4280)
- **Improved class order sensitivity for breadcrumb and checkbox/radio.** Now breadcrumb and checkbox/radio components display properly regardless of the order of the class and modifier names. Thanks @sembrat! (https://github.com/uswds/uswds/pull/4262)
- **Allow Breadcrumb to work with a broader range of focus widths.** Now the Breadcumb component isn't affected by custom focus widths. Thanks @mahoneycm! (https://github.com/uswds/uswds/pull/4248)
- **Improved how Combo Box parses and displays `option` text.** Thanks @aduth! (https://github.com/uswds/uswds/pull/4287)
- **Improved performance of Date picker and Combo box javascript.** Thanks @aduth! (https://github.com/uswds/uswds/pull/4256)
- **Simplify and optimize `uswds-init` script.** Thanks @aduth! (https://github.com/uswds/uswds/pull/4243)
- **Added appropriate ARIA label to Range input.** (https://github.com/uswds/uswds/pull/4270)
- **Improved external link icon display.** (https://github.com/uswds/uswds/pull/4277)
A big thank you to @aduth for all his work on many of the PRs in this release.
## Security and dependencies
## Dependencies
package | old | new
--- | --- | ---
@babel/preset-env | 7.14.5 | 7.15.0
@frctl/fractal | 1.5.8 | 1.5.11
@frctl/nunjucks | 2.0.10 | 2.0.13
@types/node | 14.17.3 | 16.6.1
autoprefixer | 10.2.6 | 10.3.1
axe-core | 4.2.2 | 4.3.2
chrome-remote-interface | 0.30.1 | 0.31.0
eslint | 7.28.0 | 7.32.0
eslint-config-prettier | 7.2.0 | 8.3.0
eslint-plugin-import | 2.23.4 | 2.24.0
gulp-filter | 6.0.0 | 7.0.0
jsdom | 16.5.3 | 17.0.0
mocha | 8.3.2 | 9.0.3
node-notifier | 9.0.1 | 10.0.0
postcss | 8.3.4 | 8.3.6
postcss-discard-comments | 4.0.2 | 5.0.1
prettier | 2.3.1 | 2.3.2
resemblejs | 3.2.5 | 4.0.0
sass | 1.35.1 | 1.38.0
sinon | 9.2.4 | 11.1.2
snyk | 1.634.0 | 1.683.0
stylelint-config-recommended-scss | 4.2.0 | 4.3.0
stylelint-scss | 3.19.0 | 3.20.1
typescript | 4.3.2 | 4.3.5
typescript | 16.1.1 | 17.1.1
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`5 low, 5 moderate, 3 high` vulnerabilities in devDependencies (development dependencies)
Release ZIP SHA-256 hash: `4492423dacfe6cf4f383cb2e436203c9f6b4caf302850b97bf8b6c81712312fa`
Version Library Beta 1 (2.14.0-beta.1)
July 09, 2021
This is the second beta of our codebase reorganization. While it's a follow-up to the [previous beta](https://github.com/uswds/uswds/releases/tag/v2.10.0-beta.0), it's completely independent of that beta and _does not_ use the Sass modules work from that earlier release.
This beta is focussed on our internal organization and the library that helps us build the design system itself. **For all intents and purposes, this beta should be functionally equivalent to [USWDS 2.12.0](https://github.com/uswds/uswds/releases/tag/v2.12.0).** If you install this beta release, please use it as you would have used USWDS 2.12.0. Please let us know if you encounter any errors by adding an issue to this repo with `Library Beta 1` in the title.
- - -
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`5 low, 5 moderate, 2 high` vulnerabilities in devDependencies (development dependencies)
Release ZIP SHA-256 hash: `73d2dbc8241d34476fc2a40bc44e1593b61e7513586c1515b077eeed8f3099ff`
Version 2.12.0
June 16, 2021
# What's new in USWDS 2.12.0
## New component
We have one new component in this release. Learn more about it on our website:
**[Pagination](https://designsystem.digital.gov/components/pagination):** Pagination is navigation for paginated content.
## New Spanish-language templates
We now have Spanish-language versions of our **404 template** and our **Authentication page templates**
## Other improvements and bug fixes
**Added more negative margin tokens to margin utilities.** Now you can use utilities like `margin-neg-4` and `margin-neg-5`. Thanks @mahoneycm! (https://github.com/uswds/uswds/pull/4212)
**Card's body exdent modifier now works as documented.** Now adding the `.usa-card__body--exdent` modifier will work as expected. Thanks @btwegmann! (https://github.com/uswds/uswds/pull/4165)
**Checkbox and radio buttons now include automatic accessible color.** Now checkbox and radio buttons will display in the proper accessible color, and adapt to the text, link, and background colors you set in your projects's settings. You can also declare a custom background color for checkbox and radio buttons with `$theme-input-background-color`. The selected tile color is now based on the accessible link color, and is not a custom setting. (https://github.com/uswds/uswds/pull/4199)
We also added a new mixin to make it easier to scope custom checkbox and radio button colors: `checkbox-and-radio-colors($bg-color, $selected-color)`
It takes two color token inputs, `$bg-color` and `$selected-color`. Neither are required and will assume the values in settings if omitted. It returns all the code necessary to set checkbox and radio inputs for the desired scope.
For instance, if you wanted to change the color of all checkbox and radio elements within a `.checkbox-tests` container, you could do something like the following
```
.checkbox-tests {
@include set-text-and-bg("green-80");
@include checkbox-and-radio-colors("green-80", "green-warm-10v");
padding: units(2);
border-radius: radius("md");
}
```
**State color tokens available in default utilities.** Now you can use utilities like `text-primary-dark` in the default utility set. (https://github.com/uswds/uswds/pull/4198)
**The `success-dark` color token now looks better.** We updated the value of `success-dark` to be more vivid and look more like `success`. Thanks @maya! (https://github.com/uswds/uswds/pull/4183)
**Cleaner margins in radio tiles.** Now radio tiles have cleaner, more reliable styling for their margin. Thanks @maya! (https://github.com/uswds/uswds/pull/4181)
## Settings
Status | Item | New | Old | Notes
--- | --- | --- | --- | ---
`Changed` | `$theme-color-success-dark` | `green-cool-50` | `green-cool-50v` | —
`Changed` | `$theme-color-success-darker` | `green-cool-80` | `green-cool-60v` | —
`New` | `$theme-input-background-color` | `2` | — | A value of `default` uses the value of `$theme-body-background-color`.
`New` | `$theme-pagination-background-color` | `default` | — | A value of `default` uses the value of `$theme-body-background-color`.
`New` | `$theme-pagination-breakpoint` | `tablet` | —
`New` | `$theme-pagination-button-border-radius` | `md` | —
`New` | `$theme-pagination-button-border-width` | `1px` | —
`New` | `$theme-pagination-font-family` | `ui` | —
`Removed` | `$theme-input-tile-background-color-selected` | — | `primary-lighter` | Input tiles are now automatically calculated from the site link color.
`Removed` | `$theme-input-tile-border-color` | — | `base-lighter` | This value is now calculated automatically.
`Removed` | `$theme-input-tile-border-color-selected` | — | `primary-lighter` | This value is now automatically calculated from the site link color.
## Dependencies and security
| dependency | old | new |
|:---------- |----:|---:|
| elem-dataset | 2.0.0 | `removed`
| @babel/preset-env | 7.13.15 | 7.14.5 |
| @frctl/fractal | 1.5.6 | 1.5.8
| @types/node | 14.14.43 | 14.17.3 |
| autoprefixer | 10.2.5 | 10.2.6 |
| axe-core | 4.2.1 | 4.2.2 |
| chrome-launcher | 0.13.4 | 0.14.0 |
| chrome-remote-interface | 0.28.2 | 0.30.1 |
| eslint | 7.25.0 | 7.28.0 |
| eslint-plugin-import | 2.22.1 | 2.23.4 |
| gulp-changed | 4.0.2 | 4.0.3 |
| gulp-sass | 4.1.0 | `removed`|
| postcss | 8.2.13 | 8.3.4 |
| prettier | 2.2.0 | 2.3.1 |
| sass | 1.32.11 | 1.35.1 |
| snyk | 1.570.0 | 1.634.0 |
| typescript | 4.2.4 | 4.3.2 |
---
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`8 low, 4 moderate, 4 high` vulnerabilities in devDependencies (development dependencies)
**Release ZIP SHA-256 hash:** `95be7f97ad592f68384d6cbbea87e1cd154b585207f35ca3ae2b7bdc6ffd1270 `
Version 1.6.14
June 14, 2021
# v1 Security Update: June 2021
This is a routine security update to the USWDS 1.x line.
## What we did
- Updated Node to current LTS (12.13.0)
- Rewrote `doc-util` to remove `gulp-util` and run Prettier
- Replaced `cssnano` with `csso`
- Updated outdated packages
- Removed Sass linting (since we are no longer updating code)
- Reorganized dependencies and move some to dev dependencies
## Results
### Before
npm audit: `found 1134 vulnerabilities (803 low, 84 moderate, 246 high, 1 critical) in 2320 scanned packages`
### After
npm audit: `found 7 vulnerabilities (2 low, 3 moderate, 2 high) in 1840 scanned packages`
`0` vulnerabilities in regular dependencies
Version 2.11.2
April 28, 2021
# What's new in USWDS 2.11.2
## Bugfixes
**Checked radio buttons remain checked in disabled state.** Now the visual checked state of a checked checkbox does not change if that element is later disabled. (https://github.com/uswds/uswds/pull/4160)
**Fixed incorrect variable usage ($theme-site-max-width).** We updated our docs and settings to remove the `$theme-site-max-width` variable, which was in the docs and in the settings, but not in the code itself. In its place, use `$theme-grid-container-max-width`. `$theme-site-max-width` is marked for deprecation. (https://github.com/uswds/uswds-site/pull/1198)
**Added missing Summary Box package.** Now you can add a Summary Box package to your project with `packages/usa-summary-box`. (https://github.com/uswds/uswds/pull/4162)
**Fixed unstyled button styling.** We updated and strengthened the styling of unstyled buttons to prevent any unwanted style leakage from conventional buttons, especially is used in conjunction with `usa-button--hover` and `usa-button--active` classes. Thanks @aduth! (https://github.com/uswds/uswds/pull/4077)
**Fixed color of active parents in the side navigation.** We fixed a regression where the parent items in the side navigation no longer received the `primary` color. Thanks @asarazor! (https://github.com/uswds/uswds/pull/4163)
⚠️ **Fixed the size of some of our icons.** The view box on some or our icons was 20px instead of 24px. We updated these icons to use the proper view box. This may result in small changes to the display of icons, but will result in a more consistent placement and appearance across all icons in our icon set. (https://github.com/uswds/uswds/pull/4139)
⚠️ **Swapped thumb icons in our sprite for consistency.** We replaced `thumb_down_off_alt` with `thumb_down_off` in our icon sprite for consistency with its `thumb_up` pair. (https://github.com/uswds/uswds/pull/4139)
⚠️ **Removed duplicate eye icon.** Removes `remove_red_eye` icon from `usa-icons` and sprite. Use of `visibility` instead. (https://github.com/uswds/uswds/pull/4139)
## Dependencies and security
dependency | old | new
--- | --- | ---
lodash.debounce | 4.0.7 | `REMOVED`
@babel/preset-env | 7.12.10 | 7.13.15
@frctl/fractal | 1.5.4 | 1.5.6
@frctl/nunjucks | 2.0.8 | 2.0.10
@types/node | 14.14.13 | 14.14.43
autoprefixer | 10.1.0 | 10.2.5
axe-core | 4.1.1 | 4.2.0
eslint | 7.14.0 | 7.25.0
eslint-config-prettier | 7.0.0 | 7.2.0
gulp-replace | 1.0.0 | 1.1.1
handlebars | 4.7.6 | 4.7.7
jsdom | 16.4.0 | 16.5.3
mocha | 8.2.1. | 8.3.2
mq-polyfill | — | 1.1.8
node-notifier | 9.0.0 | 9.0.1
postcss | 8.2.1 | 8.2.13
postcss-csso | 5.0.0 | 5.0.1
sass | 1.29.0 | 1.32.11
sinon | 9.2.2 | 9.2.4
snyk | 1.557.0 | 1.570.0
stylelint-prettier | 1.1.2 | 1.2.0
stylelint-scss | 3.18.0 | 3.19.0
typescript | 4.1.3 | 4.2.4
---
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`6 low, 2 high` vulnerabilities in devDependencies (development dependencies)
**Release ZIP SHA-256 hash:** `688ddc5a0807eb202093f435b9949a5b29ebef9a7d6e7d073279d28ffd83e9a8 `
Version 2.11.1
March 17, 2021
# What's new in USWDS 2.11.1
## Bugfixes
This restores seven white variant icons mistakenly removed from the `usa-icons-bg` directory in `2.11.0`:
- `add--white.svg`
- `check_circle--white.svg`
- `error--white.svg`
- `expand_more--white.svg`
- `info--white.svg`
- `remove--white.svg`
- `warning--white.svg`
We also fixed a display bug with tables affecting our website.
## Dependencies and security
_No package changes._
---
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`6 low, 2 high` vulnerabilities in devDependencies (development dependencies)
**Release ZIP SHA-256 hash:** `50f9f331b9df4681454b0abd66d968358af28456887e3e54229c3ad2ba3548d4 `
Version 2.11.0
March 17, 2021
# What's new in USWDS 2.11.0
## New components
We have three new components in this release. Learn more about them on our website:
- **[Icon list](https://designsystem.digital.gov/components/icon-list):** An icon list reinforces the meaning and visibility of individual list items with a leading icon.
- **[Modal](https://designsystem.digital.gov/components/modal):** A modal disables page content and focuses the user’s attention on a single task or message.
- **[Input prefix or suffix](https://designsystem.digital.gov/components/input-prefix-suffix):** Use input prefixes and suffixes to show symbols or abbreviations that help users enter the right type of information in a form’s text input.
## Updated components
We have two updated components in this release. Learn more about each of them on our website:
- **[Sortable table](https://designsystem.digital.gov/components/table/#sortable-table-rows):** A sorted column changes the row ordering based on alphabetical or numeric cell values.
- **[Links](https://designsystem.digital.gov/components/link):** We updated and improved our guidance around links. Notably, we no longer suggest using the external link icon, as it is often interpreted as `share` or `open in a new tab`. Instead, we recommend adding a link destination into the text of the link if you need to be clear where the link points. We've also expanded our guidance around linking to documents.
## New templates
We have one new template in this release. Learn more about it on our website:
- **[404 page](https://designsystem.digital.gov/templates/404-page/):** A 404 page informs users that a requested page doesn’t exist.
## Other improvements and bug fixes
**Fixed tooltip positioning.** We fixed an issue that prevented some longer tooltips in some positions to display incorrectly. (https://github.com/uswds/uswds/pull/4062)
**Using a custom font without a custom font stack now get a default font stack.** We fixed as bug where setting a custom font without setting a custom font stack resulted in no font stack at all. Now custom fonts will get a default stack appropriate to it's type (`sans`, `serif`, or `mono`). (https://github.com/uswds/uswds/pull/4084)
**Now you can use a custom prefix separator.** Some systems don't parse the `:` separator character in the default USWDS responsive and state prefixes like `tablet:margin-x-2`. Now you can set the value of `$theme-prefix-separator` to output any character or string between the prefix and the main class. (https://github.com/uswds/uswds/pull/4085)
Note that the default needs two `\` characters to properly output the escaped `:` character in the final CSS.
```
$theme-prefix-separator: "\\:",
ex: .tablet\:margin-x-2
<div class="tablet:margin-x-2">
$theme-prefix-separator: "--",
ex: .tablet--margin-x-2
<div class="tablet--margin-x-2">
```
**Fixed character display in checkboxes and radio buttons.** The  character can show up next to checkboxes and radio buttons where a non-breaking space should be when `<meta charset="utf-8">` isn't set properly. Now it will display properly regardless of character encoding. Thanks @andycochran! (https://github.com/uswds/uswds/pull/4080)
**Provide better support for color icons that adapt to theme settings.** Now the color of the alert icon will update automatically to adapt to the alert background, or to the color of the alert text. (https://github.com/uswds/uswds/pull/4079)
**Updated the banner to use the new icon set.**
## Settings
Status | Item | New | Old | Notes
--- | --- | --- | --- | ---
`Changed` | `$theme-alert-icon-size` | `5` | `4` | —
`New` | `$theme-alert-padding-y` | `2` | — | —
`New` | `$theme-icon-list-font-family` | `"body"` | — | —
`New` | `$theme-icon-list-title-font-family` | `"heading"` | — | —
`New` | `$theme-modal-border-radius` | `"lg"` | — | —
`New` | `$theme-modal-default-max-width` | `"mobile-lg"` | — | —
`New` | `$theme-modal-lg-content-max-width` | `"tablet"` | — | —
`New` | `$theme-modal-lg-max-width` | `"tablet-lg"` | — | —
`Changed` | `$theme-table-border-color` | `"ink"` | `default` | A value of `default` uses either the default text or reverse text color depending on the site background color.
`Changed` | `$theme-table-header-text-color` | `"ink"` | `default` | A value of `default` uses either the default text or reverse text color depending on the header background color.
`Changed` | `$theme-table-stripe-text-color` | `"ink"` | `default` | A value of `default` uses either the default text or reverse text color depending on the stripe background color.
`Changed` | `$theme-table-text-color` | `"ink"` | `default` | A value of `default` uses either the default text or reverse text color depending on the site background color.
`New` | `$theme-table-sorted-header-background-color` | `"accent-cool-light"` | — | —
`New` | `$theme-table-sorted-background-color` | `"accent-cool-lighter"` | — | —
`New` | `$theme-table-sorted-stripe-background-color` | `"blue-cool-10v"` | — | —
`New` | `$theme-table-sorted-icon-color` | `default` | — | —
`New` | `$theme-table-unsorted-icon-color` | `"base"` | — | —
`New` | `$theme-prefix-separator` | `"\\:"` | — | —
## Dependencies and security
_No package changes._
---
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`6 low, 2 high` vulnerabilities in devDependencies (development dependencies)
**Release ZIP SHA-256 hash:** `204f91185f424abdd1b65ea2d1b4565f2208726be429c455477668d1507a9a5b `
Version 2.10.3
March 15, 2021
# What's new in USWDS 2.10.3
- Removed the corrupted ZIP file erroneously included in the `2.10.2` package
- Improved our build script to more reliably build the ZIP file.
Version 2.10.2
March 03, 2021
# What’s new in USWDS 2.10.2
## Bugfixes and updates
**Fixed `SVG4Everybody` compatibility.** Now USWDS javascript will compile properly with Babel. Now you should be able to use `uswds.js` or `uswds.min.js` in a React app without any problems. Thanks @aduth!
**Fixed a flash of unstyled content in extended header megamenu.** Now there won't be a flash of megamenu content while the USWDS javascript loads. (Note: This requires `uswds-init`.)
**Added more white icon variants.** Added white icon variants for `add`, `remove`, and `expand_more` so teams can have accessible icon color combinations on dark backgrounds, especially in the accordion and the top navigation.
**More consistently use theme text and link colors across components.** Improved our use of `$theme-text-` and `$theme-link-` color settings in components and variants like `usa-dark-background` and `usa-section--dark`.
## Dependencies
Updates snyk from `1.439.1` to `1.467.0`
`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`5` low, `2` high vulnerabilities in `devDependencies` (development dependencies)
