How to Use USWDS Tokens

4 Ways to Use Tokens

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

These options enable us to maintain consistency by referring to a single-source-of-truth for reusing values.

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: I believe we need to add @use "uswds-core" as *; at the top of our scss files to use USWDS Mixins and Functions.

Examples in Context

Utility Class

Quick styling of HTML without adding new CSS.

<div class="border-top-2px bg-white text-base-darkest margin-bottom-3">
  Example
</div>

Theme Variable

Modify the USWDS defaults.

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

Design Tokens

Utility Mixin

Add several USWDS styles within a class, so HTML does not need so many utility classes.

.example {
  @include u-border-top(2px, 'red');
  @include u-bg('white');
  @include u-text('base-darkest');
  @include u-margin-bottom(3);
}

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

Token Function

Use tokens within styles that USWDS does not have Mixins for.

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