Design tokens

The Design System’s visual design is based on consistent palettes of typography, spacing units, color, and other discrete elements of style we call design tokens.

Introducing design tokens

Anything we see on a website is built from elements of style: color, spacing, typography, line height, and opacity. The CSS rules associated with these elements can accept a broad continuum of values — in the case of color, there are over 16 million separate colors in the RGB color space. Font size, line height, spacing, and others can accept a similarly wide range of values.

This degree of choice can slow down design work and make communication between designer and developer unnecessarily granular. The Design System seeks to maximize design efficiency and improve communication with design tokens: the discrete palettes of values from which we base all our visual design.

Our System design tokens are a limited set of discrete options, just like a scale of musical notes is drawn from the spectrum of all possible frequencies. Or like the presets on a car radio — not every option, just a specific selection. Take the following figure for instance: In the spectrum of hues between white and black, we provide a curated selection of five:

continuous and tokenized values

Example: Measure (line length)

For example, measure (or line length) expressed with the max-width CSS property can accept any value in units like em, rem, ch, ex, and px to at least two decimal places. The Design System limits itself to seven measure tokens, the values of which are given in the following table:

token value
1 44ex
2 60ex
3 64ex
4 68ex
5 72ex
6 88ex
'none' no max width

Anything built using the Design System will use one of these seven measure tokens when specifying measure.

Keys and values

You can think of a design token as a key that unlocks a specific value. Often, the specific value is less important than its effect. Each token is a quoted string or, with only the exceptions of 1px and 2px, a unitless number — and the mechanism by which the final display value is unlocked is a function, mixin, or utility class.

We can’t include tokens, like max-width: 1, directly in our Sass. Rather, we use a helper function like max-width: measure(1) or a mixin like @include u-measure(1). All our design tokens have helper mixins and functions to use them in component Sass.

Note: We do not include the token’s value directly into our Sass rules.

Example: Tokens in settings and component Sass

Tokens can be expressed as variables, which is how most Design System theme settings work. For instance, the following is an example of theme settings in your USWDS settings configuration. This example shows spacing unit tokens assigned to settings variables:

@use "uswds-core" with (
  $theme-grid-container-max-width:    'desktop',
  $theme-site-margins-breakpoint:     'desktop',
  $theme-site-margins-width:          4,
  $theme-site-margins-mobile-width:   2,
);

The Design System’s component Sass uses those variableized tokens to build component styles as in the following code:

.usa-example {
  @include u-padding-x($theme-site-margins-mobile-width);
  max-width: units($theme-grid-container-max-width);

  @include at-media($theme-site-margins-breakpoint) {
    @include u-padding-x($theme-site-margins-width);
  }
}

This example is the functional equivalent of the following code:

.usa-example {
  @include u-padding-x(2);
  max-width: units('desktop');

  @include at-media('desktop') {
    @include u-padding-x(4);
  }
}

In this case, if $theme-respect-user-font-size is set to true, the output would be something like the following code:

.usa-example {
  padding-left: 1rem;
  padding-right: 1rem;
  max-width: 64rem;
}

@media screen and (min-width: 64em) {
  .usa-example {
    padding-left: 2rem;
    padding-right: 2rem;
  }
}

In general, the Design System sets variables with tokens and passes those variables into functions and mixins in the source Sass.

Using design tokens

Use design tokens, like $theme-grid-container-max-width: 'desktop', directly to set the value of settings variables in our theme settings files. Otherwise, use functions, mixins, or utility classes as in the following tables on color, spacing units, font size, font family, and font family and size together:

Color

Token Function Mixin Utility class
color color(color) u-border(color) .border-color
'red' color('red') u-border('red') .border-red
'primary-vivid' color('primary-vivid') u-text('primary-vivid') .text-primary-vivid
'white' color('white') u-bg('white') .bg-white

Spacing units

Token Function Mixin Utility class
units units(units) u-padding-x(units) .padding-x-units
0.5
'05'
units(0.5)
units('05')
u-padding-x(0.5)
u-padding-x('05')
.padding-x-05
1 units(1) u-border(1) .border-1
'card-lg' units('card-lg') u-width('card-lg') .width-card-lg

Font size

Token Function Mixin Utility class
family, size size(family, size) u-font-size(family, size)
'sans', '3xs' size('sans', '3xs') u-font-size('sans', '3xs')
'ui', 'micro' size('ui', 'micro') u-font-size('ui', 'micro')
'body', 15 size('body', 15) u-font-size('body', 15)

Font family

Token Function Mixin Utility class
family family(family) u-font-family(family) .font-family-family
'sans' family('sans') u-font-family('sans') .font-family-sans
'ui' family('ui') u-font-family('ui') .font-family-ui
'body' family('body') u-font-family('body') .font-family-body

Font family and size together

Token Function Mixin Utility class
family, size u-font(family, size) .font-family-size
'sans', '3xs' u-font('sans', '3xs') .font-sans-3xs
'ui', 'lg' u-font('ui', 'lg') .font-ui-lg
'body', '2xl' u-font('body', '2xl') .font-body-2xl

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2023-12-04 N/A
  • Guidance
No

Updated token references in “Using design tokens” section. More information: uswds-site#2366

2023-12-04 N/A
  • Guidance
No

Updated the settings configuration code example. More information: uswds-site#2366