Color

Colour ships as CSS custom properties from @base-org/bds-tokens. Components read those properties, so a palette change propagates everywhere without touching component code.

@import '@base-org/bds-tokens/tokens/spectrum.css';

Spectrum

Eleven hues, each running from 0 (lightest) to 100 (darkest) across thirteen steps, plus a standalone brand colour. 50–60 is the usable mid-range for interactive fills. Every swatch below is a token — its name is --bds-{hue}-{step} and the class is bg-bds-{hue}-{step} — and the value shown is the light-mode reference.

Usage

Steps

The thirteen steps are 0, 5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100. The gap is intentional: the scale is finer at the light end, where small lightness changes read as distinct surfaces, and coarser at the dark end.

Semantic tokens

Semantic tokens name a role and resolve to one spectrum step per theme. Use them for the surfaces, text, and hairlines that make up a page; reach for a spectrum step directly only when a role does not fit, such as a status colour. The name is --bds-{token} and the class is bg-bds-{token}, text-bds-{token}, or border-bds-{token}.

The grays mirror between themes, so most tokens alias the same step in both; brand and fg-on-brand are the exceptions. Base Blue stays saturated in dark mode, so text on it stays white: pair bg-bds-brand with text-bds-fg-on-brand rather than text-bds-fg-inverse, which turns near-black in dark mode. In JS, getSemanticColor('brand', 'dark') from @base-org/bds-tokens returns the hex value.

Dark mode

The spectrum stylesheet redefines every custom property under .dark, so the same token name resolves correctly in both themes. Components never branch on theme themselves — bg-bds-gray-5 is a light surface in light mode and a dark surface in dark mode, from one class.

Guidelines

Defaults for using tokens and colour in BDS components and product UI. See the Guidelines overview for how to apply them.

Design tokens

• Have components consume tokens (colour, spacing, radius, shadow, motion, type scale) — never hardcoded values.
• Reference semantic tokens (--color-text-secondary), never primitives (--blue-500) — the primitive is the raw value, the token is how it's used.
• Name tokens by purpose, not by raw value or one screen's use case (--color-accent-solid / --radius-card, not --blue-button / --8px).
• Follow a tiered system: primitive → semantic → component-level override only when a component truly needs a one-off.
• Add a token only once a component needs it; remove unused tokens. This applies to colour steps, the spacing scale, radii, shadows, and motion durations and easings alike.
• Keep Figma variables and code tokens in sync — one source of truth, no drift.

Colour

• Reserve accent for the brand colour; don't let primary mean both brand and body text.
• Measure contrast against the background directly behind the element. fg-muted passes 4.5:1 on bg-primary and gray-5 but not on bg-secondary in light mode (4.37:1); use gray-60 for muted text there.
• Use a separate palette for dark mode, not an inversion of the light-mode palette.
• Choose one theme-switching mechanism (prefers-color-scheme or a .dark class), never both.
• Be intentional about gradient colour blending: in oklab (even brightness), in oklch (vivid midtones), or in srgb (muted midtones).