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.
About 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.
Customizing theme color tokens
Customize theme color tokens in your USWDS settings configuration using the variables listed in the theme color
tokens table below. Define theme variables with
system color tokens.
Set any unused theme color to false.
For example, if you wanted to set the value of the primary-vivid token to blue-warm-50v, your settings
configuration would look like this:
@use "uswds-core" with (
$theme-color-primary-vivid: "blue-warm-50v",
);
Theme color tokens table
| Color | Token | Default | Settings variable | Value |
|---|---|---|---|---|
| 'base-lightest' | 'gray-5' | $theme-color-base-lightest | #f0f0f0 | |
| 'base-lighter' | 'gray-cool-10' | $theme-color-base-lighter | #dfe1e2 | |
| '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-base-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-10' | $theme-color-secondary-lighter | #f3e1e4 | |
| '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 | #b50909 | |
| 'secondary-darker' | 'red-70v' | $theme-color-secondary-darker | #8b0a03 | |
| '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 theme color tokens
Your context and coding style determine how you access USWDS theme color tokens in code.
For example, all three of the following examples result in the same output:
// function
div {
background-color: color("primary");
}
// mixin
div {
@include u-bg("primary");
}
// utility
<div class="bg-primary">...</div>
| 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-link-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
|
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 |
| 2024-05-15 | N/A |
|
Updated the documented value of the |
| 2024-05-15 | N/A |
|
Removed emergency color examples. These colors are instead documented on the state color page. More information: uswds-site#2377 |
