Design tokens
Spacing units
USWDS spacing unit tokens are based on multiples of 8px, with additional tokens for small sizes, named tokens for large sizes, and a more limited selection of negative tokens.
Any spacing value in utilities or component CSS should use the following spacing unit tokens, based on multiples of 8px. The documentation below displays a target value in pixels, but the final output for tokens above 2px and below -2px is the eqivalent value in rem, which will vary depending on your project settings.
Note: Some units tokens come in two flavors: a numeric token (like 0.5 or -2) and a string token (like '05' or 'neg-2'). Utility classes use unquoted string tokens exclusively when they exist (like .margin-x-neg-2). Mixins and functions usually accept either, and we will note any exceptions.
Spacing unit tokens
| Token | Multiple | Value | Example |
|---|---|---|---|
1px
|
— | 1px | |
2px
|
— | 2px | |
0.5,
'05'
|
0.5 | 4px | |
1
|
1 | 8px | |
1.5,
'105'
|
1.5 | 12px | |
2
|
2 | 16px | |
2.5,
'205'
|
2.5 | 20px | |
3
|
3 | 24px | |
4
|
4 | 32px | |
5
|
5 | 40px | |
6
|
6 | 48px | |
7
|
7 | 56px | |
8
|
8 | 64px | |
9
|
9 | 72px | |
10
|
10 | 80px | |
15
|
15 | 120px | |
'card'
|
20 | 160px | |
'card-lg'
|
30 | 240px | |
'mobile'
|
40 | 320px | |
'mobile-lg'
|
60 | 480px | |
'tablet'
|
80 | 640px | |
'tablet-lg'
|
110 | 880px | |
'desktop'
|
128 | 1024px | |
'desktop-lg'
|
150 | 1200px | |
'widescreen'
|
175 | 1400px | |
-1px,
'neg-1px'
|
— | -1px | |
-2px,
'neg-2px'
|
— | -2px | |
-0.5,
'neg-05'
|
-0.5 | -4px | |
-1,
'neg-1'
|
-1 | -8px | |
-1.5,
'neg-105'
|
-1.5 | -12px | |
-2,
'neg-2'
|
-2 | -16px | |
-2.5,
'neg-205'
|
-2.5 | -20px | |
-3,
'neg-3'
|
-3 | -24px | |
-4,
'neg-4'
|
-4 | -32px | |
-5,
'neg-5'
|
-5 | -40px | |
-6,
'neg-6'
|
-6 | -48px | |
-7,
'neg-7'
|
-7 | -56px | |
-8,
'neg-8'
|
-8 | -64px | |
-9,
'neg-9'
|
-9 | -72px | |
-10,
'neg-10'
|
-10 | -80px | |
-15,
'neg-15'
|
-15 | -120px |
Using spacing unit tokens
Your context and coding style determine how you access USWDS spacing unit tokens in code.
Many mixins and utilities accept spacing unit tokens. See the utilities section for more on individual utilities and their matching mixins. We show only a few representative examples below.
| Context | Usage | Example |
|---|---|---|
| function | units(units) |
padding-top: units(3);margin-left: units( -2px);border-radius: units( 0.5);min-height: units( 'card'); |
|
mixin min-width media query |
at-media(units) |
@include at-media('mobile-lg') |
|
mixin max-width media query |
at-media-max(units) |
@include at-media-max('mobile-lg') |
| setting | units |
$theme-site-margin-mobile: 2
|
| utility |
.padding-x-units .margin-x-units |
.padding-x-2.margin-x- neg-2 |
Latest updates
Meaningful code and guidance updates are listed in the following table:
| Date | USWDS version | Affects | Description |
|---|---|---|---|
| 2023-08-23 | 3.6.0 |
|
Updated |
| 2023-02-24 | N/A |
|
Corrected alternate token name for token |
| 2022-03-11 | N/A |
|
Reverted value of |
| 2022-02-24 | N/A |
|
Updated value of |
