Design tokens

State color tokens

USWDS state colors tokens provide flexible, accessible, customizable colors for warning, error, and other states

USWDS state color tokens are designed to be useful and effective for any project that has states or alerts. Each state token is drawn from a system color token and we only use token-based colors in official components.

State color tokens

The state color palette is divided into five high-level role-based color families: info, error, warning, success, and disabled.

Each color family except disabled has five possible lightness grades, from lighter to darker, 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.

Customize state 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
'info-lighter' 'cyan-5' $theme-color-info-lighter #e7f6f8
'info-light' 'cyan-20' $theme-color-info-light #9ddfeb
'info' 'cyan-30v' $theme-color-info #00bde3
'info-dark' 'cyan-40v' $theme-color-info-dark #009ec1
'info-darker' 'blue-cool-60' $theme-color-info-darker #2e6276
'error-lighter' 'red-warm-10' $theme-color-error-lighter #f4e3db
'error-light' 'red-warm-30v' $theme-color-error-light #f39268
'error' 'red-warm-50v' $theme-color-error #d63e04
'error-dark' 'red-60v' $theme-color-error-dark #b51d09
'error-darker' 'red-70' $theme-color-error-darker #6f3331
'warning-lighter' 'yellow-5' $theme-color-warning-lighter #faf3d1
'warning-light' 'yellow-10v' $theme-color-warning-light #fee685
'warning' 'gold-20v' $theme-color-warning #ffbe2e
'warning-dark' 'gold-30v' $theme-color-warning-dark #e5a000
'warning-darker' 'gold-50v' $theme-color-warning-darker #936f38
'success-lighter' 'green-cool-5' $theme-color-success-lighter #ecf3ec
'success-light' 'green-cool-20v' $theme-color-success-light #70e17b
'success' 'green-cool-40v' $theme-color-success #00a91c
'success-dark' 'green-cool-50' $theme-color-success-dark #4d8055
'success-darker' 'green-cool-60' $theme-color-success-darker #446443
'disabled-light' 'gray-10' $theme-color-disabled-light #e6e6e6
'disabled' 'gray-20' $theme-color-disabled #c9c9c9
'disabled-dark' 'gray-30' $theme-color-disabled-dark #adadad

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('warning-dark')
mixin
background-color
u-bg(color) @include u-bg('warning-dark')
mixin
color
u-text(color)
@include u-text('warning-dark')
mixin
border-color
u-border(color) @include u-border('warning-dark')
mixin
text-decoration-color
u-underline(color) @include u-underline('warning-dark')
setting
color $theme-color-warning: 'warning-dark'
mixin
text-decoration-color
u-underline(color) @include u-underline('warning-dark')
utility
background-color
.bg-color .bg-warning-light
utility
border-color
.border-color .border-error
utility
color
.text-color .text-error
utility
outline-color
.outline-color .outline-error
utility
text-decoration-color
.underline-color .underline-error