Design System Tokens - Colour
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
- cset 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 e.g. you could set set dark/light mode first if you prefer.
To help you visualise 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 mode
Choose dark (default) or light mode:
export const baseLayerLuminanceValue = StandardLuminance.DarkMode;
export const baseLayerLuminanceValue = StandardLuminance.LightMode;
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);
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/foundation-ui';
import {accentFillRest} from '@genesislcap/alpha-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
The most common variable, used for plain text or icons.
| Token | CSS Custom Property | Preview |
|---|---|---|
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, if your accent colour is dark purple and you support a dark mode interface.
| Token | CSS Custom Property | Preview |
|---|---|---|
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.
| Token | CSS Custom Property | Preview |
|---|---|---|
foregroundOnAccentRest | --foreground-on-accent-rest | |
foregroundOnAccentHover | --foreground-on-accent-hover | |
foregroundOnAccentActive | --foreground-on-accent-active | |
foregroundOnAccentFocus | --foreground-on-accent-focus |
Foreground on accent large
| Token | CSS Custom Property | Preview |
|---|---|---|
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
| Token | CSS Custom Property | Preview |
|---|---|---|
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).
| Token | CSS Custom Property | Preview |
|---|---|---|
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.
| Token | CSS Custom Property | Preview |
|---|---|---|
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.
| Token | CSS Custom Property | Preview |
|---|---|---|
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.
| Token | CSS Custom Property | Preview |
|---|---|---|
neutralFillStealthRest | --neutral-fill-stealth-rest | |
neutralFillStealthHover | --neutral-fill-stealth-hover | |
neutralFillStealthActive | --neutral-fill-stealth-active | |
neutralFillStealthFocus | --neutral-fill-stealth-focus |
Neutral fill strong
| Token | CSS Custom Property | Preview |
|---|---|---|
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
| Token | CSS Custom Property | Preview |
|---|---|---|
focusStrokeOuter | --focus-stroke-outer | |
focusStrokeInner | --focus-stroke-inner |
Neutral stroke
Used for strong outline, either alone or with a fill.
| Token | CSS Custom Property | Preview |
|---|---|---|
neutralStrokeRest | --neutral-stroke-rest | |
neutralStrokeHover | --neutral-stroke-hover | |
neutralStrokeActive | --neutral-stroke-active | |
neutralStrokeFocus | --neutral-stroke-focus |
Neutral stroke divider
| Token | CSS Custom Property | Preview |
|---|---|---|
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.
| Token | CSS Custom Property | Preview |
|---|---|---|
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.
| Token | CSS Custom Property | Preview |
|---|---|---|
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.
| Token | CSS Custom Property | Preview |
|---|---|---|
neutralFillLayerRest | --neutral-fill-layer-rest |
neutralLayerFloating
A special layer for floating layers, like 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.
| Token | CSS Custom Property | Preview |
|---|---|---|
neutralLayerFloating | --neutral-layer-floating |