Colors

When choosing what colors to use, we recommend starting with semantic colors as their usage is clearly defined and common color pairings are accessible out of the box.

Using semantic colors

Semantic color tokens help ensure proper color usage across applications by building the meaning directly into the token name.

Foreground

Foreground colors are for text, links, icons, etc. For example:

• Foreground/Primary is used for primary text elements or elements that sit on top of a surface background.
• Foreground/Action is used for an actionable or interactive element within a component or page (e.g., a Link).

Border

Border colors are for borders on components or containers and for horizontal rules.

Surface

Surface colors are for the main background (or surface) of a component or container. For example:

• Surface/Primary is used as the container background of a component.

Page

Page colors are for page backgrounds. For example:

• Page/Secondary is used to highlight a section background on the main page.

Using palette colors

If you don’t find a semantic color that meets your needs, a set of base Palette colors are also available. These styles are usage agnostic which can introduce challenges in consistently scaling a complex design, but allow more freedom and flexibility in color pairing.

How to use these styles

We offer two ways to apply color to a UI element: CSS helper classes or design tokens.

We currently only provide CSS helpers for the “semantic” colors, so if you need to use the “palette” or “product/brand” colors, use the design tokens as CSS variables instead.

CSS helper classes

1. Ensure you’ve imported the relevant CSS file.

// for product applications
@import "~@hashicorp/design-system-tokens/dist/products/css/helpers/colors.css";

// for hashicorp developer platform
@import "~@hashicorp/design-system-tokens/dist/devdot/css/helpers/colors.css";

2. Use one of the predefined CSS helper classes.

<div class="hds-foreground-primary hds-surface-faint hds-border-strong">...</div>

Design tokens

Use the color design tokens directly in your CSS definitions.

.your-selector {
  color: var(--token-color-foreground-primary);
  background: var(--token-color-surface-faint);
  border: (--token-color-border-strong);
  & :hover {
    color: var(--token-color-foreground-high-contrast);
    background: var(--token-color-foreground-action-active);
  }
}

Semantic tokens

Foreground

Use for text and icons.

Surface

Use for container and component backgrounds.

Border

Use for container and component borders. Neutral values can also be used for horizontal rules.

Focus

Use to indicate an element is in a focused state. Use critical values for critical actions only and action values for everything else.

Page

Use for page backgrounds.

Brand colors

Core palette

Core palette colors should be used sparingly and only when the correct semantic mapping isn’t available for the use case.