Documentation

Settings

Theme settings variables control the appearance of USWDS components and the values of USWDS theme tokens.

Copy the dist/src/stylesheets/theme directory out of the USWDS package and use its contents to control the appearance of USWDS components and the values of USWDS theme tokens.

Use the @import directive in Sass to import these settings files before importing the main USWDS Sass with @import uswds. You can use the styles.scss file in the directory as a starting place:

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

General

Name Variable Default Kind Usage
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.

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

Set prefix output

Namespace utility.namespace 'u-' string

The utility class prefix

Namespace utility.output true boolean

Set prefix output

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

Should the layout grid classes output with !important

Border box sizing $theme-global-border-box-sizing false 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 border-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

Name Variable Default Kind Usage
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

Disabled color family $theme-color-info-family 'gray' color

Color family of disabled actions

info-light state color token $theme-color-info-light 'gray-10' color

Use grade 10

info state color token $theme-color-info 'gray-20' color

Use grade 20

info-dark state color token $theme-color-info-dark 'gray-30' color

Use grade 30

Link color $theme-color-info-family 'primary' color

Color for text links

Visited link color $theme-color-info-family 'violet-70v' color

Color for :visted text links

Hover link color $theme-color-info-family 'primary-dark' color

Color for :hover text links

Active link color $theme-color-info-family 'primary-darker' color

Color for :active text links

Components

Name Variable Default Kind Usage
Accordion border width $theme-accordion-border-width 0.5 units
Accordion border color $theme-accordion-border-color 'base-lightest' color
Accordion font family $theme-accordion-font-family 'body' family
Alert Bar width $theme-alert-bar-width 0.5 units

Width of the colored bar to the left of the alert

Alert Font family $theme-alert-font-family 'ui' family
Alert Icon size $theme-accordion-icon-size 4 units

Size of the alert icon

Alert Horizontal padding $theme-accordion-padding-x 2.5 units

Padding on the left and right of the alert

Banner Font family $theme-banner-font-family 'ui' family
Button Font family $theme-button-font-family 0.5 units
Button Border radius $theme-button-border-radius 'ui' family
Button Small width $theme-button-small-width 4 units

Size of the header search button

Button Stroke width $theme-accordion-padding-x 2px units

Stroke width of outline button variants

Footer Font family $theme-footer-font-family 0.5 units

Font family of the footer

Checkbox Border radius $theme-checkbox-border-radius 'sm' border-radius
Form Font family $theme-form-font-family 'ui' family
Input Line height $theme-input-line-height 3 line-height
Input Max width $theme-input-max-width 'mobile-lg' units
Input Border width when selected $theme-input-select-border-width 2px units

Border width when selected

Input Border width of selection element $theme-input-select-border-width 2px units

Border width of checkboxes and radio buttons

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

Height and width checkboxes and radio buttons

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

Border width of special state inputs (like error state)

Header Font family $theme-header-font-family 'ui' family
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

Navigation Font family $theme-navigation-font-family 'ui' family
Navigation Width $theme-navigation-width 'desktop' units

Max width of the top nav

Search Font family $theme-search-font-family 'ui' family
Search Min-width $theme-search-min-width 27ch

Min-width of the search input

Sidenav Font family $theme-sidenav-font-family 'ui' family
Sidenav Current border width $theme-sidenav-current-border-width 0.2 units

Width of the current section indicator

Footer Font family $theme-footer-font-family 0.5 units
Button Border radius $theme-alert-font-family 'ui' family
Button Small width $theme-accordion-icon-size 4 units

Size of the alert icon

Button Stroke width $theme-accordion-padding-x 2px units

Stroke width of outline button variants

Spacing

Name Variable Default Kind Usage
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' output

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

Sets 'grid-gap-md' output

Large grid gap $theme-column-gap-md 3 units

Sets 'grid-gap-lg' output

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

At what breakpoint should the site’s outer margin change

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

Site outer margin at mobile width

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

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

Typography

Name Variable Default Kind Usage
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. Sets the root font size to the specified px value and uses px values for media queries.

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

Adds basic styling to p elements

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

Adds basic styling to a elements

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

Adds 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-serif-token string

The 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 'serif' family

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

code font-family token $theme-font-role-code 'serif' 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-medium 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 your @font-face rules, should we 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' 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-font-size 5 line-height
Style body element $theme-style-body-element false boolean

Explicitly apply 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' line-height

Used for the smallest text on a site

Display font size $theme-display-font-size '3xs' size

Used for the largest text on a site

Narrow measure $theme-text-measure-narrow 1 measure
Default measure $theme-h2-font-size 4 measure
Wide measure $theme-h2-font-size 5 measure
Prose font family $theme-h2-font-size '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

Name Variable Default Kind Usage
Utilities use !important $utilities-use-important false boolean

When true utilities will all ouput 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 boolean
Utility breakpoints 'card-lg' false boolean
Utility breakpoints 'mobile' false boolean
Utility breakpoints 'mobile-lg' true boolean
Utility breakpoints 'tablet' true boolean
Utility breakpoints 'tablet-lg' false boolean
Utility breakpoints 'desktop' true boolean
Utility breakpoints 'desktop-lg' false boolean
Utility breakpoints 'widescreen' false boolean
Global color palettes $global-color-palettes palettes

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

Utility settings $[utility]-settings map

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

Utility settings 'output' boolean

Control output of the utility.

Utility settings 'responsive' boolean

Control output of the responsive variants

Utility settings 'active' boolean

Control output of the active: state variant

Utility settings 'focus' boolean

Control output of the focus: state variant

Utility settings 'hover' boolean

Control output of the hover: state variant

Utility settings 'visited' boolean

Control output of the visited: state variant

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

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