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.
Customizing state color tokens
Customize state color tokens in your USWDS settings configuration using the variables listed in the state color
tokens table below. Define state variables with
system color tokens.
Set any unused theme color to false.
For example, if you wanted to set the value of the error-dark token to red-warm-60v, your settings
configuration would look like this:
@use "uswds-core" with (
$theme-color-error-dark: "red-warm-60v",
);
State color tokens table
| 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-alert-text-color: '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 |
|---|---|---|---|
| 2024-05-15 | N/A |
|
Updated guidance for configuring color settings. More information: uswds-site#2377 |
| 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 |
