How to Use USWDS Tokens

The US Web Design System provides a comprehensive selection of Design Tokens and 4 ways to access the values that they represent.

The 4 Ways to Use Tokens

Utility Class

Quick styling of HTML without adding new CSS.

<div class="border-top-2px border-red bg-white text-base-darkest margin-bottom-3 desktop:padding-x-4">
  Example
</div>

Theme Variable

Modify the USWDS defaults.

$theme-focus-color: 'cyan-50v';

List of available USWDS Theme Variables

These are added within _uswds-theme.scss which is processed before the design system is compiled.

Utility Mixin

Add several USWDS styles within a class, so HTML does not need so many utility classes. The HTML below gets the same styles as the Utility Class example.

.example {
  @include u-border-top(2px, 'red');
  @include u-bg('white');
  @include u-text('base-darkest');
  @include u-margin-bottom(3);
  @include at-media("desktop") {
    @include u-padding-x(4);
  }
}

<div class="example">
  Example
</div>

Token Function

Use tokens within styles that USWDS does not have Mixins for. This example creates a gradient using USWDS color() values.

.example {
  background: linear-gradient(90deg, color('cyan-30v') 0%, color('magenta-20') 100%);
}

Each category of tokens uses a different function for obtaining values. Four such functions (color, units, size, and family) are referenced here. Other functions may be found in the "using-X-tokens" section of their respective documentation pages.

Comparison Chart

Option	Utility Classes	Theme Variables	Utility Mixins	Token Functions
Where to use	HTML	_uswds-theme.scss	SCSS	SCSS
What it does	Apply styles	Change USWDS	Copy styles	Copy token values
Example	.bg-white	$theme-color-info: "red”	u-bg('white')	color('red')
Best for	Small style tweaks	Site-wide changes	Many styles with 1 class	When there’s no mixin

Note: We need to add @use "uswds-core" as *; at the top of a scss file to use USWDS Mixins and Functions in the file.

Create Custom Utility Classes

We can create utility classes that use custom values, so this:

$background-color-manual-values: (
  'coffee': #c0ffee,
)

produces a utility class like this:

<div class="bg-coffee">
  Utility Class Example
</div>

Reference: https://designsystem.digital.gov/utilities/color/#manual-values

USWDS Color Tool

If you have a hex color and want to find out which USWDS color it is (or is most similar to), paste the hex color into this tool:

https://civicactions.github.io/uswds-color-tool/

Some Tokens We Use

Mixins

• Font Weights:

  • @include u-text('semibold');
    • equivalent would be font-weight: 600;
    • options we use are { normal, medium, semibold, bold }

• Font Family

  • @include u-font-family('sans');
    • equivalent would be font-family: "Source Sans Pro Web", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif;
  • @include u-font-family('serif');
    • equivalent would be font-family: "Merriweather Web", Georgia, Cambria, "Times New Roman", Times, serif;