About USWDS

Release notes

The Design System 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.0.1

April 05, 2019

Fixed


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:


:rocket: More about USWDS 2.0


Changes from Beta 7 to 2.0


Version 1.6.10

March 25, 2019


Version 2.0.0 Beta 7 (Release candidate)

March 25, 2019

Bug fixes

Improvements

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

Public Sans

Internal / CI


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

Improvements

General

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)

Typography

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)

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.

typography

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

button

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-disabled
usa-button-outline-inverse usa-button--outline.usa-button--inverse
usa-button-outline-inverse-disabled
usa-button-secondary usa-button--secondary
usa-button-unstyled usa-button-unstyled
usa-focus usa-focus

embed

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

figure

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

inputs

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

list

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

table

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

tag

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

accordions

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

alerts

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

banner

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

checklist

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

forms

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

header

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

hero

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

layout

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

navigation

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

section

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

sidenav

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

skipnav

Beta 5 Beta 6
usa-skipnav usa-skipnav

Version 2.0.0 Beta 5

February 20, 2019

Bug fixes

Improvements

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

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

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

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

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

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

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

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

uswds-theme-defaults

Current USWDS state defaults

uswds-state-defaults


Version 2.0.0 Beta 4

November 14, 2018

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

Internal

Bug fixes

Improvements

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.

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.

Documentation


Version 2.0.0 Beta 3

October 29, 2018

Bug Fixes

Improvements

Documentation


Version 1.6.9

October 15, 2018

Updated

Fixed


Version 2.0.0 Beta 2

October 15, 2018

Internal

Additions

Updates

Bug fixes

Improvements

Documentation


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 ✨

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

New or updated elements and classes

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

Typography

Grids

Buttons

Tags

Tables

Alerts

Accordions

Forms

Form controls

Form templates

Side navigation

Headers

Footers


Version 1.6.8

August 06, 2018

Added

Fixed


Version 1.6.7

July 23, 2018

Fixed

Changed


Version 1.6.6

June 13, 2018

Fixed


Version 1.6.5

June 13, 2018

Fixed


Version 1.6.4

June 04, 2018

Fixed

Fix margin bug on h6-level headings (#2531)


Version 1.6.3

May 07, 2018

Fixed


Version 2.0.0-alpha

August 13, 2018

Added

Fixed


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

New or updated elements and classes

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


Version 1.6.2

April 23, 2018

Fixed


Version 1.6.1

March 26, 2018

Fixed


Version 1.6.0

March 12, 2018

Changed

Fixed


Version 1.5.0

February 26, 2018

Added

Changed

Fixed


Version 1.4.6

February 12, 2018

Removed

Fixed


Version 1.4.5

January 23, 2018

Changed


Version 1.4.4

December 18, 2017

Fixed


Version 1.4.3

November 20, 2017

Changed

Removed

Fixed


Version 1.4.2

November 02, 2017

Changed

Removed

Fixed


Version 1.4.1

October 06, 2017

Header Fixes

Documentation Updates

Fixed bug with headless Chrome tests


Version 1.4.0

September 29, 2017

Accessibility improvements

Visual changes

Other changes

New features for core development


Version 1.3.1

August 22, 2017

Bug Fixes