How to use USWDS
Settings
USWDS settings variables tell the design system how to build.
A good way to get started with USWDS settings is to copy the dist/theme
directory out of the uswds
package and into the same directory where you keep your project Sass files. Then use the @forward
directive in Sass to include these settings before including the main USWDS Sass. You can use the styles.scss
example file in the dist/theme
directory as a starting point for your own Sass entry point:
@forward 'uswds-theme';
@forward 'uswds';
@forward 'uswds-theme-custom-styles';
Add only the settings you wish to modify before importing uswds
, either in a separate file (_uswds-theme.scss
), or directly in your Sass entry point. Either way you do it, you’ll use the format @use "uswds-core" with ()
including a list of your changed settings variables inside the parentheses.
If you use the _uswds-theme.scss
file, it would look something like this:
/* _uswds-theme.scss */
@use "uswds-core" with (
$theme-show-compile-warnings: false,
$theme-show-notifications: false,
);
/* styles.scss */
@forward 'uswds-theme';
@forward 'uswds';
@forward 'uswds-theme-custom-styles';
If you include settings right in your Sass entry point, it would look something like this:
/* styles.scss */
@use "uswds-core" with (
$theme-show-compile-warnings: false,
$theme-show-notifications: false,
);
@forward 'uswds';
@forward 'uswds-theme-custom-styles';
In general, when including settings and custom code, you just need to follow this order of operations:
- Include settings: Tell the design system how to build.
- Include
uswds
: Build the design system. - Include custom styles: Build on top of the design system.
General settings
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Image path |
$theme-image-path
|
"../img" | path |
Use a path relative to the location of the final compiled CSS. |
Show compile warnings |
$theme-show-compile-warnings
|
true | boolean |
Show Sass warnings when functions and mixins use non-standard tokens. |
Show notifications |
$theme-show-notifications
|
true | boolean |
Show updates and notifications about the design system. |
Namespace |
$theme-namespace
|
map |
Set a namespace for grid and utility classes. |
|
Namespace | grid.namespace | "grid-" | ||
Namespace | grid.output | true | ||
Namespace | utility.namespace | "u-" | ||
Namespace | utility.output | true | ||
Important layout grid |
$theme-layout-grid-use-important
|
false | boolean |
Output grid classes output with “!important.” |
Border box sizing |
$theme-global-border-box-sizing
|
true | boolean |
When set to true, sets the box-sizing property of all site elements to |
Focus color |
$theme-focus-color
|
"blue-40v" | color |
The default color of the focus outline. |
Focus offset |
$theme-focus-offset
|
0 | units |
The offset between the element and the focus outline. |
Focus style |
$theme-focus-style
|
solid | outline-style |
The style of the focus outline. |
Focus width |
$theme-focus-width
|
0.5 | units |
The width of the focus outline. |
Icon size |
$theme-icon-image-size
|
2 | units |
The size of a standard UI icon (like a close box). |
Color settings
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Test color tokens |
$test-system-color-tokens
|
false | boolean |
Test system color tokens against luminosity bounds. This is intended to be an internal setting, and may result in false positives. |
Base color family |
$theme-color-base-family
|
"gray-cool" | color |
Color family of site text. |
base-lightest theme color token |
$theme-color-base-lightest
|
"gray-5" | color |
Use grades from 0-10. |
base-lighter theme color token |
$theme-color-base-lighter
|
"gray-cool-10" | color |
Use grades from 10-20. |
base-light theme color token |
$theme-color-base-light
|
"gray-cool-30" | color |
Use grades from 30-40. |
base theme color token |
$theme-color-base
|
"gray-cool-50" | color |
Use grades from 40-50. |
base-dark theme color token |
$theme-color-base-dark
|
"gray-cool-60" | color |
Use grades from 50-70. |
base-darker theme color token |
$theme-color-base-darker
|
"gray-cool-70" | color |
Use grades from 60-90. |
base-darkest theme color token |
$theme-color-base-darkest
|
"gray-90" | color |
Use grades from 70-90. |
ink theme color token |
$theme-color-base-ink
|
"gray-90" | color |
Recommend a clone of |
Primary color family |
$theme-color-primary-family
|
"blue" | color |
Color family of ~60% of the non-base color. |
primary-lightest theme color token |
$theme-color-primary-lightest
|
false | color |
Use grades 0-10. |
primary-lighter theme color token |
$theme-color-primary-lighter
|
"blue-10" | color |
Use grades 10-20. |
primary-light theme color token |
$theme-color-primary-light
|
"blue-30" | color |
Use grades 30-40. |
primary theme color token |
$theme-color-primary
|
"blue-60v" | color |
Use grades 40-60. |
primary-vivid theme color token |
$theme-color-primary
|
"blue-warm-60v" | color |
Use vivid grades 30-60. |
primary-dark theme color token |
$theme-color-primary-dark
|
"blue-warm-70v" | color |
Use grades 50-70. |
primary-darker theme color token |
$theme-color-primary-darker
|
"blue-warm-80v" | color |
Use grades 60-90. |
primary-darkest theme color token |
$theme-color-primary-darkest
|
false | color |
Use grades 70-90. |
Secondary color family |
$theme-color-secondary-family
|
"red" | color |
Color family of ~30% of the non-base color. |
secondary-lightest theme color token |
$theme-color-secondary-lightest
|
false | color |
Use grades 0-10. |
secondary-lighter theme color token |
$theme-color-secondary-lighter
|
"red-cool-10" | color |
Use grades 10-20. |
secondary-light theme color token |
$theme-color-secondary-light
|
"red-30" | color |
Use grades 30-40. |
secondary theme color token |
$theme-color-secondary
|
"red-50" | color |
Use grades 40-60. |
secondary-vivid theme color token |
$theme-color-secondary
|
"red-cool-50v" | color |
Use vivid grades 30-60. |
secondary-dark theme color token |
$theme-color-secondary-dark
|
"red-60v" | color |
Use grades 50-70. |
secondary-darker theme color token |
$theme-color-secondary-darker
|
"red-70v" | color |
Use grades 60-90. |
secondary-darkest theme color token |
$theme-color-secondary-darkest
|
false | color |
Use grades 70-90. |
Accent warm color family |
$theme-color-accent-warm-family
|
"orange" | color |
Color family of occasional warm accents. |
accent-warm-lightest theme color token |
$theme-color-accent-warm-lightest
|
false | color |
Use grades 0-10. |
accent-warm-lighter theme color token |
$theme-color-accent-warm-lighter
|
"orange-10" | color |
Use grades 10-20. |
accent-warm-light theme color token |
$theme-color-accent-warm-light
|
"orange-20v" | color |
Use grades 20-40. |
accent-warm theme color token |
$theme-color-accent-warm
|
"orange-30v" | color |
Use grades 30-60. |
accent-warm-dark theme color token |
$theme-color-accent-warm-dark
|
"orange-50v" | color |
Use grades 50-70. |
accent-warm-darker theme color token |
$theme-color-accent-warm-darker
|
"orange-60v" | color |
Use grades 60-90. |
accent-warm-lightest theme color token |
$theme-color-accent-warm-darkest
|
false | color |
Use grades 70-90. |
Accent cool color family |
$theme-color-accent-cool-family
|
"blue-cool" | color |
Color family of occasional cool accents. |
accent-cool-lightest theme color token |
$theme-color-accent-cool-lightest
|
false | color |
Use grades 0-20. |
accent-cool-lighter theme color token |
$theme-color-accent-cool-lighter
|
"blue-cool-5v" | color |
Use grades 10-30. |
accent-cool-light theme color token |
$theme-color-accent-cool-light
|
"blue-cool-20v" | color |
Use grades 30-40. |
accent-cool theme color token |
$theme-color-accent-cool
|
"cyan-30v" | color | |
accent-cool-dark theme color token |
$theme-color-accent-cool-dark
|
"blue-cool-40v" | color |
Use grades 50-60. |
accent-cool-darker theme color token |
$theme-color-accent-cool-darker
|
"blue-cool-60v" | color |
Use grades 60-80. |
accent-cool-darkest theme color token |
$theme-color-accent-cool-darkest
|
false | color |
Use grades 70-100. |
Error color family |
$theme-color-error-family
|
"red-warm" | color |
Color family of error messaging. |
error-lighter state color token |
$theme-color-error-lighter
|
"red-warm-10" | color |
Use grades 10-30. |
error-light state color token |
$theme-color-error-light
|
"red-warm-30v" | color |
Use grades 30-40. |
error state color token |
$theme-color-error
|
"red-warm-50v" | color |
Use grades 50-60. |
error-dark state color token |
$theme-color-error-dark
|
"red-60v" | color |
Use grades 60-70. |
error-darker state color token |
$theme-color-error-darker
|
"red-70" | color |
Use grades 70-80. |
Warning color family |
$theme-color-warning-family
|
"gold" | color |
Color family of warning messaging. |
warning-lighter state color token |
$theme-color-warning-lighter
|
"yellow-5" | color |
Use grades 0-30. |
warning-light state color token |
$theme-color-warning-light
|
"yellow-10v" | color |
Use grades 10-40. |
warning state color token |
$theme-color-warning
|
"gold-20v" | color |
Use grades 50-60. |
warning-dark state color token |
$theme-color-warning-dark
|
"gold-30v" | color |
Use grades 60-70. |
warning-darker state color token |
$theme-color-warning-darker
|
"gold-50v" | color |
Use grades 70-80. |
Success color family |
$theme-color-success-family
|
"green-cool" | color |
Color family of success messaging. |
success-lighter state color token |
$theme-color-success-lighter
|
"green-cool-5" | color |
Use grades 0-30. |
success-light state color token |
$theme-color-success-light
|
"green-cool-20v" | color |
Use grades 10-40. |
success state color token |
$theme-color-success
|
"green-cool-40v" | color |
Use grades 50-60. |
success-dark state color token |
$theme-color-success-dark
|
"green-cool-50" | color |
Use grades 60-70. |
success-darker state color token |
$theme-color-success-darker
|
"green-cool-60" | color |
Use grades 70-80. |
Info color family |
$theme-color-info-family
|
"cyan" | color |
Color family of info messaging. |
info-lighter state color token |
$theme-color-info-lighter
|
"cyan-5" | color |
Use grades 0-30. |
info-light state color token |
$theme-color-info-light
|
"cyan-20" | color |
Use grades 10-40. |
info state color token |
$theme-color-info
|
"cyan-30v" | color |
Use grades 50-60. |
info-dark state color token |
$theme-color-info-dark
|
"cyan-40v" | color |
Use grades 60-70. |
info-darker state color token |
$theme-color-info-darker
|
"blue-cool-60" | color |
Use grades 70-80. |
Emergency colors |
Colors of emergency actions. |
|||
emergency state color token |
$theme-color-emergency
|
"red-warm-60v" | color | |
emergency-dark state color token |
$theme-color-emergency-dark
|
"red-warm-80" | color | |
Disabled color family |
$theme-color-disabled-family
|
"gray" | color |
Color family of disabled actions. |
info-light state color token |
$theme-color-disabled-light
|
"gray-10" | color |
Use grade 10. |
info state color token |
$theme-color-disabled
|
"gray-20" | color |
Use grade 20. |
info-dark state color token |
$theme-color-disabled-dark
|
"gray-30" | color |
Use grade 30. |
Body background color |
$theme-body-background-color
|
"white" | color |
Background color of the site body. |
Body text color |
$theme-text-color
|
"ink" | color |
Color of body text |
Body text reverse color |
$theme-text-reverse-color
|
"white" | color |
Color of body text on dark backgrounds. |
Link color |
$theme-link-color
|
"primary" | color |
Color for text links. |
Visited link color |
$theme-link-visited-color
|
"violet-70v" | color |
Color for |
Hover link color |
$theme-link-hover-color
|
"primary-dark" | color |
Color for |
Active link color |
$theme-link-active-color
|
"primary-darker" | color |
Color for |
Link reverse color |
$theme-link-reverse-color
|
"base-lighter" | color |
Color for reverse text links. |
Link reverse hover color |
$theme-link-reverse-hover-color
|
"base-lightest" | color |
Color for reverse |
Link reverse hover color |
$theme-link-reverse-active-color
|
"white" | color |
Color for reverse |
Component settings
Accordion
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Border width |
$theme-accordion-border-width
|
0.5 | units |
Border width of the bordered accordion. |
Border color |
$theme-accordion-border-color
|
"base-lightest" | color |
Border color of the bordered accordion. |
Font family |
$theme-accordion-font-family
|
"body" | family |
Font family of the accordion. |
Alert
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Bar width |
$theme-alert-bar-width
|
1 | units |
Width of the colored bar to the left of the alert. |
Font family |
$theme-alert-font-family
|
"ui" | family |
Font family of the alert. |
Icon size |
$theme-alert-icon-size
|
4 | units |
Size of the alert icon. |
Horizontal padding |
$theme-alert-padding-x
|
2.5 | units |
Padding on the left and right of the alert. |
Text color |
$theme-alert-text-color
|
default | color |
Text color on light backgrounds. |
Reverse text color |
$theme-alert-text-reverse-color
|
default | color |
Text color on dark backgrounds. |
Link color |
$theme-alert-text-color
|
default | color |
Link color on light backgrounds. |
Reverse link color |
$theme-alert-link-reverse-color
|
default | color |
Link color on dark backgrounds. |
Banner
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Background color |
$theme-banner-background-color
|
"base-lightest" | family |
Background color of the banner and its content. |
Font family |
$theme-banner-font-family
|
"ui" | family |
The font family of the banner. |
Link color |
$theme-banner-link-color
|
default | color |
The color of banner link. Add the link color and the system will generate the hover state. |
Maximum width |
$theme-banner-max-width
|
"desktop" | units |
Maximum width of the banner content. |
Breadcrumb
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Background color |
$theme-breadcrumb-background-color
|
default | color |
The background color of the complete breadcrumb bar. |
Font family |
$theme-breadcrumb-font-family
|
"sm" | family |
The family of the breadcrumb text. |
Font size |
$theme-breadcrumb-font-size
|
"sm" | units |
The size of the breadcrumb text. |
Breadcrumb gap |
$theme-breadcrumb-gap
|
1.5 | units |
The space between indicator icons and text. |
Link color |
$theme-breadcrumb-link-color
|
default | color |
The color of breadcrumb link. Add the link color and the system will generate the hover state. |
Full breadcrumb minimum width |
$theme-breadcrumb-min-width
|
mobile-lg | units |
The width at which the breadcrumb displays the full breadcrumb list. |
Bottom padding |
$theme-breadcrumb-padding-bottom
|
2 | units |
Padding under the breadcrumb. |
Top padding |
$theme-breadcrumb-padding-top
|
2 | units |
Padding above the breadcrumb. |
Horizontal padding |
$theme-breadcrumb-padding-x
|
0 | units |
Padding to the right and left of the breadcrumb. |
Separator color |
$theme-breadcrumb-separator-color
|
base | color |
Color of the breadcrumb separator. This value needs AA contrast against the background. |
Button
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Font family |
$theme-button-font-family
|
"ui" | family |
Font family of the button. |
Border radius |
$theme-button-border-radius
|
"md" | units |
Button border radius for rounded corners. |
Small width |
$theme-button-small-width
|
6 | units |
Size of the header search button. |
Stroke width |
$theme-button-stroke-width
|
2px | units |
Stroke width of |
Card
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Border color |
$theme-card-border-color
|
"base-lighter" | color |
Stroke color of card. |
Border radius |
$theme-card-border-radius
|
"lg" | units |
Border radius of card. |
Border width |
$theme-card-border-width
|
2px | units |
Stroke thickness of card. |
Gap |
$theme-card-gap
|
2 | units |
Gap between cards in a card group. |
Flag minimum width |
$theme-card-flag-min-width
|
"tablet" | units |
Width at which flag cards change to horizontal layout. |
Flag image width |
$theme-card-flag-image-width
|
"card-lg" | units |
Fixed image width in the card flag variant. |
Font family |
$theme-card-font-family
|
"body" | family |
Font family for card body. |
Header typeset |
$theme-card-header-typeset
|
'heading', 'lg', 2 | family |
Family, size, and line height of the heading. |
Margin bottom |
$theme-card-margin-bottom
|
4 | units |
Bottom margin for card. |
Perimeter padding |
$theme-card-padding-perimeter
|
3 | units |
Padding between card elements and card border. |
Vertical padding |
$theme-card-padding-y
|
2 | units |
Vertical padding between card elements. |
Checkbox
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Border radius |
$theme-checkbox-border-radius
|
"sm" | units |
Checkbox border radius for rounded corners. |
Selected background color |
$theme-input-tile-background-color-selected
|
"accent-cool-lighter" | color |
Tile background color when selected. |
Tile border radius |
$theme-input-tile-border-radius
|
"md" | units |
Tile border radius for rounded corners. |
Tile border width |
$theme-input-tile-border-width
|
"2px" | units |
Tile border thickness |
Tile border color |
$theme-input-tile-border-color
|
"base-lighter" | color |
Tile border color. |
Tile border color selected |
$theme-input-tile-border-color-selected
|
"accent-cool-light" | color |
Tile border color when selected. |
Collection
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Font family |
$theme-collection-font-family
|
"ui" | family |
Font family for collection body. |
Header typeset |
$theme-collection-header-typeset
|
"ui", "md", 3 | family |
Family, size, and line height of the heading. |
Footer
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Font family |
$theme-footer-font-family
|
"body" | family |
Font family of the footer. |
Form
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Font family |
$theme-form-font-family
|
"ui" | family |
Font family of the form. |
Header
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Font family |
$theme-header-font-family
|
"ui" | family |
Font family of the header. |
Logo text width |
$theme-header-logo-text-width
|
33% | percentage |
Width of the logo text area at desktop width as a percentage of the total header width. |
Max width |
$theme-header-max-width
|
"desktop" | units |
Maximum width of the header. |
Min width |
$theme-header-min-width
|
"desktop" | units |
Breakpoint at which the non-mobile header is shown. |
Hero
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Hero image |
$theme-hero-image
|
"#{$theme-image-path}/hero.png" | path |
Background image for the hero. Use a path relative to the final project CSS. |
Icon list
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Icon list font family |
$theme-icon-list-font-family
|
"body" | family |
Font family of the content text. |
Icon list title font family |
$theme-icon-list-title-font-family
|
"heading" | family |
Font family of the content title. |
Identifier
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Background color |
$theme-identifier-background-color
|
"base-darkest" | color |
The background color of the identifier. Use a color of grade 80 or higher, darker than the section that precedes it. |
Font family |
$theme-identifier-font-family
|
"ui" | family |
The font family of the identifier. |
Domain text color |
$theme-identifier-identity-domain-color
|
"base-light" | color |
The color of your domain text in the identifier masthead. This should be grade 20-30 in the same family as the |
Maximum width |
$theme-identifier-max-width
|
"desktop" | units |
The maximum width of the content within the identifier. Use the same max-width as your site footer. |
Primary link color |
$theme-identifier-primary-link-color
|
default | color |
The color of the links in the masthead section. |
Secondary link color |
$theme-identifier-secondary-link-color
|
"base-light" | color |
The color of the links in the required links section. This should be grade 20-30 in a |
Input
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Line height |
$theme-input-line-height
|
3 | line-height |
Line-height of input element. |
Max width |
$theme-input-max-width
|
"mobile-lg" | units |
Max width of the input element. |
Border width when selected |
$theme-input-select-border-width
|
2px | units |
Border width when selected. |
Size of selection element |
$theme-input-select-size
|
2.5 | units |
Height and width checkboxes and radio buttons. |
State border width |
$theme-input-state-border-width
|
0.5 | units |
Border width of special state inputs (like error state). |
Modal
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Border Radius |
$theme-modal-border-radius
|
'lg' | units |
The border radius of the modal window. |
Max width |
$theme-modal-default-max-width
|
'mobile-lg' | units |
Maximum width of default modal window. |
Max width |
$theme-modal-lg-max-width
|
'tablet-lg' | units |
Maximum width of large modal window. |
Max width |
$theme-modal-lg-content-max-width
|
'tablet' | units |
Maximum width of content area within large modal window. |
Navigation
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Font family |
$theme-navigation-font-family
|
"ui" | family |
Font family of the navigation. |
Megamenu columns |
$theme-megamenu-columns
|
3 | number |
Number of columns in the megamenu. |
Pagination
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Pagination background color |
$theme-pagination-background-color
|
"white" | color |
The background color of the entire pagination component, used for accessible color setting. |
Breakpoint |
$theme-pagination-breakpoint
|
"tablet" | units |
Breakpoint at which full pagination displays. |
Button border radius |
$theme-pagination-button-border-radius
|
"md" | units |
Default pagination button border radius. |
Button border width |
$theme-pagination-button-border-width
|
1px | units |
Width of button border. |
Font family |
$theme-pagination-font-family
|
"ui" | family |
Default font family for pagination. |
Process list
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Counter background color |
$theme-process-list-counter-background-color
|
"white" | color |
Background color of the counter circle. |
Counter border color |
$theme-process-list-counter-border-color
|
"ink" | color |
Color of the border around the counter circle. |
Counter border width |
$theme-process-list-counter-border-width
|
0.5 | size |
Size of the border around the counter circle. |
Counter font family |
$theme-process-list-counter-font-family
|
"ui" | family |
Font family of the counter text. |
Counter font size |
$theme-process-list-counter-font-size
|
"lg" | size |
Font size of the counter text. |
Counter gap color |
$theme-process-list-counter-gap-color
|
"white" | units |
Color of gap between counter and connector. This should the the same as the background color behind the component. |
Counter gap width |
$theme-process-list-counter-gap-width
|
0.5 | units |
Size of gap between counter and connector. |
Counter circle size |
$theme-process-list-counter-size
|
5 | size |
Size of the counter circle. |
Counter text color |
$theme-process-list-counter-text-color
|
"ink" | color |
Color of the number text inside the counter circle. |
Connector color |
$theme-process-list-connector-color
|
"primary-lighter" | color |
Color of the connector line between counter circles. |
Connector width |
$theme-process-list-connector-width
|
1 | size |
Width of the connector line between counter circles. |
Font family of content |
$theme-process-list-font-family
|
"ui" | family |
Font family of the content text. |
Content font size |
$theme-process-list-font-size
|
"sm" | size |
Font size of the content text. |
Heading text color |
$theme-process-list-heading-color
|
"ink" | color |
Color of the heading text. |
Font family of heading |
$theme-process-list-heading-font-family
|
"ui" | family |
Font family of the heading text. |
Heading font size |
$theme-process-list-heading-font-size
|
"lg" | size |
Font size of the heading text. |
Radio buttons
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Selected background color |
$theme-input-tile-background-color-selected
|
"accent-cool-lighter" | color |
Tile background color when selected. |
Tile border radius |
$theme-input-tile-border-radius
|
"md" | units |
Tile border radius for rounded corners. |
Tile border width |
$theme-input-tile-border-width
|
"2px" | units |
Tile border thickness. |
Tile border color |
$theme-input-tile-border-color
|
"base-lighter" | color |
Tile border color. |
Tile border color selected |
$theme-input-tile-border-color-selected
|
"accent-cool-light" | color |
Tile border color when selected. |
Search
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Font family |
$theme-search-font-family
|
"ui" | family |
Font family of the search. |
Min-width |
$theme-search-min-width
|
27ch | — |
Min-width of the search input. |
Sidenav
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Current border width |
$theme-sidenav-current-border-width
|
0.5 | units |
Width of the current section indicator. |
Font family |
$theme-sidenav-font-family
|
"ui" | family |
Font family of the side navigation. |
Site Alert
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Maximum width |
$theme-site-alert-max-width
|
"desktop" | units |
Maximum width of the site alert content. |
Step indicator
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Background color |
$step-indicator-background-color
|
"white" | color |
Background color of the component and the gaps around the counters. |
Counter gap |
$theme-step-indicator-counter-gap
|
0.5 | size |
Gap between the counter and the segment. |
Counter border width |
$theme-step-indicator-counter-border-width
|
0.5 | size |
Size of the border around the pending steps. |
Font family |
$theme-step-indicator-font-family
|
"ui" | family |
Font family of the labels and counter numbers. |
Heading font family |
$theme-step-indicator-heading-font-family
|
"ui" | family |
Font family of the heading. |
Heading color |
$theme-step-indicator-heading-color
|
"ink" | color |
Color of the heading. |
Heading font size |
$theme-step-indicator-heading-font-size
|
"lg" | size |
Font size of the heading on screens of $theme-step-indicator-min-width and larger. |
Mobile heading font size |
$theme-step-indicator-heading-font-size-small
|
"md" | size |
Font size of the heading on screens smaller than $theme-step-indicator-min-width. |
Label font size |
$theme-step-indicator-label-font-size
|
"sm" | size |
Font size of segment labels. |
Minimum width |
$theme-step-indicator-min-width
|
"tablet" | size |
Width at which the component displays large-width features. |
Pending segment color |
$theme-step-indicator-segment-color-pending
|
"base-lighter" | color |
Color of pending step segments. Use a grade of 20 more than $step-indicator-background-color. |
Complete segment color |
$theme-step-indicator-segment-color-complete
|
"primary-darker" | color |
Color of complete step segments. Use a grade at least 60. |
Current segment color |
$theme-step-indicator-segment-color-current
|
"primary" | color |
Color of the current step segments. Use a grade at least 20 more than $theme-step-indicator-segment-color-complete. |
Segment gap |
$theme-step-indicator-segment-gap
|
2px | units |
Gap between step segments. |
Segment height |
$theme-step-indicator-segment-height
|
1 | units |
Height of the step segment. Note that the mobile segment height is always 1 unit. |
Pending text color |
$theme-step-indicator-text-pending-color
|
"base-dark" | color |
The text color of pending steps. Use a gray grade of 60 more than the $step-indicator-background-color. |
Summary box
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Background color |
$theme-summary-box-background-color
|
"info-lighter" | color |
Background color of the Summary box. |
Border color |
$theme-summary-box-border-color
|
"info-light" | color |
Color the border around the Summary box. |
Border width |
$theme-summary-box-border-width
|
1px | size |
Width of the border around the Summary box. |
Border radius |
$theme-summary-box-border-radius
|
"md" | radius |
Border radius of the summary box. |
Font family |
$theme-summary-box-font-family
|
"ui" | family |
Font family of the content text. |
Link color |
$theme-summary-box-link-color
|
default | color |
Color of the links inside the content text. When set to “default”, links will get one of three values, based on contrast: $theme-link-color, $theme-link-reverse-color, or “ink”. |
Text color |
$theme-summary-box-link-color
|
default | color |
Color of the links inside the content text. When set to “default”, text will get one of two values, based on contrast: “white” or “ink”. |
Tables
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Border color |
$theme-table-border-color
|
default | color |
Defines a border color for table cells. A value of |
Text color |
$theme-table-text-color
|
default | color |
Defines a text color for table cells. A value of |
Header Background Color |
$theme-table-header-background-color
|
"base-lighter" | color |
Defines a background color for header cells. |
Header Text Color |
$theme-table-header-text-color
|
default | color |
Defines a text color for header cells. A value of |
Stripe Background Color |
$theme-table-stripe-background-color
|
"base-lightest" | color |
Defines a background color for alternating horizontal stripes in the striped table variant. |
Stripe Text Color |
$theme-table-stripe-text-color
|
default | color |
Defines a text color for alternating horizontal stripes in the striped table variant. A value of |
Sorted Column Header Background Color |
$theme-table-sorted-header-background-color
|
"accent-cool-light" | color |
Defines a background color for the sorted column header. |
Sorted Column Background Color |
$theme-table-sorted-background-color
|
"accent-cool-lighter" | color |
Defines a background color for the cells of the sorted column. |
Sorted Column Stripe Background Color |
$theme-table-sorted-stripe-background-color
|
"blue-cool-10v" | color |
Defines a background color for the alternating horizontal stripes applied to cells of the sorted column |
Sorted Column Icon Color |
$theme-table-sorted-icon-color
|
default | color |
Defines a fill color for the activated sort button in a sortable column header. A value of |
Unsorted Column Icon Color |
$theme-table-unsorted-icon-color
|
"base" | color |
Defines a fill color for the unactivated sort button in a sortable column header. |
Spacing settings
Name | Variable | Default | Type | Description |
---|---|---|---|---|
sm border-radius token |
$theme-border-radius-sm
|
2px | units |
Sets |
md border-radius token |
$theme-border-radius-md
|
0.5 | units |
Sets |
lg border-radius token |
$theme-border-radius-lg
|
1 | units |
Sets |
Small grid gap |
$theme-column-gap-sm
|
2px | units |
Sets |
Medium grid gap |
$theme-column-gap-md
|
2 | units |
Sets |
Large grid gap |
$theme-column-gap-md
|
3 | units |
Sets |
Mobile grid gap |
$theme-column-gap-mobile
|
2 | units |
Sets value of |
Desktop grid gap |
$theme-column-gap-desktop
|
4 | units |
Sets value of |
Grid container max width |
$theme-grid-container-max-width
|
"desktop" | units |
Sets the |
Site outer margins breakpoint |
$theme-site-margins-breakpoint
|
"desktop" | units |
The breakpoint at which the site’s outer margin changes. |
Site outer margins |
$theme-site-margins-width
|
4 | units |
Site outer margin at non-mobile width (breakpoint defined by |
Site mobile outer margins |
$theme-site-margins-mobile-width
|
2 | units |
Site outer margin at mobile width. |
Typography settings
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Respect user font size |
$theme-respect-user-font-size
|
true | boolean |
When |
Root font size |
$theme-root-font-size
|
10px | px |
Only applies when |
Global paragraph styles |
$theme-global-paragraph-styles
|
false | boolean |
Add basic styling to |
Global link styles |
$theme-global-link-styles
|
false | boolean |
Add basic styling to |
Global content styles |
$theme-global-content-styles
|
false | boolean |
Add basic styling to paragraph text, links, headings, lists, and tables. |
Font path |
$theme-font-path
|
"../fonts" | path |
Path to the font files, relative to the compiled CSS. |
Custom typeface tokens |
$theme-typeface-tokens
|
map |
Add custom typeface tokens. |
|
Custom typeface tokens | token | example-sans-token | ||
Custom typeface tokens | token.display-name | "Example Sans Display Name" | ||
Custom typeface tokens | token.cap-height | 364px | ||
cond font-family token |
$theme-font-type-cond
|
false | family |
Project condensed font. |
icon font-type token |
$theme-font-type-icon
|
false | family |
Project icon font. |
lang font-family token |
$theme-font-type-lang
|
false | family |
Project language-specific font. |
mono font family token |
$theme-font-type-mono
|
"roboto-mono" | family |
Project monospaced font. |
sans font-family token |
$theme-font-type-sans
|
"source-sans-pro" | family |
Project sans-serif font. |
serif font-family token |
$theme-font-type-serif
|
"merriweather" | family |
Project serif font. |
ui font-family token |
$theme-font-role-ui
|
"sans" | family |
Assign font family used for interfaces and buttons from type-based |
heading font-family token |
$theme-font-role-heading
|
"serif" | family |
Assign font family used for headings from type-based |
body font-family token |
$theme-font-role-body
|
"sans" | family |
Assign font family used for body text from type-based |
code font-family token |
$theme-font-role-code
|
"mono" | family |
Assign font family used for code from type-based |
alt font-family token |
$theme-font-role-alt
|
"serif" | family |
Assign font family used for alternative type sections from type-based |
3xs font-size token |
$theme-type-scale-3xs
|
2 | size |
Use system |
2xs font-size token |
$theme-type-scale-2xs
|
3 | size |
Use system |
xs font-size token |
$theme-type-scale-xs
|
4 | size |
Use system |
sm font-size token |
$theme-type-scale-sm
|
5 | size |
Use system |
md font-size token |
$theme-type-scale-md
|
6 | size |
Use system |
lg font-size token |
$theme-type-scale-lg
|
9 | size |
Use system |
xl font-size token |
$theme-type-scale-xl
|
12 | size |
Use system |
2xl font-size token |
$theme-type-scale-2xl
|
14 | size |
Use system |
3xl font-size token |
$theme-type-scale-3xl
|
15 | size |
Use system |
thin font-weight token |
$theme-font-weight-thin
|
false | weight |
Use system |
light font-weight token |
$theme-font-weight-light
|
300 | weight |
Use system |
normal font-weight token |
$theme-font-weight-normal
|
400 | weight |
Use system |
medium font-weight token |
$theme-font-weight-medium
|
false | weight |
Use system |
semibold font-weight token |
$theme-font-weight-semibold
|
false | weight |
Use system |
bold font-weight token |
$theme-font-weight-bold
|
700 | weight |
Use system |
heavy font-weight token |
$theme-font-weight-heavy
|
false | weight |
Use system |
Generate all font weights font-weight token |
$theme-generate-all-weights
|
false | boolean |
If USWDS is generating |
Condensed custom font stack |
$theme-font-cond-custom-stack
|
false | font stack |
Custom font stack for condensed font. |
Icon font stack |
$theme-font-icon-custom-stack
|
false | font stack |
Custom font stack for icon font. |
Language-specific font stack |
$theme-font-lang-custom-stack
|
false | font stack |
Custom font stack for language-specific font. |
Monospaced font stack |
$theme-font-mono-custom-stack
|
false | font stack |
Custom font stack for monospaced font. |
Sans-serif font stack |
$theme-font-sans-custom-stack
|
false | font stack |
Custom font stack for sans-serif font. |
Serif font stack |
$theme-font-serif-custom-stack
|
false | font stack |
Custom font stack for serif font. |
Custom font source files |
$theme-font-[family]-custom-src
|
map |
If you want USWDS to generate additional |
|
Custom font source files | dir | "custom/example-serif" | ||
Custom font source files | roman.100 | false | ||
Custom font source files | roman.200 | false | ||
Custom font source files | roman.300 | "ExampleSerif-Light" | ||
Custom font source files | roman.400 | "ExampleSerif-Normal" | ||
Custom font source files | roman.500 | false | ||
Custom font source files | roman.600 | false | ||
Custom font source files | roman.700 | "ExampleSerif-Bold" | ||
Custom font source files | roman.800 | false | ||
Custom font source files | roman.900 | false | ||
Custom font source files | italic.100 | false | ||
Custom font source files | italic.200 | false | ||
Custom font source files | italic.300 | "ExampleSerif-LightItalic" | ||
Custom font source files | italic.400 | "ExampleSerif-Italic" | ||
Custom font source files | italic.500 | false | ||
Custom font source files | italic.600 | false | ||
Custom font source files | italic.700 | "ExampleSerif-BoldItalic" | ||
Custom font source files | italic.800 | false | ||
Custom font source files | italic.900 | false | ||
Custom condensed source files |
$theme-font-cond-custom-src
|
false | map |
See guidance above. |
Custom icon source files |
$theme-font-icon-custom-src
|
false | map |
See guidance above. |
Custom language-specific source files |
$theme-font-lang-custom-src
|
false | map |
See guidance above. |
Custom monospaced source files |
$theme-font-mono-custom-src
|
false | map |
See guidance above. |
Custom sans-serif source files |
$theme-font-sans-custom-src
|
false | map |
See guidance above. |
Custom serif source files |
$theme-font-serif-custom-src
|
false | map |
See guidance above. |
Body font family |
$theme-body-font-family
|
"body" | family |
Use theme tokens when possible. |
Body font size |
$theme-body-font-size
|
"sm" | size |
Use theme tokens when possible. |
Body line height |
$theme-body-line-height
|
5 | line-height | |
Style body element |
$theme-style-body-element
|
false | boolean |
Add explicit body styles to the |
h1 font size |
$theme-h1-font-size
|
"2xl" | size | |
h2 font size |
$theme-h2-font-size
|
"xl" | size | |
h3 font size |
$theme-h3-font-size
|
"lg" | size | |
h4 font size |
$theme-h4-font-size
|
"sm" | size | |
h5 font size |
$theme-h5-font-size
|
"xs" | size | |
h6 font size |
$theme-h6-font-size
|
"3xs" | size | |
Heading line height |
$theme-heading-line-height
|
2 | line-height | |
Small font size |
$theme-small-font-size
|
"2xs" | size |
Used for the smallest text on a site. |
Display font size |
$theme-display-font-size
|
"3xl" | size |
Used for the largest text on a site. |
Narrow measure |
$theme-text-measure-narrow
|
1 | measure | |
Default measure |
$theme-text-measure
|
4 | measure | |
Wide measure |
$theme-text-measure-wide
|
6 | measure | |
Prose font family |
$theme-prose-font-family
|
"body" | family |
Font family used for body text in |
Lead (intro) font family |
$theme-lead-font-family
|
"heading" | family |
This name may change. Use role-based |
Lead (intro) font size |
$theme-lead-font-size
|
"lg" | size |
This name may change. Use role-based |
Lead (intro) line height |
$theme-lead-line-height
|
6 | line-height |
This name may change. |
Lead (intro) measure |
$theme-lead-measure
|
6 | measure |
This name may change. |
Utilities settings
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Utilities use !important |
$utilities-use-important
|
false | boolean |
Output all utilities with |
Utilities uselist |
$output-these-utilities
|
default | list |
Include a list of all utility modules to output. Ex: |
Utility breakpoints |
$theme-utility-breakpoints
|
map |
Set which mobile-first breakpoints are output for the utilities. |
|
Utility breakpoints | "card" | false | ||
Utility breakpoints | "card-lg" | false | ||
Utility breakpoints | "mobile" | false | ||
Utility breakpoints | "mobile-lg" | true | ||
Utility breakpoints | "tablet" | true | ||
Utility breakpoints | "tablet-lg" | false | ||
Utility breakpoints | "desktop" | true | ||
Utility breakpoints | "desktop-lg" | false | ||
Utility breakpoints | "widescreen" | false | ||
Global color palettes |
$global-color-palettes
|
palettes |
Any palettes added to this list will output in the the following utilities:
|
|
Utility settings |
$[utility-module]-settings
|
map |
Control the output of a [utility-module] and its responsive and state variants. |
|
Utility settings | "output" | — | ||
Utility settings | "responsive" | — | ||
Utility settings | "active" | — | ||
Utility settings | "focus" | — | ||
Utility settings | "hover" | — | ||
Utility settings | "visited" | — | ||
Utility palettes |
$[utility-module]-palettes
|
"palette-[utility-module]-default" | palettes |
Utilities output with the values set in the palettes list. |
Utility manual values |
$[utility-module]-palettes
|
"palette-[utility-module]-manual-values" | map |
Utilities output with the tokens and values set in the manual values map. |
Utility manual values | [token name] | [token value] |
Utility modules
Utility module name | Class base | Gzip size | Default full size |
---|---|---|---|
add-aspect | add-aspect- | 0.08 KB | 0.44 KB |
add-list-reset | add-list-reset | 0.02 KB | 0.12 KB |
align-items | flex- | 0.04 KB | 0.24 KB |
align-self | flex- | 0.06 KB | 0.31 KB |
background-color | bg- | 1.0 KB | 5.4 KB |
border | border- | 4.35 KB | 23.5 KB |
border-color | border- | 4.35 KB | 23.5 KB |
border-radius | border- | 1.61 KB | 8.7 KB |
border-style | border- | 0.03 KB | 0.14 KB |
border-width | border- | 0.56 KB | 3 KB |
bottom | bottom- | 0.18 KB | 0.96 KB |
box-shadow | shadow- | 0.06 KB | 0.33 KB |
circle | circle- | 0.19 KB | 1 KB |
clearfix | clearfix | 0.02 KB | 0.09 KB |
color | text- | 0.37 KB | 2 KB |
cursor | cursor- | 0.07 KB | 0.39 KB |
display | display- | 0.28 KB | 1.5 KB |
flex | flex- | 0.06 KB | 0.33 KB |
flex-direction | flex- | 0.02 KB | 0.1 KB |
flex-wrap | flex- | 0.02 KB | 0.1 KB |
float | float- | 0.02 KB | 0.1 KB |
font | font- | 2.41 KB | 13 KB |
font-family | font-family- | 0.37 KB | 2 KB |
font-feature | text- | 0.03 KB | 0.14 KB |
font-style | text- | 0.02 KB | 0.11 KB |
font-weight | text- | 0.1 KB | 0.54 KB |
height | height- | 0.11 KB | 0.6 KB |
justify-content | flex- | 0.18 KB | 0.95 KB |
left | left- | 0.08 KB | 0.44 KB |
letter-spacing | text-ls- | 0.05 KB | 0.28 KB |
line-height | line-height- | 1.61 KB | 8.7 KB |
margin | margin- | 0.8 KB | 4.35 KB |
margin-horizontal | margin- | 4.02 KB | 21.75 KB |
margin-vertical | margin- | 4.02 KB | 21.75 KB |
max-height | maxh- | 0.12 KB | 0.65 KB |
max-width | maxw- | 0.13 KB | 0.72 KB |
measure | measure- | 0.18 KB | 0.98 KB |
min-height | minh- | 0.13 KB | 0.72 KB |
min-width | minw- | 0.07 KB | 0.4 KB |
opacity | opacity- | 0.24 KB | 1.3 KB |
order | order- | 0.26 KB | 1.4 KB |
outline | outline- | 0.03 KB | 0.18 KB |
outline-color | outline- | 0.56 KB | 3 KB |
overflow | overflow- | 0.09 KB | 0.46 KB |
padding | padding- | 4.02 KB | 21.75 KB |
pin | pin- | 0.06 KB | 0.35 KB |
position | position- | 0.04 KB | 0.21 KB |
right | right- | 0.09 KB | 0.47 KB |
square | square- | 0.14 KB | 0.73 KB |
text-align | text- | 0.03 KB | 0.16 KB |
text-decoration | underline- | 0.06 KB | 0.32 KB |
text-decoration-color | text- | 2.33 KB | 12.6 KB |
text-indent | text-indent- | 0.19 KB | 1 KB |
text-transform | text- | 0.04 KB | 0.2 KB |
top | top- | 0.07 KB | 0.4 KB |
vertical-align | text- | 0.06 KB | 0.32 KB |
whitespace | text- | 0.04 KB | 0.2 KB |
width | width- | 0.56 KB | 3 KB |
z-index | z- | 0.04 KB | 0.22 KB |