How to use USWDS

Settings

USWDS settings variables tell the design system how to build.

A good way to get started with USWDS settings is to copy the dist/scss/theme directory out of the uswds package and into the same directory where you keep your project Sass files. Then use the @import directive in Sass to import these settings before importing the main USWDS Sass. You can use the styles.scss example file in the dist/scss/theme directory as a starting point for your own Sass entry point:

// -------------------------------------
// Import individual theme settings

@import 'uswds-theme-general';
@import 'uswds-theme-typography';
@import 'uswds-theme-spacing';
@import 'uswds-theme-color';
@import 'uswds-theme-utilities';

// -------------------------------------
// Import individual USWDS modules...

// @import 'uswds-fonts';
// @import 'uswds-layout-grid';
// @import 'uswds-components';
// @import 'uswds-utilities';

// -------------------------------------
// ...or import all USWDS modules

@import 'uswds';

// -------------------------------------
// Import theme custom styles

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

You can also add only the settings you wish to modify before importing uswds, either in a separate file, or directly in your Sass entry point:

$theme-show-compile-warnings: false;
$theme-show-notifications: false;

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

In general, when importing settings and custom code, you just need to follow this order of operations:

  1. Import settings: Tell the design system how to build.
  2. Import uswds: Build the design system.
  3. Import custom styles: Build on top of the design system.

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
Focus offset $theme-focus-offset 0 units

The offset between the element and the focus outline
Focus style $theme-focus-style solid outline-style
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 "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 "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-60v" 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-50" color

Use grades 60-70.
success-darker state color token $theme-color-success-darker "green-cool-60" 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 color $theme-accordion-border-color "base-lightest" color
Font family $theme-accordion-font-family "body" family

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

Breadcrumb

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
Border radius $theme-button-border-radius "md" units
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 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

Form

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

Header

Name Variable Default Type Description
Font family $theme-header-font-family "ui" family
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.

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.

Input

Name Variable Default Type Description
Line height $theme-input-line-height 3 line-height
Max width $theme-input-max-width "mobile-lg" units
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)

Navigation

Name Variable Default Type Description
Font family $theme-navigation-font-family "ui" family
Megamenu columns $theme-megamenu-columns 3 number

Number of columns in the megamenu

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

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

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 "base-dark" color

Defines a border color for table cells.
Text color $theme-table-text-color "ink" color

Defines a text color for table cells.
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 "ink" color

Defines a text color for header cells.
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 "ink" color

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

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 max width $theme-site-max-width "desktop" units

Used to set a consistent max-width across components
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.
Output all utilities $output-all-utilities true boolean

Output all utilities regardless of any individual utility’s output setting.
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]-settings map

Control the output of a [utility] 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]-palettes "palette-[utility]-default" palettes

Utilities output with the values set in the palettes list.
Utility manual values $[utility]-palettes "palette-[utility]-manual-values" map

Utilities output with the tokens and values set in the manual values map.
Utility manual values [token name] [token value]