Design tokens

USWDS 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: elements like 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. USWDS seeks to maximize design efficiency and improve communication with design tokens: the discrete palettes of values from which we base all our visual design.

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.

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. USWDS limits itself to 7 measure tokens:

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

Anything built using USWDS will use one of these 7 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 directly in our Sass, like max-width: 1, rather we use a helper function like max-width: measure(1) or a mixin like @include u-measure(1). All USWDS 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, themselves, be expressed as variables. And this is how most USWDS theme settings work. For instance, the following is an example of theme settings from _uswds-theme-spacing.scss showing settings variables assigned spacing unit tokens:

$theme-site-max-width:              'desktop';
$theme-site-margins-breakpoint:     'desktop';
$theme-site-margins-width:          4;
$theme-site-margins-mobile-width:   2;

USWDS component Sass uses those variableized tokens to build component styles:

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

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

This is the functional equivalent of:

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

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

Which, if $theme-respect-user-font-size is set to true would output something like:

.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, USWDS sets variables with tokens, and passes those variables into functions and mixins in the source Sass.

Using design tokens

Use design tokens directly to set the value of settings variables in USWDS theme settings files, like $theme-site-max-width: 'desktop'. Otherwise, use functions, mixins, or utility classes as in the examples below. See individual design token section for more details.

Color

Token Function Mixin Utility class
color color(color) u-border(color) .border-color
'red-warm-50' color('red-warm-50') u-border('red-warm-50') .border-red-warm-50
'red-warm-50v' color('red-warm-50v') u-border('red-warm-50v') .border-red-warm-50v
'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', 'micro' u-font('ui', 'micro') .font-ui-micro
'body', 15 u-font('body', 15) .font-body-15