Design tokens

Theme color tokens

USWDS theme color tokens provide flexible, accessible, customizable color choices for your project.

USWDS theme color tokens are designed to be useful and effective for small and large projects. Each theme token is drawn from a system color token and we only use token-based colors in official components.

Theme color tokens

USWDS theme color tokens are divided into five high-level role-based color families: base, primary, secondary, accent-warm, and accent-cool.

Base is a project’s neutral color, typically some tint of gray, and usually used as the text color throughout.

Primary, secondary, and accent colors can be thought of as falling into a proportional 60/30/10 relationship: about 60% of your site’s color would be the primary color family, about 30% would be the secondary color family, and about 10% would be the accent color families (accent-warm and accent-cool). Note that these proportions are for non-base colors. In many cases, the neutral base text color will be the predominant tone on your site.

Each color family has seven possible lightness grades, from lightest to darkest, though not every family needs to include a color at each grade. Some grades may be set to false in your project’s theme settings. The default USWDS theme palette does not use every grade for every family. The primary and secondary families also have a vivid grade available.

Customize theme color tokens using the variables listed below in _uswds_theme_color.scss with system color tokens. Set any unused theme color to false.

Color Token Default Settings variable Value
'base-lightest' 'gray-5' $theme-color-base-lightest #f0f0f0
'base-lighter' 'gray-cool-10' $theme-color-base-lighter #dcdee0
'base-light' 'gray-cool-30' $theme-color-base-light #a9aeb1
'base' 'gray-cool-50' $theme-color-base #71767a
'base-dark' 'gray-cool-60' $theme-color-base-dark #565c65
'base-darker' 'gray-cool-70' $theme-color-base-darker #3d4551
'base-darkest' 'gray-90' $theme-color-base-darkest #1b1b1b
'ink' 'gray-90' $theme-color-ink #1b1b1b
'primary-lighter' 'blue-10' $theme-color-primary-lighter #d9e8f6
'primary-light' 'blue-30' $theme-color-primary-light #73b3e7
'primary' 'blue-60v' $theme-color-primary #005ea2
'primary-vivid' 'blue-warm-60v' $theme-color-primary-vivid #0050d8
'primary-dark' 'blue-warm-70v' $theme-color-primary-dark #1a4480
'primary-darker' 'blue-warm-80v' $theme-color-primary-darker #162e51
'secondary-lighter' 'red-cool-10v' $theme-color-secondary-lighter #f8dfe2
'secondary-light' 'red-30' $theme-color-secondary-light #f2938c
'secondary' 'red-50' $theme-color-secondary #d83933
'secondary-vivid' 'red-cool-50v' $theme-color-secondary-vivid #e41d3d
'secondary-dark' 'red-60v' $theme-color-secondary-dark #b51d09
'secondary-darker' 'red-70v' $theme-color-secondary-darker #8b1303
'accent-cool-lighter' 'blue-cool-5v' $theme-color-accent-cool-lighter #e1f3f8
'accent-cool-light' 'blue-cool-20v' $theme-color-accent-cool-light #97d4ea
'accent-cool' 'cyan-30v' $theme-color-accent-cool #00bde3
'accent-cool-dark' 'blue-cool-40v' $theme-color-accent-cool-dark #28a0cb
'accent-cool-darker' 'blue-cool-60v' $theme-color-accent-cool-darker #07648d
'accent-warm-lighter' 'orange-10' $theme-color-accent-warm-lighter #f2e4d4
'accent-warm-light' 'orange-20v' $theme-color-accent-warm-light #ffbc78
'accent-warm' 'orange-30v' $theme-color-accent-warm #fa9441
'accent-warm-dark' 'orange-50v' $theme-color-accent-warm-dark #c05600
'accent-warm-darker' 'orange-60' $theme-color-accent-warm-darker #775540

Using color tokens

Your context and coding style determine how you access USWDS color tokens in code.

Context Usage Example
function color(color) color: color('primary-vivid')
mixin
background-color
u-bg(color) @include u-bg('primary-vivid')
mixin
color
u-text(color)
@include u-text('primary-vivid')
mixin
border-color
u-border(color) @include u-border('primary-vivid')
mixin
text-decoration-color
u-underline(color) @include u-underline('primary-vivid')
setting
color $theme-border-color: 'primary-vivid'
utility
background-color
.bg-color .bg-base-lighter
utility
border-color
.border-color .border-primary
utility
color
.text-color .text-primary
utility
outline-color
.outline-color .outline-primary
utility
text-decoration-color
.underline-color .underline-primary-vivid