Design tokens
Font family
USWDS font family tokens allow designers and developers to set font family either by the type of font or the role the font plays in the design.
Please see the Typesetting section for more about font size normalization and how USWDS uses size and family tokens for typesetting.
Available fonts
The following fonts have normalization metadata in USWDS, and are available to settings variables as tokens:
| Token | Value |
|---|---|
'georgia'
|
"Georgia", "Cambria", "Times New Roman", "Times", serif |
'helvetica'
|
"Helvetica Neue", "Helvetica", "Roboto", "Arial", sans-serif |
'merriweather'
|
"Merriweather Web", "Georgia", "Cambria", "Times New Roman", "Times", serif |
'open-sans'
|
"Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" |
'public-sans'
|
"Public Sans Web", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" |
'roboto-mono'
|
"Roboto Mono Web", "Roboto Mono Web", "Bitstream Vera Sans Mono", "Consolas", "Courier", monospace |
'source-sans-pro'
|
"Source Sans Pro", "Helvetica Neue", "Helvetica", "Roboto", "Arial", sans-serif |
'system'
|
-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" |
'tahoma'
|
"Tahoma", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" |
'verdana'
|
"Verdana", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" |
Type-based tokens
Type based tokens set the font family value based on the type of the requested font: icon, language, monospaced, sans-serif, serif, and condensed families.
| Token | Default | Settings variable |
|---|---|---|
'cond'
|
false | $theme-font-type-cond |
'icon'
|
false | $theme-font-type-icon |
'lang'
|
false | $theme-font-type-lang |
'mono'
|
'roboto-mono' | $theme-font-type-mono |
'sans'
|
'source-sans-pro' | $theme-font-type-sans |
'serif'
|
'merriweather' | $theme-font-type-serif |
Role-based tokens
Role-based tokens set the font family value based on the role the face plays in the project: heading, body, ui, code, and alternate.
| Token | Default | Settings variable |
|---|---|---|
'alt'
|
'serif' | $theme-font-role-alt |
'body'
|
'sans' | $theme-font-role-body |
'code'
|
'mono' | $theme-font-role-code |
'heading'
|
'serif' | $theme-font-role-heading |
'ui'
|
'sans' | $theme-font-role-ui |
Note: It is possible to add custom font metadata, custom font stacks, and custom font source files in your USWDS settings. This documentation is coming soon. See the inline documentation in _uswds-theme-typography for more details.
Customizing family tokens
Customize type and role family tokens in your project’s theme settings with available font tokens. All typography-related settings are in _uswds-theme-typography.scss.
First, use font tokens to set the type family tokens. Set any unused types to false.
$theme-font-type-cond: false;
$theme-font-type-icon: false;
$theme-font-type-lang: false;
$theme-font-type-mono: 'roboto-mono';
$theme-font-type-sans: 'source-sans-pro';
$theme-font-type-serif: 'merriweather';
Then use the type variables you just set to set the role family tokens. Set any unused types to false.
$theme-font-role-ui: $theme-font-sans;
$theme-font-role-heading: $theme-font-serif;
$theme-font-role-body: $theme-font-sans;
$theme-font-role-code: $theme-font-mono;
$theme-font-role-alt: $theme-font-serif;
Using family tokens
Your context and coding style determine how you access USWDS family tokens in code.
