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

Banner

Name	Variable	Default	Type	Description
Background color	`$theme-banner-background-color`	"base-lightest"	color	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.

Footer

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.

Header

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.

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

Link

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.

Search

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.

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
Custom breakpoints	`$theme-utility-breakpoints-custom`		map	Set additional custom mobile-first breakpoints to be output for the utilities. Values must be passed in with `px` values inside a Sass map.
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-10-04	3.9.0	Styles Settings	No	Added new `$theme-utility-breakpoints-custom` setting. Users can now set custom breakpoints which will generate utilities alongside the default system breakpoints. More information: uswds#6048
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