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

April 28, 2021

What’s new in USWDS 2.11.2


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


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: An icon list reinforces the meaning and visibility of individual list items with a leading icon.
  • Modal: A modal disables page content and focuses the user’s attention on a single task or message.
  • Input prefix or 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: A sorted column changes the row ordering based on alphabetical or numeric cell values.
  • Links: 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: 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.


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.


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


  • 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: 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: A process list displays the steps or stages of important instructions or processes.
  • Site alert: A site alert communicates urgent sitewide information.
  • 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): We added a “tile” display to provide a larger, more obvious touch target for checkboxes.
  • Icons: We improved our default icon support and now provide a broader selection of consistent icons in our package.
  • Radio button (tile display): We added a “tile” display to provide a larger, more obvious touch target for radio buttons, as well.
  • Table (mobile and data display): 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:

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


  • 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

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

Include inline

<!DOCTYPE html>
      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()}
    <link rel="stylesheet" href="assets/uswds/css/uswds.min.css" />
    <script src="assets/uswds/js/uswds.min.js"></script>

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. 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 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ñolVisite 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 Alpha 0

September 25, 2020

Alpha release for testing only.

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


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.


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.

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

// 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";
// 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.

// 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";
// theme-modules.scss
@forward "../node_modules/uswds/dist/uswds";
@forward "theme-custom-styles";
// 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.

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

// theme-modules.scss
@forward "theme-packages";
@forward "theme-custom-styles";

For packages, include individual component packages…

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

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

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

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

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

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

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

// 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.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: The identifier communicates a site’s parent agency and displays agency links required by federal laws and policies.
  • Step indicator: A step indicator updates users on their progress through a multi-step process.
  • 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: 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)