How to use USWDS

Settings

USWDS settings variables tell the design system how to build.

Introducing USWDS settings

USWDS is built using a suite of customizable settings that allows you to configure the Design System to fit your project’s needs. These settings are Sass variables that begin with the $theme- prefix and are typically defined with USWDS design tokens. You can find the full list of USWDS settings and their default values in the USWDS settings tables.

Configuring custom USWDS settings

With the introduction of Sass modules in USWDS 3, you can now create a custom configuration of USWDS by loading a single @use...with() rule into your Sass entry point.

All USWDS settings are defined in the uswds-core module, which means the USWDS settings configuration rule is @use "uswds-core" with ().

To create your custom configuration, add the USWDS settings variables that you wish to modify inside the parentheses of this statement, as shown in this example:

  @use "uswds-core" with (
    $theme-image-path: "../uswds/img",
    $theme-show-compile-warnings: true,
    $theme-show-notifications: false,
    $theme-banner-background-color: "ink",
    $theme-banner-link-color: "primary-light",
    $theme-banner-max-width: "widescreen",
    $theme-checkbox-border-radius: "md",
  )

Note that the settings variables in this module inform both general theme and component customizations.

What to include in your configuration

Include only USWDS settings that you wish to modify in this configuration. These items should be comma-separated and given values of the appropriate type, as identified in the settings tables on this page.

Please note that this configuration accepts only current USWDS settings variables — adding anything else here will result in an error.

Note: If you receive the error This module was already loaded, so it can't be configured using "with", confirm that all your declared variables exist in the settings tables and try compiling again.

Configuring settings maps

Similar to single-value settings, when configuring Sass settings maps in USWDS, you will only need to include the map items you wish to customize. Any item that is not defined in your configuration will keep its default value.

For example, if you wanted to customize the $background-color-settings defaults to output focus styles and remove hover styles, you would configure the setting like this:

@use "uswds-core" with (
  $background-color-settings: (
    focus: true,
    hover: false,
  )
);

This will generate the same output as configuring the setting with default values for all other map items:

@use "uswds-core" with (
  $background-color-settings: (
    output: true, // default value
    responsive: false, // default value
    active: false, // default value
    focus: true,
    hover: false,
    visited: false, // default value
  )
);

Where to include your configuration

Add your settings configuration to your Sass entry point. You can choose to set up the settings configuration either directly in your entry point or in its own file.

Whatever path you choose, it is important to note that your settings configuration must be included above @forward 'uswds' in your Sass entry point. (To learn more about why this matters, read our guide for setting up your Sass entry point.)

We’ve created some example setups to give you an idea of how this works:

Configure USWDS settings in a separate file

/* _uswds-theme.scss */

@use "uswds-core" with (
  $theme-show-compile-warnings: false,
  $theme-show-notifications: false,
);
/* styles.scss */

@forward 'uswds-theme';
@forward 'uswds';
@forward 'uswds-theme-custom-styles';

Configure USWDS settings in your Sass entry point

/* styles.scss */

@use "uswds-core" with (
  $theme-show-compile-warnings: false,
  $theme-show-notifications: false,
);

@forward 'uswds';
@forward 'uswds-theme-custom-styles';

Settings maps and dot notation

We use dot notation in our documentation to describe settings that are nested inside a Sass map. Dot notation is a syntax that uses a period (or dot) to reference an object’s properties.

For example, in the general settings table on this page, we use grid.namespace to refer to the namespace property in the $theme-namespace grid map. Following the settings map configuration instructions described earlier, you could configure that setting like this:

@use "uswds-core" with (
  $theme-namespace: (
    grid: (
      namespace: "custom-grid-name-",
    )
  )
);

General settings

Name Variable Default Type Description
Image path $theme-image-path "../img" path

Use a path relative to the location of the final compiled CSS.

Show compile warnings $theme-show-compile-warnings true boolean

Show Sass warnings when functions and mixins use non-standard tokens.

Show notifications $theme-show-notifications true boolean

Show updates and notifications about the design system.

Namespace $theme-namespace map

Set a namespace for grid and utility classes.

Namespace grid.namespace "grid-" string

The grid class prefix.

Namespace grid.output true boolean

Output the grid prefix.

Namespace utility.namespace "u-" string

The utility class prefix.

Namespace utility.output false boolean

Output the utility prefix.

Prefix separator $theme-prefix-separator "\\:" string

Set the character that separates responsive and state prefixes from the main class name. The default (“:”) is preceded by two backslashes so that it is properly escaped.

Important layout grid $theme-layout-grid-use-important false boolean

Output grid classes with !important.

Border box sizing $theme-global-border-box-sizing true boolean

When set to true, sets the box-sizing property of all site elements to border-box.

Focus color $theme-focus-color "blue-40v" color

The color of the focus outline.

Focus offset $theme-focus-offset 0 units

The offset between the element and the focus outline.

Focus style $theme-focus-style solid outline-style

The style of the focus outline.

Focus width $theme-focus-width 0.5 units

The width of the focus outline.

Icon size $theme-icon-image-size 2 units

The size of a standard UI icon (like a close box).

Color settings

Name Variable Default Type Description
Test color tokens $test-system-color-tokens false boolean

Test system color tokens against luminosity bounds. This is intended to be an internal setting, and may result in false positives.

Base color family $theme-color-base-family "gray-cool" color

Color family of site text.

base-lightest theme color token $theme-color-base-lightest "gray-5" color

Use grades from 0-10.

base-lighter theme color token $theme-color-base-lighter "gray-cool-10" color

Use grades from 10-20.

base-light theme color token $theme-color-base-light "gray-cool-30" color

Use grades from 30-40.

base theme color token $theme-color-base "gray-cool-50" color

Use grades from 40-50.

base-dark theme color token $theme-color-base-dark "gray-cool-60" color

Use grades from 50-70.

base-darker theme color token $theme-color-base-darker "gray-cool-70" color

Use grades from 60-90.

base-darkest theme color token $theme-color-base-darkest "gray-90" color

Use grades from 70-90.

ink theme color token $theme-color-base-ink "gray-90" color

Recommend a clone of base-darkest.

Primary color family $theme-color-primary-family "blue" color

Color family of ~60% of the non-base color.

primary-lightest theme color token $theme-color-primary-lightest false color

Use grades 0-10.

primary-lighter theme color token $theme-color-primary-lighter "blue-10" color

Use grades 10-20.

primary-light theme color token $theme-color-primary-light "blue-30" color

Use grades 30-40.

primary theme color token $theme-color-primary "blue-60v" color

Use grades 40-60.

primary-vivid theme color token $theme-color-primary-vivid "blue-warm-60v" color

Use vivid grades 30-60.

primary-dark theme color token $theme-color-primary-dark "blue-warm-70v" color

Use grades 50-70.

primary-darker theme color token $theme-color-primary-darker "blue-warm-80v" color

Use grades 60-90.

primary-darkest theme color token $theme-color-primary-darkest false color

Use grades 70-90.

Secondary color family $theme-color-secondary-family "red" color

Color family of ~30% of the non-base color.

secondary-lightest theme color token $theme-color-secondary-lightest false color

Use grades 0-10.

secondary-lighter theme color token $theme-color-secondary-lighter "red-cool-10" color

Use grades 10-20.

secondary-light theme color token $theme-color-secondary-light "red-30" color

Use grades 30-40.

secondary theme color token $theme-color-secondary "red-50" color

Use grades 40-60.

secondary-vivid theme color token $theme-color-secondary-vivid "red-cool-50v" color

Use vivid grades 30-60.

secondary-dark theme color token $theme-color-secondary-dark "red-60v" color

Use grades 50-70.

secondary-darker theme color token $theme-color-secondary-darker "red-70v" color

Use grades 60-90.

secondary-darkest theme color token $theme-color-secondary-darkest false color

Use grades 70-90.

Accent warm color family $theme-color-accent-warm-family "orange" color

Color family of occasional warm accents.

accent-warm-lightest theme color token $theme-color-accent-warm-lightest false color

Use grades 0-10.

accent-warm-lighter theme color token $theme-color-accent-warm-lighter "orange-10" color

Use grades 10-20.

accent-warm-light theme color token $theme-color-accent-warm-light "orange-20v" color

Use grades 20-40.

accent-warm theme color token $theme-color-accent-warm "orange-30v" color

Use grades 30-60.

accent-warm-dark theme color token $theme-color-accent-warm-dark "orange-50v" color

Use grades 50-70.

accent-warm-darker theme color token $theme-color-accent-warm-darker "orange-60" color

Use grades 60-90.

accent-warm-darkest theme color token $theme-color-accent-warm-darkest false color

Use grades 70-90.

Accent cool color family $theme-color-accent-cool-family "blue-cool" color

Color family of occasional cool accents.

accent-cool-lightest theme color token $theme-color-accent-cool-lightest false color

Use grades 0-20.

accent-cool-lighter theme color token $theme-color-accent-cool-lighter "blue-cool-5v" color

Use grades 10-30.

accent-cool-light theme color token $theme-color-accent-cool-light "blue-cool-20v" color

Use grades 30-40.

accent-cool theme color token $theme-color-accent-cool "cyan-30v" color
accent-cool-dark theme color token $theme-color-accent-cool-dark "blue-cool-40v" color

Use grades 50-60.

accent-cool-darker theme color token $theme-color-accent-cool-darker "blue-cool-60v" color

Use grades 60-80.

accent-cool-darkest theme color token $theme-color-accent-cool-darkest false color

Use grades 70-100.

Error color family $theme-color-error-family "red-warm" color

Color family of error messaging.

error-lighter state color token $theme-color-error-lighter "red-warm-10" color

Use grades 10-30.

error-light state color token $theme-color-error-light "red-warm-30v" color

Use grades 30-40.

error state color token $theme-color-error "red-warm-50v" color

Use grades 50-60.

error-dark state color token $theme-color-error-dark "red-60v" color

Use grades 60-70.

error-darker state color token $theme-color-error-darker "red-70" color

Use grades 70-80.

Warning color family $theme-color-warning-family "gold" color

Color family of warning messaging.

warning-lighter state color token $theme-color-warning-lighter "yellow-5" color

Use grades 0-30.

warning-light state color token $theme-color-warning-light "yellow-10v" color

Use grades 10-40.

warning state color token $theme-color-warning "gold-20v" color

Use grades 50-60.

warning-dark state color token $theme-color-warning-dark "gold-30v" color

Use grades 60-70.

warning-darker state color token $theme-color-warning-darker "gold-50v" color

Use grades 70-80.

Success color family $theme-color-success-family "green-cool" color

Color family of success messaging.

success-lighter state color token $theme-color-success-lighter "green-cool-5" color

Use grades 0-30.

success-light state color token $theme-color-success-light "green-cool-20v" color

Use grades 10-40.

success state color token $theme-color-success "green-cool-40v" color

Use grades 50-60.

success-dark state color token $theme-color-success-dark "green-cool-50v" color

Use grades 60-70.

success-darker state color token $theme-color-success-darker "green-cool-60v" color

Use grades 70-80.

Info color family $theme-color-info-family "cyan" color

Color family of info messaging.

info-lighter state color token $theme-color-info-lighter "cyan-5" color

Use grades 0-30.

info-light state color token $theme-color-info-light "cyan-20" color

Use grades 10-40.

info state color token $theme-color-info "cyan-30v" color

Use grades 50-60.

info-dark state color token $theme-color-info-dark "cyan-40v" color

Use grades 60-70.

info-darker state color token $theme-color-info-darker "blue-cool-60" color

Use grades 70-80.

Emergency colors

Colors of emergency actions.

emergency state color token $theme-color-emergency "red-warm-60v" color
emergency-dark state color token $theme-color-emergency-dark "red-warm-80" color
Disabled color family $theme-color-disabled-family "gray" color

Color family of disabled actions.

disabled-lighter state color token $theme-color-disabled-lighter "gray-20" color

Use grade 20.

disabled-light state color token $theme-color-disabled-light "gray-40" color

Use grade 40.

disabled state color token $theme-color-disabled "gray-50" color

Use grade 50.

disabled-dark state color token $theme-color-disabled-dark "gray-70" color

Use grade 70.

disabled-darker state color token $theme-color-disabled-darker "gray-90" color

Use grade 90.

Body background color $theme-body-background-color "white" color

Background color of the site body.

Body text color $theme-text-color "ink" color

Color of body text.

Body text reverse color $theme-text-reverse-color "white" color

Color of body text on dark backgrounds.

Link color $theme-link-color "primary" color

Color for text links.

Visited link color $theme-link-visited-color "violet-70v" color

Color for :visited text links

Hover link color $theme-link-hover-color "primary-dark" color

Color for :hover text links.

Active link color $theme-link-active-color "primary-darker" color

Color for :active text links.

Link reverse color $theme-link-reverse-color "base-lighter" color

Color for text links on dark backgrounds.

Link reverse hover color $theme-link-reverse-hover-color "base-lightest" color

Color for :hover text links on dark backgrounds.

Link reverse active color $theme-link-reverse-active-color "white" color

Color for :active text links on dark backgrounds.

Component settings

Accordion

Name Variable Default Type Description
Background color $theme-accordion-background-color default color

Background color of the accordion content.

Border width $theme-accordion-border-width 0.5 units

Border width of the bordered accordion.

Border color $theme-accordion-border-color "base-lightest" color

Border color of the bordered accordion.

Button background color $theme-accordion-button-background-color "base-lightest" color

Background color of the accordion button.

Font family $theme-accordion-font-family "body" family

Font family of the accordion.

Alert

Name Variable Default Type Description
Bar width $theme-alert-bar-width 1 units

Width of the colored bar to the left of the alert.

Font family $theme-alert-font-family "ui" family

Font family of the alert.

Icon size $theme-alert-icon-size 4 units

Size of the alert icon.

Horizontal padding $theme-alert-padding-x 2.5 units

Padding on the left and right of the alert.

Vertical padding $theme-alert-padding-y 2 units

Padding on the top and bottom of the alert.

Text color $theme-alert-text-color default color

Text color on light backgrounds. Default uses text color set in $theme-text-color.

Link color $theme-alert-link-color default color

Link color on light backgrounds. Default uses text color set in $theme-text-color.

Reverse text color $theme-alert-text-reverse-color default color

Text color on dark backgrounds. Default uses reverse text color set in $theme-text-reverse-color.

Reverse link color $theme-alert-link-reverse-color default color

Link color on dark backgrounds. Default uses reverse link color set in $theme-link-reverse-color.

Name Variable Default Type Description
Background color $theme-banner-background-color "base-lightest" family

Background color of the banner and its content.

Font family $theme-banner-font-family "ui" family

The font family of the banner.

Link color $theme-banner-link-color default color

The color of banner link. Add the link color and the system will generate the hover state. Default uses the default link settings calculated from your background color.

Maximum width $theme-banner-max-width "desktop" units

Maximum width of the banner content.

Name Variable Default Type Description
Background color $theme-breadcrumb-background-color default color

The background color of the complete breadcrumb bar. Default uses body background color set in $theme-body-background-color.

Font family $theme-breadcrumb-font-family "body" family

The family of the breadcrumb text.

Font size $theme-breadcrumb-font-size "sm" units

The size of the breadcrumb text.

Link color $theme-breadcrumb-link-color default color

The color of breadcrumb link. Add the link color and the system will generate the hover state. Default uses the default link settings calculated from your background color.

Full breadcrumb minimum width $theme-breadcrumb-min-width "mobile-lg" units

The width at which the breadcrumb displays the full breadcrumb list.

Bottom padding $theme-breadcrumb-padding-bottom 2 units

Padding below the breadcrumb.

Top padding $theme-breadcrumb-padding-top 2 units

Padding above the breadcrumb.

Horizontal padding $theme-breadcrumb-padding-x 0 units

Padding to the right and left of the breadcrumb.

Separator color $theme-breadcrumb-separator-color "base" color

Color of the breadcrumb separator. This value needs AA contrast against the background.

Button

Name Variable Default Type Description
Border radius $theme-button-border-radius "md" units

Button border radius for rounded corners.

Font family $theme-button-font-family "ui" family

Font family of the button.

Icon gap $theme-button-icon-gap 1 units

Size of the gap between the button’s text and icon.

Small width $theme-button-small-width 6 units

Width of small buttons. Used to define the size of the header search button and small language selector button.

Stroke width $theme-button-stroke-width 2px units

Stroke width of outline button variants.

Card

Name Variable Default Type Description
Border color $theme-card-border-color "base-lighter" color

Stroke color of card.

Border radius $theme-card-border-radius "lg" units

Border radius of card.

Border width $theme-card-border-width 2px units

Stroke thickness of card.

Gap $theme-card-gap 2 units

Gap between cards in a card group.

Flag minimum width $theme-card-flag-min-width "tablet" units

Width at which flag cards change to horizontal layout.

Flag image width $theme-card-flag-image-width "card-lg" units

Fixed image width in the card flag variant.

Font family $theme-card-font-family "body" family

Font family for card body.

Header typeset $theme-card-header-typeset "heading", "lg", 2 family size line-height

Family, size, and line height of the heading.

Margin bottom $theme-card-margin-bottom 4 units

Bottom margin for card.

Perimeter padding $theme-card-padding-perimeter 3 units

Padding between card elements and card border.

Vertical padding $theme-card-padding-y 2 units

Vertical padding between card elements.

Checkbox

Name Variable Default Type Description
Border radius $theme-checkbox-border-radius "sm" units

Checkbox border radius for rounded corners.

Background color $theme-input-background-color default color

Background color for radio and checkbox inputs.

Tile border radius $theme-input-tile-border-radius "md" units

Tile border radius for rounded corners.

Tile border width $theme-input-tile-border-width "2px" units

Tile border thickness

Collection

Name Variable Default Type Description
Font family $theme-collection-font-family "ui" family

Font family for collection body.

Header typeset $theme-collection-header-typeset "ui", "md", 3 family size line-height

Family, size, and line height of the heading.

Name Variable Default Type Description
Font family $theme-footer-font-family "body" family

Font family of the footer.

Max width $theme-footer-max-width "desktop" units

Maximum width of footer container.

Form

Name Variable Default Type Description
Font family $theme-form-font-family "ui" family

Font family of the form.

Name Variable Default Type Description
Font family $theme-header-font-family "ui" family

Font family of the header.

Logo text width $theme-header-logo-text-width 33% percentage

Width of the logo text area at desktop width as a percentage of the total header width.

Max width $theme-header-max-width "desktop" units

Maximum width of the header.

Min width $theme-header-min-width "desktop" units

Breakpoint at which the non-mobile header is shown.

Hero

Name Variable Default Type Description
Hero image $theme-hero-image "#{$theme-image-path}/hero.png" path

Background image for the hero. Use a path relative to the final project CSS.

Icon list

Name Variable Default Type Description
Icon list font family $theme-icon-list-font-family "body" family

Font family of the content text.

Icon list title font family $theme-icon-list-title-font-family "heading" family

Font family of the content title.

Identifier

Name Variable Default Type Description
Background color $theme-identifier-background-color "base-darkest" color

The background color of the identifier. Use a color of grade 80 or higher, darker than the section that precedes it.

Font family $theme-identifier-font-family "ui" family

The font family of the identifier.

Domain text color $theme-identifier-identity-domain-color "base-light" color

The color of your domain text in the identifier masthead. This should be grade 20-30 in the same family as the $theme-identifier-background-color.

Maximum width $theme-identifier-max-width "desktop" units

The maximum width of the content within the identifier. Use the same max-width as your site footer.

Primary link color $theme-identifier-primary-link-color default color

The color of the links in the masthead section. Default uses either the standard or reverse link color set with $theme-link-color and $theme-link-reverse-color.

Secondary link color $theme-identifier-secondary-link-color "base-light" color

The color of the links in the required links section. This should be grade 20-30 in a gray family.

In-page navigation

Name Variable Default Type Description
Background color $theme-in-page-nav-background-color "default" color

Background color of the in-page navigation block. Default uses body background color set in $theme-body-background-color.

Perimeter padding $theme-in-page-nav-background-padding 2 units

Padding of the in-page navigation block.

Border radius $theme-in-page-nav-background-radius "lg" units

The border radius of the in-page navigation block.

Active state vertical line color $theme-in-page-nav-bar-color "default" color

Color of the bar representing the active state of a link in the in-page navigation. Default uses the default link settings calculated from your background color.

Active state vertical line width $theme-in-page-nav-bar-width "05" units

Width of the colored bar representing the active state of a link in the in-page navigation.

Font family $theme-in-page-nav-font-family "ui" family

Font family of the in-page navigation.

Link color $theme-in-page-nav-link-color "default" color

The color of the link in the in-page navigation. Default uses the default link settings calculated from your background color.

Main content max width $theme-in-page-nav-main-content-max-width "desktop" units

Maximum width of the main element.

Left margin $theme-in-page-nav-margin-left 4 units

Margin to the left of in-page navigation.

Top margin $theme-in-page-nav-margin-top 2.5 units

Margin above in-page navigation.

Position from top $theme-in-page-nav-top 4 units

Distance from top of page to top of navigation when the sticky position is engaged on scroll.

Input

Name Variable Default Type Description
Line height $theme-input-line-height 3 line-height

Line-height of input element.

Max width $theme-input-max-width "mobile-lg" units

Max width of the input element.

Border width when selected $theme-input-select-border-width 2px units

Border width of selection element for checkbox, radio, and range.

Size of selection element $theme-input-select-size 2.5 units

Height and width checkboxes and radio buttons.

State border width $theme-input-state-border-width 0.5 units

Border width of special state inputs (like error state).

Name Variable Default Type Description
New tab screen reader label $theme-external-link-sr-label-tab-new "External, opens in a new tab." string

Screen reader label for external links that open in new tabs.

Same tab screen reader label $theme-external-link-sr-label-tab-same "External." string

Screen reader label for external links that open in current tab.

Name Variable Default Type Description
Border radius $theme-modal-border-radius "lg" units

The border radius of the modal window.

Max width $theme-modal-default-max-width "mobile-lg" units

Maximum width of default modal window.

Large max width $theme-modal-lg-max-width "tablet-lg" units

Maximum width of large modal window.

Large content max width $theme-modal-lg-content-max-width "tablet" units

Maximum width of content area within large modal window.

Name Variable Default Type Description
Font family $theme-navigation-font-family "ui" family

Font family of the navigation.

Megamenu column count $theme-megamenu-columns 3 number

Number of columns in the megamenu.

Pagination

Name Variable Default Type Description
Pagination background color $theme-pagination-background-color "default" color

The background color of the entire pagination component.

Breakpoint $theme-pagination-breakpoint "tablet" units

Breakpoint at which full pagination displays.

Button border radius $theme-pagination-button-border-radius "md" units

Default pagination button border radius.

Button border width $theme-pagination-button-border-width 1px units

Width of button border.

Font family $theme-pagination-font-family "ui" family

Default font family for pagination.

Process list

Name Variable Default Type Description
Counter background color $theme-process-list-counter-background-color "white" color

Background color of the counter circle.

Counter border color $theme-process-list-counter-border-color "ink" color

Color of the border around the counter circle.

Counter border width $theme-process-list-counter-border-width 0.5 units

Size of the border around the counter circle.

Counter font family $theme-process-list-counter-font-family "ui" family

Font family of the counter text.

Counter font size $theme-process-list-counter-font-size "lg" size

Font size of the counter text.

Counter gap color $theme-process-list-counter-gap-color "white" color

Color of gap between counter and connector. This should the the same as the background color behind the component.

Counter gap width $theme-process-list-counter-gap-width 0.5 units

Size of gap between counter and connector.

Counter circle size $theme-process-list-counter-size 5 units

Size of the counter circle.

Counter text color $theme-process-list-counter-text-color "ink" color

Color of the number text inside the counter circle.

Connector color $theme-process-list-connector-color "primary-lighter" color

Color of the connector line between counter circles.

Connector width $theme-process-list-connector-width 1 units

Width of the connector line between counter circles.

Content font family $theme-process-list-font-family "ui" family

Font family of the content text.

Content font size $theme-process-list-font-size "sm" size

Font size of the content text.

Heading text color $theme-process-list-heading-color "ink" color

Color of the heading text.

Heading font family $theme-process-list-heading-font-family "ui" family

Font family of the heading text.

Heading font size $theme-process-list-heading-font-size "lg" size

Font size of the heading text.

Radio buttons

Name Variable Default Type Description
Background color $theme-input-background-color default color

Background color for radio and checkbox inputs.

Tile border radius $theme-input-tile-border-radius "md" units

Tile border radius for rounded corners.

Tile border width $theme-input-tile-border-width "2px" units

Tile border thickness.

Name Variable Default Type Description
Font family $theme-search-font-family "ui" family

Font family of the search.

Min-width $theme-search-min-width 27ch

Min-width of the search input.

Sidenav

Name Variable Default Type Description
Current border width $theme-sidenav-current-border-width 0.5 units

Width of the current section indicator.

Font family $theme-sidenav-font-family "ui" family

Font family of the side navigation.

Reorder sidenav $theme-sidenav-reorder false boolean

Reorder Documentation template sidenav with CSS. Favor code example in Documentation template instead.

Site Alert

Name Variable Default Type Description
Maximum width $theme-site-alert-max-width "desktop" units

Maximum width of the site alert content.

Step indicator

Name Variable Default Type Description
Background color $step-indicator-background-color "white" color

Background color of the component and the gaps around the counters.

Counter gap $theme-step-indicator-counter-gap 0.5 units

Gap between the counter and the segment.

Counter border width $theme-step-indicator-counter-border-width 0.5 units

Size of the border around the pending steps.

Font family $theme-step-indicator-font-family "ui" family

Font family of the labels and counter numbers.

Heading font family $theme-step-indicator-heading-font-family "ui" family

Font family of the heading.

Heading color $theme-step-indicator-heading-color "ink" color

Color of the heading.

Heading font size $theme-step-indicator-heading-font-size "lg" size

Font size of the heading on screens of $theme-step-indicator-min-width and larger.

Mobile heading font size $theme-step-indicator-heading-font-size-small "md" size

Font size of the heading on screens smaller than $theme-step-indicator-min-width.

Label font size $theme-step-indicator-label-font-size "sm" size

Font size of segment labels.

Minimum width $theme-step-indicator-min-width "tablet" units

Width at which the component displays large-width features.

Pending segment color $theme-step-indicator-segment-color-pending "gray-40" color

Color of pending step segments. Use a grade of 40 more than $step-indicator-background-color.

Complete segment color $theme-step-indicator-segment-color-complete "primary-darker" color

Color of complete step segments. Use a grade of at least 60.

Current segment color $theme-step-indicator-segment-color-current "primary" color

Color of the current step segments. Use a grade at least 20 less than $theme-step-indicator-segment-color-complete.

Segment gap $theme-step-indicator-segment-gap 2px units

Gap between step segments.

Segment height $theme-step-indicator-segment-height 1 units

Height of the step segment. Note that the mobile segment height is always 1 unit.

Pending text color $theme-step-indicator-text-pending-color "base-dark" color

The text color of pending steps. Use a gray grade of 60 more than the $step-indicator-background-color.

Summary box

Name Variable Default Type Description
Background color $theme-summary-box-background-color "info-lighter" color

Background color of the Summary box.

Border color $theme-summary-box-border-color "info-light" color

Color the border around the Summary box.

Border width $theme-summary-box-border-width 1px border-width

Width of the border around the Summary box.

Border radius $theme-summary-box-border-radius "md" radius

Border radius of the summary box.

Font family $theme-summary-box-font-family "ui" family

Font family of the content text.

Link color $theme-summary-box-link-color default color

Color of the links inside the content text. When set to “default”, links will get one of three values, based on contrast: $theme-link-color, $theme-link-reverse-color, or “ink”.

Text color $theme-summary-box-text-color default color

Color of the content text. When set to “default”, text will get one of two values, based on contrast: $theme-text-reverse-color or $theme-text-color.

Tables

Name Variable Default Type Description
Background color $theme-table-background-color default color

Defines the table background color. A value of default uses the body background color.

Border color $theme-table-border-color "ink" color

Defines a border color for table cells. A value of default uses either the default text or reverse text color depending on the site background color.

Header background color $theme-table-header-background-color "base-lighter" color

Defines a background color for header cells.

Header text color $theme-table-header-text-color default color

Defines a text color for header cells. A value of default uses either the default text or reverse text color depending on the header background color.

Sorted column background color $theme-table-sorted-background-color "accent-cool-lighter" color

Defines a background color for the cells of the sorted column.

Sorted column header background color $theme-table-sorted-header-background-color "accent-cool-light" color

Defines a background color for the sorted column header.

Sorted column icon color $theme-table-sorted-icon-color default color

Defines a fill color for the activated sort button in a sortable column header. A value of default uses either the default text or reverse text color depending on the sorted column header background color.

Sorted column stripe background color $theme-table-sorted-stripe-background-color "blue-cool-10v" color

Defines a background color for the alternating horizontal stripes applied to cells of the sorted column.

Sticky header top offset $theme-table-sticky-top-offset -1px CSS length

Defines the top offset for sticky headers. This setting value must include the CSS unit type, for example 10px or 2rem.

Stripe background color $theme-table-stripe-background-color "base-lightest" color

Defines a background color for alternating horizontal stripes in the striped table variant.

Stripe text color $theme-table-stripe-text-color default color

Defines a text color for alternating horizontal stripes in the striped table variant. A value of default uses either the default text or reverse text color depending on the stripe background color.

Text color $theme-table-text-color default color

Defines a text color for table cells. A value of default uses either the default text or reverse text color depending on the site background color.

Unsorted column icon color $theme-table-unsorted-icon-color "base" color

Defines a fill color for the unactivated sort button in a sortable column header.

Tooltip

Name Variable Default Type Description
Background color $theme-tooltip-background-color "ink" color

Background color of tooltip.

Text color $theme-tooltip-font-color "base-lightest" color

Text color of tooltip.

Font size $theme-tooltip-font-size "xs" size

Font size of tooltip.

Spacing settings

Name Variable Default Type Description
Small border radius border-radius token $theme-border-radius-sm 2px units

Sets "sm" border-radius theme token.

Medium border radius border-radius token $theme-border-radius-md 0.5 units

Sets "md" border-radius theme token.

Large border radius border-radius token $theme-border-radius-lg 1 units

Sets "lg" border-radius theme token.

Small grid gap grid-gap token $theme-column-gap-sm 2px units

Sets "grid-gap-sm" token.

Medium grid gap grid-gap token $theme-column-gap-md 2 units

Sets "grid-gap-md" token.

Large grid gap grid-gap token $theme-column-gap-lg 3 units

Sets "grid-gap-lg" token.

Mobile grid gap grid-gap token $theme-column-gap-mobile 2 units

Sets value of "grid-gap" at mobile width.

Desktop grid gap grid-gap token $theme-column-gap-desktop 4 units

Sets value of "grid-gap" at desktop width.

Grid container max width $theme-grid-container-max-width "desktop" units

Sets the max-width value of the .grid-container utility.

Site outer margins breakpoint $theme-site-margins-breakpoint "desktop" units

The breakpoint at which the site’s outer margin changes.

Site outer margins $theme-site-margins-width 4 units

Site outer margin at non-mobile width (breakpoint defined by $theme-site-margins-breakpoint).

Site mobile outer margins $theme-site-margins-mobile-width 2 units

Site outer margin at mobile width (breakpoint defined by $theme-site-margins-breakpoint).

Typography settings

Name Variable Default Type Description
Respect user font size $theme-respect-user-font-size true boolean

When true the root font size will be 100% and media queries use ems. When false, the root font size will be the px value specified in $theme-root-font-size and media queries will use px values.

Root font size $theme-root-font-size 10px px

Only applies when $theme-respect-user-font-size is false. Set the root font size to the specified px value and use px values for media queries.

Global paragraph styles $theme-global-paragraph-styles false boolean

Add basic styling to p elements.

Global link styles $theme-global-link-styles false boolean

Add basic styling to a elements.

Global content styles $theme-global-content-styles false boolean

Add basic styling to paragraph text, links, headings, lists, and tables.

Font path $theme-font-path "../fonts" path

Path to the font files, relative to the compiled CSS.

Browser compatibility mode $theme-font-browser-compatibility false boolean

Output additional font formats (woff and ttf) to support IE11.

Custom typeface tokens $theme-typeface-tokens map

Add custom typeface tokens.

Custom typeface tokens token example-serif-token string

Name of the token.

Custom typeface tokens token.display-name "Example Serif Display Name" string

Display name of the typeface.

Custom typeface tokens token.cap-height 364px px

Height of a 500px N character in Sketch.

cond font-family token $theme-font-type-cond false family

Project condensed font. Set to false if unused.

icon font-type token $theme-font-type-icon false family

Project icon font. Set to false if unused.

lang font-family token $theme-font-type-lang false family

Project language-specific font. Set to false if unused.

mono font-family token $theme-font-type-mono "roboto-mono" family

Project monospaced font. Set to false if unused.

sans font-family token $theme-font-type-sans "source-sans-pro" family

Project sans-serif font. Set to false if unused.

serif font-family token $theme-font-type-serif "merriweather" family

Project serif font. Set to false if unused.

ui font-family token $theme-font-role-ui "sans" family

Assign font family used for interfaces and buttons from type-based family tokens.

heading font-family token $theme-font-role-heading "serif" family

Assign font family used for headings from type-based family tokens.

body font-family token $theme-font-role-body "sans" family

Assign font family used for body text from type-based family tokens.

code font-family token $theme-font-role-code "mono" family

Assign font family used for code from type-based family tokens.

alt font-family token $theme-font-role-alt "serif" family

Assign font family used for alternative type sections from type-based family tokens.

3xs font-size token $theme-type-scale-3xs 2 size

Use system size tokens.
Use false if unused.

2xs font-size token $theme-type-scale-2xs 3 size

Use system size tokens.
Use false if unused.

xs font-size token $theme-type-scale-xs 4 size

Use system size tokens.
Use false if unused.

sm font-size token $theme-type-scale-sm 5 size

Use system size tokens.
Use false if unused.

md font-size token $theme-type-scale-md 6 size

Use system size tokens.
Use false if unused.

lg font-size token $theme-type-scale-lg 9 size

Use system size tokens.
Use false if unused.

xl font-size token $theme-type-scale-xl 12 size

Use system size tokens.
Use false if unused.

2xl font-size token $theme-type-scale-2xl 14 size

Use system size tokens.
Use false if unused.

3xl font-size token $theme-type-scale-3xl 15 size

Use system size tokens.
Use false if unused.

thin font-weight token $theme-font-weight-thin false weight

Use system weight tokens.
Use false if unused.

light font-weight token $theme-font-weight-light 300 weight

Use system weight tokens.
Use false if unused.

normal font-weight token $theme-font-weight-normal 400 weight

Use system weight tokens.
Use false if unused.

medium font-weight token $theme-font-weight-medium false weight

Use system weight tokens.
Use false if unused.

semibold font-weight token $theme-font-weight-semibold false weight

Use system weight tokens.
Use false if unused.

bold font-weight token $theme-font-weight-bold 700 weight

Use system weight tokens.
Use false if unused.

heavy font-weight token $theme-font-weight-heavy false weight

Use system weight tokens.
Use false if unused.

Generate all font weights font-weight token $theme-generate-all-weights false boolean

If USWDS is generating @font-face rules, generate all available weights regardless of the assignments above.

Condensed custom font stack $theme-font-cond-custom-stack false font stack

Custom font stack for condensed font. Set to false if unused.

Icon custom font stack $theme-font-icon-custom-stack false font stack

Custom font stack for icon font. Set to false if unused.

Language-specific custom font stack $theme-font-lang-custom-stack false font stack

Custom font stack for language-specific font. Set to false if unused.

Monospaced custom font stack $theme-font-mono-custom-stack false font stack

Custom font stack for monospaced font. Set to false if unused.

Sans-serif custom font stack $theme-font-sans-custom-stack false font stack

Custom font stack for sans-serif font. Set to false if unused.

Serif custom font stack $theme-font-serif-custom-stack false font stack

Custom font stack for serif font. Set to false if unused.

Custom font source files $theme-font-[family]-custom-src map

If you want USWDS to generate additional @font-face declarations, add your font data to the following variables as a map with these keys. You must include fonts saved as .woff2. Include .ttf and .woff fonts as well if $theme-font-browser-compatibility is set to true. Instructions can be found on the font-family page.

Custom font source files dir "custom/example-serif" path

Path relative to $theme-font-path.

Custom font source files roman.100 false file name

The Roman 100 font file, filetype excluded. Set to false if unused.

Custom font source files roman.200 false file name

The Roman 200 font file, filetype excluded. Set to false if unused.

Custom font source files roman.300 "ExampleSerif-Light" file name

The Roman 300 font file, filetype excluded. Set to false if unused.

Custom font source files roman.400 "ExampleSerif-Normal" file name

The Roman 400 font file, filetype excluded. Set to false if unused.

Custom font source files roman.500 false file name

The Roman 500 font file, filetype excluded. Set to false if unused.

Custom font source files roman.600 false file name

The Roman 600 font file, filetype excluded. Set to false if unused.

Custom font source files roman.700 "ExampleSerif-Bold" file name

The Roman 700 font file, filetype excluded. Set to false if unused.

Custom font source files roman.800 false file name

The Roman 800 font file, filetype excluded. Set to false if unused.

Custom font source files roman.900 false file name

The Roman 900 font file, filetype excluded. Set to false if unused.

Custom font source files italic.100 false file name

The Italic 100 font file, filetype excluded. Set to false if unused.

Custom font source files italic.200 false file name

The Italic 200 font file, filetype excluded. Set to false if unused.

Custom font source files italic.300 "ExampleSerif-LightItalic" file name

The Italic 300 font file, filetype excluded. Set to false if unused.

Custom font source files italic.400 "ExampleSerif-Italic" file name

The Italic 400 font file, filetype excluded. Set to false if unused.

Custom font source files italic.500 false file name

The Italic 500 font file, filetype excluded. Set to false if unused.

Custom font source files italic.600 false file name

The Italic 600 font file, filetype excluded. Set to false if unused.

Custom font source files italic.700 "ExampleSerif-BoldItalic" file name

The Italic 700 font file, filetype excluded. Set to false if unused.

Custom font source files italic.800 false file name

The Italic 800 font file, filetype excluded. Set to false if unused.

Custom font source files italic.900 false file name

The Italic 900 font file, filetype excluded. Set to false if unused.

Custom condensed source files $theme-font-cond-custom-src false map

See guidance above. Set to false if unused.

Custom icon source files $theme-font-icon-custom-src false map

See guidance above. Set to false if unused.

Custom language-specific source files $theme-font-lang-custom-src false map

See guidance above. Set to false if unused.

Custom monospaced source files $theme-font-mono-custom-src false map

See guidance above. Set to false if unused.

Custom sans-serif source files $theme-font-sans-custom-src false map

See guidance above. Set to false if unused.

Custom serif source files $theme-font-serif-custom-src false map

See guidance above. Set to false if unused.

Body font family $theme-body-font-family "body" family

Use theme tokens when possible.

Body font size $theme-body-font-size "sm" size

Use theme tokens when possible.

Body line height $theme-body-line-height 5 line-height

Use theme tokens when possible.

Style body element $theme-style-body-element false boolean

Add explicit body styles to the body element.

h1 font size $theme-h1-font-size "2xl" size
h2 font size $theme-h2-font-size "xl" size
h3 font size $theme-h3-font-size "lg" size
h4 font size $theme-h4-font-size "sm" size
h5 font size $theme-h5-font-size "xs" size
h6 font size $theme-h6-font-size "3xs" size
Heading line height $theme-heading-line-height 2 line-height
Small font size $theme-small-font-size "2xs" size

Used for the smallest text on a site.

Display font size $theme-display-font-size "3xl" size

Used for the largest text on a site.

Narrow measure $theme-text-measure-narrow 1 measure

Narrow line length.

Default measure $theme-text-measure 4 measure

Standard line length.

Wide measure $theme-text-measure-wide 6 measure

Wide line length.

Prose font family $theme-prose-font-family "body" family

Font family used for body text in usa-prose. Use role-based family tokens.

Lead (intro) font family $theme-lead-font-family "heading" family

Font family of intro text.

Lead (intro) font size $theme-lead-font-size "lg" size

Font size of intro text.

Lead (intro) line height $theme-lead-line-height 6 line-height

Line height of intro text.

Lead (intro) measure $theme-lead-measure 6 measure

Line length of intro text.

Heading top margin $theme-heading-margin-top 1.5em em

Top margin for headings in usa-prose.

Paragraph top margin $theme-paragraph-margin-top 1em em

Top margin for paragraphs in usa-prose.

Utilities settings

Name Variable Default Type Description
Utilities use !important $utilities-use-important false boolean

Output all utilities with !important. This can be necessary if you intend utilities to override existing styles.

Utilities uselist $output-these-utilities default list

Include a list of all utility modules to output. Ex: ("align-items", "border", "margin", "padding"). default includes all utilities.

Utility breakpoints $theme-utility-breakpoints map

Set which mobile-first breakpoints are output for the utilities.

Utility breakpoints "card" false boolean
Utility breakpoints "card-lg" false boolean
Utility breakpoints "mobile" false boolean
Utility breakpoints "mobile-lg" true boolean
Utility breakpoints "tablet" true boolean
Utility breakpoints "tablet-lg" false boolean
Utility breakpoints "desktop" true boolean
Utility breakpoints "desktop-lg" false boolean
Utility breakpoints "widescreen" false boolean
Global color palettes $global-color-palettes palettes

Any palettes added to this list will output in the the following utilities: background-color, border-color, color, text-decoration-color.

Utility settings $[utility-module]-settings map

Control the output of a [utility-module] and its responsive and state variants.

Utility settings "output" boolean

Output the utility.

Utility settings "responsive" boolean

Output the responsive variants.

Utility settings "active" boolean

Output the active: state variant.

Utility settings "focus" boolean

Output the focus: state variant.

Utility settings "hover" boolean

Output the hover: state variant.

Utility settings "visited" boolean

Output the visited: state variant.

Utility palettes $[utility-module]-palettes "palette-[utility-module]-default" palettes

Utilities output with the values set in the palettes list.

Utility manual values $[utility-module]-manual-values map

Utilities output with the tokens and values set in the manual values map.

Utility manual values [token name] [token value] map

Add a map of manual tokens and values in the form name: value.

Utility modules

Utility module name Class base Gzip size Default full size
add-aspect add-aspect- 0.08 KB 0.44 KB
add-list-reset add-list-reset 0.02 KB 0.12 KB
align-items flex- 0.04 KB 0.24 KB
align-self flex- 0.06 KB 0.31 KB
background-color bg- 1.0 KB 5.4 KB
border border- 4.35 KB 23.5 KB
border-color border- 4.35 KB 23.5 KB
border-radius border- 1.61 KB 8.7 KB
border-style border- 0.03 KB 0.14 KB
border-width border- 0.56 KB 3 KB
bottom bottom- 0.18 KB 0.96 KB
box-shadow shadow- 0.06 KB 0.33 KB
circle circle- 0.19 KB 1 KB
clearfix clearfix 0.02 KB 0.09 KB
color text- 0.37 KB 2 KB
cursor cursor- 0.07 KB 0.39 KB
display display- 0.28 KB 1.5 KB
flex flex- 0.06 KB 0.33 KB
flex-direction flex- 0.02 KB 0.1 KB
flex-wrap flex- 0.02 KB 0.1 KB
float float- 0.02 KB 0.1 KB
font font- 2.41 KB 13 KB
font-family font-family- 0.37 KB 2 KB
font-feature text- 0.03 KB 0.14 KB
font-style text- 0.02 KB 0.11 KB
font-weight text- 0.1 KB 0.54 KB
height height- 0.11 KB 0.6 KB
justify-content flex- 0.18 KB 0.95 KB
left left- 0.08 KB 0.44 KB
letter-spacing text-ls- 0.05 KB 0.28 KB
line-height line-height- 1.61 KB 8.7 KB
margin margin- 0.8 KB 4.35 KB
margin-horizontal margin- 4.02 KB 21.75 KB
margin-vertical margin- 4.02 KB 21.75 KB
max-height maxh- 0.12 KB 0.65 KB
max-width maxw- 0.13 KB 0.72 KB
measure measure- 0.18 KB 0.98 KB
min-height minh- 0.13 KB 0.72 KB
min-width minw- 0.07 KB 0.4 KB
opacity opacity- 0.24 KB 1.3 KB
order order- 0.26 KB 1.4 KB
outline outline- 0.03 KB 0.18 KB
outline-color outline- 0.56 KB 3 KB
overflow overflow- 0.09 KB 0.46 KB
padding padding- 4.02 KB 21.75 KB
pin pin- 0.06 KB 0.35 KB
position position- 0.04 KB 0.21 KB
right right- 0.09 KB 0.47 KB
square square- 0.14 KB 0.73 KB
text-align text- 0.03 KB 0.16 KB
text-decoration underline- 0.06 KB 0.32 KB
text-decoration-color text- 2.33 KB 12.6 KB
text-indent text-indent- 0.19 KB 1 KB
text-transform text- 0.04 KB 0.2 KB
top top- 0.07 KB 0.4 KB
vertical-align text- 0.06 KB 0.32 KB
whitespace text- 0.04 KB 0.2 KB
width width- 0.56 KB 3 KB
z-index z- 0.04 KB 0.22 KB

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-03-11 3.8.0
  • Accessibility
  • Styles
  • Settings
No

Added new sidenav setting to temporarily address visual regression in new markup guidance. The new setting $theme-sidenav-reorder allows users to temporarily reorder the sidenav with CSS. Users should follow new markup recommendation in code example to avoid accessibility issues. More information: uswds#5809

2024-03-11 3.8.0
  • Styles
  • Settings
No

Added $theme-table-background-color and $theme-table-sticky-top-offset settings. More information: uswds#5420

2024-03-11 3.8.0
  • Accessibility
  • Styles
No

Added color contrast checks for disabled tokens. On compilation, USWDS will test disabled element color contrast and provide a fallback color if minimum contrast is not met. If the fallback does not meet minimum requirements, USWDS will provide a warning in the terminal. More information: uswds#5455

2024-03-11 3.8.0
  • Styles
  • Settings
No

Added button icon gap setting. You can now customize the size of the gap between a button’s text and icon with $theme-button-icon-gap. More information: uswds#5398

2023-12-08 3.7.1
  • Styles
No

Fixed a bug that prevented $theme-max-header-width from accepting a value of “none”. More information: uswds#5624

2023-11-09 3.7.0
  • Styles
  • Settings
No

Fixed a bug that prevented $theme-site-margins-width from accepting expected token values. More information: uswds#5582

2023-11-09 3.7.0
  • Styles
  • Settings
No

Fixed a bug that prevented $theme-card-padding-y from accepting expected token values. More information: uswds#5571

2023-08-23 3.6.0
  • Styles
  • Settings
Breaking

Breaking Updated default disabled color settings values and added $theme-color-disabled-lighter and $theme-color-disabled-darker. If your project customizes disabled color settings, you probably need to update your configuration. More information: uswds#5402

2023-08-23 3.6.0
  • Styles
  • Settings
No

Fixed configuration errors with disabled color settings. All disabled color settings should now be configurable and accept hex color values. More information: uswds#5402

2023-08-23 3.6.0
  • Styles
No

Fixed a bug that prevented $theme-body-font-size from accepting 2xs and 3xs size tokens. More information: uswds#5363

2023-07-28 N/A
  • Guidance
No

Added a note about configuring settings that are described using dot notation. More information: uswds-site#2122

2023-06-09 3.5.0
  • Guidance
  • Settings
No

Added accordion color settings. You can now customize accordion button and content background colors with $theme-accordion-button-background-color and $theme-accordion-background-color. More information: uswds-site#2081

2023-06-09 3.5.0
  • Accessibility
  • Settings
No

Added settings for announcing external links. Added $theme-external-link-sr-label-tab-same and $theme-external-link-sr-label-tab-new to control how screen readers announce external links. More information: uswds#5166

2023-06-09 3.5.0
  • Guidance
  • Styles
Breaking

Breaking Updated individual Sass map settings without affecting defaults. Now adjusting a single Sass map setting no longer sets all other values in the map to false. Users can now update only the map values they wish to change. More information: uswds#5216

2023-03-20 N/A
  • Guidance
No

Updated settings information to match what is found in USWDS. More information: uswds-site#2016

2023-03-09 3.4.0
  • Guidance
  • Settings
No

Added $theme-font-browser-compatibility setting. We now only output woff2 fonts in our @font-face rules. If you need woff and ttf for IE11 compatibility, set this new setting to true. More information: uswds#5108

2023-03-09 3.4.0
  • Assets
  • Guidance
No

Removed woff and ttf file format requirements from custom font source settings. More information: uswds#5108

2022-09-16 N/A
  • Guidance
No

Fixed typos in primary-vivid and secondary-vivid variable names. More information: uswds-site#1767

2022-09-26 N/A
  • Guidance
No

Clarified instructions for settings configuration. More information: uswds-site#1755

2022-08-29 N/A
  • Guidance
No

Added documentation for $theme-footer-max-width. More information: uswds-site#1719

2022-08-05 3.1.0
  • Assets
  • Styles
Breaking

Breaking Updated the value of $theme-hero-image. We replaced our default hero image (PNG) with an optimized image (JPG). More information: uswds#4885

2022-07-17 N/A
  • Guidance
No

Added note about error handling for @use "uswds-core" with (). More information: uswds-site#1698

2022-06-17 3.0.2
  • Styles
No

Updated value of $theme-table-border-color from default to ink. More information: uswds#4712

2022-06-17 3.0.2
  • Assets
  • Styles
No

Fixed errors related to $theme-body-background-color. Updated icons so that custom background colors no longer cause compile failures. More information: uswds#4686

2022-06-17 3.0.2
  • Styles
No

Fixed precedence issue related to $theme-global-content-styles and $theme-global-paragraph-styles. More information: uswds#4726

2022-04-28 3.0.0
  • Styles
No

Replaced the outdated text: $output-all-utilities with updated: $output-these-utilities. This setting allows users to create a list of the utility modules they want to include in the project. More information: uswds#4631

2022-04-28 N/A
  • Guidance
No

Updated the settings page to use USWDS 3.0 conventions. More information: uswds-site#1538

2022-03-11 N/A
  • Guidance
No

Updated value of $theme-modal-lg-max-width from 800px to 880px. More information: uswds-site#1474

2021-06-16 2.12.0
  • Styles
No

Updated input settings. Added $theme-input-background-color; removed $theme-input-tile-background-color-selected, $theme-input-tile-border-color, and $theme-input-tile-border-color-selected. More information: uswds#4199

2021-06-16 2.12.0
  • Styles
No

Added pagination settings. More information: uswds#4175

2021-06-16 2.12.0
  • Styles
No

Updated values for $theme-color-success-dark and $theme-color-success-darker. More information: uswds#4183

2021-04-28 N/A
  • Guidance
No

Updated our docs and settings to remove $theme-site-max-width. In its place, use $theme-grid-container-max-width. More information: uswds-site#1198

2021-03-17 2.11.0
  • Styles
No

Added $theme-prefix-separator. This setting allows you to output any character or string for the separator between the prefix and main class. More information: uswds#4085

2021-03-17 2.11.0
  • Styles
No

Added $theme-alert-padding-y. More information: uswds#4079

2021-03-17 2.11.0
  • Styles
No

Added sortable table settings and updated values of other table settings. More information: uswds#3950

2021-03-17 2.11.0
  • Styles
No

Added modal settings. More information: uswds#3981

2021-03-17 2.11.0
  • Styles
No

Added icon list settings. More information: uswds#3876

2021-03-03 2.10.2
  • Styles
No

Improved use of $theme-text- and $theme-link- settings in components and variants like usa-dark-background and usa-section--dark. More information: uswds#4059

2021-02-19 2.10.1
  • Styles
No

Added new settings and updated settings values to repair color contrast issues. Added $theme-body-background-color, $theme identifier-primary-link-color, $theme-text- settings, and $theme-alert- settings; changed the value of $theme-breadcrumb-background-color. More information: uswds#3966

2021-02-19 2.10.1
  • Styles
Breaking

Breaking Replaced hard-coded value for alert component icon size with $theme-alert-icon-size. This update also changes the default value of the $theme-alert-icon-size from 4 to 5. More information: uswds#3942

2020-12-17 2.10.0
  • Styles
No

Added support for custom bold font weight by defining theme bold styles with $theme-font-weight-bold. More information: uswds#3811