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/scss/theme
directory out of the uswds
package and into the same directory where you keep your project Sass files. Then use the @import
directive in Sass to import these settings before importing the main USWDS Sass. You can use the styles.scss
example file in the dist/scss/theme
directory as a starting point for your own Sass entry point:
// -------------------------------------
// Import individual theme settings
@import 'uswds-theme-general';
@import 'uswds-theme-typography';
@import 'uswds-theme-spacing';
@import 'uswds-theme-color';
@import 'uswds-theme-utilities';
// -------------------------------------
// Import individual USWDS modules...
// @import 'uswds-fonts';
// @import 'uswds-layout-grid';
// @import 'uswds-components';
// @import 'uswds-utilities';
// -------------------------------------
// ...or import all USWDS modules
@import 'uswds';
// -------------------------------------
// Import theme custom styles
@import 'uswds-theme-custom-styles';
You can also add only the settings you wish to modify before importing uswds
, either in a separate file, or directly in your Sass entry point:
$theme-show-compile-warnings: false;
$theme-show-notifications: false;
@import 'uswds';
@import 'uswds-theme-custom-styles';
In general, when importing settings and custom code, you just need to follow this order of operations:
- Import settings: Tell the design system how to build.
- Import
uswds
: Build the design system. - Import 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 | |
Focus offset | $theme-focus-offset | 0 | units |
The offset between the element and the focus outline |
Focus style | $theme-focus-style | solid | outline-style | |
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 color | $theme-accordion-border-color | "base-lightest" | color | |
Font family | $theme-accordion-font-family | "body" | family |
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 | |
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 | |
Border radius | $theme-button-border-radius | "md" | units | |
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 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 |
Form
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Font family | $theme-form-font-family | "ui" | family |
Header
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Font family | $theme-header-font-family | "ui" | family | |
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. |
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 | |
Max width | $theme-input-max-width | "mobile-lg" | units | |
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) |
Navigation
Name | Variable | Default | Type | Description |
---|---|---|---|---|
Font family | $theme-navigation-font-family | "ui" | family | |
Megamenu columns | $theme-megamenu-columns | 3 | number |
Number of columns in the megamenu |
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
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 | |
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 |
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 | "base-dark" | color |
Defines a border color for table cells. |
Text color | $theme-table-text-color | "ink" | color |
Defines a text color for table cells. |
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 | "ink" | color |
Defines a text color for header cells. |
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 | "ink" | color |
Defines a text color for alternating horizontal stripes in the striped table variant. |
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 max width | $theme-site-max-width | "desktop" | units |
Used to set a consistent |
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 |
Output all utilities | $output-all-utilities | true | boolean |
Output all utilities regardless of any individual utility’s output setting. |
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]-settings | map |
Control the output of a [utility] 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]-palettes | "palette-[utility]-default" | palettes |
Utilities output with the values set in the palettes list. |
Utility manual values | $[utility]-palettes | "palette-[utility]-manual-values" | map |
Utilities output with the tokens and values set in the manual values map. |
Utility manual values | [token name] | [token value] |