Skip to main content

Color Roles

Semantic color tokens with a predefined purpose.

What are color roles?

Bolt color roles are heavily inspired by Material 3 color roles. As such, there are many parallels between the two.

  • Color roles are ingrained into Bolt design.
    • If your project contains custom components, they'll need to be wired up to Bolt color roles in order to take advantage of the benefits they provide.
  • Color roles ensure accessibility.
    • Bolt's color system is built on accessible pairings to provide a minimum accessible contrast, as defined by WCAG 2.2 guidelines.
  • Color roles are tokenized.
    • Roles are implemented in both design and code via design tokens.
    • Whether you apply global theming via Light mode and Dark mode, or tap into contextual theming, tokenized color roles ensure that your UI components can adapt to a variety of theming contexts.

Terminology

Color roles follow a naming scheme to help communicate their intended use.

The following terms will be helpful to know when deciding which color role to apply in a specific scenario.

Surface
Role used for backgrounds and large, low-emphasis areas of an app screen.
On
Roles with this term in their name indicate that they're meant to be used as a foreground color.
In some edge cases, an "on" role may also be used as an outline to provide adequate contrast between two surfaces.
For example, "On Surface" is used for text and icons against a "Surface" role fill color.
Container
A type of surface, typically used for elevated elements and emphasized sections of content..
Container roles should not be used for text or icons.
Variant
Roles ending with this term offer a lower emphasis alternative to its non-variant counterpart.
For example, "Outline Variant" is a less pronounced version of "Outline".
Primary, Secondary, Tertiary
Brand accent color roles used to emphasize or de-emphasize foreground elements.
Low, Lowest, High, Highest
Roles with these terms provide relative emphasis, compared to a base role.
For example, "Primary Highest" provides greater emphasis than "Primary High" or "Primary".

Surface

Surfaces are opaque layers that initialize a stacking context for elements that sit on top of them.

If it were possible to lift a surface off of the screen, elements that sit on the surface would be brought along as well.

Container roles are also surfaces.

Use surface roles for more neutral backrounds and container roles for more meaningful emphasis.
Surface
Default background color of an application
Inverse Surface
Background color that highly contrasts against "Surface" role
Input Surface
Default background color for inputs
Used as the background for interactive elements like Text field, Text area, Select, Checkbox, Radio button, etc.
Input Surface High
Input background color for emphasized interaction states
Input Surface Highest
Input background color for strongly emphasized interaction states

Relative surfaces

  • Lightness is always relative to default Surface
  • Provide various surface colors for varying degrees of visual emphasis
  • Names do not correlate with elevation (currently)
  • Avoid mixing relative and uniform surface tokens
Surface Container Lowest
Container background color with lowest emphasis against "Surface" role
Surface Container Low
Container background color with low emphasis against "Surface" role
Surface Container
Container background color with medium emphasis against "Surface" role
Surface Container High
Container background color with high emphasis against "Surface" role
Surface Container Highest
Container background color with highest emphasis against "Surface" role

Uniform surfaces

  • Maintains real-world lightness across light and dark mode.
    • The lightest surface in light mode will also be the lightest surface in dark mode.
  • Dim = darkest (always)
  • Bright = brightest (always)
  • Avoid mixing relative and uniform surface tokens
Surface Dimmest
Darkest value surface, approximates appearing in deep shadow, farthest from a real-world light source
Surface Dim
Darker value surface, approximates appearing in shadow, farther from a real-world light source
Surface Mid
Middle value surface, approximates appearing in between a highlight and a shadow from a real-world light source
Surface Bright
Lighter value surface, approximates appearing close to a real-world light source
Surface Brightest
Lightest value surface, approximates appearing closest to a real-world light source

On Surface

If you think of surfaces like pages of a book, then "On Surface" roles would be the ink used to print the text.

On Surface
Accessible foreground color for use on a surface role
On Surface Variant
Lower-emphasis, accessible foreground color for use on a surface role

Accent

Accent roles provide a means to capture or divert attention within the UI.

Bolt defines two categories of accent colors:

Contextual accent

  • prioritizes accessibility above all else
  • favors themed colors, but cannot guarantee specific values
  • best for compatibility with contextual themes

Contextual accent roles are used when your design requires an accent but there's no strict business requirement to use a particular themed accent.

Contextual accents are dynamic in that they will update with the global theme and adapt to contextual themes to ensure that they meet minimum WCAG 2.2 color contrast requirements.

When no contextual theme applies, values won't be any different than the Primary accent.

However, when resolved against a contextual theme, accessible accent color roles may be radically different in order to ensure that role pairings meet accessible minimum color contrast thresholds.
Accent
Accessible accent color (base)
Accent High
Background color for emphasized interaction states of "Accent" themed elements
Accent Highest
Background color for strongly emphasized interaction states of "Accent" themed elements
On Accent
Accessible foreground color for use on any of the three Accent roles above

Themed accents

  • prioritizes brand-based theming above all else
  • best for global theming contexts

Consumers are responsible for ensuring that their choice of themed accent colors meet minimum WCAG 2.2 color contrast requirements.

Themed accents are dynamic in that they will update with the global theme, but they will not adapt to any contextual themes.

Themed accents fall into one of three categories:

Primary accent

Primary accent roles are typically applied to the most prominent components of the UI.

Primary
Primary brand accent color
Primary High
Background color for emphasized interaction states of "Primary" themed elements
Primary Highest
Background color for strongly emphasized interaction states of "Primary" themed elements
On Primary
Accessible foreground color for use on any of the three Primary accents above
Primary Container
Background color for a "Primary" themed container
On Primary Container
Accessible foreground color for use on a "Primary Container" fill

Secondary accent

Secondary accent roles are used for less prominent components in the UI.

Secondary
Secondary brand accent color
Secondary High
Background color for emphasized interaction states of "Secondary" themed elements
Secondary Highest
Background color for strongly emphasized interaction states of "Secondary" themed elements
On Secondary
Accessible foreground color for use on any of the three Secondary accents above
Secondary Container
Background color for a "Secondary" themed container
On Secondary Container
Accessible foreground color for use on a "Secondary Container" fill

Tertiary accent

Tertiary accent roles are typically used for the least prominent components of the UI.

Tertiary
Tertiary brand accent color
Tertiary High
Background color for emphasized interaction states of "Tertiary" themed elements
Tertiary Highest
Background color for strongly emphasized interaction states of "Tertiary" themed elements
On Tertiary
Accessible foreground color for use on any of the three Tertiary accents above
Tertiary Container
Background color for a "Tertiary" themed container
On Tertiary Container
Accessible foreground color for use on a "Tertiary Container" fill

Outline

Outlines are dynamic in that they will update with the global theme and adapt to contextual themes to ensure that they meet minimum WCAG 2.2 color contrast requirements against surface fills.

An outline role is not expected to pass 3:1 color contrast against accent fills.

Instead, use the most specific "On" role as the outline, based on the applied accent.
Outline
Stroke color used for important boundaries, like a text field outline.
Outline Variant
Stroke color used for decoarative elements, like dividers.

Status

Status roles help communicate system health, data validity, critical tasks, important information and much more.

Bolt defines four status categories:

Error

Apply to content that communicates there is an immediate (critical) problem that needs to be corrected or solved.

Error
Error status color
On Error
Accessible foreground color for use on an "Error" fill
Error Container
Background color for an "Error" themed container
On Error Container
Accessible foreground color for use on an "Error Container" fill

Info

Apply to content that communicates useful and relevant (but not critical) information that helps users understand how current conditions affect what they can and cannot do.

Info
Info status color
On Info
Accessible foreground color for use on an "Info" fill
Info Container
Background color for an "Info" themed container
On Info Container
Accessible foreground color for use on an "Info Container" fill

Success

Apply to content that confirms an action or task has been successfully completed.

Success
Success status color
On Success
Accessible foreground color for use on a "Success" fill
Success Container
Background color for a "Success" themed container
On Success Container
Accessible foreground color for use on a "Success Container" fill

Warning

Apply to content that communicates there is an issue that may become a problem in the future.

Warning
Warning status color
On Warning
Accessible foreground color for use on a "Warning" fill
Warning Container
Background color for a "Warning" themed container
On Warning Container
Accessible foreground color for use on a "Warning Container" fill

Special roles

Special roles exist for specific use cases.

Should only be applied to text and icons of a hyperlink.
(contextually dynamic) Its value adapts to the most specific contextual theme applicable to an element in the UI hierarchy.
Focus
Default color used to indicate that an element has interactive focus
(contextually dynamic) Its value adapts to the most specific contextual theme applicable to an element in the UI hierarchy.
Shadow
Color used for drop shadows applied to elevated elements like tooltips and menus
Scrim
Background color used for full-page, semi-transparent overlays arranged between page content and modal containers
Inverse On Surface
"On" role that is only applicable on an "Inverse Surface" background.
Inverse Primary
Only applicable for actionable elements on an "Inverse Surface" background.

Display settings

Note: not all settings persist across pages

Default Compact (-1) Sparse (+1) XL (default) 2XL 3XL Default Min Max Light (default) System Dark Branded (default) Unbranded