Colors

When choosing color values in design, we recommend starting with semantic color tokens — values with clearly defined intent — and relying on color pairings in Helios that are accessible out of the box.

Color tokens

Color-naming syntax and usage can vary depending on context and tooling. Semantic naming conventions within our system allow us to implement consistent standards in our libraries.

In Figma, we use Variables to define and organize color values. Variables allow us to create palettes that reference (or alias) each other. Our Core palette is a collection of HEX values and their color ramps (neutral-50, neutral-100,…neutral-700). These values are then connected to Semantic Variables (foreground-color-primary, surface--color-faint, border-color-critical). This alias connection allows us to designate multiple token uses for individual HEX values that lead back to the same Core palette token.

Tokens in code are generated from platform-agnostic files, in our case JSON, and create atomic colors regardless of what platform or framework is used. Core palette values are directly referenced in Semantic palette values in the same way that Figma variables alias one another.

What are semantic colors?

The Semantic palette embeds meaning into color names, making it easier to select correct consistent values across applications. These colors are designed to meet accessibility standards when used in combination with one another.

• Foreground colors are intended to be used with surface or page colors.
• Status color values consist of "surface," "on-surface," and "high-contrast" options to meet accessibility standards when used together.

Some examples of semantic color combinations with their respective contrast ratios are:

• Foreground/Color/Strong on Surface/Color/Primary nets a ratio of 19.54:1
• Foreground/Color/Primary on Surface/Color/Primary nets a ratio of 10.82:1
• Foreground/Color/Action on Surface/Color/Faint nets a ratio of 4.86:1

How are semantic names created?

In semantic token naming, the semantic and modifier values are defined to make color decisions easier and more consistent. HDS organizes tokens into semantic categories, followed by properties, and then modifiers.

Examples of semantic naming include:

• Foreground - For text, link, status, and icon elements
• Border - For borders (or strokes) on components, containers, or dividers
• Surface - For the background (or surface) of a component or container
• Page - For page backgrounds

Examples of modifiers in naming include:

• Strong
• Primary
• Faint
• Action (not to be used outside of context)
• Disabled (not to be used outside of context)

Foreground

Foreground colors are used for informational and decorative elements such as text, links, and icons.

Some common examples of semantic foreground colors include:

• Foreground/Color/Strong for headings and secondary links
• Foreground/Color/Primary for body text
• Foreground/Color/Faint for less prominent text and UI elements
• Foreground/Color/Action for primary calls to action such as links

Status foreground colors contextualize responses from user actions or indicate status within a UI. These colors should be used sparingly and within the context of specific components, for example:

• Alerts
• Toasts

Border

Some examples of border colors include:

• Border/Color/Strong for secondary Button border
• Border/Color/Primary for Card border or divider
• Border/Color/{Status color} for Alert borders

Surface

Surface colors are intended to be used for the background (or surface) of a component or container.

Examples of surface colors include:

• Surface/Color/Strong for the Toggle background
• Surface/Color/Primary for component containers
• Surface/Color/Faint for the secondary Button
• Surface/Color/{Status color} for Alert backgrounds

Page

Page colors are used for page backgrounds. HDS components do not use these tokens; however, we recommend Page/Color/Primary for all standard page backgrounds and Page/Color/Faint as a means to create a secondary level on a page if necessary.

Accessible color combinations

HDS colors are conformant with WCAG 2.2 Level AA requirements. For color contrast, this means a luminosity ratio of 4.5:1 for normal sized text, and 3:1 for large text (commonly 22px). Further details are outlined on WCAG’s understanding of Contrast (Minimum).

HDS semantic color tokens provide accessible color combinations out of the box when used according to their naming conventions (Surface/Color/{Status color} is compliant in combination with Foreground/Color/{Status color on surface}). Using other color token combinations requires manual validation.

It is important to note that we do not recommend the usage of disabled elements, especially the use of disabled colors out of context, as they are not accessible.

Using palette colors

If the Semantic tokens do not meet your needs, the Core palette has been published for general use. These values are usage-agnostic, which can introduce challenges in consistently scaling designs but also allows more freedom and flexibility in color pairing.

When pairing colors from the Core palette, check that adjacent colors meet accessible contrast ratios. To validate your color combinations, use free tools like the WebAIM contrast checker or Stark’s Figma plugin.

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>

When a “border-color” CSS helper is used on an element a 1px solid border is applied to it. If needing a different border width/style, it’s ok to override it.

Design tokens

Use the color design tokens directly in your CSS definitions.

.your-selector {
  color: var(--hds-foreground-color-primary);
  background: var(--hds-surface-color-faint);
  border: 1px solid var(--hds-border-color-strong);

  & :hover {
    color: var(--hds-foreground-color-high-contrast);
    background: var(--hds-foreground-color-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.