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.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

    

![A colorful group of shapes spell out "3.0"](https://user-images.githubusercontent.com/11464021/165827090-492e5b6d-e645-436d-9b8c-ac589e1421a4.jpg)



## 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)


    
  

Version 2.10.1

February 19, 2021

    
# What’s new in USWDS 2.10.1

## Bugfixes and updates
**Fix automatic accessible color picker:** Now the accessible color picker will properly pick the correct text color from a given background color. It will also throw warnings instead of errors if accessible combinations aren't found. (#3906 and #3926)

New or ⚠️ changed setting | Default | Description
--- | --- | ---
$theme-body-background-color | `"white"` | Background for the page body
$theme-text-color | `"ink"` | Page text color
$theme-text-reverse-color | `"white"` | Text color with dark backgrounds
$theme-alert-text-color | `default` (uses whatever is set for `$theme-text-color`) | Text color for light-background alerts
$theme-alert-text-reverse-color | `default` (uses whatever is set for `$theme-text-reverse-color`) | Text color for dark-background alerts
$theme-alert-link-color | `default` (uses whatever is set for `$theme-link-color`) | Link color for light-background alerts
$theme-alert-link-reverse-color | `default` (uses whatever is set for `$theme-link-reverse-color`) | Link color for dark-background alerts
⚠️ $theme-breadcrumb-background-color | `default` (uses whatever is set for `$theme-body-background-color`) | Background color for the breadcrumb
$theme-identifier-primary-link-color | `default` (system picks between `$theme-alert-link-color` and `$theme-alert-link-reverse-color` depending on the background color) | Color of the links in the identifier masthead

**Allows `svg4everybody` polyfill to compile properly in React and Vue:** Now React and Vue applications won't crash with a TypeError caused by `svgforeverybody`. (https://github.com/uswds/uswds/issues/3909)

**Properly give an accessible name to the combobox:** Now the combobox will have an accessible name as long as the label's `for` attribute matches the id of the `input.usa-combo-box` or `input.usa-time-picker`. (https://github.com/uswds/uswds/issues/3900)

**Fix styling in collection calendars:** Removes a thin white line which could appear at the top of calendars in collection items. (https://github.com/uswds/uswds/pull/3917)

**Fix a radio/checkbox focus outline bug on Firefox.** Removes unwanted text indent from checkbox and radio input, which was causing the focus outline to be improperly sized on Firefox. (https://github.com/uswds/uswds/issues/3916)

**Utilize `$theme-alert-icon-size` variable for setting the alert icon size:** Now the setting works as expected. Thanks @sawyerh! (https://github.com/uswds/uswds/pull/3942) 

> ⚠️ NOTE: This changes the value of the `$theme-alert-icon-size` default to `5` from `4`.

**Adds an instagram social icon to our default footer.** (https://github.com/uswds/uswds/pull/3948)

**Updates all icons used by components to the new icon set.** (https://github.com/uswds/uswds/pull/3992)

**Fixes left padding for anchor links in the sidenav.** Thanks @fsierra! (https://github.com/uswds/uswds/issues/3944)

**Fixes the import path for the `usa-icons` package.** Thanks @jennyychaa! (https://github.com/uswds/uswds/issues/3954)

**Fixes a secondary nav display bug in the header in Safari:** Now the search component and the secondary nav display and resize properly in Safari. Thanks @akanelson! (https://github.com/uswds/uswds/issues/3805)

⚠️ **Use proper semantic markup for footer title:** Now we're using a `p` instead of an `h3` for `usa-footer__logo-heading` since the name of the project or agency is hot a heading in this context.

**Properly wrap the wrapped breadcrumb on Safari:** Now the `usa-breadcrumb--wrap` breadcrumb variant will wrap properly on Safari, instead of overflowing. (https://github.com/uswds/uswds/issues/3997)

**Update project's version of Node to the most current LTS (14.15.4).**

## Dependencies
- Adds `sass-true@6.0.1` for Sass unit testing
- Updates `snyk` to `1.439.1`
- Updates `@frctl/fractal` to `1.5.4`
- Updates `@frctl/nunjucks` to `2.0.8`

- - -

`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)

`5` low, `2` high vulnerabilities in devDependencies (development dependencies)

    
  

Version 2.10.0

December 17, 2020

    
# What’s new in USWDS 2.10

## New components

We have four new components in this release. Learn more about each of them on our website:

- **[Collection](https://designsystem.digital.gov/components/collection):** A collection displays a compact list of multiple related items like articles or events. The list links each item to its original source.
- **[Process list](https://designsystem.digital.gov/components/process-list):** A process list displays the steps or stages of important instructions or processes.
- **[Site alert](https://designsystem.digital.gov/components/site-alert):** A site alert communicates urgent sitewide information.
- **[Summary box](https://designsystem.digital.gov/components/summary-box):** A summary box highlights key information from a longer page or displays next steps.

## Updated components

We have four updated components in this release. Learn more about each of them on our website:

- **[Checkbox (tile display)](https://designsystem.digital.gov/components/form-controls/#checkbox):** We added a "tile" display to provide a larger, more obvious touch target for checkboxes.
- **[Icons](https://designsystem.digital.gov/components/icons):** We improved our default icon support and now provide a broader selection of consistent icons in our package.
- **[Radio button (tile display)](https://designsystem.digital.gov/components/form-controls/#radio-buttons):** We added a "tile" display to provide a larger, more obvious touch target for radio buttons, as well.
- **[Table (mobile and data display)](https://designsystem.digital.gov/components/table):** We improved the mobile performance of our tables and included more formatting options for data tables.

## New templates

We have three new templates in this release. Learn more about each of them on our website:

- **[Create account](https://designsystem.digital.gov/page-templates/authentication-pages/#create-account):** Create a new account
- **[Sign in](https://designsystem.digital.gov/page-templates/authentication-pages/#sign-in):** Sign in to a service
- **[Sign in (multiple sign-in options)](https://designsystem.digital.gov/page-templates/authentication-pages/#multiple-sign-in-options):** Choose from multiple sign-in providers

## No more banner flash: The USWDS initializer script

USWDS 2.10.0 adds a small (under 1 KB minified) initialization script (`uswds-init.min.js`) to the package. When included in the `<head>` — either by reference or inline — this script prevents the banner from flashing its content on page load and shifting content (https://github.com/uswds/uswds/issues/3092).

**Note: This only prevents flashing when you use CSS generated from USWDS 2.10.0 or later.**

### What it does

Simply:

- It adds a `.usa-js-loading` class to the `<html>` element as the USWDS JS library is loading.

In more detail:

- If JavaScript is present, it adds a `.usa-js-loading` class to the `<html>` element before the `body` renders.
- If the USWDS JS library loads, it removes the `.usa-js-loading` class.
- If the USWDS JS library does not load in a timeout period, it removes the `.usa-js-loading` class.

Since USWDS components are meant to make their content available even if our JS does not load, their visibility of any toggle-able content defaults to visible and the JS is responsible for hiding it. This resulted in a flash of "hidden" content between when the page renders and the JS loads.

This initialization script allows us to visually hide "hidden" content at page render by hooking those styles to the `.usa-js-loading` class. When the USWDS JS loads, the JavaScript is responsible for hiding/showing interactive content as usual and the class hook is removed. If the USWDS JS does not load, `uswds-init` removes the `.usa-ls-loading` class and the content will revert to visible. If there is no JS present at all, `uswds-init` will not load and the content will be visible at page render.

### Using the initializer

1. Copy `uswds-init-min.js` out of the USWDS package an into your project directory.
2. Reference the script in the document `<head>` or include the entire script inline.

#### Include by reference

```html
<!DOCTYPE html>
<html>
  <head>
    ...
    <script src="assets/uswds/js/uswds-init.min.js"></script>
    <link rel="stylesheet" href="assets/uswds/css/uswds.min.css" />
  </head>
  <body>
    ...
    <script src="assets/uswds/js/uswds.min.js"></script>
  </body>
</html>
```

#### Include inline

```html
<!DOCTYPE html>
<html>
  <head>
    ...
    <script>
      const docElem=window.document.documentElement,loadingClass="usa-js-loading";function addLoadingClass(){docElem.className+=` ${loadingClass}`}function revertClass(){docElem.className=docElem.className.replace(loadingClass,"")}if("querySelector"in window.document&&"addEventListener"in window){addLoadingClass();const e=setTimeout(revertClass,8e3);let s=100;const n=()=>{setTimeout(()=>{s+=1,"undefined"!=typeof uswdsPresent?(clearTimeout(e),setTimeout(revertClass,100)):s>0&&n()},100)};n()}
    </script>
    <link rel="stylesheet" href="assets/uswds/css/uswds.min.css" />
  </head>
  <body>
    ...
    <script src="assets/uswds/js/uswds.min.js"></script>
  </body>
</html>
```

## Other improvements and bug fixes

**Improved non-autoprefixed state of colored icons.** When you see a USWDS icon that appears as a rectangle instead of its proper shape, this is because some USWDS colored icons require Autoprefixer to display properly. Now the non-Autoprefixer icon will appear as a black icon instead of as a rectangle. All projects should still [use Autoprefixer when compiling their stylesheets](https://designsystem.digital.gov/documentation/developers/#sass-compilation-requirements). Thanks @aduth! (https://github.com/uswds/uswds/pull/3860)

**Improved the accessibility of decorative images in the Banner.** We modified the Banner to properly mark up SVG files used as decorative images. Now all decorative images are hidden from screen readers, and all SVGs are more resilient to browser bugs. See the Banner page for the complete, correct markup, and see the pull request for more context on the changes. (https://github.com/uswds/uswds/pull/3892)

> :warning: This requires a manual change on any site that uses the Banner.
>
> - Use `alt=""` for any decorative `<img>` element
> - Use `role="img"` for `<img>` elements with an SVG source
> - Use `aria-hidden="true"` for decorative `<img>` elements with an SVG source
> - Use `role="img"` and `focusable="false"` for `<svg>` elements meant to be images (ie don't contain text/data)
> - Use `aria-hidden="true"` for decorative `<svg>` elements
> - Use `aria-label="[accessible name]"` or `aria-labelledby="[id list]"` for `<svg>` elements that convey information and need an accessible description

**Created a Spanish version of the Search component.** We recommend using "Buscar" in Spanish-language version of Search. See the [Search guidance page](https://designsystem.digital.gov/components/search/) for more information. Thanks @lggsa! (https://github.com/uswds/uswds/pull/3861)

**Updated the Spanish USAGov link in the identifier.** The Spanish-language USAGov link in the identifier should read `Visite USAGov en Español` (https://github.com/uswds/uswds/pull/3863)

> :warning: This requires a manual change on any site that uses the Spanish-language identifier.
>
> `Visite USA.gov en Español` → `Visite USAGov en Español`

**Support custom bold font weight.** Now `$theme-font-weight-bold` will change the theme bold font weight as expected. Thanks @sawyerh! (https://github.com/uswds/uswds/pull/3811)

**Allow proper drag/drop on File input component.** Now drag and drop will accept or reject files as expected when using a File input set to accept multiple extensions. Thanks @ConnorDY! (https://github.com/uswds/uswds/pull/3851)

**Enable proper hover styles on visited links.** Now visited links have a visible hover state. Thanks @astiefvater! (https://github.com/uswds/uswds/pull/3868)

**Enable and disable File Input programmatically.** Now developers can set the status of the File Input component dynamically. Thanks @ConnorDY! (https://github.com/uswds/uswds/pull/3760)

**Better support for buttons with multiple variants.** We fixed a display bug with visited inverse unstyled buttons. Button styling is more reliable with different combinations of variants. Thanks @andycochran! (https://github.com/uswds/uswds/pull/3846)

**Support buttons in side navigation.** Now any anchor link button in a Side Navigation component hill have expected display. Thanks @ajware-uscis! (https://github.com/uswds/uswds/pull/3839)

**Allow custom hex colors as File Input disabled color.** We fixed a bug that prevented a custom hex value for `disabled-light` from working in the File Input component. Thanks @aduth! https://github.com/uswds/uswds/pull/3762

**Improved font display in the Identifier.** We're now using normal weight text in the Identifier domain text instead of light text for more consistent appearance. (https://github.com/uswds/uswds/pull/3740)

**Improved breadcrumb padding.** Fixes a bug that could make some values of `$theme-focus-width` incompatible with the Breadcrumb. (https://github.com/uswds/uswds/pull/3737)

## Dependencies and security

| package                   | old     | new      |
| ------------------------- | ------- | -------- |
| del                       | 5.1.0   | 6.0.0    |
| @babel/preset-env         | 7.11.5  | 7.12.10  |
| @frctl/fractal            | 1.3.0   | 1.5.1    |
| @frctl/nunjucks           | 2.0.2   | 2.0.5    |
| @types/node               | 14.11.1 | 14.14.13 |
| autoprefixer              | 9.8.6   | 10.1.0   |
| axe-core                  | 4.0.2   | 4.1.1    |
| browserify                | 16.5.2  | 17.0.0   |
| eslint                    | 7.9.0   | 7.14.0   |
| eslint-config-airbnb-base | 14.2.0  | 14.2.1   |
| eslint-config-prettier    | 6.11.0  | 7.0.0    |
| eslint-plugin-import      | 2.22.0  | 2.22.1   |
| gulp-postcss              | 8.0.0   | 9.0.0    |
| gulp-sourcemaps           | 2.6.5   | 3.0.0    |
| gulp-svg-sprite           | —       | 1.5.0    |
| gulp-uglify               | 3.0.0   | 3.0.2    |
| mocha                     | 8.1.3   | 8.2.1    |
| node-notifier             | 8.0.0   | 9.0.0    |
| postcss                   | —       | 8.2.1    |
| postcss-csso              | 4.0.0   | 5.0.0    |
| prettier                  | 2.1.2   | 2.2.0    |
| sass                      | 1.26.11 | 1.29.0   |
| sinon                     | 9.0.3   | 9.2.2    |
| snyk                      | —       | 1.437.0  |
| stylelint                 | 13.7.1  | 13.8.0   |
| typescript                | 4.0.3   | 4.1.3    |
| yargs                     | 16.0.3  | 16.1.1   |

---

`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)

`5 low, 2 high` vulnerabilities in devDependencies (development dependencies)

**Release ZIP SHA-256 hash:** `1c3c31de6fdb62bd327b54e46c1513a252ffc4a54b9152db1e2fcafb7dbc4c4e `

    
  

Version 2.10.0 Beta 0

September 28, 2020

    
# About 2.10.0 Beta 0
This release is a port of USWDS 2.9.0 to the most recent Sass syntax, the [Sass Module System](https://sass-lang.com/blog/the-module-system-is-launched) [SaMS]. This new syntax allows a couple specific improvements to the design system:

- **Namespacing: It's more compatible with other Sass frameworks.** SaMS offers optional custom namespace for any USWDS variables, mixins, and functions, assuring that there are never any collisions between similarly named functionality across libraries (like two functions called `color()`).
- **Subsetting: It loads only what you need.** SaMS makes it simpler to subset the design system to include only the components you need, with no redundant imports and minimal unused rules.

There's a lot of reorganization under the hood to reflect our focus on modularity (and more to come as the beta integrates a new library structure) but this reorganization should have minimal impact on how you load and use the design system. Just how you load the new code depends on how extensively you want to use namespacing or subsetting

**⚠️ Note:** Throughout this guidance, we'll be referring to the **Sass entry point**, your project's `.scss` file that points the compiler to the files it needs to compile the design system CSS. If this is an unfamiliar concept we discuss it in greater detail in our [USWDS Fundamentals and quickstart guide](https://designsystem.digital.gov/documentation/fundamentals/).

## Requirements
This currently requires a compile path that uses Dart Sass.

- **Example:** Use Gulp with `gulp-sass` and `sass`,  and `sass.compiler = require('sass');` set in the gulpfile.
- **Example:** Use `uswds-gulp`

**⚠️ Note: Many compilers based on libsass or other libraries do not fulfill these requirements.** Notably, this includes the native compiler built into Jekyll (`jekyll-sass-converter`), `node-sass`, and likely others. If this beta package doesn't work for you, it's probably due to this requirement. We're working to see what kinds of compile workarounds are possible in the most common environments. Your feedback and experimentation during the beta process will help us evaluate the practicality of integrating SaMS into USWDS.

## Implementation
The most important thing to remember is that you can't use `@import` in the same file that you use a new SaMS rule like `@use` or `@forward`. Each individual file can play by its own rules, but you can't mix old and new rules in any individual file.  In effect, mixed implementations need to create a SaMS entry point imported from the primary Sass entry point. In the examples below, we've named that SaMS entry point `theme-modules`.

**Note:** In mixed implementations, the SaMS entry point must `@forward` either `uswds` or a USWDS package (like `packages/uswds-core`) to apply the imported settings upstream of using  `@use` to load mixins and functions into a stylesheet.

Additionally, each example in this section assumes that you're keeping all your project sass files in a single directory in the project root. Your project can have a different structure, you'd just have to adjust the load paths to fit.

### Simple: Use USWDS as in earlier versions
You should be able to use this beta release without making any changes to your Sass entry point. Conventional `@import` rules will work with this release just as they did with earlier USWDS releases.

```scss
// styles.scss
 
@import "uswds-theme-general";
@import "uswds-theme-typography";
@import "uswds-theme-spacing";
@import "uswds-theme-color";
@import "uswds-theme-utilities";
@import "uswds-theme-components";
@import "../node_modules/uswds/dist/uswds";
@import "uswds-theme-custom-styles";
```

### Intermediate: Package subsetting
Subsetting means loading only the packages and styles you need for your project. Each USWDS component has a package (typically the same as its class name, `usa-[component]`). There are also a few special packages:

package | description
--- | ---
**uswds-components** | all components
**uswds-core** | only the USWDS core internals — tokens, functions, and mixins
**uswds-elements** | limited styling for unclassed html elements
**uswds-fonts** | the font-face generator
**uswds-form-controls** | all form controls
**uswds-form-templates** | all form templates
**uswds-global** | core, elements, and helpers + normalize
**uswds-helpers** | non-utility helper classes, like usa-sr-only and usa-focus
**uswds-layout-grid** | the layout grid classes
**uswds-typography** | styles related to text and headings
**uswds-utilities** | utility classes
**uswds-validation** | components related to form validation

Find packages in the `dist/packages` directory in the USWDS npm package.
```scss
// styles.scss
 
@import "uswds-theme-general";
@import "uswds-theme-typography";
@import "uswds-theme-spacing";
@import "uswds-theme-color";
@import "uswds-theme-utilities";
@import "uswds-theme-components";
@import "theme-modules";
@import "uswds-theme-custom-styles";
```

```scss
// theme-modules.scss

@forward "../node_modules/uswds/dist/packages/usa-banner";
@forward "../node_modules/uswds/dist/packages/usa-identifier";
@forward "../node_modules/uswds/dist/packages/usa-button";
@forward "../node_modules/uswds/dist/packages/uswds-form-controls";
...
```

### Intermediate: Namespacing
Namespacing adds a custom prefix to variables, mixins, and functions loaded with the @use rule. Use custom namespacing to prevent collisions between similarly-named functionality in multiple libraries.

```scss
// styles.scss
 
@import "uswds-theme-general";
@import "uswds-theme-typography";
@import "uswds-theme-spacing";
@import "uswds-theme-color";
@import "uswds-theme-utilities";
@import "uswds-theme-components";
@import "theme-modules";
```

```scss
// theme-modules.scss
 
@forward "../node_modules/uswds/dist/uswds";
@forward "theme-custom-styles";
```

```scss
// theme-custom-styles.scss
 
@use "../node_modules/uswds/dist/uswds" as usa;
.foo {
  @include usa.u-margin-x(1)
  color: usa.color("primary-vivid");
}
```

### Intermediate: Package subsetting and custom namespace
You can also do both subsetting and namespacing with a hybrid implementation.

```scss
// styles.scss
 
@import "uswds-theme-general";
@import "uswds-theme-typography";
@import "uswds-theme-spacing";
@import "uswds-theme-color";
@import "uswds-theme-utilities";
@import "uswds-theme-components";
@import "theme-modules";
```

In the SaMS entry point, include both packages and custom styles.
```scss
// theme-modules.scss
 
@forward "theme-packages";
@forward "theme-custom-styles";
```

For packages, include individual component packages…
```scss
// theme-packages.scss
 
@forward "../node_modules/uswds/dist/packages/usa-banner";
@forward "../node_modules/uswds/dist/packages/usa-identifier";
@forward "../node_modules/uswds/dist/packages/usa-button";
@forward "../node_modules/uswds/dist/packages/uswds-form-controls";
```

…or include just the USWDS core internals
```scss
// theme-packages.scss
 
@forward "../node_modules/uswds/dist/packages/uswds-core";
```

Load custom styles as before, using the `uswds-core` package with the desired namespace.
```scss
// theme-custom-styles.scss
 
// Use packages/uswds-core to include core internals only
@use "../node_modules/uswds/dist/packages/uswds-core" as usa;
.foo {
  @include usa.u-margin-x(1)
  color: usa.color("primary-vivid");
}
```

### Advanced: Use native SaMS instead of imports
The big change in using a SaMS-only implementation is that your packages forward needs to include all changed settings as a single map object passed as its config.
```scss
// styles.scss
 
@forward "theme-modules--packages" with (
  $theme-show-notifications: false,
  $theme-color-primary-vivid: "orange-20v",
  ...
);
@forward "theme-modules--custom";
```

Include any packages or USWDS core internals, as before.
```scss
// theme-modules--packages.scss

@forward "../node_modules/uswds/dist/packages/usa-banner";
@forward "../node_modules/uswds/dist/packages/usa-identifier";
@forward "../node_modules/uswds/dist/packages/usa-button";
@forward "../node_modules/uswds/dist/packages/uswds-form-controls";
 
// or
 
@forward "../node_modules/uswds/dist/packages/uswds-core";
```

Include any packages or USWDS core internals, as before.
```scss
// theme-modules--custom.scss
 
@use "../node_modules/uswds/dist/packages/uswds-core" as usa;
@forward "custom-styles-one";
@forward "custom-styles-two";
...
```

Each custom styles file needs to `@use` the `uswds-core` package.
```scss
// custom-styles-one.scss
 
@use "../node_modules/uswds/dist/packages/uswds-core" as usa;
 
.foo {
  @include usa.u-margin-x(1)
  color: usa.color("primary-vivid");
}
...
```

Stylesheets can reference other sheets if they `@use` that stylesheet explicitly.
```scss
// custom-styles-two.scss
 
@use "../node_modules/uswds/dist/packages/uswds-core" as *;
@use "custom-styles-one" as *;
 
.bar {
  @extend .foo;
  @include u-margin-y(1)
  color: color("secondary-vivid");
}
...
```

## What we expect from a beta tester
- Add the beta package to your project with the simple implementation and see if it compiles as expected
- Try some of the intermediate implementations: subsetting or namespacing
- File any questions of bugs in the `uswds` repo
  - Use the `beta` label
  - Be as descriptive as possible about how to reproduce a bug
  - Attach any setup information (beta version, compiler, framework, os, etc)
- Ask questions in the` #uswds-public` Slack
    
  

Version 2.10.0 Alpha 0

September 25, 2020

    
Alpha release for testing only.
    
  

Version 2.9.0

September 22, 2020

    
# What’s new in USWDS 2.9.0

## New components
We have three new components in this release. Learn more about each of them on our website:

- **[Identifier](https://designsystem.digital.gov/components/identifier):** The identifier communicates a site's parent agency and displays agency links required by federal laws and policies.
- **[Step indicator](https://designsystem.digital.gov/components/step-indicator):** A step indicator updates users on their progress through a multi-step process.
- **[Time picker](https://designsystem.digital.gov/components/form-controls/#time-picker):** A time picker helps users select a specific time.

## Improvements and bug fixes
**Added flex-align-self utilities.** Now you can apply the `align-self` property to an element using flex-align-self utilities. The align-self rule is conceptually similar to flex-align, except `align-self` applies at the flex child level instead of the flex parent level. Thanks @taylorsolomon! (https://github.com/uswds/uswds/pull/3588)

- **flex-align-self-start:** align element at the start of the parent's cross axis
- **flex-align-self-middle:** align element in the middle of the parent's cross axis
- **flex-align-self-end:** align element at the end of the parent's cross axis
- **flex-align-self-stretch:** stretch across the full extent of the parent's cross axis

**Added an accent-warm button variant.** Now you can use `accent-warm` buttons with `usa-button--accent-warm`. (https://github.com/uswds/uswds/pull/3623)

**Generating SHA-256 hashes for our ZIP releases.** We're now generating a SHA-256 hash with the ZIP download and documenting this hash in our repo and on our website. Anyone can now check the integrity of a release ZIP file by generating a hash for their local file and comparing it to the hash we post in the github repo and on our site. (https://github.com/uswds/uswds/pull/3577)

**Proper disabled radio buttons.** We fixed the display of disabled radio buttons so both the label and radio button both appear disabled. Thanks @brayfe! (https://github.com/uswds/uswds/pull/3613)

**Proper secondary button active state.** We fixed the active state of the secondary color button. Thanks @maya! (https://github.com/uswds/uswds/pull/3615)

**Improved styling of lists inside alerts.** We improved the styling of simple and complex lists inside alerts. (https://github.com/uswds/uswds/pull/3507)

**More consistent styling of legend element.** We improved the styling of the  usa-legend element to better match other labels in a form, and improved the spacing between legends and both radio buttons and checkboxes. We added a `usa-label--large` variant to mimic the older, less consistent styling for backward compatibility. (https://github.com/uswds/uswds/pull/3465)

## Dependencies and security

package | old | new
-- | -- | --
@babel/preset-env | 7.11.0 | 7.11.5
@types/node | 14.0.27 | 14.11.1
axe-core | 4.0.1 | 4.0.2
eslint | 7.6.0 | 7.9.0
mocha | 8.1.1 | 8.1.3
prettier | 2.1.1 | 2.1.2
sass | 1.26.10 | 1.26.11
stylelint | 13.6.1 | 13.7.1
typescript | 3.9.7 | 4.0.3
yargs | 15.4.1 | 16.0.3

`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`3 low, 2 high` vulnerabilities in devDependencies (development dependencies)

**Release ZIP SHA-256 hash:** `4b3928e5a292ee4a2ac0b1a5106c179c4cfadd9355e56f5fb6b8e6e1954cfdb2`

    
  

Version 2.8.1

August 17, 2020

    
# What's new in USWDS 2.8.1
## Improvements and bug fixes
**Allow custom colors in link calculations.** Now projects that use custom hex colors in their theme colors can generate CSS without errors. For standard USWDS tokens, the link color calculator generates a hover color one system grade level above or below the link color in the same vivid state. Now the calculator does the same with custom hex theme tokens, except using the theme color grades. (https://github.com/uswds/uswds/issues/3568)

**Added a max-width setting to the footer.** We added a `$theme-footer-max-width` setting to constrain the footer content, similar to what we already provide for the banner. (https://github.com/uswds/uswds/issues/3532)

**Improved date picker focus state.** We fixed a bug that cut off part of the date picker's date focus ring in IE11. (https://github.com/uswds/uswds/issues/3578)

**Improved combo box resizing.** We fixed a display bug with the combo box where custom combo box sizing wasn't reflected in its input. Thanks @fafnirical! (https://github.com/uswds/uswds/pull/3583)

**Improved combo box dropdown overlapping.** We fixed a display bug with the combo box where neighboring combo box UI elements could overlap with the combo box dropdown. Thanks @Pharmasolin! (https://github.com/uswds/uswds/pull/3572)

## Dependencies and security
package | old | new
-- | -- | --
elem-dataset | 1.1.1 | 2.0.0
@babel/preset-env | 7.10.4 | 7.11.0
@types/node | 13.13.13 | 14.0.27
autoprefixer | 9.8.4 | 9.8.6
browserify | 16.5.1. | 16.5.2
eslint | 5.16.0 | 7.6.0
eslint-config-airbnb-base | 13.2.0 | 14.2.0
gulp-eslint | 5.0.0 | 6.0.0
gulp-rename | 1.2.2 | 2.0.0
jsdom | 16.2.2 | 16.4.0
mocha | 7.2.0 | 8.1.1
node-notifier | 6.0.0. | 8.0.0
prettier | 1.19.1 | 2.0.5
resemblejs | 3.2.4 | 3.2.5
sinon | 7.5.0 | 9.0.3
typescript | 2.4.1 | 3.9.7
yargs | 15.4.0 | 15.4.1

`0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
`3 low, 2 high` vulnerabilities in devDependencies (development dependencies)

    
  

Version 2.8.0

July 09, 2020

    
# What's new in USWDS 2.8.0

## New components
We're excited to release a new batch of components. Learn more about each of them on our website:

- **[Breadcrumb](https://designsystem.digital.gov/components/breadcrumb/):** Breadcrumbs provide secondary navigation to help users understand where they are in a website.
- **[Date picker](https://designsystem.digital.gov/components/form-controls/#date-picker):** A date picker helps users select a single date.
- **[Date range picker](https://designsystem.digital.gov/components/form-controls/#date-range-picker):** A date range picker helps users select a range between two dates.
- **[File input](https://designsystem.digital.gov/components/form-controls/#file-input):** File input allows users to attach one or multiple files.
- **[Tooltip](https://designsystem.digital.gov/components/tooltip/):** A tooltip is a short descriptive message that appears when a user hovers or focuses on an element.


## Updates to the banner
We've made some important [updates to the banner text](https://designsystem.digital.gov/components/banner/). Our new banner text incorporates feedback we've received over the last year or so, and incorporates a few key enhancements:

- [Emphasize that trustworthiness is a combination of an official TLD and a secure HTTPS connection](https://github.com/uswds/uswds/pull/3373)
- [Stay up to date with the different ways to determine HTTPS usage in your browser](https://github.com/uswds/uswds/issues/3281)
- Provide official language support for other languages, starting with Spanish (with the help of the USAGov en Español team)
- Focus the message by using TLD-specific copy for .mil sites

Teams should work to update this banner text as soon as possible. Consistency improves the reliability, trustworthiness, and awareness of this important component. Thanks @h-m-f-t, @konklone, @wslack, @lggsa, and @leilanimartinez!

These banner updates also include **better settings support** for the banner, including support for custom banner background and link colors, and **improved readability at wide display widths**. 

⚠️ The banner code requires Autoprefixer to work properly. See https://designsystem.digital.gov/documentation/developers/#sass-compilation-requirements

### .gov domains
| Official websites use .gov | Secure .gov websites use HTTPS
| --- | ---
| A **.gov** website belongs to an official government organization in the United States. | A **lock** (🔒) or **https://** means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.

### .gov domains (Spanish)
| Los sitios web oficiales usan .gov | Los sitios web seguros .gov usan HTTPS
| --- | ---
| Un sitio web **.gov** pertenece a una organización oficial del Gobierno de Estados Unidos. | Un **candado** (🔒) o **https://** significa que usted se conectó de forma segura a un sitio web .gov.  Comparta información sensible sólo en sitios web oficiales y seguros.

### .mil domains
| Official websites use .mil | Secure .mil websites use HTTPS
| --- | ---
| A **.mil** website belongs to an official U.S. Department of Defense organization. | A **lock** (🔒) or **https://** means you've safely connected to the .mil website. Share sensitive information only on official, secure websites.

### .mil domains (Spanish)
| Los sitios web oficiales usan .mil | Los sitios web seguros .mil usan HTTPS
| --- | ---
| Un sitio web **.mil** pertenece a una organización oficial del Departamento de Defensa de EE. UU. | Un **candado** (🔒) o **https://** significa que usted se conectó de forma segura a un sitio web .mil.  Comparta información sensible sólo en sitios web oficiales y seguros. 

## New settings

Setting | Accepts | Default | Usage
-- | -- | -- | ---
$theme-link-reverse-color | color token | `"base-lighter"` | Default link color for reverse (dark) backgrounds
$theme-link-reverse-hover-color | color token | `"base-lightest"`| Default link hover color for reverse (dark) backgrounds
$theme-link-reverse-active-color | color token | `"white"`| Default link hover color for reverse (dark) backgrounds
$theme-banner-background-color | color token | `"base-lightest"` | Banner background color
$theme-banner-link-color | color token or `default` | `default` | Banner link color. `default` uses the value in `$theme-link-color. The system will calculate hover, active, and visited states.
$theme-breadcrumb-background-color | color token | `"white"` | Breadcrumb background color. Note that the system needs to evaluate color contrast, so this cannot be any `transparent`-based token.
$theme-breadcrumb-font-size | font size token | `"sm"` | Breadcrumb font size
$theme-breadcrumb-font-family | font family token | `"body"` | Breadcrumb font family
$theme-breadcrumb-link-color | color token or `default` | `default` | Breadcrumb link color. `default` uses the value in `$theme-link-color. The system will calculate hover, active, and visited states.
$theme-breadcrumb-min-width | spacing token | `"mobile-lg"` | Breakpoint at which the breadcrumb switches to non-mobile display
$theme-breadcrumb-padding-bottom | spacing token | 2 | Breadcrumb bottom padding
$theme-breadcrumb-padding-top | spacing token | 2 | Breadcrumb top padding
$theme-breadcrumb-padding-x | spacing token | 0 | Breadcrumb left and right padding
$theme-breadcrumb-separator-color | color token | `"base"` | Color of the breadcrumb chevron separator


## Dependencies and security

package | old | new
-- | -- | --
@types/node | 13.13.12 | 13.13.13
yargs | 15.3.1 | 15.4.0
@babel/preset-env | 7.10.2 | 7.10.4
autoprefixer | 9.8.0 | 9.8.4
axe-core | 3.5.4 | 3.5.5
chrome-launcher | 0.13.3 | 0.13.4
eslint-plugin-import | 2.21.2 | 2.22.0
sass | 1.26.8 | 1.26.10
stylelint | 13.6.0 | 13.6.1
stylelint-config-prettier | 8.0.1 | 8.0.2
stylelint-scss | 3.17.2 | 3.18.0

- - -

- `0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
- `5 low, 3 high` vulnerabilities in devDependencies (development dependencies)
    
  

Version 2.7.1

June 17, 2020

    
# What's new in USWDS 2.7.1

## Improvements to combo box
We listened to your feedback and made a number of improvements and upgrades to our new combo box.

**Show proper focus in combo box.** Hover and keyboard events transfer focus to individual options, and now the styling reflects that. (https://github.com/uswds/uswds/pull/3493)

**Disabled combo boxes remain disabled after enhancement.** The `disabled` attribute now correctly results in a disabled combo box. (https://github.com/uswds/uswds/pull/3484)

**Use data attributes to set combo box placeholder and default.** We now use data attributes to set the default value (`data-default-value`) and placeholder (`data-placeholder`). (https://github.com/uswds/uswds/pull/3486)

**Improved combo box interactions.** Allows list toggling with the toggle button, and adds a "clear input" button to start a subsequent combo box interaction. Makes a number of additional improvement to how the combo box handles changes and new selections. (https://github.com/uswds/uswds/pull/3505)

**Combo box now triggers a change event on `input` and `select` change.** Now we fire proper change events on the `<select>`. Thanks @ConnorDY! (https://github.com/uswds/uswds/pull/3487)

**We fixed the punctuation on the default combo box.** Now there's no more colon, consistent with other input guidance. (https://github.com/uswds/uswds/pull/3473)

**The combo box scrollbar works.** Now you can scroll a combo box with the scrollbar! (https://github.com/uswds/uswds/pull/3483)

## Other improvements and bug fixes
**Improved the reliability and cross-browser compatibility of our flexbox usage.** We rebuilt how the design system outputs its flex utilities and mixins so any flex-based rules display properly and as expected in browsers from IE11 up. (https://github.com/uswds/uswds/pull/3480)

**Improve display of media block.** This element now uses flexbox instead of floats, so text in a media block is no longer cut occasionally cut off at the end of a line in IE11. Thanks @maya! (https://github.com/uswds/uswds/pull/3453)

**Mobile menus can now be closed with the `esc` key in IE11.** Now, the escape key will properly close mobile menus in IE11. Thanks @joncasey! (https://github.com/uswds/uswds/pull/3468)

**Improved our Autoprefixer and Browserslist settings.** We added `not dead` to our Autoprefixer settings and now use a `.browserslistrc` file for these options. This gets us more in line with Autoprefixer and Browserslist best practices. Thanks @ai! (https://github.com/uswds/uswds/pull/3458)

**Fixed IE11 display issue in mobile nav.** Now nav elements display as expected at mobile width on IE11. (https://github.com/uswds/uswds/pull/3470)

**Fixed a potential Unhandled rejection Parsing error in the codebase.** Thanks @hursey013! (https://github.com/uswds/uswds/pull/3497)

**Added `role="img"` to SVG images.** Thanks @sslawrence521! (https://github.com/uswds/uswds/pull/3501)

**Fixed spacing in nested lists.** Now nested lists will have proper formatting and spacing regardless of the value of `$theme-global-content-styles`. Thanks @jonraedeke! (https://github.com/uswds/uswds/pull/3495)

**Fixed a color contrast issue in our `accent-cool` button.** Now all our buttons have the proper AA contrast between the button background and the button text. And we've built our code to be smart enough to adjust the text color to adapt to any project's theme color definitions. (https://github.com/uswds/uswds/pull/3492)

To better provide resilience in our color contrast, we're introducing two new mixins to help provide a more resilient codebase:

```
@include set-text-from-bg( 
  background-color, 
  preferred-text-color, 
  fallback-text-color, 
  WCAG-level
)

@include set-text-and-bg( 
  background-color, 
  preferred-text-color, 
  fallback-text-color, 
  WCAG-level
)

preferred-text-color default: "white"
fallback-text-color default: "ink"
WCAG-level default: "AA"

WCAG-levels:
  "AA"
  "AA-large"
  "AAA"
```

For a given `background-color` token, each mixin checks contrast against the `preferred-text-color` and uses that as the text color unless it doesn't pass the contrast requirements of the `WCAG-level`. Then it checks `fallback-text-color` and uses that color unless it doesn't meet contrast requirements, in which case it returns an error.

**set-text-from-bg**(): Sets only the text color.
**set-text-and-bg**(): Sets both the background color and the text color.

## Dependencies and security

package | old | new
-- | -- | --
@types/node | 13.9.1 | 13.13.12
@babel/preset-env | 7.8.7 | 7.10.2
@frctl/fractal | 1.2.1 | 1.3.0
@frctl/nunjucks | 2.0.1 | 2.0.2
autoprefixer | 9.7.4 | 9.8.0
axe-core | 3.5.2 | 3.5.4
browserify | 16.5.0 | 16.5.1
chrome-launcher | 0.13.2 | 0.13.3
chrome-remote-interface | 0.28.1 | 0.28.2
cross-spawn | 7.0.1 | 7.0.3
eslint-config-prettier | 6.10.0 | 6.11.0
eslint-plugin-import | 2.20.1 | 2.21.2
gulp-cli | 2.2.0 | 2.3.0
gulp-sass | 4.0.2 | 4.1.0
jsdom | 16.2.1 | 16.2.2
mocha | 7.1.12 | 7.2.0
nyc | 15.0.0 | 15.1.0
sass | 1.26.3 | 1.26.8
stylelint | 13.2.1 | 13.6.0
stylelint-scss | 3.15.0 | 3.17.2

- - -

- `0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
- `4 low, 3 high` vulnerabilities in devDependencies (development dependencies)

    
  

Version 2.7.0

May 11, 2020

    
# What's new in USWDS 2.7.0

## New components
Read more about these components on our website, but we're excited to start releasing the first of a number of new design system components planned for 2020:

- **Button group:** Use button groups to collect similar or related actions.
- **Card:** Cards contain content and actions about a single subject.
- **Character count:** Character count helps users know how much text they can enter when there is a limit on the number of characters.
- **Combo box:** A combo box helps users select an item from a large list of options.

## Improvements and bug fixes
**Improved mobile experience for numeric fields.** We updated our guidance and code for numeric fields to follow the lead of gov.uk's recent [guidance](https://design-system.service.gov.uk/components/text-input/#numbers) and [research](https://technology.blog.gov.uk/2020/02/24/why-the-gov-uk-design-system-team-changed-the-input-type-for-numbers/). This updates those fields to use `text` rather than `number` inputs with an `inputmode` of `numeric`. (https://github.com/uswds/uswds/pull/3392)

**Fixed color token errors.** We made some mistakes adding the new color tokens into the system in `2.6.0`. Now the values of `Indigo cool 60v`, `Indigo cool 70v`, and `Indigo cool 80v` fall within our grade guidance, and match both the documentation and the design assets. (https://github.com/uswds/uswds/pull/3455)

**Improved styling of Skipnav component.** Now the Skipnav includes proper link formatting. (https://github.com/uswds/uswds/pull/3393)

**Improved display of the `Here's how you know` link in the gov banner.** Now there's no distracting change to the length of the underline on hover. (https://github.com/uswds/uswds/pull/3427)

**Assure external link icon wraps properly.** Now the external link icon won't get stranded as a widow on a new line. It will break to a new line only with its link text. (https://github.com/uswds/uswds/pull/3428)

**Provide a more reliable treatment for dropdown menus.** Now dropdown menus won't get cut off if they come too close to the header boundary (https://github.com/uswds/uswds/pull/3438) and menus with `usa-current` nav elements won't display an unnecessary underline at desktop widths (https://github.com/uswds/uswds/pull/3434).

## Dependencies and security

package | old | new
-- | -- | --
chrome-launcher | 0.12.0 | 0.13.2
handlebars | 4.7.3 | 4.7.6
mocha | 7.1.0 | 7.1.2

- - -

- `0` vulnerabilities in regular dependencies (dependencies for USWDS projects installed with `npm install uswds`)
- `318 low, 2 high` vulnerabilities in devDependencies (development dependencies)
> Note: The devDependencies number is high because we're still having issues with `npm audit fix`.