Design tokens
Font
USWDS font tokens combine our font-family and font-size tokens into a single token that sets the font size and family together. Since USWDS font size is customized to specific font families, it’s often best to typeset them together using a font token.
The USWDS typescale is designed to display type at a consistent size regardless of the typeface. Theme font tokens use a nine-step scale drawn from a 21-step system scale. Theme and system font tokens are the only tokens we accept for setting set font family and size in official components.
Font size is output in rem. If you have $theme-respect-user-font-size set to true in your theme settings, the root font size is set to 100% and typescale is calculated based on 16px. If $theme-respect-user-font-size set to false, the root font size is set to the value of $theme-root-font-size and typescale is calculated based on that root.
Since both the rem and absolute px values change depending on the theme settings and the typeface, the following table displays only the px value of the target.
Font normalization
To make different typefaces appear the same size at each step of the scale, the absolute size of each step in the typescale varies from typeface to typeface. Each supported typeface is regularized to a target value set by the the size of common system fonts — specifically Apple’s typeface San Francisco and Google’s typeface Roboto. Optically smaller faces like Source Sans Pro will have a relatively larger rem value at each step in the scale, and optically larger faces like Merriweather will have a relatively smaller rem value. The USWDS typeface Public Sans is developed to be optically similar to system fonts.
Theme typescale
The nine-step theme scale should be sufficient for most project needs. First, try to use the theme scale. If your projects needs require more than nine sizes, use steps from the system scale as needed.
'3xs'font-sans-3xs'2xs'font-lang-2xs'xs'font-sans-xs'sm'font-lang-4'md'font-sans-md'lg'font-sans-lg'xl'font-sans-xl'2xl'font-sans-2xl'3xl'font-sans-3xlSystem typescale
'micro'font-sans-micro1font-sans-12font-sans-23font-sans-34font-sans-45font-sans-56font-sans-67font-sans-78font-sans-89font-sans-910font-sans-1011font-sans-1112font-sans-1213font-sans-1314font-sans-1415font-sans-1516font-sans-1617font-sans-1718font-sans-1819font-sans-1920font-sans-20Setting theme typeface families
Since typescale is tied to the specific typeface, any technique that directly outputs a specific size must use both a typescale token and a type family token. Type family tokens are set with variables in your project’s theme settings.
The following typefaces have been regularized and are available in settings to the type-based settings variables:
'system''public-sans''source-sans-pro''helvetica''georgia''merriweather''roboto-mono''tahoma'Type-based family tokens
Each project can choose a family from the available typefaces for monospaced, sans-serif, serif, and condensed families. The value of any of these families can be set to false if that family isn’t used in your project.
'mono''sans''serif''cond'$theme-font-mono: 'roboto-mono';
$theme-font-sans: 'source-sans-pro';
$theme-font-serif: 'merriweather';
$theme-font-cond: false;
Role-based family tokens
Next, set role-based tokens with the type-based theme variables.
'heading''body''code''alt'$theme-font-heading: $theme-font-serif;
$theme-font-ui: $theme-font-serif;
$theme-font-body: $theme-font-sans;
$theme-font-code: $theme-font-mono;
$theme-font-alt: $theme-font-sans;
Using typescale in utilities, settings, and component Sass
You’ll access USWDS typecale units using a few different techniques, depending on your situation and coding style.
Settings
Use the scale token when assigning a typescale unit to a settings variable.
$theme-type-scale-3xs: 1;
$theme-type-scale-2xs: 3;
$theme-type-scale-xs: 5;
$theme-type-scale-sm: 6;
$theme-type-scale-md: 7;
$theme-type-scale-lg: 10;
$theme-type-scale-xl: 12;
$theme-type-scale-2xl: 14;
$theme-type-scale-3xl: 16;
$theme-h1-font-size: '2xl';
Utilities
The font utility requires both an unquoted family token and an unquoted scale token in the form font-[family]-[size].
The font utilities set both the font size and family.
.font-sans-3xs
.font-body-md
.font-sans-micro
.font-mono-sm
Functions
Use the font-size() function to set the font size. The function requires both a family token and a scale token in the form font-size([family], [scale]).
The scale() function is only for font-size.
font-size: font-size('mono', 'sm');
font-size: font-size('body', 8);
Utility mixins
Use the u-font() mixin to set both the font size and the font family. The mixin requires both a family token and a scale token in the form @include u-font([family], [scale]).
Use the u-font-size() mixin to set the font size only. The mixin requires both a family token and a scale token in the form @include u-font-size([family], [scale]).
Use the u-font-family() mixin to set the font family only. The mixin requires a family token in the form @include u-font-family([family]).
Use u-font() instead of using both u-font-family() and u-font-size() on a single selector, but avoid using it unneccessarily to avoid duplicate code.
@include u-font('heading', 'xl')
@include u-font-family('sans')
@include u-font-size('sans', 12)
@include u-font-family('body')
@include u-font-size('body', 'sm')
