Design tokens

Font size

Font size tokens determine how big or small the referenced text will appear on the screen. The USWDS typescale includes nine regularized theme tokens drawn from 21 system tokens.

Please see the Typesetting section for more about font size normalization and how USWDS uses tokens for typesetting. The documentation below displays a value in pixels, rather than the actual final output, which will be normalized depending on the typeface and output in rem customized to your project settings.

Theme tokens

The following chart shows the USWDS default settings for the nine theme size tokens. Customize the output to your project needs in $uswds-theme-typography.scss by setting the variables listed below. If your project requires more than nine sizes, use system size tokens as needed.

Token Default Example Value Settings variable
'3xs' 2 Tallahassee 13px $theme-type-scale-3xs
'2xs' 3 Tallahassee 14px $theme-type-scale-2xs
'xs' 4 Tallahassee 15px $theme-type-scale-xs
'sm' 5 Tallahassee 16px $theme-type-scale-sm
'md' 6 Tallahassee 17px $theme-type-scale-md
'lg' 9 Tallahassee 22px $theme-type-scale-lg
'xl' 12 Tallahassee 32px $theme-type-scale-xl
'2xl' 14 Tallahassee 40px $theme-type-scale-2xl
'3xl' 15 Tallahassee 48px $theme-type-scale-3xl

System tokens

Token Value Example
'micro' 10px Tallahassee
1 12px Tallahassee
2 13px Tallahassee
3 14px Tallahassee
4 15px Tallahassee
5 16px Tallahassee
6 17px Tallahassee
7 18px Tallahassee
8 20px Tallahassee
9 22px Tallahassee
10 24px Tallahassee
11 28px Tallahassee
12 32px Tallahassee
13 36px Tallahassee
14 40px Tallahassee
15 48px Tallahassee
16 56px Tallahassee
17 64px Tallahassee
18 80px Tallahassee
19 120px Tallahassee
20 140px Tallahassee

Using size tokens

Your context and coding style determine how you access USWDS font size tokens in code. Because of font size normalization, font size functions, utilities, and mixins also require a family token.

Context Usage Example
function size(family, size) font-size: size('body', '2xl')
mixin font-size u-font-size(family, size) @include u-font-size('body', '2xl')
mixin font-family font-size u-font(family, size) @include u-font('body', '2xl')
setting size $theme-h1-font-size: '2xl'
utility font-family font-size .font-family-size .font-body-2xl