How to use USWDS
Migrating to USWDS 2.0
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.
Summary
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-grid-container-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-grid-container-max-width);
@include at-media($theme-site-margins-breakpoint) {
@include u-padding-x($theme-site-margins-width);
}
}
or
.usa-example {
@include u-padding-x(2);
max-width: units('desktop');
@include at-media('desktop') {
@include u-padding-x(4);
}
}
BEM
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-alertis 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:
USWDS v1
<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>
</div>
USWDS v2
<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>
</div>
</div>
Mixins and functions
| USWDS v1 | USWDS v2 |
|---|---|
| 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 |
Variables
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 |
| $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 |
| $medium | n/a | — | — | — |
use |
| $large | n/a | — | — | — |
use |
| $asset-path | n/a | — | — | — |
use |
| $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-grid-container-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 | component | |
| $label-border-radius | n/a | — | — | — |
not used in v2 — currently |
| $checkbox-border-radius | $theme-checkbox-border-radius | sm | border-radius|units | component | |
| $border-radius | $theme-border-radius-md | 0.5 | units | spacing |
use alongside |
| $button-border-radius | $theme-button-border-radius | md | border-radius|units | component | |
| $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 | component |
The maximum width of header and nav. |
| $nav-width | $theme-header-min-width | desktop | units | component |
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 | component | |
| $hit-area | n/a | — | — | — |
no longer a user-settable variable (now |
| $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 responsive behavior. Breakpoints are specified manually.
- Grid column classes must be enclosed by a
grid-row. - See the layout grid documentation for more details.
| USWDS v1 | USWDS v2 |
|---|---|
| .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 |
Typography
| USWDS v1 | USWDS v2 |
|---|---|
| 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 |
Button
| USWDS v1 | USWDS v2 |
|---|---|
| .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 |
Embed
| USWDS v1 | USWDS v2 |
|---|---|
| .usa-embed-container | .usa-embed-container |
Figure
| USWDS v1 | USWDS v2 |
|---|---|
| media-link | .usa-media-link |
Inputs
| USWDS v1 | USWDS v2 |
|---|---|
| [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 |
List
| USWDS v1 | USWDS v2 |
|---|---|
| li | .usa-list li |
| ol | ol.usa-list |
| ul | ul.usa-list |
| .usa-unstyled-list | .usa-list.usa-list--unstyled |
Table
| USWDS v1 | USWDS v2 |
|---|---|
| media-link | .usa-media-link |
Tag
- Formerly called “labels”
| USWDS v1 | USWDS v2 |
|---|---|
| .usa-label | .usa-tag |
| .usa-label-big | .usa-tag.usa-tag--big |
Accordion
| USWDS v1 | USWDS v2 |
|---|---|
| .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-accordion__heading |
Alert
| USWDS v1 | USWDS v2 |
|---|---|
| .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 |
Banner
| USWDS v1 | USWDS v2 |
|---|---|
| .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-banner__header-action |
| — | .usa-banner__header-close-text |
| — | .usa-banner__header-flag |
| — | .usa-banner__header-text |
Checklist
| USWDS v1 | USWDS v2 |
|---|---|
| .usa-checklist | .usa-checklist |
| .usa-checklist li | .usa-checklist__item |
| .usa-checklist-checked | .usa-checklist__item.usa-checklist__item--checked |
Footer
| USWDS v1 | USWDS v2 |
|---|---|
| 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
| USWDS v1 | USWDS v2 |
|---|---|
| .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
| USWDS v1 | USWDS v2 |
|---|---|
| .usa-graphic_list | .usa-graphic-list |
| .usa-graphic_list h3 | .usa-graphic-list__heading |
| .usa-graphic_list-row | .usa-graphic-list__row |
Header
| USWDS v1 | USWDS v2 |
|---|---|
| .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-overlay.is-visible | .usa-overlay.is-visible |
| .usa-header-basic | .usa-header.usa-header--basic |
| .usa-navbar | .usa-navbar |
| .usa-header-extended | .usa-header.usa-header--extended |
| .usa-current | .usa-current |
Hero
| USWDS v1 | USWDS v2 |
|---|---|
| .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 |
Layout
| USWDS v1 | USWDS v2 |
|---|---|
| .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
| USWDS v1 | USWDS v2 |
|---|---|
| .usa-media_block | .usa-media-block |
| .usa-media_block-body | .usa-media-block__body |
| .usa-media_block-img | .usa-media-block__img |
Navigation
| USWDS v1 | USWDS v2 |
|---|---|
| .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 |
Search
| USWDS v1 | USWDS v2 |
|---|---|
| .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 |
Section
| USWDS v1 | USWDS v2 |
|---|---|
| .usa-section-dark | .usa-section.usa-section--dark |
| .usa-section-light | .usa-section.usa-section--light |
Sidenav
| USWDS v1 | USWDS v2 |
|---|---|
| .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 |
Skipnav
| USWDS v1 | USWDS v2 |
|---|---|
| .usa-skipnav | .usa-skipnav |
