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 tables below.

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

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

Note: the @use "uswds-core" with () configuration accepts only current USWDS settings variables. 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 list below and try compiling again.

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-"
Namespace	grid.output	true
Namespace	utility.namespace	"u-"
Namespace	utility.output	true
Important layout grid	`$theme-layout-grid-use-important`	false	boolean	Output grid classes output 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 default 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-lightest 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.
info-light state color token	`$theme-color-disabled-light`	"gray-10"	color	Use grade 10.
info state color token	`$theme-color-disabled`	"gray-20"	color	Use grade 20.
info-dark state color token	`$theme-color-disabled-dark`	"gray-30"	color	Use grade 30.
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 `:visted` 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 reverse text links.
Link reverse hover color	`$theme-link-reverse-hover-color`	"base-lightest"	color	Color for reverse `:hover` text links.
Link reverse hover color	`$theme-link-reverse-active-color`	"white"	color	Color for reverse `:active` text links.

Component settings

Accordion

Name	Variable	Default	Type	Description
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.
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.
Text color	`$theme-alert-text-color`	default	color	Text 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`.
Link color	`$theme-alert-text-color`	default	color	Link color on light backgrounds. `Default` uses link color set in `$theme-link-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"	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`	"sm"	family	The family of the breadcrumb text.
Font size	`$theme-breadcrumb-font-size`	"sm"	units	The size of the breadcrumb text.
Breadcrumb gap	`$theme-breadcrumb-gap`	1.5	units	The space between indicator icons and 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 under 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
Font family	`$theme-button-font-family`	"ui"	family	Font family of the button.
Border radius	`$theme-button-border-radius`	"md"	units	Button border radius for rounded corners.
Small width	`$theme-button-small-width`	6	units	Size of the header search 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	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.
Selected background color	`$theme-input-tile-background-color-selected`	"accent-cool-lighter"	color	Tile background color when selected.
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
Tile border color	`$theme-input-tile-border-color`	"base-lighter"	color	Tile border color.
Tile border color selected	`$theme-input-tile-border-color-selected`	"accent-cool-light"	color	Tile border color when selected.

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	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 nav. `Default` uses the default link settings calculated from your background color.
Active state 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 nav.
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 nav. `Default` uses the default link settings calculated from your background color.
Content 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 when selected.
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
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.
Max width	`$theme-modal-lg-max-width`	'tablet-lg'	units	Maximum width of large modal window.
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 columns	`$theme-megamenu-columns`	3	number	Number of columns in the megamenu.

Pagination

Name	Variable	Default	Type	Description
Pagination background color	`$theme-pagination-background-color`	"white"	color	The background color of the entire pagination component, used for accessible color setting.
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	size	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"	units	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	size	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	size	Width of the connector line between counter circles.
Font family of content	`$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.
Font family of heading	`$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
Selected background color	`$theme-input-tile-background-color-selected`	"accent-cool-lighter"	color	Tile background color when selected.
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.
Tile border color	`$theme-input-tile-border-color`	"base-lighter"	color	Tile border color.
Tile border color selected	`$theme-input-tile-border-color-selected`	"accent-cool-light"	color	Tile border color when selected.

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.

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	size	Gap between the counter and the segment.
Counter border width	`$theme-step-indicator-counter-border-width`	0.5	size	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"	size	Width at which the component displays large-width features.
Pending segment color	`$theme-step-indicator-segment-color-pending`	"base-lighter"	color	Color of pending step segments. Use a grade of 20 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 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 more 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	size	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-link-color`	default	color	Color of the links inside the content text. When set to “default”, text will get one of two values, based on contrast: “white” or “ink”.

Tables

Name	Variable	Default	Type	Description
Border color	`$theme-table-border-color`	default	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.
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.
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.
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.
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 Background Color	`$theme-table-sorted-background-color`	"accent-cool-lighter"	color	Defines a background color for the cells of the sorted column.
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
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.
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.

Spacing settings

Name	Variable	Default	Type	Description
sm border-radius token	`$theme-border-radius-sm`	2px	units	Sets `"sm"` `border-radius` theme token.
md border-radius token	`$theme-border-radius-md`	0.5	units	Sets `"md"` `border-radius` theme token.
lg border-radius token	`$theme-border-radius-lg`	1	units	Sets `"lg"` `border-radius` theme token.
Small grid gap	`$theme-column-gap-sm`	2px	units	Sets `"grid-gap-sm"` token.
Medium grid gap	`$theme-column-gap-md`	2	units	Sets `"grid-gap-md"` token.
Large grid gap	`$theme-column-gap-md`	3	units	Sets `"grid-gap-lg"` token.
Mobile grid gap	`$theme-column-gap-mobile`	2	units	Sets value of `"grid-gap"` at `mobile` width.
Desktop grid gap	`$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.

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.
Custom typeface tokens	`$theme-typeface-tokens`		map	Add custom typeface tokens.
Custom typeface tokens	token	example-sans-token
Custom typeface tokens	token.display-name	"Example Sans Display Name"
Custom typeface tokens	token.cap-height	364px
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 font stack	`$theme-font-icon-custom-stack`	false	font stack	Custom font stack for icon font. Set to `false` if unused.
Language-specific font stack	`$theme-font-lang-custom-stack`	false	font stack	Custom font stack for language-specific font. Set to `false` if unused.
Monospaced font stack	`$theme-font-mono-custom-stack`	false	font stack	Custom font stack for monospaced font. Set to `false` if unused.
Sans-serif font stack	`$theme-font-sans-custom-stack`	false	font stack	Custom font stack for sans-serif font. Set to `false` if unused.
Serif 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 `.ttf`, `.woff`, and `.woff2`.
Custom font source files	dir	"custom/example-serif"
Custom font source files	roman.100	false
Custom font source files	roman.200	false
Custom font source files	roman.300	"ExampleSerif-Light"
Custom font source files	roman.400	"ExampleSerif-Normal"
Custom font source files	roman.500	false
Custom font source files	roman.600	false
Custom font source files	roman.700	"ExampleSerif-Bold"
Custom font source files	roman.800	false
Custom font source files	roman.900	false
Custom font source files	italic.100	false
Custom font source files	italic.200	false
Custom font source files	italic.300	"ExampleSerif-LightItalic"
Custom font source files	italic.400	"ExampleSerif-Italic"
Custom font source files	italic.500	false
Custom font source files	italic.600	false
Custom font source files	italic.700	"ExampleSerif-BoldItalic"
Custom font source files	italic.800	false
Custom font source files	italic.900	false
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
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
Default measure	`$theme-text-measure`	4	measure
Wide measure	`$theme-text-measure-wide`	6	measure
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	This name may change. Use role-based `family` tokens.
Lead (intro) font size	`$theme-lead-font-size`	"lg"	size	This name may change. Use role-based `size` tokens.
Lead (intro) line height	`$theme-lead-line-height`	6	line-height	This name may change.
Lead (intro) measure	`$theme-lead-measure`	6	measure	This name may change.

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-tems", "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
Utility breakpoints	"card-lg"	false
Utility breakpoints	"mobile"	false
Utility breakpoints	"mobile-lg"	true
Utility breakpoints	"tablet"	true
Utility breakpoints	"tablet-lg"	false
Utility breakpoints	"desktop"	true
Utility breakpoints	"desktop-lg"	false
Utility breakpoints	"widescreen"	false
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"	—
Utility settings	"responsive"	—
Utility settings	"active"	—
Utility settings	"focus"	—
Utility settings	"hover"	—
Utility settings	"visited"	—
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]-palettes`	"palette-[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]

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