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 |
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 |
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 |
Hover link color | $theme-color-info-family | 'primary-dark' | color |
Color for |
Active link color | $theme-color-info-family | 'primary-darker' | color |
Color for |
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 | |
Banner Max width | $theme-banner-max-width | 'desktop' | units |
Maximum width of the banner |
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 |
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 Max width | $theme-header-max-width | 'desktop' | units |
Maximum width of the header |
Header Min width | $theme-header-min-width | 'desktop' | units |
Breakpoint at which the non-mobile header is shown |
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 |
Hero Hero image | $theme-hero-image | '../img/hero.png' | path |
Background image for the hero. Use a path relative to the final project CSS. |
Navigation Font family | $theme-navigation-font-family | 'ui' | family | |
Navigation Megamenu columns | $theme-megamenu-columns | 3 | number |
Number of columns in the megamenu |
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 |
Spacing
Name | Variable | Default | Kind | Usage |
---|---|---|---|---|
sm border-radius token | $theme-border-radius-sm | 2px | units |
Sets |
md border-radius token | $theme-border-radius-md | 0.5 | units |
Sets |
lg border-radius token | $theme-border-radius-lg | 1 | units |
Sets |
Small grid gap | $theme-column-gap-sm | 2px | units |
Sets |
Medium grid gap | $theme-column-gap-md | 2 | units |
Sets |
Large grid gap | $theme-column-gap-md | 3 | units |
Sets |
Mobile grid gap | $theme-column-gap-mobile | 2 | units |
Sets value of |
Desktop grid gap | $theme-column-gap-desktop | 4 | units |
Sets value of |
Grid container max width | $theme-grid-container-max-width | 'desktop' | units |
Sets the |
Site max width | $theme-site-max-width | 'desktop' | units |
Used to set a consistent |
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 |
Typography
Name | Variable | Default | Kind | Usage |
---|---|---|---|---|
Respect user font size | $theme-respect-user-font-size | true | boolean |
When |
Root font size | $theme-root-font-size | 10px | px |
Only applies when |
Global paragraph styles | $theme-global-paragraph-styles | false | boolean |
Adds basic styling to |
Global link styles | $theme-global-link-styles | false | boolean |
Adds basic styling to |
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 |
cond font-family token | $theme-font-type-cond | false | family |
Project condensed font. |
icon font-type token | $theme-font-type-icon | false | family |
Project icon font. |
lang font-family token | $theme-font-type-lang | false | family |
Project language-specific font. |
mono font family token | $theme-font-type-mono | 'roboto-mono' | family |
Project monospaced font. |
sans font-family token | $theme-font-type-sans | 'source-sans-pro' | family |
Project sans-serif font. |
serif font-family token | $theme-font-type-serif | 'merriweather' | family |
Project serif font. |
ui font-family token | $theme-font-role-ui | 'sans' | family |
Assign font family used for interfaces and buttons from type-based |
heading font-family token | $theme-font-role-heading | 'serif' | family |
Assign font family used for headings from type-based |
body font-family token | $theme-font-role-body | 'serif' | family |
Assign font family used for body text from type-based |
code font-family token | $theme-font-role-code | 'serif' | family |
Assign font family used for code from type-based |
alt font-family token | $theme-font-role-alt | 'serif' | family |
Assign font family used for alternative type sections from type-based |
3xs font-size token | $theme-type-scale-3xs | 2 | size |
Use system |
2xs font-size token | $theme-type-scale-2xs | 3 | size |
Use system |
xs font-size token | $theme-type-scale-xs | 4 | size |
Use system |
sm font-size token | $theme-type-scale-sm | 5 | size |
Use system |
md font-size token | $theme-type-scale-md | 6 | size |
Use system |
lg font-size token | $theme-type-scale-lg | 9 | size |
Use system |
xl font-size token | $theme-type-scale-xl | 12 | size |
Use system |
2xl font-size token | $theme-type-scale-2xl | 14 | size |
Use system |
3xl font-size token | $theme-type-scale-3xl | 15 | size |
Use system |
thin font-weight token | $theme-font-weight-thin | false | weight |
Use system |
light font-weight token | $theme-font-weight-light | 300 | weight |
Use system |
normal font-weight token | $theme-font-weight-normal | 400 | weight |
Use system |
medium font-weight token | $theme-font-weight-medium | false | weight |
Use system |
semibold font-weight token | $theme-font-weight-medium | false | weight |
Use system |
bold font-weight token | $theme-font-weight-bold | 700 | weight |
Use system |
heavy font-weight token | $theme-font-weight-heavy | false | weight |
Use system |
Generate all font weights font-weight token | $theme-generate-all-weights | false | boolean |
If USWDS is generating your |
Condensed custom font stack | $theme-font-cond-custom-stack | false | font stack |
Custom font stack for condensed font. |
Icon font stack | $theme-font-icon-custom-stack | false | font stack |
Custom font stack for icon font. |
Language-specific font stack | $theme-font-lang-custom-stack | false | font stack |
Custom font stack for language-specific font. |
Monospaced font stack | $theme-font-mono-custom-stack | false | font stack |
Custom font stack for monospaced font. |
Sans-serif font stack | $theme-font-sans-custom-stack | false | font stack |
Custom font stack for sans-serif font. |
Serif font stack | $theme-font-serif-custom-stack | false | font stack |
Custom font stack for serif font. |
Custom font source files | $theme-font-[family]-custom-src | map |
If you want USWDS to generate additional |
|
Custom font source files | dir | 'custom/example-serif' | path |
Path relative to |
Custom font source files | roman.100 | false | file name |
The Roman 100 font file, filetype excluded.
|
Custom font source files | roman.200 | false | file name |
The Roman 200 font file, filetype excluded.
|
Custom font source files | roman.300 | 'ExampleSerif-Light' | file name |
The Roman 300 font file, filetype excluded.
|
Custom font source files | roman.400 | 'ExampleSerif-Normal' | file name |
The Roman 400 font file, filetype excluded.
|
Custom font source files | roman.500 | false | file name |
The Roman 500 font file, filetype excluded.
|
Custom font source files | roman.600 | false | file name |
The Roman 600 font file, filetype excluded.
|
Custom font source files | roman.700 | 'ExampleSerif-Bold' | file name |
The Roman 700 font file, filetype excluded.
|
Custom font source files | roman.800 | false | file name |
The Roman 800 font file, filetype excluded.
|
Custom font source files | roman.900 | false | file name |
The Roman 900 font file, filetype excluded.
|
Custom font source files | italic.100 | false | file name |
The Italic 100 font file, filetype excluded.
|
Custom font source files | italic.200 | false | file name |
The Italic 200 font file, filetype excluded.
|
Custom font source files | italic.300 | 'ExampleSerif-LightItalic' | file name |
The Italic 300 font file, filetype excluded.
|
Custom font source files | italic.400 | 'ExampleSerif-Italic' | file name |
The Italic 400 font file, filetype excluded.
|
Custom font source files | italic.500 | false | file name |
The Italic 500 font file, filetype excluded.
|
Custom font source files | italic.600 | false | file name |
The Italic 600 font file, filetype excluded.
|
Custom font source files | italic.700 | 'ExampleSerif-BoldItalic' | file name |
The Italic 700 font file, filetype excluded.
|
Custom font source files | italic.800 | false | file name |
The Italic 800 font file, filetype excluded.
|
Custom font source files | italic.900 | false | file name |
The Italic 900 font file, filetype excluded.
|
Custom condensed source files | $theme-font-cond-custom-src | false | map |
See guidance above. |
Custom icon source files | $theme-font-icon-custom-src | false | map |
See guidance above. |
Custom language-specific source files | $theme-font-lang-custom-src | false | map |
See guidance above. |
Custom monospaced source files | $theme-font-mono-custom-src | false | map |
See guidance above. |
Custom sans-serif source files | $theme-font-sans-custom-src | false | map |
See guidance above. |
Custom serif source files | $theme-font-serif-custom-src | false | map |
See guidance above. |
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 |
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 |
Lead (intro) font family | $theme-lead-font-family | 'heading' | family |
This name may change. Use role-based |
Lead (intro) font size | $theme-lead-font-size | 'lg' | size |
This name may change. Use role-based |
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 |
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: |
|
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 |
Utility settings | 'focus' | — | boolean |
Control output of the |
Utility settings | 'hover' | — | boolean |
Control output of the |
Utility settings | 'visited' | — | boolean |
Control output of the |
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 |