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, emergency, and disabled.
Each color family except emergency and 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 | #99deea | |
| '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 | #d54309 | |
| 'error-dark' | 'red-60v' | $theme-color-error-dark | #b50909 | |
| '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-50v' | $theme-color-success-dark | #008817 | |
| 'success-darker' | 'green-cool-60v' | $theme-color-success-darker | #216e1f | |
| 'disabled-lighter' | 'gray-20' | $theme-color-disabled-lighter | #c9c9c9 | |
| 'disabled-light' | 'gray-40' | $theme-color-disabled-light | #919191 | |
| 'disabled' | 'gray-50' | $theme-color-disabled | #757575 | |
| 'disabled-dark' | 'gray-70' | $theme-color-disabled-dark | #454545 | |
| 'disabled-darker' | 'gray-90' | $theme-color-disabled-darker | #1b1b1b | |
| 'emergency' | 'red-warm-60v' | $theme-color-emergency | #9c3d10 | |
| 'emergency-dark' | 'red-warm-80' | $theme-color-emergency-dark | #332d29 |
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
|
Latest updates
Meaningful code and guidance updates are listed in the following table:
| Date | USWDS version | Affects | Description |
|---|---|---|---|
| 2023-08-23 | 3.6.0 |
|
Breaking
Updated the default values for all disabled tokens and added |
| 2021-12-21 | N/A |
|
Updated the documentation for |
| 2021-06-16 | 2.12.0 |
|
Updated the values of |
