Migrating to USWDS 2

USWDS 2 is a major rewrite of the entire codebase and migration can be complicated. We’ve outlined the high-level changes any project will need to implement, followed by more specific component changes and complete release notes from each related release.

Note: If you’re migrating, expect that every USWDS component on your site will change, and that USWDS v1 functions, mixins, and variables will not work as expected. We will expand and improve this page as we learn from teams that are migrating their own projects. Leave feedback and make suggestions at this site’s GitHub page.


Every component has changed in some way or another from USWDS v1 to USWDS v2. There are also some important conceptual differences in v2 — most notably, the introduction of design tokens which, in most cases, are used somewhat differently from v1 variables. Design tokens are at the core of the USWDS 2 design language and we expect that sites will transition toward using these tokens exclusively for their projects, though this may be an incremental process.

  • Now USWDS CSS almost always applies to classes not directly to HTML elements.
  • We’ve moved toward a flatter, more modular coding style.
  • We changed our overall naming system to BEM.
  • The values we apply to rules are drawn from a fixed palette of value keys called design tokens. We use functions and mixins to apply these tokens to our Sass rules.
  • A suite of settings files that use design tokens replace a single variables.

Integrating tokens

You can think of a design token as a key that unlocks a specific value. They are distinct from variables in that they are usually strings or unitless numbers (like 'sm' or 2) instead of something like $variable. Unlike variables, system tokens are constants and not meant to be modified. They aren’t included directly in component Sass like color: $primary, rather the mechanism by which the final display value is unlocked is a function, mixin, or utility class, like color: color('primary').

The design tokens section of the documentation describes how we use design tokens in depth, but here’s a simple example:

In settings files

Settings variables are assigned design tokens.

$theme-site-max-width:              'desktop';
$theme-site-margins-breakpoint:     'desktop';
$theme-site-margins-width:          4;
$theme-site-margins-mobile-width:   2;

In component Sass

We use tokens (or tokens expressed as variables) in mixins and functions.

.usa-example {
  @include u-padding-x($theme-site-margins-mobile-width);
  max-width: units($theme-site-max-width);

  @include at-media($theme-site-margins-breakpoint) {
    @include u-padding-x($theme-site-margins-width);


.usa-example {
  @include u-padding-x(2);
  max-width: units('desktop');

  @include at-media('desktop') {
    @include u-padding-x(4);


To change your components from USWDS v1 to USWDS v2, you’ll need to update your classes to the BEM naming convention. We’ll walk through how to do that by looking at the alert component.

  • usa-alert is the block, the outermost parent element of the component. No need to change anything from v1 to v2.
  • The “informative status” or “info” alert is a variation of the alert component. In BEM, this is called the modifier and is separated by two dashes (usa-alert--info).
  • There are several items nested inside the alert component: a body, heading, and text. These are called the elements and are separated by two underscores (usa-alert__body, usa-alert__heading, usa-alert__text)

This is what the HTML markup looks like going from v1 to v2:


<div class="usa-alert usa-alert-info" >
  <div class="usa-alert-body">
    <h3 class="usa-alert-heading">Information Status</h3>
    <p class="usa-alert-text">An alert message.</p>


<div class="usa-alert usa-alert--info" >
  <div class="usa-alert__body">
    <h3 class="usa-alert__heading">Informative status</h3>
    <p class="usa-alert__text">An alert message.</p>

Mixins and functions

All Bourbon functions and mixins deprecated
@include media() @include at-media(spacing-units)
@include focus deprecated
@include font-smoothing @mixin add-knockout-font-smoothing
@include allow-layout-classes deprecated
@include display-icon() now uses tokens for spacing units
@include usa-sidenav-list @include nav-list
@include usa-sidenav-sublist @include nav-sublist

Spacing units

Spacing units in USWDS 2 are based on multiples of 8px with a handful of half sizes (0.5, 1.5, and 2.5), plus 1px and 2px. You’ll need to update your project spacing when you migrate from v1 to v2 to use these new units tokens.

Negative values should use the same migration pattern as positive values. See the units section for their naming convention and how to use negative tokens in functions, mixins, settings, and utilities.

Rule of thumb: We recommend rounding up to the larger spacing token when you have an existing value that falls between tokens. Only round down if the existing value is within 2px of the token and less than half of the distance between the bigger token and the smaller token. For instance 14px would round up to 2 units since 14px is halfway between 1.5 units (12px) and 2 units (16px).

USWDS v1 USWDS v2 Function Mixin Utility Setting Value
1px 1px units(1px) u-margin-top(1px) .margin-top-1px 1px 1px
2px 2px units(2px) u-margin-top(2px) .margin-top-2px 2px 2px
3px 0.5 units units(0.5) u-margin-top(0.5) .margin-top-05 0.5 4px
4px 0.5 units units(0.5) u-margin-top(0.5) .margin-top-05 0.5 4px
5px 0.5 units units(0.5) u-margin-top(0.5) .margin-top-05 0.5 4px
6px 1 unit units(1) u-margin-top(1) .margin-top-1 1 8px
7px 1 unit units(1) u-margin-top(1) .margin-top-1 1 8px
8px 1 unit units(1) u-margin-top(1) .margin-top-1 1 8px
9px 1 unit units(1) u-margin-top(1) .margin-top-1 1 8px
10px 1.5 units units(1.5) u-margin-top(1.5) .margin-top-105 1.5 12px
11px 1.5 units units(1.5) u-margin-top(1.5) .margin-top-105 1.5 12px
12px 1.5 units units(1.5) u-margin-top(1.5) .margin-top-105 1.5 12px
13px 1.5 units units(1.5) u-margin-top(1.5) .margin-top-105 1.5 12px
14px 2 units units(2) u-margin-top(2) .margin-top-2 2 16px
15px 2 units units(2) u-margin-top(2) .margin-top-2 2 16px
16px 2 units units(2) u-margin-top(2) .margin-top-2 2 16px
17px 2 units units(2) u-margin-top(2) .margin-top-2 2 16px
18px 2.5 units units(2.5) u-margin-top(2.5) .margin-top-205 2.5 20px
19px 2.5 units units(2.5) u-margin-top(2.5) .margin-top-205 2.5 20px
20px 2.5 units units(2.5) u-margin-top(2.5) .margin-top-205 2.5 20px
25px 3 units units(3) u-margin-top(3) .margin-top-3 3 24px
30px 4 units units(4) u-margin-top(4) .margin-top-4 4 32px
35px 5 units units(5) u-margin-top(5) .margin-top-5 5 40px
40px 5 units units(5) u-margin-top(5) .margin-top-5 5 40px


USWDS v1 variables have been replaced with new variables called settings. Theme settings variables control the appearance of USWDS components and the values of USWDS theme tokens.

USWDS v1 USWDS v2 v2 default Kind Settings file Note
$em-base $theme-root-font-size 16px px typography

only applies when $theme-respect-user-font-size is set to false

$base-font-size $theme-body-font-size sm size typography
$small-font-size $theme-small-font-size 2xs size typography
$lead-font-size $theme-lead-font-size lg size typography
$title-font-size $theme-display-font-size 3xl size typography
$h1-font-size $theme-h1-font-size 2xl size typography
$h2-font-size $theme-h2-font-size xl size typography
$h3-font-size $theme-h3-font-size lg size typography
$h4-font-size $theme-h4-font-size sm size typography
$h5-font-size $theme-h5-font-size xs size typography
$h6-font-size $theme-h6-font-size 3xs size typography
$base-line-height $theme-body-line-height 5 line-height typography
$heading-line-height $theme-heading-line-height 2 line-height typography
$lead-line-height $theme-lead-line-height 6 line-height typography
$font-sans $theme-font-type-sans source-sans-pro family typography
$font-serif $theme-font-type-serif merriweather family typography
$font-normal $theme-font-weight-normal 400 weight typography
$font-bold $theme-font-weight-bold 700 weight typography
$color-blue n/a blue-60v

use color token

$color-blue-darker n/a blue-warm-70v

use color token

$color-blue-darkest n/a blue-warm-80v

use color token

$color-aqua n/a cyan-30v

use color token

$color-aqua-dark n/a cyan-40v

use color token

$color-aqua-darkest n/a blue-cool-60v

use color token

$color-aqua-light n/a blue-cool-20v

use color token

$color-aqua-lightest n/a blue-cool-5v

use color token

$color-red n/a red-cool-50v

use color token

$color-red-dark n/a red-60v

use color token

$color-red-darkest n/a red-70v

use color token

$color-red-light n/a red-30

use color token

$color-red-lightest n/a red-cool-10v

use color token

$color-white n/a white

use color token

$color-black n/a black

use color token

$color-black-light n/a gray-90

use color token

$color-gray-dark n/a gray-cool-70

use color token

$color-gray n/a gray-cool-60

use color token

$color-gray-medium n/a gray-50

use color token

$color-gray-light n/a gray-cool-30

use color token

$color-gray-lighter n/a gray-cool-10

use color token

$color-gray-lightest n/a gray-cool-5

use color token

$color-gray-warm-dark n/a gray-warm-70

use color token

$color-gray-warm-light n/a gray-warm-10

use color token

$color-gray-cool-light n/a blue-warm-10

use color token

$color-gold n/a gold-20v

use color token

$color-gold-light n/a yellow-20v

use color token

$color-gold-lighter n/a gold-10v

use color token

$color-gold-lightest n/a gold-5v

use color token

$color-green n/a green-cool-50v

use color token

$color-green-light n/a green-cool-40

use color token

$color-green-lighter n/a green-cool-20

use color token

$color-green-lightest n/a green-cool-5

use color token

$color-cool-blue n/a blue-warm-60

use color token

$color-cool-blue-light n/a blue-warm-50

use color token

$color-cool-blue-lighter n/a blue-warm-30

use color token

$color-cool-blue-lightest n/a blue-warm-10

use color token

$color-purple n/a violet-70v

use color token

$color-primary $theme-color-primary blue-60v color color
$color-primary-darker $theme-color-primary-dark blue-warm-70v color color
$color-primary-darkest $theme-color-primary-darker blue-warm-80v color color
$color-primary-alt $theme-color-accent-cool cyan-30v color color
$color-primary-alt-dark $theme-color-accent-cool-dark blue-cool-40v color color
$color-primary-alt-darkest $theme-color-accent-cool-darker blue-cool-60v color color
$color-primary-alt-light $theme-color-accent-cool-light blue-cool-20v color color
$color-primary-alt-lightest $theme-color-accent-cool-lighter blue-cool-5v color color
$color-secondary $theme-color-secondary-vivid red-cool-50v color color
$color-secondary-dark $theme-color-secondary-dark red-60v color color
$color-secondary-darkest $theme-color-secondary-darker red-70v color color
$color-secondary-light $theme-color-secondary-light red-30 color color
$color-secondary-lightest $theme-color-secondary-lighter red-cool-10v color color
$color-base $theme-color-base-darkest black-90 color color
$color-focus $theme-focus-color blue-40v color general
$color-visited $theme-link-visited-color violet-70v color color
$color-shadow n/a

use shadow tokens

$color-transparent n/a transparent

use color token

$small-screen n/a mobile-lg

use width token

$medium-screen n/a tablet

use width token

$large-screen n/a desktop-lg

use width token

$grid-columns-small n/a

use layout grid

$grid-columns-medium n/a

use layout grid

$grid-columns-large n/a

use layout grid

$small n/a

use at-media() mixin and width tokens

$medium n/a

use at-media() mixin and width tokens

$large n/a

use at-media() mixin and width tokens

$asset-path n/a

use $theme-font-path and $theme-image-path

$font-path $theme-font-path ../fonts path typography

relative to the compiled css

$image-path $theme-image-path ../img path general

relative to the compiled css

$asset-pipeline n/a

this functionality is not implemented in v2

$text-max-width $theme-text-measure 4 measure typography
$lead-max-width $theme-lead-measure 6 measure typography
$site-max-width $theme-site-max-width desktop units spacing
$site-margins $theme-site-margins-width 4 units spacing
$site-margins-mobile $theme-site-margins-mobile-width 2 units spacing
$article-max-width n/a
$input-max-width $theme-input-max-width mobile-lg units components
$label-border-radius n/a

not used in v2 — currently sm

$checkbox-border-radius $theme-checkbox-border-radius sm border-radius|units components
$border-radius $theme-border-radius-md 0.5 units spacing

use alongside $theme-border-radius-sm and $theme-border-radius-lg. sets value of sm, md, and lg border-radius theme tokens

$button-border-radius $theme-button-border-radius md border-radius|units components
$box-shadow n/a

use shadow tokens

$focus-outline $theme-focus-width 0.5 units general
$focus-spacing $theme-focus-offset 0 units general
$nav-width $theme-header-max-width desktop units components

The maximum width of header and nav.

$nav-width $theme-header-min-width desktop units components

The minimum width of the header and nav. In practice, this is the breakpoint at which the mobile nav becomes the desktop nav. Used in media queries.

$sidenav-current-border-width $theme-sidenav-current-border-width 0.5 units components
$hit-area n/a

no longer a user-settable variable (now $size-touch-target)

$spacing-x-small n/a

use spacing tokens

$spacing-small n/a

use spacing tokens

$spacing-md-small n/a

use spacing tokens

$spacing-medium n/a

use spacing tokens

$spacing-large n/a

use spacing tokens

Migration by component

Note: While this page should serve as a reference for the kind of class name changes in USWDS v2, most components have additional markup changes. When in doubt, replace your existing v1 component with the updated v2 markup and don’t count on find-and-replaces to work effectively.

Layout grid

  • Deprecated the float-based grid system (and Bourbon Neat) in favor of a flexbox grid system
  • Grid no longer makes assumptions about reponsive behavior. Breakpoints are specified manually.
  • Grid column classes must be enclosed by a grid-row.
  • See the layout grid documetation for more details.
.usa-grid .grid-container
.usa-grid-full .grid-container.padding-x-0
.usa-width-one-whole .grid-col-12
.usa-width-one-half .grid-col-6
.usa-width-one-third .grid-col-4
.usa-width-two-thirds .grid-col-8
.usa-width-one-fourth .grid-col-3
.usa-width-three-fourths .grid-col-9
.usa-width-one-sixth .grid-col-2
.usa-width-five-sixths .grid-col-10
.usa-width-one-twelfth .grid-col-1
.usa-width-five-twelfths .grid-col-5
.usa-width-seven-twelfths .grid-col-7
.usa-offset-one-twelfth .grid-offset-1
.usa-offset-one-sixth .grid-offset-2
.usa-offset-one-fourth .grid-offset-3
.usa-offset-one-third .grid-offset-4
.usa-offset-five-twelfths .grid-offset-5
.usa-offset-one-half .grid-offset-6
.usa-offset-seven-twelfths .grid-offset-7
.usa-offset-two-thirds .grid-offset-8
.usa-offset-three-fourths .grid-offset-9
.usa-offset-five-sixths .grid-offset-10
.usa-offset-eleven-twelfths .grid-offset-11


a .usa-link
p .usa-paragraph
h1 .usa-prose > h1
h2 .usa-prose > h2
h3 .usa-prose > h3
h4 .usa-prose > h4
h5 .usa-prose > h6
h6 .usa-prose > h6
ol ol.usa-list
ul ul.usa-list
.usa-background-dark .usa-dark-background
.usa-content .usa-content
.usa-content-list .usa-content-list
.usa-display .usa-display
.usa-external_link .usa-external-link
.usa-external_link-alt .usa-external-link-alt
.usa-font-lead .usa-intro
.usa-heading-alt deprecated: use utilities
.usa-sans deprecated: use utilities
.usa-serif deprecated: use utilities
.usa-text-small deprecated: use utilities


.usa-button .usa-button
.usa-button-active .usa-button.usa-button--active
.usa-button-big .usa-button.usa-button--big
.usa-button-disabled .usa-button.usa-button--disabled
.usa-button-gray .usa-button.usa-button--base
.usa-button-hover .usa-button.usa-button--hover
.usa-button-primary .usa-button
.usa-button-primary-alt .usa-button.usa-button--accent-cool
.usa-button-secondary .usa-button.usa-button--outline
.usa-button-secondary-disabled .usa-button.usa-button--outline.usa-button--disabled
.usa-button-secondary-inverse .usa-button.usa-button--outline.usa-button--inverse
.usa-button-secondary-inverse-disabled .usa-button.usa-button--outline.usa-button--inverse.usa-button--disabled
.usa-button-red .usa-button.usa-button--secondary
.usa-button-unstyled .usa-button.usa-button--unstyled
.usa-focus .usa-focus


.usa-embed-container .usa-embed-container


media-link .usa-media-link


[type=checkbox] .usa-checkbox__input
[type=checkbox] + label .usa-checkbox__label
[type=radio] .usa-radio__input
[type=radio] label .usa-radio__label
[type=range] .usa-range
fieldset .usa-fieldset
input .usa-input
label .usa-label
legend .usa-legend
select .usa-select
textarea .usa-textarea
.usa-date-of-birth .usa-memorable-date
.usa-fieldset-inputs deprecated: see new checkbox and radio markup
.usa-form-group .usa-form-group
.usa-form-group-day .usa-form-group.usa-form-group--day
.usa-form-group-month .usa-form-group.usa-form-group--month
.usa-form-group-year .usa-form-group.usa-form-group--year
.usa-form-hint .usa-hint
.usa-input-error .usa-form-group.usa-form-group--error
.usa-input-inline .usa-input.usa-input--inline
.usa-input-medium .usa-input.usa-input--medium
.usa-input-error .usa-input.usa-input--error
.usa-input-error-label .usa-label.usa-label--error
.usa-input-error-message .usa-error-message
.usa-input-inline-error .usa-input.usa-input--error
.usa-input-label-helper .usa-hint
.usa-input-label-required .usa-label.usa-label--required
.usa-input-optional deprecated: use .usa-hint for option text in a .usa-label
.usa-input-required deprecated: no longer recommended
.usa-input-success .usa-input.usa-input--success
.usa-input-tiny .usa-input.usa-input--small
.usa-unstyled-list (for checkboxes) div.usa-checkbox
.usa-unstyled-list (for radio buttons) div.usa-radio


li .usa-list li
ol ol.usa-list
ul ul.usa-list
.usa-unstyled-list .usa-list.usa-list--unstyled


media-link .usa-media-link


  • Formerly called “labels”
.usa-label .usa-tag
.usa-label-big .usa-tag.usa-tag--big


.usa-accordion .usa-accordion
.usa-accordion-bordered .usa-accordion.usa-accordion--bordered
.usa-accordion-button .usa-accordion__button
.usa-accordion-content .usa-accordion__content


.usa-alert .usa-alert
.usa-alert-error .usa-alert.usa-alert--error
.usa-alert-no_icon .usa-alert.usa-alert--no-icon
.usa-alert-slim .usa-alert.usa-alert--slim
.usa-alert-success .usa-alert.usa-alert--success
.usa-alert-warning .usa-alert.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.usa-alert--info
.usa-alert-paragraph .usa-alert__paragraph
.usa-alert-text .usa-alert__text
.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-gov .usa-banner__guidance
.usa-banner-guidance-ssl .usa-banner__guidance
.usa-banner-header .usa-banner__header
.usa-banner-header-expanded .usa-banner__header.usa-banner__header--expanded
.usa-banner-icon .usa-banner__icon
.usa-banner-inner .usa-banner__inner


.usa-checklist .usa-checklist
.usa-checklist li .usa-checklist__item
.usa-checklist-checked .usa-checklist__item.usa-checklist__item--checked
address .usa-footer__address
.usa-footer .usa-footer
.usa-footer-big .usa-footer.usa-footer--big
.usa-footer-big .usa-footer.usa-footer--big
.usa-footer-big-secondary-section .usa-footer__secondary-section
.usa-footer-big-logo-heading .usa-footer__logo-heading
.usa-footer-big-logo-img .usa-footer__logo-img
.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-medium .usa-footer
.usa-footer-nav .usa-footer__nav
.usa-footer-slim .usa-footer.usa-footer--slim
.usa-footer-slim-logo-heading .usa-footer__logo-heading
.usa-footer-slim-logo-img .usa-footer__logo-img
.usa-footer-primary-content .usa-footer__primary-content
.usa-footer-primary-content (collapsible) .usa-footer__primary-content.usa-footer__primary-content--collapsible
.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-topic deprecated
.usa-link-facebook .usa-social-link.usa-social-link--facebook
.usa-link-rss .usa-social-link.usa-social-link--rss
.usa-link-twitter .usa-social-link.usa-social-link--twitter
.usa-link-youtube .usa-social-link.usa-social-link--youtube
.usa-sign_up-block .usa-sign-up
.usa-sign_up-header .usa-sign-up__heading
.usa-social-links .usa-footer__social-links
.usa-social_link .usa-social-link

Form controls

.usa-additional_text deprecated: not used
.usa-checklist .usa-checklist
.usa-checklist li .usa-checklist__item
.usa-checklist-checked .usa-checklist__item.usa-checklist__item--checked
.usa-form .usa-form
.usa-form-large .usa-form.usa-form--large
.usa-form-note .usa-form__note
.usa-input-medium .usa-input.usa-input--medium
.usa-input-tiny .usa-input.usa-input--small
.usa-input-grid deprecated: use grid utilities
.usa-input-grid-small deprecated: use grid utilities
.usa-input-grid-medium deprecated: use grid utilities
.usa-input-grid-large deprecated: use grid utilities

Graphic list

.usa-graphic_list .usa-graphic-list
.usa-graphic_list h3 .usa-graphic-list__heading
.usa-graphic_list-row .usa-graphic-list__row
.usa-header .usa-header
.usa-logo .usa-logo
.usa-logo-text .usa-logo__text
.usa-menu-btn .usa-menu-btn
.usa-overlay .usa-overlay
.usa-header-basic .usa-header.usa-header--basic
.usa-navbar .usa-navbar
.usa-header-extended .usa-header.usa-header--extended
.usa-current .usa-current


.usa-hero .usa-hero
.usa-hero h2 .usa-hero__heading
.usa-hero-callout .usa-hero__callout
.usa-hero-callout-alt .usa-hero__callout-alt
.usa-hero-link deprecated: use utilities


.usa-layout-docs-main_content .usa-layout-docs__main
.usa-layout-docs-sidenav .usa-layout-docs__sidenav
.usa-layout-docs .usa-layout-docs

Media block

.usa-media_block .usa-media-block
.usa-media_block-body .usa-media-block__body
.usa-media_block-img .usa-media-block__img
.usa-accordion-button .usa-accordion__button
.usa-current .usa-current
.usa-header-basic-megamenu .usa-header.usa-header--megamenu
.usa-header-extended .usa-header.usa-header--extended
.usa-header-search-button deprecated: not used
.usa-megamenu .usa-megamenu
.usa-megamenu-col deprecated: use utilities
.usa-mobile_nav-active .usa-mobile-nav.usa-mobile-nav--active
.usa-nav .usa-nav
.usa-nav-close .usa-nav__close
.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-primary li .usa-nav__primary-item
.usa-nav-secondary .usa-nav__secondary
.usa-nav-secondary li .usa-nav__secondary-item
.usa-nav-secondary-links .usa-nav__secondary-links
.usa-nav-submenu .usa-nav__submenu
.usa-nav-submenu li .usa-nav__submenu-item
.usa-nav-submenu ul .usa-nav__submenu-list
.usa-navbar .usa-navbar
.usa-search .usa-search
.usa-search .usa-search
.usa-search-big .usa-search.usa-search--big
.usa-search-input .usa-search__input
.usa-search-small .usa-search.usa-search--small
.usa-search-submit .usa-search__submit
.usa-search-submit-text .usa-search__submit-text


.usa-section-dark .usa-section.usa-section--dark
.usa-section-light .usa-section.usa-section--light


.usa-layout-docs-sidenav .usa-layout-docs__sidenav
.usa-sidenav-list .usa-sidenav
.usa-sidenav-sub_list .usa-sidenav__sublist
.usa-sidenav li .usa-sidenav__item


.usa-skipnav .usa-skipnav

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. (
  • Updated our icon colors to USWDS 2.0 tokens (
  • Now you can use token values of .5 and -.5 — without leading zeros — in functions and mixins. Thanks @dmethvin-gov! (
  • The u-outline() mixin now properly accepts all the tokens it’s meant to accept. Thanks @jeremyzilar! (
  • Added u-overflow-x() and u-overflow-y() mixins to match utilities. Thanks @jeremyzilar! (
  • The offset-none utilities now support responsive prefixes as intended. Thanks @robertromore! (

Version 2.0.0 Beta 7 (Release candidate)

March 25, 2019

Bug fixes

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


  • ⚠️ breaking change: gov banner markup now points to the flag in the img folder and not the favicon (
  • ⚠️ breaking change: hero component now uses an h1 for its tagline for better accessibility (
  • ⚠️ breaking change: Removed the alert paragraph component as its functionality is now better controlled with utilities. (
  • ⚠️ 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 (
  • ⚠️ breaking change: Updated measure tokens to conform to guidance and be more reliable ( and
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 (
  • Documented supported Node and NPM versions in the README (
  • Update to most current versions of Source Sans Pro and Merriweather. Thanks @miguelsousa! (
  • Updated the favicon to match our logo (
  • Removed EOT and SVG font versions since we do not support IE8 or Safari older than 4.1. Thanks @miguelsousa! (

Public Sans

  • Fixed a display error resulting in poor font rendering on Windows. Thanks @fat32 and @stphnwlkr! (
  • Lightened the regular weight (
  • 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! (
  • Coming soon: a new url for specimen site (

Internal / CI

  • Updated to Gulp 4 (
  • 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 (
  • Grid columns now display properly when your project doesn’t explicitly include component styles (
  • Extra large content no longer breaks fill and auto columns. (
  • 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! (
  • Media query styling now applies to print jobs, fixing a number of current issues with print output. (


More up-to-date node dependency ( 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 ( 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 (
  • Added a red-cool family (
  • Saturated gold-20v (
  • Desaturated blue-cool standard colors and added vivid variants (
  • Made small hue consistency modifications to the following families (

    • 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 (
    • 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' (
    • 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 (
    • font-size()size()
    • font-size()fs()
    • font-family()family()
    • font-family()ff()
  • Update to newest Public Sans (
    • 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 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. (
    • 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 (

Bug fixes

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


  • Added a AAA magic number to the docs and updated contrast references to WCAG 2.0 (
  • Removed utility classes from any component (
    • ⚠️ 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 (
  • Added any public-facing mixin into files within the core/mixins folder so they can be imported without importing any styles (
  • 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 (
  • The ‘object’ namespace was causing confusion and wasn’t useful enough to justify its inclusion. (
    • 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. (
  • Added a $theme-show-compile-warnings setting (default: true) to show compile warnings when using false or nonstandard tokens (
  • Use the word ‘token’ instead of ‘value’ in compile errors to align with our naming convention (
  • 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. (
    • ⚠️ 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 (
    • 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 (
    • 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 (
  • Fixed the order of colors in the the system colors sidenav to reflect the actual order of the content (
  • Updated our color guidance to include more specific guidance around contrast sensitivity and Irlen Syndrome. (
    • 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 2.0.0-alpha

August 13, 2018


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


  • Update accordions to be more semantic and accessible (#2360, #2406, #2360) [breaking change]
  • Fix footer class naming inconsistency (#2583) [breaking change]

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.