Color Palettes

Control which color values are available for USWDS color-based utility classes in your project.

The Civic Design System uses the USWDS utility class system to apply styles directly in HTML. Color palettes determine which color values are available when using utilities like .bg-primary, .text-white, or .border-base-lighter. These palettes are configured in the _utilities.scss settings file.

How to Customize

All palette settings follow the same three-step customization process used throughout the Civic Design System:

1. Find the setting you want to change in src/styles/uswds-settings/_utilities.scss
2. Uncomment it (remove the //) and set your value
3. Uncomment the matching line in src/styles/_bridge.scss

The bridge file connects your custom settings to the USWDS core. Both files have all settings pre-written—just uncomment to activate.

Global Color Palettes

Global color palettes define a shared set of color values that are applied to all color-based utilities at once. This is the most efficient way to control which colors are available across your project.

The global palette is set with the $global-color-palettes variable:

$global-color-palettes: ("palette-color-default");

The value "palette-color-default" is the standard USWDS color palette. This single setting controls the available colors for four utilities simultaneously:

• background-color — utilities like .bg-primary, .bg-base-lightest
• border-color — utilities like .border-primary, .border-base-light
• color (text color) — utilities like .text-primary, .text-white
• text-decoration-color — utilities like .text-decoration-color-primary

By changing the global palette, you change the available color values for all four utilities at once. You can also add multiple palettes by providing a comma-separated list.

Individual Color Utility Palettes

Each color-based utility also has its own palette variable for fine-grained control. These are empty by default because they inherit from the global palette:

// Background color
$background-color-palettes: ();      // See Global colors
$background-color-manual-values: ();

// Border color
$border-color-palettes: ();          // See Global colors
$border-color-manual-values: ();

// Color (text)
$color-palettes: ();                 // See Global colors
$color-manual-values: ();

// Text decoration color
$text-decoration-color-palettes: (); // See Global colors
$text-decoration-color-manual-values: ();

When a utility’s palette is left empty (), it uses the global color palettes. If you set a value here, it will override the global palette for that specific utility.

Palette Variables

The -palettes variable accepts a list of named USWDS palette strings. These are predefined sets of values that USWDS provides for each utility. For example, "palette-color-default" includes all standard theme and state color tokens.

Manual Values

The -manual-values variable lets you add custom values beyond what the palettes provide. This is useful when you need a specific color value that isn’t included in the default palette. Manual values are specified as a Sass map of name-value pairs:

$background-color-manual-values: (
  "brand-highlight": #F5F0E6,
  "section-alt": #FAFAFA,
);

This would generate utility classes like .bg-brand-highlight and .bg-section-alt.

Non-Color Utility Palettes

The same palette system applies to all USWDS utilities, not just color-based ones. Each utility has its own -palettes and -manual-values variables. Some examples:

Each utility’s default palette (e.g., "palette-border-radius-default") includes the standard USWDS values for that property. You can replace or extend these with custom palettes and manual values.

Theme Colors vs. Utility Palettes

It’s important to understand the distinction between theme color settings (configured in _colors.scss) and utility palettes (configured in _utilities.scss):

• Theme colors define what your brand colors are—the actual hex values for primary, secondary, accent, and state colors. These are the color definitions.
• Utility palettes control which color tokens are available as utility classes. These determine what color values you can use in markup via utility classes like .bg-* and .text-*.

For example, setting $theme-color-primary: #4D8157 in _colors.scss defines what “primary” means. The utility palettes in _utilities.scss determine whether .bg-primary, .text-primary, and similar classes are generated in your CSS output.

Utility Settings

In addition to palettes, each utility has a settings map that controls its output behavior. These settings are also defined in _utilities.scss:

$background-color-settings: (
  output: true,       // Generate this utility
  responsive: false,  // Generate responsive variants (e.g., tablet:bg-primary)
  active: false,      // Generate :active state variants
  focus: false,       // Generate :focus state variants
  hover: false,       // Generate :hover state variants
  visited: false,     // Generate :visited state variants
);

Setting responsive: true generates breakpoint-prefixed classes like .tablet:bg-primary and .desktop:bg-primary. State variants generate classes like .hover:bg-primary-dark. These are controlled per utility to keep CSS output size manageable.

Additional Resources

• USWDS Utilities Documentation
• USWDS Color Design Tokens
• USWDS System Color Tokens