Skip to main content

Color tokens

Genesis design systems implement an adaptive colour system that provides some unique advantages:

  • ensure text meets WCAG contrast requirements
  • easily swap from light mode to dark, or anywhere in-between
  • set up colour theming through palette tinting
  • create a perceptually uniform UI across background colours

Workflow​

In practice, typical adaptive colour workflow looks like this:

You don't have to follow the steps in this exact order. For example, you could set set dark/light mode first if you prefer.

tip

To help you visualize how modifying tokens impacts the component look and feel, we have created a live configuration preview.

Choose base colours​

You can set values for accent and neutral colours:

const accentColorValue = '#0EAFE2';
const neutralColorValue = '#808080';

Behind the scenes, accent and neutral colour palettes will be generated from the base colours provided:

Choose the mode​

Choose dark (default) or light mode:

export const baseLayerLuminanceValue = StandardLuminance.DarkMode;
export const baseLayerLuminanceValue = StandardLuminance.LightMode;
tip

StandardLuminance.DarkMode and StandardLuminance.LightMode correspond to values of 0.23 and 1 respectively. You can set baseLayerLuminanceValue to a custom value between 0 for black or 1 for white.

Adjust variations​

Colour variations (e.g. accent colour used on hover) are derived from the base colours using multipliers called deltas. You can modify a specific colour variant by adjusting its delta:

export const accentFillHoverDeltaValue = 4;

Use semantic colour variables in your code​

After you have configured your colours, you have a number of variables available, which can be used in your code to ensure visual consistency across the design system.

Variable names are not tied to specific colours, as they are context-dependent and can vary between light and dark modes - they follow the semantic naming conventions described below.

CSS custom property​

background: var(--accent-fill-rest);
caution

You should consider the CSS custom properties emitted by design tokens to be immutable. Avoid changing their values in CSS, as that can lead to rendering and accessibility issues. If you need to change any values, update the base colour and delta configuration, as described above.

Token​

import {css} from '@genesislcap/web-core';
import {accentFillRest} from '@genesislcap/rapid-design-system';

const styles = css`
  :host {
    background: ${accentFillRest};
}`;

Available variables​

Foreground​

Foreground variables are intended for text, icons, or other lightweight decorations where you need or want to meet contrast requirements.

Neutral foreground​

This is the most common variable, used for plain text or icons.

TokenCSS Custom PropertyPreview
neutralForegroundRest --neutral-foreground-rest
neutralForegroundHint --neutral-foreground-hint

Accent foreground​

This is commonly used for link text or icon. It is also used for smaller elements that might not show up well using accentFill; for instance, use it if your accent colour is dark purple and you support a dark mode interface.

TokenCSS Custom PropertyPreview
accentForegroundRest--accent-foreground-rest
accentForegroundHover--accent-foreground-hover
accentForegroundActive--accent-foreground-active
accentForegroundFocus--accent-foreground-focus

Foreground On Accent​

This is either black or white, based on the contrast requirements. It returns white if possible, as a common treatment for an accent button is white text over the accent colour.

TokenCSS Custom PropertyPreview
foregroundOnAccentRest --foreground-on-accent-rest
foregroundOnAccentHover --foreground-on-accent-hover
foregroundOnAccentActive--foreground-on-accent-active
foregroundOnAccentFocus--foreground-on-accent-focus

Foreground on accent large​

TokenCSS Custom PropertyPreview
foregroundOnAccentRestLarge --foreground-on-accent-rest-large
foregroundOnAccentHoverLarge --foreground-on-accent-hover-large
foregroundOnAccentActiveLarge--foreground-on-accent-active-large
foregroundOnAccentFocusLarge--foreground-on-accent-focus-large

Fill​

Fill variables are intended to fill a larger area, commonly a component background.

Fill colour​

TokenCSS Custom PropertyPreview
fillColor--fill-color

Accent fill​

The closest colours from the supplied palette that can be used for component states. For instance, colours needed to support white text and a 14px font (requires 4.5:1 contrast).

TokenCSS Custom PropertyPreview
accentFillRest--accent-fill-rest
accentFillHover--accent-fill-hover
accentFillActive--accent-fill-active
accentFillFocus--accent-fill-focus

Neutral fill​

This is the most basic fill used for buttons or other components.

TokenCSS Custom PropertyPreview
neutralFillRest--neutral-fill-rest
neutralFillHover--neutral-fill-hover
neutralFillActive--neutral-fill-active
neutralFillFocus--neutral-fill-focus

Neutral fill input​

This is another basic fill, applied to input elements to allow easy differentiation from other components, such as buttons.

TokenCSS Custom PropertyPreview
neutralFillInputRest--neutral-fill-input-rest
neutralFillInputHover--neutral-fill-input-hover
neutralFillInputActive--neutral-fill-input-active
neutralFillInputFocus--neutral-fill-input-focus

Neutral fill stealth​

This is more subtle than neutralFill where the resting state is transparent. It is often used for low-priority features to draw less attention.

TokenCSS Custom PropertyPreview
neutralFillStealthRest--neutral-fill-stealth-rest
neutralFillStealthHover--neutral-fill-stealth-hover
neutralFillStealthActive--neutral-fill-stealth-active
neutralFillStealthFocus--neutral-fill-stealth-focus

Neutral fill strong​

TokenCSS Custom PropertyPreview
neutralFillStrongRest--neutral-fill-strong-rest
neutralFillStrongHover--neutral-fill-strong-hover
neutralFillStrongActive--neutral-fill-strong-active
neutralFillStrongFocus--neutral-fill-strong-focus

Stroke​

Stroke variables are intended for lines, either outline or divider.

Focus stroke​

TokenCSS Custom PropertyPreview
focusStrokeOuter--focus-stroke-outer
focusStrokeInner--focus-stroke-inner

Neutral stroke​

Used for strong outline, either alone or with a fill.

TokenCSS Custom PropertyPreview
neutralStrokeRest--neutral-stroke-rest
neutralStrokeHover--neutral-stroke-hover
neutralStrokeActive--neutral-stroke-active
neutralStrokeFocus--neutral-stroke-focus

Neutral stroke divider​

TokenCSS Custom PropertyPreview
neutralStrokeDividerRest--neutral-stroke-divider-rest

Layer​

The layer variables are used for different sections of an app or site. They are designed to be able to stack, but that is not a requirement. When stacked in sequence, the layers will lighten on top of each other.

The key feature of layering is to support the primary container colour for light or dark mode. This produces absolute colours, based on the baseLayerLuminance value, which sets the luminance for layer one.

The difference between each layer is defined with neutralFillLayerRestDelta.

Neutral layers​

Absolute layer colours derived from and starting at baseLayerLuminance. Layer one is lightest and the values darken as the layer number increases.

TokenCSS Custom PropertyPreview
neutralLayer1--neutral-layer-1
neutralLayer2--neutral-layer-2
neutralLayer3--neutral-layer-3
neutralLayer4--neutral-layer-4

neutralLayerCardContainer​

A special layer to support experiences primarily built with cards, especially in light mode, so cards can be white and the container colour can be one layer darker.

TokenCSS Custom PropertyPreview
neutralLayerCardContainer--neutral-layer-card-container

Neutral fill layer​

This the only layer recipe that's relative to the container colour instead of absolute. The most common example of this is a Card, which will be one layer colour lighter than its container.

TokenCSS Custom PropertyPreview
neutralFillLayerRest--neutral-fill-layer-rest

neutralLayerFloating​

A special layer for floating layers, such as flyouts or menus. It will be lighter than any other layers if possible, but will also be white in default light mode, as will neutral layer one.

TokenCSS Custom PropertyPreview
neutralLayerFloating--neutral-layer-floating