Skip to main content

Design Tokens

Design tokens are the basic construction pieces of a design system such as colors, spacing, and typography. They support visual consistency across Bolt components, patterns, layouts, and the Nationwide brand.

Using Sass tokens

  • Sass tokens are designed to be consumed via the @use syntax, as demonstrated below.
  • Sass tokens are built to @use anywhere you need them, without introducing any side-effects.

If you're interested in incorporating Bolt's design tokens into a third-party front end framework such as Angular Material, please refer to Bolt Adapters documentation.
Consuming Sass tokens, via the "Bolt" namespace: 
@use "path/to/bolt/tokens" as Bolt;

.foobar {
  background: Bolt.$theme-background;
  border: 1px solid Bolt.$theme-outline;
  color: Bolt.$theme-onBackground;
}

Consumption via Sass @import is not recommended.

  • It can introduce subtle bugs in your code via unwanted side-effects.
  • Sass @import has been deprecated for removal in Sass 2.0

Using CSS custom properties

Bolt provides many runtime-fluid CSS custom properties whose values adapt to various configurations and styling contexts.

Unless explicitly documented, CSS custom properties should not be overridden in downstream project styles.
  • CSS custom properties are available via Bolt's precompiled CSS styles.
  • CSS custom properties are at the center of Bolt theming capabilities like Density, Global theming, and Contextual theming.
Consuming CSS custom properties: 
@use "path/to/bolt/css";

body {
  background: var(--bolt-theme-surface);
  color: var(--bolt-theme-onSurface);
}

.custom-link {
  color: var(--bolt-context-link);
}

Supported tokens

Only those tokens that are documented below are supported by Bolt for consumer use.

There are numerous undocumented tokens that may be available, but aren't meant for public consumption.

Spacing tokens

Spacing tokens are best applied to properties that configure white space and relative positioning.

  • Sass tokens have a constant, fixed value.
  • CSS tokens are affected by global density configuration
  • CSS tokens support
Token Details
3xs

3XS white space
Since
Default
2px
Sass
$space-3xs
CSS
--bolt-space-3xs
2xs

2XS white space
Default
4px
Sass
$space-2xs
CSS
--bolt-space-2xs
xs

XS white space
Default
8px
Sass
$space-xs
CSS
--bolt-space-xs
sm

SM white space
Default
12px
Sass
$space-sm
CSS
--bolt-space-sm
md

MD white space
Default
16px
Sass
$space-md
CSS
--bolt-space-md
lg

LG white space
Default
20px
Sass
$space-lg
CSS
--bolt-space-lg
xl

XL white space
Default
24px
Sass
$space-xl
CSS
--bolt-space-xl
2xl

2XL white space
Default
32px
Sass
$space-2xl
CSS
--bolt-space-2xl
3xl

3XL white space
Default
40px
Sass
$space-3xl
CSS
--bolt-space-3xl
4xl

4XL white space
Default
48px
Sass
$space-4xl
CSS
--bolt-space-4xl

Breakpoint tokens

Breakpoint tokens define the smallest viewport width for a given responsive breakpoint.

Token Details
2xs

Extra extra small (2XS) screens (e.g., wearables, smart phones in portrait orientation, etc.)
Value
0px
Sass
$screen-2xs
xs

Extra small screens (e.g., smart phones)
Value
360px
Sass
$screen-xs
sm

Small screens (e.g., smart phones in landscape)
Value
576px
Sass
$screen-sm
md

Medium screens (tablets, high-end smart phones in landscape, etc.)
Value
768px
Sass
$screen-md
lg

Large screens (laptops, desktop monitors, tablets in landscape, etc.)
Value
992px
Sass
$screen-lg
xl

HD displays (720p)
Value
1200px
Sass
$screen-xl
2xl

Wide HD displays
Value
1444px
Sass
$screen-2xl
3xl

Full HD displays (1080p)
Value
1752px
Sass
$screen-3xl

Radius tokens

Radius tokens are best applied to round over sharp corners.

Token Details
default

default border radius
Value
4px
Sass
$radius-default

Elevation tokens

Elevation tokens are provided for logical z-index configuration (larger values placed closer than smaller values).

Elevation tokens do not apply nor correlate to any drop shadow implementations.
Token Details
low

Z-index value for minimal elevation
Value
1
Sass
$elevation-low
med

Z-index value for non-modal elevation
Value
50
Sass
$elevation-med
sticky

Z-index value for sticky content
Value
100
Sass
$elevation-sticky
overlay

Z-index value for overlay container
Value
500
Sass
$elevation-overlay
overlayContent

Z-index value for overlay content
Value
510
Sass
$elevation-overlayContent
top

Z-index value for highest elevation
Value
999
Sass
$elevation-top

Timing tokens

Timing tokens are best applied as the duration configuration of animations, transitions, and other movement-based interactions.

Token Details
slowest

slowest time duration
Value
1500ms
Sass
$time-slowest
slow

slow time duration
Value
650ms
Sass
$time-slow
default

default time duration
Value
350ms
Sass
$time-default
fast

fast time duration
Value
150ms
Sass
$time-fast
Hover over an example to preview a timing token.

Color tokens

Bolt's color tokens include two dynamic sets of colors and one static set, for use in different scenarios.

Color tokens can be used anywhere a CSS color is applicable.

As of Bolt 7.11.0, Bolt's colors include updated values and an expanded palette in alignment with Nationwide Brand updates.
Context colors (dynamic)
Respond to both contextual theme (background color) and global theme (light/dark mode).
Use when styling elements whose visibility would be affected by a background color.
For example, text or icons.
Theme colors (dynamic)
Respond only to global theme (light/dark mode).
Use when styling elements that should not be affected by the background color of a parent.
For example, a tile's surface follows global theme, regardless of local context.
Brand palette colors (static)
These colors reflect the Nationwide brand.
They have a constant value and do not change with theme nor context.

Context tokens

For more information, see contextual themes.

context.surface

Background color for a contextual container

context.onSurface

Accessible foreground color for use on a context.surface background

MUST pass 4.5:1 contrast vs context.surface token
context.onSurfaceVariant

Lower-emphasis, accessible foreground color for use on a context.surface background

MUST pass 4.5:1 contrast vs context.surface token
context.outline

Stroke color used for important boundaries within a contextual container

MUST pass 3:1 contrast vs context.surface token
context.outlineVariant

Stroke color used for decorative elements within a contextual container

MAY pass 3:1 contrast vs context.surface token
context.focus

Default color used to indicate that an element within a contextual container has interactive focus

MUST pass 3:1 contrast vs context.surface token
context.link

Default foreground color for hyperlinks within a contextual container

MUST pass 4.5:1 contrast vs context.surface token
context.accent

Generic accent color for use within a contextual container

MUST pass 3:1 contrast vs context.surface token
context.accentHigh

Background color for emphasized interaction states of context.accent themed elements within a contextual container

MUST pass 4.5:1 contrast vs context.onAccent token
context.accentHighest

Background color for strongly emphasized interaction states of context.accent themed elements within a contextual container

MUST pass 4.5:1 contrast vs context.onAccent token
context.onAccent

Accessible foreground color for use on any context.accent themed background within a contextual container

MUST pass 4.5:1 contrast vs context.accent, context.accentHigh, and context.accentHighest tokens

Theme tokens

For more information, see global theme.

Sass tokens have a static value and are forever coupled to the default theme.

CSS tokens must be used to support non-default themes like dark mode.
theme.surface

Default background color of an application

theme.surfaceContainerLowest

Container background color with lowest emphasis against theme.surface token

theme.surfaceContainerLow

Container background color with low emphasis against theme.surface token

theme.surfaceContainer

Container background color with medium emphasis against theme.surface token

theme.surfaceContainerHigh

Container background color with high emphasis against theme.surface token

theme.surfaceContainerHighest

Container background color with highest emphasis against theme.surface token

theme.surfaceDimmest

Darkest surface color

theme.surfaceDim

2nd-darkest surface color

theme.surfaceMid

Surface color midway between surfaceDimmest and surfaceBrightest

theme.surfaceBright

2nd-brightest surface color

theme.surfaceBrightest

Brightest surface color

theme.inputSurface

Default background color for inputs

theme.inputSurfaceHigh

Input background color for emphasized interaction states

theme.inputSurfaceHighest

Input background color for strongly emphasized interaction states

theme.onSurface

Accessible foreground color for use on theme-based surfaces

For best results in localized theming contexts, use context.onSurface instead.
theme.onSurfaceVariant

Lower-emphasis, accessible foreground color for use on theme-based surfaces

For best results in localized theming contexts, use context.onSurfaceVariant instead.
theme.inverseSurface

Background color that highly contrasts against theme.surface token

theme.inverseOnSurface

Accessible foreground color for use on theme.inverseSurface background

theme.outline

Default stroke color used for important boundaries, like a text field outline

This color is not guaranteed to pass accessible color contrast against theme-based accents.

This color should pass accessible color contrast against theme-based surfaces.

For best results in localized theming contexts, use context.outline instead.
theme.outlineVariant

Default stroke color used for decorative elements, like dividers

This color is not guaranteed to pass accessible color contrast against theme-based surfaces or accents.

For best results in localized theming contexts, use context.outlineVariant instead.
theme.focus

Default color used to indicate that an element has interactive focus

For best results in localized theming contexts, use context.focus instead.
theme.shadow

Color used for drop shadows applied to elevated elements like tooltips and menus

theme.scrim

Background color used for full-page, semi-transparent overlays arranged between page content and modal containers

theme.scrimOpacity

Default scrim opacity

theme.link

Default foreground color for hyperlinks

For best results in localized theming contexts, use context.link instead.
theme.accent

Generic accent color

For best results in localized theming contexts, use context.accent instead.
theme.accentHigh

Background color for emphasized interaction states of theme.accent themed elements

For best results in localized theming contexts, use context.accentHigh instead.
theme.accentHighest

Background color for strongly emphasized interaction states of theme.accent themed elements

For best results in localized theming contexts, use context.accentHighest instead.
theme.onAccent

Accessible foreground color for use on any theme.accent themed background

For best results in localized theming contexts, use context.onAccent instead.

May also be used as an outline around a theme.accent background
theme.primary

Primary brand accent color

theme.primaryHigh

Background color for emphasized interaction states of theme.primary themed elements

theme.primaryHighest

Background color for strongly emphasized interaction states of theme.primary themed elements

theme.inversePrimary

Color for actionable elements on a theme.inverseSurface background

theme.onPrimary

Accessible foreground color for use on a theme.primary themed background

May also be used as an outline around a theme.primary background
theme.primaryContainer

Background color for a theme.primary themed container

theme.onPrimaryContainer

Accessible foreground color for use on a theme.primaryContainer background

theme.secondary

Secondary brand accent color

theme.secondaryHigh

Background color for emphasized interaction states of theme.secondary themed elements

theme.secondaryHighest

Background color for strongly emphasized interaction states of theme.secondary themed elements

theme.onSecondary

Accessible foreground color for use on a theme.secondary themed background

May also be used as an outline around a theme.secondary background
theme.secondaryContainer

Background color for a theme.secondary themed container

theme.onSecondaryContainer

Accessible foreground color for use on a theme.secondaryContainer background

theme.tertiary

Tertiary brand accent color

theme.tertiaryHigh

Background color for emphasized interaction states of theme.tertiary themed elements

theme.tertiaryHighest

Background color for strongly emphasized interaction states of theme.tertiary themed elements

theme.onTertiary

Accessible foreground color for use on a theme.tertiary themed background

May also be used as an outline around a theme.tertiary background
theme.tertiaryContainer

Background color for a theme.tertiary themed container

theme.onTertiaryContainer

Accessible foreground color for use on a theme.tertiaryContainer background

theme.error

Error status color

theme.onError

Accessible foreground color for use on a theme.error background

May also be used as an outline around a theme.error background
theme.errorContainer

Background color for a theme.error themed container

theme.onErrorContainer

Accessible foreground color for use on a theme.errorContainer background

theme.warning

Warning status color

theme.onWarning

Accessible foreground color for use on a theme.warning background

May also be used as an outline around a theme.warning background
theme.warningContainer

Background color for a theme.warning themed container

theme.onWarningContainer

Accessible foreground color for use on a theme.warningContainer background

theme.info

Info status color

theme.onInfo

Accessible foreground color for use on a theme.info background

May also be used as an outline around a theme.info background
theme.infoContainer

Background color for a theme.info themed container

theme.onInfoContainer

Accessible foreground color for use on a theme.infoContainer background

theme.success

Success status color

theme.onSuccess

Accessible foreground color for use on a theme.success background

May also be used as an outline around a theme.success background
theme.successContainer

Background color for a theme.success themed container

theme.onSuccessContainer

Accessible foreground color for use on a theme.successContainer background

Brand palette tokens

Brand palette tokens represent brand-compliant colors for use in Bolt-based UIs.

  • Brand palette tokens have a static value (regardless of format).
  • "On" tokens are provided for each brand color.
palette.vibrantBlue

Palette / Vibrant Blue

palette.onVibrantBlue

Accessible foreground color on a palette.vibrantBlue background

palette.darkVibrantBlue

Palette / Dark Vibrant Blue

palette.onDarkVibrantBlue

Accessible foreground color on a palette.darkVibrantBlue background

palette.white

Palette / White

palette.onWhite

Accessible foreground color on a palette.white background

palette.nCropBlue

Palette / N Crop Blue

palette.onNCropBlue

Accessible foreground color on a palette.nCropBlue background

palette.darkBlue

Palette / Dark Blue

palette.onDarkBlue

Accessible foreground color on a palette.darkBlue background

palette.mediumBlue

Palette / Medium Blue

palette.onMediumBlue

Accessible foreground color on a palette.mediumBlue background

palette.lightBlue

Palette / Light Blue

palette.onLightBlue

Accessible foreground color on a palette.lightBlue background

palette.ultralightBlue

Palette / Ultralight Blue

palette.onUltralightBlue

Accessible foreground color on a palette.ultralightBlue background

palette.mint

Palette / Mint

palette.onMint

Accessible foreground color on a palette.mint background

palette.darkMint

Palette / Dark Mint

palette.onDarkMint

Accessible foreground color on a palette.darkMint background

palette.seaBlue

Palette / Sea Blue

palette.onSeaBlue

Accessible foreground color on a palette.seaBlue background

palette.darkSeaBlue

Palette / Dark Sea Blue

palette.onDarkSeaBlue

Accessible foreground color on a palette.darkSeaBlue background

palette.lavender

Palette / Lavender

palette.onLavender

Accessible foreground color on a palette.lavender background

palette.deepPurple

Palette / Deep Purple

palette.onDeepPurple

Accessible foreground color on a palette.deepPurple background

palette.darkGreen

Palette / Dark Green

palette.onDarkGreen

Accessible foreground color on a palette.darkGreen background

palette.green

Palette / Green

palette.onGreen

Accessible foreground color on a palette.green background

palette.sunburstOrange

Palette / Sunburst Orange

palette.onSunburstOrange

Accessible foreground color on a palette.sunburstOrange background

palette.burntOrange

Palette / Burnt Orange

palette.onBurntOrange

Accessible foreground color on a palette.burntOrange background

palette.lemonYellow

Palette / Lemon Yellow

palette.onLemonYellow

Accessible foreground color on a palette.lemonYellow background

palette.wheat

Palette / Wheat

palette.onWheat

Accessible foreground color on a palette.wheat background

palette.charcoal

Palette / Charcoal

palette.onCharcoal

Accessible foreground color on a palette.charcoal background

palette.ultralightGray

Palette / Ultralight Gray

palette.onUltralightGray

Accessible foreground color on a palette.ultralightGray background

palette.lightGray

Palette / Light Gray

palette.onLightGray

Accessible foreground color on a palette.lightGray background

palette.mediumGray

Palette / Medium Gray

palette.onMediumGray

Accessible foreground color on a palette.mediumGray background

palette.darkGray

Palette / Dark Gray

palette.onDarkGray

Accessible foreground color on a palette.darkGray background

palette.mediumFossil

Palette / Medium Fossil

palette.onMediumFossil

Accessible foreground color on a palette.mediumFossil background

palette.lightFossil

Palette / Light Fossil

palette.onLightFossil

Accessible foreground color on a palette.lightFossil background

palette.ultralightFossil

Palette / Ultralight Fossil

palette.onUltralightFossil

Accessible foreground color on a palette.ultralightFossil background

palette.darkFossil

Palette / Dark Fossil

palette.onDarkFossil

Accessible foreground color on a palette.darkFossil background

Deprecated palette tokens

Deprecated tokens will be removed in a future major release of Bolt.
palette.cherryRed

Palette / Cherry Red

palette.onCherryRed

Accessible foreground color on a palette.cherryRed background

palette.mustard

Palette / Mustard

palette.onMustard

Accessible foreground color on a palette.mustard background

palette.paleGray

Palette / Pale Gray

palette.onPaleGray

Accessible foreground color on a palette.paleGray background

palette.fossil

Palette / Fossil

palette.onFossil

Accessible foreground color on a palette.fossil 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