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 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: Breadcrumbs provide secondary navigation to help users understand where they are in a website.
  • Date picker: A date picker helps users select a single date.
  • Date range picker: A date range picker helps users select a range between two dates.
  • File input: File input allows users to attach one or multiple files.
  • 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. Our new banner text incorporates feedback we’ve received over the last year or so, and incorporates a few key enhancements:

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( 

@include set-text-and-bg( 

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


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

Version 2.6.0

March 18, 2020

Use more consistent search markup. We made the markup of usa-search more consistent and assured that the styling worked properly regardless of what version of the markup you’re using. This is not as breaking change, but we recommend updating your search markup to the most current version. (https://github.com/uswds/uswds/pull/3327)

Utilities output specified pseudoclasses correctly. We fixed a bug that prevented the utilities from outputting certain pseudoclass prefixes like active:, visited: and focus:. (https://github.com/uswds/uswds/pull/3346) Thanks @greenca6!

Improved letterspacing function. This fixes a bug that caused the letterspacing functions to output the wrong value for 1. Now the utilities and the functions output the same values. (https://github.com/uswds/uswds/pull/3343) Thanks @maya!

Provide complete vivid color families. Now each color family has vivid grades from 5-80. Changing families in settings is more reliable and will no longer result in pointing to false values. Each new color is normalized to our new color grade luminance range guidance. (https://github.com/uswds/uswds/pull/3351) Thanks @jlarmstrongiv!

Provide a more reliable and consistent color system. Each new color is normalized to our new color grade luminance range guidance, so all magic number combinations will work as promised. (https://github.com/uswds/uswds/pull/3351) Thanks @darekkay!

Standard color wheel 2.6.0

uswds-standard-color-wheel-2 6 0

Vivid color wheel 2.6.0

uswds-vivid-color-wheel-2 6 0

changed-colors-in-2 6 0

Dependencies and security

package old new
@types/node 13.5.0 13.9.1
@babel/preset-env 7.7.6 7.8.7
yargs 12.0.5 15.3.1
autoprefixer 9.7.3 9.7.4
axe-core 3.4.1 3.5.2
eslint-config-prettier 6.7.0 6.10.0
eslint-plugin-import 12.19.1 12.20.1
gulp-stylelint 10.0.0 13.0.0
handlebars 4.5.3 4.7.3
jsdom 16.0.1 16.2.1
resemblejs 3.2.3 3.2.4
sass 1.25.0 1.26.3
stylelint 11.1.1 13.2.1
stylelint-config-prettier 6.0.0 8.0.1
stylelint-config-recommended-scss 4.1.0 4.2.0
stylelint-scss 3.13.0 3.15.0

Updated our recommended version of Node to the current LTS (12.16.1)

  • 0 vulnerabilities in regular dependencies (dependencies for USWDS projects installed with npm install uswds)
  • 313 low, 35 moderate, 2 high vulnerabilities in devDependencies (development dependencies)

    Note: The devDependencies number seems high. We’ve had some issues with npm audit recently

Version 2.5.1

March 03, 2020

Removed media query sorting. CSSO’s forceMediaMerge wasn’t exporting media queries in the expected order, so we’re disabling it for more reliable CSS output. While both the minified and unminified CSS files are modestly larger as a result: 268 KB unsorted vs. 259 KB sorted, our testing indicates that once the files are compressed server side with gzip, the unsorted CSS is actually smaller: 36 KB unsorted and gzipped vs. 38 KB sorted and gzipped. As a result, we recommend that teams do not use media query sorting at this time.

Note: This release also temporarily removes the best practice tests from our aXe testing until we can reinstate these tests as warnings rather than errors (#3333). This aXe change should come in the next minor version this month (2.6.0).

Version 2.5.0

February 14, 2020

What’s new in USWDS 2.5.0

:warning: Improved component accessibility and testing. We upgraded our accessibility testing with aXe from 2.6.1 to 3.4.1 and improved the accessibility of our markup in the process. This introduces minor changes to the markup of 5 components and our documentation template — you should update your markup, but existing markup will not break:

  • banner: is now a <section> instead of a <div> with the ARIA label Official government website
  • footer: nav includes the ARIA label of Footer navigation
  • graphic-list: uses h2 as a heading default instead of h3
  • hero: includes the ARIA label of Introduction
  • search: the search form is given the ARIA role of search
  • documentation template: includes only the main content in the <main> element. The nav is no longer treated as an <aside>

PR: https://github.com/uswds/uswds/pull/3280

Allow non-token values in state color settings. Now state tokens (like "warning") can accept non-token colors, just as we introduced for theme colors in 2.4.0. Teams using non-token values can now keep colors consistent between theme and state. Using non-token values will throw a warning in the compile process, but this, like all compile warnings, can be disabled by setting $theme-show-compile-warnings: false. Thanks @sawyerh! https://github.com/uswds/uswds/pull/3289

Updated to the canonical Sass compiler. We’re now using Dart Sass to compile the system Sass. Dart Sass is the canonical Sass compiler, so using it will keep us at feature parity and help prevent inadvertent inconsistencies. https://github.com/uswds/uswds/pull/3304

Output utility classes in proper order without media query sorting. We no longer require media query sorting for proper utility class output. We no longer use a dedicated media query sorter in our dependencies, and do all our optimization with csso (deprecating cssnano). https://github.com/uswds/uswds/pull/3308

Improved performance. We’ve improved the time it takes to compile the design system and its overall file size:

version build:sass gulp sass unminified minified
2.4.0 14s 6.5s 359 KB 270 KB
2.5.0 7.5s 5.2s 357 KB 259 KB

Allows USWDS notifications to render in all environments. We removed the multiline strings that were causing our notification to cause build failures in environments like webpack. Now the Sass should compile properly in all environments. https://github.com/uswds/uswds/pull/3290

Update to the most recent version of Public Sans. Updated to Public Sans 1.008 for better readability and display. https://github.com/uswds/uswds/pull/3275

Added missing add-aspect() mixin. This adds the mixin equivalent to the add-aspect utility classes. https://github.com/uswds/uswds/pull/3283

Improved error messaging for the lh() function. Now it lets you know why it failed and how to fix the error. https://github.com/uswds/uswds/pull/3284

Disabled JS in our Fractal library to remediate an out-of-date jQuery vulnerability. https://github.com/uswds/uswds/pull/3274

Package updates:

package old new
@types/node 12.12.20 13.5.0
axe-core 2.6.1 3.4.1
cssnano   deprecated
css-mqpacker   deprecated
gulp-spawn-mocha 5.0.1 6.0.0
jsdom 9.0.0 16.0.1
jsdom-global 2.1.0 3.0.2
mocha 5.2.0 7.0.1
nyc 14.1.1 15.0.0
postcss-csso 4.0.0
sass 1.25.0

7 vulnerabilities (5 low, 2 high) in 29833 scanned packages All but one low vulnerability are related to Fractal.

Version 2.4.0

December 18, 2019

What’s new in USWDS 2.4.0

Allow non-token values in theme color settings. While USWDS promotes and encourages using our system tokens in theme color settings, agencies have a real need to occasionally use non-token colors. This includes instances where certain colors are mandated by law and cannot be easily changed. Now, teams can add non-token colors to theme color settings like $theme-color-primary: #f00. This new non-token value of 'primary' will apply anywhere the 'primary' token is used: functions, mixins, settings, and utilities. Using non-token values will throw a warning in the compile process, but this, like all compile warnings, can be disabled by setting $theme-show-compile-warnings: false. (https://github.com/uswds/uswds/pull/3258)

Handle deprecations more gracefully. Occasionally the design system will deprecate variables or functionality. Now we’ll display a deprecation message in the terminal when compiling USWDS Sass to better communicate these changes. (This notification can be disabled in settings.) We’re also improving backward compatibility by supporting deprecated variables, functions, and mixins throughout the major version cycle. This way, we can continue to improve how our code is structured while minimizing the effects of this restructuring on your projects. (https://github.com/uswds/uswds/pull/3261)

This is how the deprecation warning prints in the terminal:

✉ USWDS Notifications
2.4.0: If your component settings aren't working as expected, make
sure you're importing the components settings in your Sass entry
point (often styles.scss) with `@import "uswds-theme-components"`.
A bug in 2.0 omitted that import.
2.2.0: We changed the names of some settings.
$theme-navigation-width → $theme-header-min-width
$theme-megamenu-logo-text-width → $theme-header-logo-text-width
2.0.2: We changed the names of some settings and mixins.
$theme-title-font-size → $theme-display-font-size
@include title → @include display
@include typeset-title → @include typeset-display
These are notifications from the USWDS team, not necessarily a
problem with your code.

Disable notifications using $theme-show-notifications: false

Now components reliably respect their font settings. Setting values like $theme-footer-font-family should set the font face for the entire component, but some CSS specificity quirks were overriding these values in some instances. Now, setting a component’s font face works as expected, with no secret overrides. (https://github.com/uswds/uswds/pull/3253)


  • Added a border-collapse: collapse rule to our tables to to fix a bug introduced when we upgraded our version of Normalize. Thanks for the heads up @maya! (https://github.com/uswds/uswds/pull/3250)
  • Removed a duplicate layout grid import (https://github.com/uswds/uswds/pull/3252)
  • Fixed the focus outline’s offset, which was being overridden by a specificity bug (https://github.com/uswds/uswds/pull/3259)


npm audit: found 7 vulnerabilities (5 low, 2 high) in 30585 scanned packages Both High vulnerabilities are related to Fractal and lodash

Version 1.6.13

November 26, 2019

Starting point

npm audit: 965 vulnerabilities (96 low, 236 moderate, 623 high, 10 critical)

What we did

  • Removed Fractal, since we are no longer making changes to component code
  • Removed unused regression tests
  • Added precompiled component previews and renders to a committed directory for testing
  • Using v1-master and v1-develop as v1 production branches


npm audit: 4 moderate severity vulnerabilities

All current moderate vulnerabilities related to jsdom > hoek

Version 1.6.12

November 25, 2019

  • Fix Snyk tests on Circle
  • Fix cache bug on Circle

Version 1.6.11

November 25, 2019

  • Changed Circle cache settings

Version 2.3.1

November 21, 2019

What’s new in USWDS 2.3.1

Now the success icon looks like a checkmark and not a warning. This fixes a bug introduced in 2.2.0 related to SVG normalization. (#3230) Thanks @nickscialli-usds

Version 2.3.0

November 20, 2019

What’s new in USWDS 2.3.0

Properly include component theme variables: Now we’re properly including the component theme variables from _uswds-theme-components.scss in theme/styles.scss so anyone who uses that file in their Sass compile process (like users of uswds-gulp) will see component theme settings applied as expected.

These should be the proper theme imports for USWDS projects:

@import 'uswds-theme-general';
@import 'uswds-theme-typography';
@import 'uswds-theme-components'; <-- previously missing
@import 'uswds-theme-spacing';
@import 'uswds-theme-color';
@import 'uswds-theme-utilities';

Issue: https://github.com/uswds/uswds/issues/3117

Hero image theme setting default is now backward compatible: The $theme-hero-image theme variable now has a default equivalent to its effective value pre v2.2.0 so users that had a working version of their hero are more likely to see no issues upgrading to the latest version of USWDS.

  • Although the new default includes a variable reference to $theme-image-path, users can change this to any path needed. It need not refer to $theme-image-path.
  • This new default requires that the component theme variables (uswds-theme-components) be imported after uswds-theme-general. We suggest that uswds-theme-components be the last of the theme variables imported.

Old default:

$theme-hero-image: '..img/hero.png'

Markup changes

⚠️ We made a small change to the footer markup. This change fixes some small footer spacing issues — not adding this new markup will not negatively affect your existing footer, but adding it will make it better. See the diff: https://github.com/uswds/uswds/pull/3214/files

Smaller issues

  • Megamenu sections now appear at the proper width in the mobile menu: Fixes a megamenu column-width bug that made some subsection menu items appear at less than the full column width.
  • Contact Info underline scope applies to each item individually: This fixes an issue where the :hover selector was too broad. This attaches it to the a link instead of the parent div.
  • Contact info spaced properly in slim footer: Fixes a grid-gap error to assure that contact info items have space in-between.
  • Contact info displays properly regardless of whether utilities use important: Fixes an issue where the contact info wouldn’t display properly unless project utilities were set to use important.
  • Open/close carets in the mobile big footer are now the proper size.
  • Improved footer link spacing @desktop width.
  • Updated and clarified all the font licenses.
  • Added Public Sans v1.007
  • Use Prettier formatting for files.
  • Completely install USWDS when building on Federalist.
  • Update our security test with Snyk.


Removes the following dependencies:

  • @frctl/mandelbrot
  • array-filter
  • acorn
  • canvas-prebuilt
  • chalk
  • cracks
  • jquery

Updates the following dependencies:

  • @types/node12.12.9
  • del5.1.0
  • @babel/preset-env7.7.1
  • @frctl/fractal1.2.1.beta-1 (to fix a 404-related bug)
  • ansi-colors4.1.1
  • autoprefixer9.7.1
  • gulp-filter6.0.0
  • gulp-stylelint10.0.0
  • handlebars4.5.3
  • node-notifier6.0.0
  • node-sass4.13.0
  • normalize.css8.0.1
  • resemble.js3.2.3
  • sinon7.5.0
  • stylelint11.1.1
  • stylelint-scss3.12.1

Adds the following dependencies:

  • eslint-config-prettier
  • prettier
  • stylelint-config-prettier
  • stylelint-config-recommended-scss
  • stylelint-prettier

Other improvements

  • Update node version to latest LTS (12.13.0) and document
  • Update sinon usage to use most current API

npm audit results

15 low, 2 moderate, 6 high, 2 critical

All but one Low vulnerability are related to Fractal.

Version 2.2.1

September 23, 2019

What’s new in USWDS 2.2.1

Sass compiles properly: Now importing uswds using @import uswds will compile properly. The packages/uswds-components package newly referenced by uswds.scss was using incorrect paths and now they point to the proper locations.

Why did this happen? A quirk of how Sass evaluates paths prevented us from seeing this error before we published the release. Sass will, apparently, accept paths relative both to the the file containing the import and also to the entry point (ie, the primary file the compiler points to). The incorrect /base paths evaluated properly for us internally since uswds.scss is the entry point from which we compile our Sass (that is, we do not @import uswds from a separate file). By chance, /base is valid relative to this internal entry point.

How are we preventing this in the future? We’ve made the build process more strict in uswds-site (https://github.com/uswds/uswds-site/pull/816/commits/103dd3ff0569f3a6c61cfd254df031dfdb5c5045#diff-d0940386a71c685fc307161a767958b4R54) so it’ll be far less likely that such a bug will make it through our testing. We may also change our internal build process to surface errors such as this one.

Version 2.2.0

September 19, 2019

What’s new in USWDS 2.2.0

Extended megamenu now works: This fixes a CSS specificity error introduced in 2.1.0 affecting the extended header’s megamenu. (https://github.com/uswds/uswds/pull/3100)

Primary nav indicators are properly aligned: This fixes a spacing issue affecting the header nav indicator bars present since 2.0 that seems to have been a result of rounding errors in line-height calculation. (https://github.com/uswds/uswds/pull/3100)

All component font functions now use role-based tokens: Now code will generate properly, even if a user decides not to use a certain font type in their project (like serif). (https://github.com/uswds/uswds/pull/3103)

Example: a project uses only a sans-serif font on their site, all other font types are set to false.

Improved ARIA markup: We no longer add manual ARIA roles to semantic elements with implicit roles (like header, nav and footer), as this is redundant in modern HTML 5. However, we now add unique and sensical identification to both our primary and secondary navigation with aria-label. (https://github.com/uswds/uswds/pull/3104)

Reference: https://www.w3.org/WAI/tutorials/page-structure/regions/#navigation

Consistent sizing for SVG assets: Now our SVG image assets are sized and built consistently, so CSS styling affects each image as expected. Previously, inconsistent sizing and viewBox settings could cause unexpected effects or necessitate compensatory styling. (https://github.com/uswds/uswds/pull/3105)

Now, each SVG asset is set in a 64px max bounding box flush to the edge of the image — that is, the image is exactly 64px in the maximum dimension, with no space around the perimeter. This allows us to more accurately control the output with CSS. The image is minimally opinionated.

This PR affects:

  • all SVG assets
  • some components that use SVG assets
    • alerts
    • search
    • checkboxes
    • checklist

⚠️ This change has the potential to affect any custom components built with existing SVG assets.

Header and banner width now controlled in settings: Now there are explicit settings for controlling the max-width of the gov banner and the header. (https://github.com/uswds/uswds/pull/3106)

:warning: This change affects the markup of the megamenu. :warning: This change affects settings. Replace instances of the deprecated setting with the new one.

old variable 2.2.0+
$theme-navigation-width $theme-header-min-width
$theme-megamenu-logo-text-width $theme-header-logo-text-width

Your settings file will require the new settings below:

file setting variable controls default
components $theme-banner-max-width maximum width of the banner desktop
components $theme-header-max-width maximum width of the header desktop
components $theme-header-min-width breakpoint at which full header shows desktop
components $theme-header-logo-text-width width of the logo/title region of the header (replaces $theme-megamenu-logo-text-width 33%
components $theme-megamenu-columns number of columns in the megamenu 3

Settings can control hero image: Now you can change the hero image in settings! (https://github.com/uswds/uswds/pull/3107)

:warning: This change affects settings. Your settings file will require the new settings below:

file setting variable controls default
components $theme-hero image path to the hero image, relative to the compiled stylesheet '../img/hero.png'

Improve package documentation and usage: This improves the package documentation in the theme styles.scss by including all available packages in the comments. It also modifies the package contents of uswds-components to require the required and global packages — to be consistent with other packages. (https://github.com/uswds/uswds/pull/3108)

:warning: If you use the uswds-components package, you will no need to include the required and global packages before including uswds-components.

Version 2.1.0

August 14, 2019

Made it simpler to subset the design system and include only the components your project needs with USWDS packages.

  • Thanks @turnerhayes for getting the ball rolling here, even if the final product might not be what you envisioned!
  • Created custom packages in stylesheets/packages used to import only code related to the component package (ie @import uswds-banner)
  • Analyzed each USWDS component’s stylesheet dependencies
  • Left existing default build process alone (ie @import uswds)
  • Allows users to dramatically reduce the USWDS code footprint
package .css .min .zip
default USWDS 359 271 40 KB
form-controls 18 15 3
form-templates 60 47 6
typography 17 15 3
validation 32 28 5
usa-accordion 13 12 2
usa-alert 13 12 2
usa-banner 50 38 5
usa-button 19 16 3
usa-checklist 11 9 2
usa-footer 59 46 6
usa-header 113 63 9
usa-hero 48 37 5
usa-media-block 10 9 2
usa-search 29 25 4
usa-sidenav 12 10 2
usa-skipnav 10 9 2
usa-table 11 9 2
usa-tag 10 9 2
usa-header + usa-footer 162 72 10
usa-banner + usa-footer 99 55 7

Reorganized the source code (in the stylesheets directory) to better reflect its relationship to the build process:

  • Split subcomponents into separate files
  • Move global stylesheets into their own folder
  • Move all code-emitting source out of required dependencies

Version 2.0.3

June 07, 2019

  • Fixed a bug that prevented in-page anchor links from linking properly from the main nav (https://github.com/uswds/uswds/pull/3059)
  • Updated to Public Sans 1.005

Version 2.0.2

May 08, 2019


  • Fixed a bug where footer sections were closing on iOS when a user scrolled up and down. Thanks @joncasey! (https://github.com/uswds/uswds/pull/3047)
  • Fixed a bug where uswds.css was outputting minified (https://github.com/uswds/uswds/pull/3050)


  • Now using primary-dark for our default link hover instead of primary-darker (https://github.com/uswds/uswds/pull/3023)
  • Improved the reliability of our Snyk integration (https://github.com/uswds/uswds/pull/3028)
  • Changed the title typography mixin to display to make it more clear that it’s meant for the largest type on the page, not necessarily for the title or h1 (https://github.com/uswds/uswds/pull/3034)
  • Changed the max date to 2019 for the date input (https://github.com/uswds/uswds/pull/3039)
  • Linted all development Javascript against Airbnb eslint
  • Updated to Public Sans v1.003

Version 2.0.1

April 05, 2019


  • Remove png from external link mixin and checkmark input print style

Version 2.0.0

April 04, 2019

USWDS 2.0 is a new foundation for the future of our design system. This new version was designed to make it easier for any project to integrate USWDS and use it to support both your mission and the needs of your audience. It introduces a powerful toolkit of new features to help make creating useful, consistent digital services faster, simpler, and more fun.

New and notable features:

  • Easier incremental adoption
  • Practical design tokens, functions, and mixins
  • Accessible color system
  • Expressive theming
  • Powerful utility classes
  • Simplified 12-column layout grid
  • Introducing the Public Sans typeface
  • A stable foundation that’s built to grow

:rocket: More about USWDS 2.0

Changes from Beta 7 to 2.0

  • Removed unneeded PNG fallbacks for images since we no longer support the bowsers that require them. (https://github.com/uswds/uswds/pull/3007)
  • Updated our icon colors to USWDS 2.0 tokens (https://github.com/uswds/uswds/pull/3007)
  • Now you can use token values of .5 and -.5 — without leading zeros — in functions and mixins. Thanks @dmethvin-gov! (https://github.com/uswds/uswds/pull/3009)
  • The u-outline() mixin now properly accepts all the tokens it’s meant to accept. Thanks @jeremyzilar! (https://github.com/uswds/uswds/pull/3012)
  • Added u-overflow-x() and u-overflow-y() mixins to match utilities. Thanks @jeremyzilar! (https://github.com/uswds/uswds/pull/3012)
  • The offset-none utilities now support responsive prefixes as intended. Thanks @robertromore! (https://github.com/uswds/uswds/pull/3014)

Version 1.6.10

March 25, 2019

  • Radio buttons are now printable (https://github.com/uswds/uswds/pull/2857)
  • We documented our supported Node and NPM versions in the README (https://github.com/uswds/uswds/pull/2969)
  • Non-focusable elements no longer get a focus indicator in Windows 11. Thanks @ncksllvn! (https://github.com/uswds/uswds/pull/2983)

Version 2.0.0 Beta 7 (Release candidate)

March 25, 2019

Bug fixes

  • Radio buttons are now printable (https://github.com/uswds/uswds/pull/2950)
  • Slim alert has the correct (smaller) icon size alert (https://github.com/uswds/uswds/pull/2946)
  • usa-alert--no-icon has proper padding (https://github.com/uswds/uswds/pull/2959)
  • Font stacks now output properly. Thanks @stphnwlkr! (https://github.com/uswds/uswds/pull/2947)
  • Non-focusable elements no longer get a focus indicator in Windows 11. Thanks @ncksllvn! (https://github.com/uswds/uswds/pull/2988)
  • All type tokens (even lang, cond, and icon) output proper theme font size utilities. (https://github.com/uswds/uswds/pull/2980)


  • ⚠️ breaking change: gov banner markup now points to the flag in the img folder and not the favicon (https://github.com/uswds/uswds/pull/2985)
  • ⚠️ breaking change: hero component now uses an h1 for its tagline for better accessibility (https://github.com/uswds/uswds/pull/2973)
  • ⚠️ breaking change: Removed the alert paragraph component as its functionality is now better controlled with utilities. (https://github.com/uswds/uswds/pull/2990)
  • ⚠️ breaking change: BEM implementation is clearer and more consistent:
old new
.usa-button-unstyled .usa-button.usa-button--unstyled
.usa-unstyled-list .usa-list.usa-list--unstyled
.usa-linput-list removed
ul and li for checkbox just div.usa-checkbox
.usa-checkbox-input .usa-checkbox__input
.usa-checkbox-label .usa-checkbox__label
ul and li for radio buttons just div.usa-radio
.usa-radio-input .usa-radio__input
.usa-radio-label .usa-radio__label
.media_link .usa-media-link
.usa-font-lead .usa-intro
.usa-form-hint .usa-hint
.usa-label-helper .usa-hint
.usa-input-error-message .usa-error-message
.usa-mobile-nav-active .usa-js-mobile-nav--active
  • ⚠️ breaking change: Updated footer-big component to use new BEM (https://github.com/uswds/uswds/pull/2974)
  • ⚠️ breaking change: Updated measure tokens to conform to guidance and be more reliable (https://github.com/uswds/uswds/issues/2960 and https://github.com/uswds/uswds/pull/2981)
token old value new value migration old → new
1 40ch 44ex 11
2 60ch 60ex 24
3 66ch 64ex 35
4 72ch 68ex 45
5 77ch 72ex 56
6 88ex
  • Tightened letterspacing of letterspacing 1 to conform to guidance for small text (https://github.com/uswds/uswds/pull/2965)
  • Documented supported Node and NPM versions in the README (https://github.com/uswds/uswds/pull/2968)
  • Update to most current versions of Source Sans Pro and Merriweather. Thanks @miguelsousa! (https://github.com/uswds/uswds/pull/2934)
  • Updated the favicon to match our logo (https://github.com/uswds/uswds/pull/2985)
  • Removed EOT and SVG font versions since we do not support IE8 or Safari older than 4.1. Thanks @miguelsousa! (https://github.com/uswds/uswds/pull/2989)

Public Sans

  • Fixed a display error resulting in poor font rendering on Windows. Thanks @fat32 and @stphnwlkr! (https://github.com/uswds/public-sans/pull/27)
  • Lightened the regular weight (https://github.com/uswds/public-sans/pull/27)
  • Updated the license to restore the original author’s copyright and remove the reserved font name to conform to SIL OFL best practices. Thanks @davelab6! (https://github.com/uswds/public-sans/pull/27)
  • Coming soon: a new url for specimen site (https://public-sans.digital.gov)

Internal / CI

  • Updated to Gulp 4 (https://github.com/uswds/uswds/pull/2957)
  • Addressed all outstanding Snyk vulnerabilities

Version 2.0.0 Beta 6

March 11, 2019

This release features some significant breaking changes, but it should be the last release of major code changes before the final release of USWDS 2.0.

Bug Fixes

  • Added the missing u-order() utility mixin



We’re now adding the USWDS version number to our settings files to better communicate which version of settings files your project uses. (Thanks @jeremyzilar!)

The layout grid now has its own switch for using !important (general > $theme-layout-grid-uses-important) instead of being connected to the $theme-utilities-use-important variable.

We’re now flipping the caret in dropdown menus when the menu is open to consistently indicate that it is closable (#2616)


We’ve added two new font-types to typography settings: lang and icon for icon fonts and language-specific fonts (#2683)

There’s now support for adding custom font stacks and custom font source files in the typography settings file. (#2858)

Adding custom typefaces is now a bit simpler and actually works. (#2858)

We’ve improved the font rendering speed by adding font-display: fallback to our @font-face declarations (#2744)

Global styling options and prose scope are simpler and more streamlined. (#2814)

  • Removed $theme-content-styles and its options (global, scoped, none)
  • Now usa-prose always applies content styles to its direct children
  • Replaced the $theme-global-styles-basic variable with three explicit global styling vars — each set to false by default.
    • $theme-global-paragraph-styles applies styling to p elements
    • $theme-global-link-styles applies styling to a elements
    • $theme-global-content-styles applies styling to p, a, h[1-6], ol, ul, and table elements
  • Now USWDS will only apply global styling when the user enables it.

There’s better, more clear documentation in the typography settings

previous setting Beta 6 equivalent
$theme-content-styles: 'scoped' no explicit setting necessary
$theme-content-styles: 'global' $theme-global-content-styles: true
$theme-content-styles: 'none' $theme-global-paragraph-styles: false
  $theme-global-link-styles: false
  $theme-global-content-styles: false
$theme-global-styles-basic: true $theme-global-paragraph-styles: true
  $theme-global-link-styles: true

Breaking typography changes

old settings new settings
$theme-font-path in settings-general $theme-font-path in settings-typography
$theme-font-definitions $theme-typeface-tokens
$theme-font-definitions.[token].name $theme-typeface-tokens.[token].display-name
removed generate, system-font, and variable-font keys from typeface token maps
moved custom font source and directory data to $theme-font-[type]-custom-src
moved custom font stack data to $theme-font-[type]-custom-stack
$theme-font-[type] $theme-font-type-[type]
$theme-font-[role] $theme-font-role-[role]
$theme-font-[role] accepts $theme-font-[type] variables $theme-font-[role] accepts font-type tokens like 'mono', 'sans', and 'serif'
$theme-output-all-weights $theme-generate-all-weights
no longer import core/font-definitions — this file is deprecated
$theme-global-styles-basic $theme-global-paragraph-styles, $theme-global-link-styles, and $theme-global-content-styles
basic styles set to true by default basic styles (paragraph and link styles) set to false by default

Class names

We’ve decided to use BEM naming for our class naming for disambiguation and consistency with industry norms. This is a major change that affects a majority of USWDS classes.

  • Use BEM for class naming: .usa-block-name__element-name--modifier (#2915)
  • Use single hyphens for all blocks and elements (.usa-media-block)


Beta 5 Beta 6
usa-background-dark usa-dark-background
usa-content usa-content
usa-content-list usa-content-list
usa-display usa-display
usa-external_link usa-link--external
usa-external_link-alt usa-link--external.usa-link--alt
usa-font-lead usa-font-lead
usa-heading-alt usa-heading-alt
usa-link usa-link
usa-paragraph usa-paragraph
usa-prose usa-prose


Beta 5 Beta 6
usa-button usa-button
usa-button-accent-cool usa-button--accent-cool
usa-button-active usa-button--active
usa-button-base usa-button--base
usa-button-big usa-button--big
usa-button-disabled usa-button--disabled
usa-button-hover usa-button--hover
usa-button-outline usa-button--outline
usa-button-outline usa-button--outline
usa-button-outline-inverse usa-button--outline.usa-button--inverse
usa-button-secondary usa-button--secondary
usa-button-unstyled usa-button-unstyled
usa-focus usa-focus


Beta 5 Beta 6
usa-embed-container usa-embed-container


Beta 5 Beta 6
usa-media_link usa-media-link


Beta 5 Beta 6
usa-checkbox-input usa-checkbox__input
usa-checkbox-label usa-checkbox__label
usa-fieldset usa-fieldset
usa-form-group usa-form-group
usa-form-group-day usa-form-group--day
usa-form-group-error usa-form-group--error
usa-form-group-month usa-form-group--month
usa-form-group-year usa-form-group--year
usa-form-hint usa-form__hint
usa-input usa-input
usa-input-inline usa-input--inline
usa-input-medium usa-input--medium
usa-input-small usa-input--small
usa-input-success usa-input--success
usa-input-error usa-input--error
usa-input-error-message usa-input-error-message
usa-input-label-helper usa-input__label-helper
usa-input-label-required usa-input__label-required
usa-input-list usa-input-list
usa-label usa-label
usa-label-error usa-label--error
usa-legend usa-legend
usa-memorable-date usa-memorable-date
usa-radio-input usa-radio__input
usa-radio-label usa-radio__label
usa-range usa-range
usa-select usa-select
usa-textarea usa-textarea


Beta 5 Beta 6
usa-list usa-list
usa-unstyled-list usa-unstyled-list


Beta 5 Beta 6
usa-table usa-table
usa-table-borderless usa-table--borderless


Beta 5 Beta 6
usa-tag usa-tag
usa-tag-big usa-tag--big


Beta 5 Beta 6
usa-accordion usa-accordion
usa-accordion-bordered usa-accordion--bordered
usa-accordion-button usa-accordion__button
usa-accordion-content usa-accordion__content
usa-accordion-heading usa-accordion__heading


Beta 5 Beta 6
usa-alert usa-alert
usa-alert-error usa-alert--error
usa-alert-no-icon usa-alert--no-icon
usa-alert-slim usa-alert--slim
usa-alert-success usa-alert--success
usa-alert-warning usa-alert--warning
usa-alert-body usa-alert__body
usa-alert-heading usa-alert__heading
usa-alert-icon usa-alert__icon
usa-alert-info usa-alert__info
usa-alert-paragraph usa-alert__paragraph
usa-alert-text usa-alert__text


Beta 5 Beta 6
banner-header-expanded usa-banner__header--expanded
usa-banner usa-banner
usa-banner-button usa-banner__button
usa-banner-button-text usa-banner__button-text
usa-banner-content usa-banner__content
usa-banner-guidance usa-banner__guidance
usa-banner-header usa-banner__header
usa-banner-header-action usa-banner__header-action
usa-banner-header-close-text usa-banner__header-close-text
usa-banner-header-expanded usa-banner__header-expanded
usa-banner-header-flag usa-banner__header-flag
usa-banner-header-text usa-banner__header-text
usa-banner-icon usa-banner__icon
usa-banner-inner usa-banner__inner


Beta 5 Beta 6
is-checked is-checked
usa-checklist usa-checklist
usa-checklist-checked usa-checklist__checked
usa-checklist-item usa-checklist__item
Beta 5 Beta 6
usa-footer usa-footer
usa-footer-big usa-footer--big
usa-footer-slim usa-footer--slim
usa-footer-address usa-footer__address
usa-footer-collapsible usa-footer__primary-content--collapsible
usa-footer-contact-heading usa-footer__contact-heading
usa-footer-contact-links usa-footer__contact-links
usa-footer-contact-info usa-footer__contact-info
usa-footer-logo usa-footer__logo
usa-footer-logo-heading usa-footer__logo-heading
usa-footer-logo-img usa-footer__logo-img
usa-footer-nav usa-footer__nav
usa-footer-primary-content usa-footer__primary-content
usa-footer-primary-link usa-footer__primary-link
usa-footer-primary-section usa-footer__primary-section
usa-footer-return-to-top usa-footer__return-to-top
usa-footer-secondary-link usa-footer__secondary-link
usa-footer-secondary-section usa-footer__secondary-section
usa-footer-social-links usa-footer__social-links
usa-social-link usa-social-link
usa-social-link-facebook usa-social-link--facebook
usa-social-link-rss usa-social-link--rss
usa-social-link-twitter usa-social-link--twitter
usa-social-link-youtube usa-social-link--youtube
usa-sign_up-block usa-sign-up
usa-sign_up-header usa-sign-up__heading


Beta 5 Beta 6
usa-form usa-form
usa-form-large usa-form--large
usa-input-medium usa-input--medium
usa-input-small usa-input--small
usa-form-note usa-form__note

graphic list

Beta 5 Beta 6
usa-graphic-list usa-graphic-list
usa-graphic-list-heading usa-graphic-list__heading
usa-graphic-list-row usa-graphic-list__row


Beta 5 Beta 6
usa-current usa-current
usa-header usa-header
usa-header-basic usa-header--basic
usa-header-megamenu usa-header--megamenu
usa-header-extended usa-header--extended
usa-header-extended-megamenu usa-header-extended-megamenu
usa-logo usa-logo
usa-logo-text usa-logo__text
usa-megamenu usa-megamenu
usa-menu-btn usa-menu-btn
usa-nav usa-nav
usa-nav-container usa-nav__container
usa-nav-inner usa-nav__inner
usa-nav-link usa-nav__link
usa-nav-primary usa-nav__primary
usa-nav-submenu usa-nav__submenu
usa-navbar usa-navbar
usa-overlay usa-overlay
usa-search usa-search


Beta 5 Beta 6
usa-hero usa-hero
usa-hero-callout usa-hero__callout
usa-hero-callout-alt usa-hero__callout-alt
usa-hero-heading usa-hero__heading


Beta 5 Beta 6
usa-layout-docs-main usa-layout__docs-main
usa-layout-docs-sidenav usa-layout__docs-sidenav

media block

Beta 5 Beta 6
usa-media_block-body usa-media-block__body
usa-media_block-img usa-media-block__img


Beta 5 Beta 6
usa-accordion-button usa-accordion__button
usa-megamenu usa-megamenu
usa-mobile-nav-active usa-mobile-nav--active
usa-nav usa-nav
usa-nav-close usa-nav__close
usa-nav-container usa-nav__container
usa-nav-primary usa-nav__primary
usa-nav-primary-item usa-nav__primary-item
usa-nav-secondary usa-nav__secondary
usa-nav-secondary-item usa-nav__secondary-item
usa-nav-secondary-links usa-nav__secondary-links
usa-nav-submenu usa-nav__submenu
usa-nav-submenu-item usa-nav__submenu-item
usa-nav-submenu-list usa-nav__submenu-list
usa-nav-submenu-list-item usa-nav__submenu-list-item
usa-navbar usa-navbar
usa-search usa-search
Beta 5 Beta 6
usa-search usa-search
usa-search-big usa-search--big
usa-search-small usa-search--small
usa-search-input usa-search__input
usa-search-submit usa-search__submit
usa-search-submit-text usa-search__submit-text


Beta 5 Beta 6
usa-section usa-section
usa-section-dark usa-section--dark
usa-section-light usa-section--light


Beta 5 Beta 6
usa-sidenav usa-sidenav
usa-sidenav-sublist usa-sidenav__sublist


Beta 5 Beta 6
usa-skipnav usa-skipnav

Version 2.0.0 Beta 5

February 20, 2019

Bug fixes

  • The borderless table variant now displays properly in prose scope (https://github.com/uswds/uswds/pull/2881)
  • Grid columns now display properly when your project doesn’t explicitly include component styles (https://github.com/uswds/uswds/pull/2900)
  • Extra large content no longer breaks fill and auto columns. (https://github.com/uswds/uswds/pull/2900)
  • List items now have a maximum width, similar to their <p> counterparts. Additionally, when a list is the last child of a container, it now does have any bottom margin. Thanks @adunkman! (https://github.com/uswds/uswds/pull/2906)
  • Media query styling now applies to print jobs, fixing a number of current issues with print output. (https://github.com/uswds/uswds/pull/2910)


More up-to-date node dependency (https://github.com/uswds/uswds/pull/2900) We updated the required node version to the current LTS version of node (10.15.1) and updated our dependencies to build properly in this environment.

Now we’re exposing some internal component variables to user-accessible settings (https://github.com/uswds/uswds/pull/2901) Here’s what we added:

// Accordion
$theme-accordion-border-width:        0.5;
$theme-accordion-border-color:        'base-lightest';

// Alert
$theme-alert-bar-width:               1;
$theme-alert-icon-size:               4;
$theme-alert-padding-x:               2.5;

// Banner
$theme-button-stroke-width:           2px;

// Footer
$theme-input-select-border-width:     2px;
$theme-input-select-size:             2.5;
$theme-input-state-border-width:      0.5;

We expanded and improved our system color families and theme defaults These new colors are a bit more harmonious, and have a better 1.x-to-2.0 conversion.

  • Added a blue-cool color family (https://github.com/uswds/uswds/pull/2902)
  • Added a red-cool family (https://github.com/uswds/uswds/pull/2911)
  • Saturated gold-20v (https://github.com/uswds/uswds/pull/2911)
  • Desaturated blue-cool standard colors and added vivid variants (https://github.com/uswds/uswds/pull/2911)
  • Made small hue consistency modifications to the following families (https://github.com/uswds/uswds/pull/2911):

    • blue-warm
    • blue
    • gold
    • gray-cool
    • green-cool
    • mint
    • orange
    • red-cool
    • red
    • yellow
  • Updated the following theme palettes for better consistency with 1.x defaults (https://github.com/uswds/uswds/pull/2911)
    • base
    • primary
    • accent-cool
    • error
    • warning
    • success
    • info

Here’s what changed:

base changes

$theme-color-base-family:           'gray-cool';
$theme-color-base-lightest:         'gray-5';
$theme-color-base-lighter:          'gray-cool-10';
$theme-color-base-light:            'gray-cool-30';
$theme-color-base:                  'gray-cool-50';
$theme-color-base-dark:             'gray-cool-60';
$theme-color-base-darker:           'gray-cool-70';
$theme-color-base-darkest:          'gray-90';
$theme-color-base-ink:              'gray-90';

primary changes

$theme-color-primary-lighter:       '#{$theme-color-primary-family}-10';
$theme-color-primary-vivid:         'blue-warm-60v';

accent-warm changes

$theme-color-accent-warm-family:    'orange';
$theme-color-accent-warm-lighter:   '#{$theme-color-accent-warm-family}-10';
$theme-color-accent-warm-light:     '#{$theme-color-accent-warm-family}-20v';
$theme-color-accent-warm:           '#{$theme-color-accent-warm-family}-30v';
$theme-color-accent-warm-darker:    '#{$theme-color-accent-warm-family}-60';

error changes

$theme-color-error-family:     'red-warm';
$theme-color-error-light:      '#{$theme-color-error-family}-30v';
$theme-color-error:            '#{$theme-color-error-family}-50v';
$theme-color-error-dark:       'red-60v';
$theme-color-error-darker:     'red-70';

warning changes

$theme-color-warning-lighter:  'yellow-5';
$theme-color-warning-light:    'yellow-10v';
$theme-color-warning-darker:   '#{$theme-color-warning-family}-50v';

success changes

$theme-color-success-light:    '#{$theme-color-success-family}-20v';
$theme-color-success-darker:   '#{$theme-color-success-family}-60';

info changes

$theme-color-info-darker:      'blue-cool-60';

USWDS 1.x to 20 color conversion

uswds conversion table

Current USWDS theme defaults


Current USWDS state defaults


Version 2.0.0 Beta 4

November 14, 2018

Note: Items with a ⚠️ icon are potentially breaking changes


  • Welcome @greensteph to the USWDS Core team 🎉

Bug fixes

  • Checkboxes now print correctly (link)
  • The $theme-font-definitions variable for adding custom font definitions is no longer overridden by the system default. Thanks for the heads up @yomatters! (link)
  • Added the missing u-text-indent() mixin. Thanks for the heads up @jeremyzilar! (link)
  • Fixed errors when compiling with Dart Sass or Jekyll. Thanks to Matt Langan in the #uswds-public channel for surfacing this! (link)


  • u-pin() mixin now uses the format u-pin-[side] instead of u-pin([side]) for simplicity

    Example: u-pin-y instead of u-pin('y') — though the latter will still work

  • Removed u-list-reset() since there’s already add-list-reset() but also included list-reset() as a clone of add-list-reset() for backward compatibility

    ⚠️ Replace any instance of u-list-reset with add-list-reset

  • Added u-radius-[modifier]() mixins.

    Example: u-pin-radius-left('pill')

This is a big one with lots of potentially breaking changes. See the pull request and the v2 documentation for a more complete record of the changes and the final palette names.

⚠️ If you’ve experimented with using palettes for your utility classes, you will need to update to the new names or you will get Palette not found in the registry errors when you compile.

  • Palette naming is additive: each subset has the palette name of its parent, plus a subset suffix
  • Default palettes use palette-[property]-default not palette-system-[property]
  • Palettes with no suffix include all tokens in the category
  • Palettes attempt to mimic the token categories/functions/properties: like units, color, and font
  • Palettes attempt to mimic the token categories/functions/properties: like units, color, and font
  • Palettes have a relative subset suffix (like -small, -smaller)
  • Palettes that include all values in a set, have no special suffix (-all goes away)
  • Any palette that had a -negative grouping now also has a corresponding -positive
  • The -negative and -positive groups now appear before the sizing groups
  • The font-weights category is now font-weight
  • Numeric font-weights use the -system suffix, not -numeric

The .usa-prose component allows developers to style unclassed elements within a scoped container. However, this could result in unpredictable behavior (like style specificity errors) if other components are inside in a usa-prose container. Now, usa-prose only affects direct children (using the > selector). See the pull request for more details and context.

⚠️ Make sure any content you want styled with usa-prose is a direct child of usa-prose — this could mean adding usa-prose to grid-col or section elements previously styled simply by being inside usa-prose.

  • Better, more readable numbers
  • Narrower italic
  • Thickened light and normal weights
  • Better spacing of tabular figures


  • Now data tables are responsive, even at very narrow widths! Thanks for the technique @line47! (link)
  • Lots of updated docs around utilities and palettes (link)
  • Removed the utility output section since it was largely redundant with the utility examples and the style tokens sections (link)
  • Added a banner to the main site that directs folks to the v2 Beta site. (link)
  • Removed unsupported webp images
  • Fixed a bunch of typos 🎉
  • Fixed code block wrapping
  • Fixed the navigation on the Developers page (link)
  • Fixed some problems with svg rendering (link)

Version 2.0.0 Beta 3

October 29, 2018

Bug Fixes

  • Repair u-border() mixin to accept valid units string tokens like '05' and '105' (https://github.com/uswds/uswds/pull/2860)
    • Thanks to the USWDS public Slack channel for surfacing this issue!


  • Added a few new token function clones to make them simpler to type. Note: All the previous functions continue to work as-is, this just adds some new functions that duplicate the functionality with a shorter name (https://github.com/uswds/uswds/pull/2861)
    • font-size()size()
    • font-size()fs()
    • font-family()family()
    • font-family()ff()
  • Update to newest Public Sans (https://github.com/uswds/uswds/pull/2862)
    • A small update to Public Sans that tweaks the b and d characters, as well as the dot on the i character


  • Expanded the Style section and renamed it Style tokens to be explicit about its content
  • Added the following section to Style Tokens
    • Overview
    • Color
      • Using color
      • Theme color tokens
      • State color tokens
      • System color tokens
    • Typesetting
      • Using type
      • Font family
      • Font size
      • Font weight
      • Letterspacing
      • Line height
      • Measure
    • Flex
    • Opacity
    • Order
    • Shadow
    • Spacing units
    • Z-index
  • Updated the fonts and heading styles
  • Updated the appearance of the docs sidebar to better display nested pages
  • Added a new USWDS logo
  • Added updated design principles

Version 1.6.9

October 15, 2018


  • Addressed a potential vulnerability with mem@1.1.0 by updating to yargs@12.0.2 (https://github.com/uswds/uswds/commit/8aad13c9d4e88f549dd761f1b2d4b91c7921ecc4)


  • Improved the print styling of checkboxes to properly show checked boxes. (https://github.com/uswds/uswds/pull/2811) Thanks @David-Way

Version 2.0.0 Beta 2

October 15, 2018


  • Say goodbye to @maya
  • Welcome @saracope to the core team
  • Added a new build process to uswds-site to modularize the CSS output and compile only the Sass necessary to see the change. For instance, utility classes, layout grid, fonts, and USWDS components don’t need to be re-generated when making a change to custom Sass. (https://github.com/uswds/uswds-site/pull/674)
    • Add new gulp scripts and npm scripts to process only the necessary Sass
    • Add conditional stylesheets to uswds-site that load individual CSS modules when in the local environment and a single, minified CSS file when built through Federalist
    • This can speed up most builds by about 10x!


  • Added Public Sans to its own repo: uswds/public-sans
  • Added basic gulp pipeline to its own repo: uswds/uswds-gulp


  • Updated the font license information in LICENSE.md (https://github.com/uswds/uswds/pull/2800)

Bug fixes

  • Fixed a typo that prevented the gray, gray-warm, and gray-cool grade 60 colors from appearing (https://github.com/uswds/uswds/pull/2801)
  • Gray cool and Gray warm were reversed in token data. Now they aren’t and should output correctly. (https://github.com/uswds/uswds/pull/2823)
  • Added the ui font family to line-height. Now you can use something like line-height('ui', 3) (https://github.com/uswds/uswds/pull/2824)
  • Fixed a problem with the display of some items in our documentation (https://github.com/uswds/uswds-site/issues/673)
  • Addressed a potential vulnerability with mem@1.1.0 by updating to yargs@12.0.2 (https://github.com/uswds/uswds/pull/2842)
  • Fixed a bug where a elements classed with usa-button variants were being overridden by usa-button:visited styles. (https://github.com/uswds/uswds/pull/2827)
    • Thanks @stphnwlkr!


  • Added a AAA magic number to the docs and updated contrast references to WCAG 2.0 (https://github.com/uswds/uswds-site/pull/656)
  • Removed utility classes from any component (https://github.com/uswds/uswds/pull/2823)
    • ⚠️ breaking change: Removes a flex-justify utility from the footer component and revises footer markup to add this rule to component code. This markup would need to be updated.
  • Modified some nunjucks templates to improve the rendering of markup code in the components docs (https://github.com/uswds/uswds/pull/2823)
  • Added any public-facing mixin into files within the core/mixins folder so they can be imported without importing any styles (https://github.com/uswds/uswds/pull/2844)
  • Removed _uswds-theme.scss stylesheet from the theme stylesheets. This was an abstraction file that collected all the settings files together, but it proved a little confusing and may have been a premature optimization. Now all the settings files are included directly in styles.scss (https://github.com/uswds/uswds/pull/2830)
  • The ‘object’ namespace was causing confusion and wasn’t useful enough to justify its inclusion. (https://github.com/uswds/uswds/pull/2829)
    • Removed object from namespace options since it proved confusing to users
    • Output all utilities with utility namespace
    • Add add- manually to those utilities that previously added them with the object namespace
  • Now the letterspacing function can accept numerical equivalents and not just 'ls-[token]' strings. So ls(-2) is now valid. (https://github.com/uswds/uswds/pull/2826)
  • Added a $theme-show-compile-warnings setting (default: true) to show compile warnings when using false or nonstandard tokens (https://github.com/uswds/uswds/pull/2828)
  • Use the word ‘token’ instead of ‘value’ in compile errors to align with our naming convention (https://github.com/uswds/uswds/pull/2828)
  • Use ‘system’ instead of ‘uswds’ in palette names (ex: $palette-font-system-mono-micro instead of $palette-font-uswds-mono-micro) to align with our naming convention. (https://github.com/uswds/uswds/pull/2828)
    • ⚠️ Breaking change: Any palette using uswds in its name needs to be update to use system instead, as show above.


  • Removed out of date references and added notes when some documentation or features were consipicuously absent (https://github.com/uswds/uswds-site/pull/657)
    • Removed references to palette variables
    • Updated USWDS 2.0 token references
    • Added notes when documentation is notably not in with USWDS 2.0 (typesetting, for instance)
  • Updated readme with USWDS 2.0-specific information (https://github.com/uswds/uswds/pull/2819)
    • Installing using npm
    • Using the USWDS package
    • Sass and theme settings
    • Sass compilation requirements
    • Customization, theming, and tokens
  • Added design principles and design notes to the Public Sans readme (https://github.com/uswds/public-sans/issues/18)
  • Fixed the order of colors in the the system colors sidenav to reflect the actual order of the content (https://github.com/uswds/uswds-site/pull/665)
  • Updated our color guidance to include more specific guidance around contrast sensitivity and Irlen Syndrome. (https://github.com/uswds/uswds-site/pull/664)
    • Added references to the bottom of the page
    • Included new guidance on using color for readability
    • Thanks @vizionsinmotion!

Version 2.0.0-beta

October 01, 2018

USWDS 2.0 is a major rewrite of the entire project. The most notable changes are summarized below, followed by more specific changes to relevant components.

New ✨

  • Add utilities (#2289)

CSS applied to classes not HTML

$theme-content-styles will add base typography styles inside .usa-prose class, as global elements applied to base HTML, or none at all.

Element styles added to scoping

  • Paragraph text (p)
  • Links (a)
  • Headings (h1-h6)
  • Lists (ul, ol, li)
  • Table (table)

New or updated elements and classes

  • .usa-button (button) (class already existed)
  • .usa-list (ul, ol)
  • .usa-table (table)
  • .usa-label (label) for HTML <label>s changed from Label component which is now tag
  • .usa-input (input)
  • .usa-select (select) - dropdown
  • .usa-textarea (textarea)
  • .usa-legend (legend)
  • .usa-tag changed from .usa-label which we’re now using for HTML <label>
  • .usa-checkbox-input [type=”checkbox”]
  • .usa-checkbox-label [type=”checkbox”]
  • .usa-radio-input [type=”radio”]
  • .usa-radio-label [type=”radio”]
  • .usa-range [type=”range”]

*All former elements will need to use these classes to display properly.

By component

This list highlights key changes by component between v1.x.x and v2.0.0.



  • Deprecated the float-based grid system, Bourbon Neat, in favor of a flexbox system


  • Must add usa-button class alongside variant buttons, e.g. usa-button button-secondary


  • Formerly called “labels”
  • Must add usa-tag class alongside variant tags, i.e. usa-tag usa-tag-big




  • Update accordions to be more semantic and accessible (#2360, #2406, #2360) [breaking change]


Form controls

Form templates

Side navigation


  • Clicking away will close the header navigation dropdown (#2669, #2617)


  • Fix footer class naming inconsistency (#2583) [breaking change]

Version 1.6.8

August 06, 2018


  • Add range slider that already existed in the Sass to Fractal (#2644, #2374)


  • Fix headers that were not displaying in IE 9-11 (#2643, #2637).
    • This was an issue introduced in version 1.6.7 (#2574) when we updated ESLint to use the Airbnb style guide.
  • Fix Firefox zooming bug in extended header (#2635, #2631)
  • Fix improper nesting in big footer that caused invalid HTML (#2620, #1659)
  • Fix header mega menu HTML validation (#2645, #2634)