Color
Color token values are defined by context. Toggle theme and hue to preview each context.
Overview
Beacon uses color tokens to keep UI consistent, themeable, and accessible. In product UI, prefer the brand role tokens (background/foreground/border) and treat the palette as reference.
- Use role tokens for implementation:
--bg-*,--fg-*,--border-*. - Avoid hard-coded hex values in components.
- Palette tokens (
--color-*) are primarily for reference and token wiring.
General concepts
Color themes and device color modes aren't synonymous. Themes are tailored to the product; modes are system-wide. Use theme-aware tokens so the UI remains readable and intentional.
In Beacon, context comes from two switches:
data-theme(light/dark) overrides brand role tokens.data-hue(chromatic/sky/indigo) changes the semantic primary palette that brand roles reference.
Token mapping
Beacon uses a three-layer token system where each layer references the one below it. This creates a flexible, maintainable color system.
Primitives
--color-purple-500Raw color values defined in hex. These are the foundation colors that never change.
↓
Semantic
--color-primary-500Context-aware colors that reference primitives. The primary color changes based on the selected hue (chromatic/sky/indigo).
↓
Brand
--bg-primaryProduct-facing role tokens that reference semantic tokens. These adapt to both theme (light/dark) and hue settings.
Example mapping: --bg-primary → --color-primary-500 → --color-purple-500 (when hue is "chromatic-prime")
Theme
Hue
Palette
Palette tokens are reference values and semantic wiring. Use role tokens for product UI, and use this section to understand the underlying system.
Primitives
Raw color families (hex + alpha variants).
Purple
(unavailable)
Blue
(unavailable)
Gray
(unavailable)
Chromatic
(unavailable)
Green
(unavailable)
Orange
(unavailable)
Red
(unavailable)
White (alpha)
(unavailable)
Black (alpha)
(unavailable)
Semantic
Semantic families (primary is hue-dependent).
Primary
(unavailable)
Neutral
(unavailable)
Success
(unavailable)
Warning
(unavailable)
Critical
(unavailable)
Alpha Neutral White
(unavailable)
Alpha Neutral Black
(unavailable)
Brand
These are the product-facing color roles. Prefer these in components and avoid selecting raw palette values by appearance.
Background
Surface and status backgrounds. Use these for containers, fills, and stateful backgrounds.
Token
Role
Preview
Resolved
Actions
--bg-page-primaryPage Primary
Default app background for main surfaces.
Aa
Preview
(unavailable)--bg-page-secondaryPage Secondary
Secondary surface background for grouped content.
Aa
Preview
(unavailable)--bg-page-tertiaryPage Tertiary
Tertiary surface background for subtle elevation.
Aa
Preview
(unavailable)--bg-whiteWhite Surface (Brand)
A “white” surface role that adapts to theme.
Aa
Preview
(unavailable)--bg-disabledDisabled Background
Background for disabled containers or controls.
Aa
Preview
(unavailable)--bg-transparentTransparent Background
Transparent background role (use for overlays/ghost elements).
Aa
Preview
(unavailable)--bg-primaryBrand
Primary brand action background.
Aa
Preview
(unavailable)--bg-primary-on-hoverBrand Hover
Hover background for primary brand actions.
Aa
Preview
(unavailable)--bg-primary-pressedBrand Pressed
Pressed background for primary brand actions.
Aa
Preview
(unavailable)--bg-primary-on-focusedBrand Focus
Focus background for primary brand actions (when specified).
Aa
Preview
(unavailable)--bg-primary-disabledBrand Disabled
Disabled background for brand actions.
Aa
Preview
(unavailable)--bg-primary-tonalBrand Tonal
Tonal brand surface (subtle emphasis).
Aa
Preview
(unavailable)--bg-primary-tonal-on-hoverBrand Tonal Hover
Hover state for tonal brand surfaces.
Aa
Preview
(unavailable)--bg-primary-darkBrand Dark
High-contrast brand surface role (when specified).
Aa
Preview
(unavailable)--bg-successSuccess
Success status background.
Aa
Preview
(unavailable)--bg-success-on-hoverSuccess Hover
Hover background for success actions.
Aa
Preview
(unavailable)--bg-success-tonalSuccess Tonal
Tonal success surface (banners, subtle callouts).
Aa
Preview
(unavailable)--bg-success-darkSuccess Dark
High-contrast success surface role (when specified).
Aa
Preview
(unavailable)--bg-warningWarning
Warning status background.
Aa
Preview
(unavailable)--bg-warning-on-hoverWarning Hover
Hover background for warning actions.
Aa
Preview
(unavailable)--bg-warning-tonalWarning Tonal
Tonal warning surface (banners, subtle callouts).
Aa
Preview
(unavailable)--bg-warning-darkWarning Dark
High-contrast warning surface role (when specified).
Aa
Preview
(unavailable)--bg-criticalCritical
Critical/error status background.
Aa
Preview
(unavailable)--bg-critical-on-hoverCritical Hover
Hover background for critical actions.
Aa
Preview
(unavailable)--bg-critical-tonalCritical Tonal
Tonal critical surface (banners, subtle callouts).
Aa
Preview
(unavailable)--bg-critical-darkCritical Dark
High-contrast critical surface role (when specified).
Aa
Preview
(unavailable)Foreground
Text and icon colors. Use these for readable content and semantic emphasis.
Token
Role
Preview
Resolved
Actions
--fg-neutralNeutral
Default text color for reading.
Aa
Preview
(unavailable)--fg-neutral-secondaryNeutral Secondary
Secondary text (supporting content, metadata).
Aa
Preview
(unavailable)--fg-neutral-tertiaryNeutral Tertiary
Tertiary text (helper text, quiet labels).
Aa
Preview
(unavailable)--fg-primaryPrimary
Brand foreground (links, accents).
Aa
Preview
(unavailable)--fg-primary-on-hoverPrimary Hover
Hover foreground for brand accents.
Aa
Preview
(unavailable)--fg-primary-pressedPrimary Pressed
Pressed foreground for brand accents.
Aa
Preview
(unavailable)--fg-primary-on-focusPrimary Focus
Focus foreground for brand accents (when specified).
Aa
Preview
(unavailable)--fg-primary-tonalPrimary Tonal
Foreground on tonal brand surfaces (paired with tonal roles).
Aa
Preview
(unavailable)--fg-primary-on-tonalPrimary On Tonal
Readable text/icon color on tonal brand surfaces.
Aa
Preview
(unavailable)--fg-primary-disabledPrimary Disabled
Disabled foreground for brand accents.
Aa
Preview
(unavailable)--fg-criticalCritical
Critical foreground (errors, destructive actions).
Aa
Preview
(unavailable)--fg-critical-tonalCritical Tonal
Foreground on tonal critical surfaces.
Aa
Preview
(unavailable)--fg-critical-on-tonalCritical On Tonal
Readable text/icon color on tonal critical surfaces.
Aa
Preview
(unavailable)--fg-warningWarning
Warning foreground.
Aa
Preview
(unavailable)--fg-warning-tonalWarning Tonal
Foreground on tonal warning surfaces.
Aa
Preview
(unavailable)--fg-warning-on-tonalWarning On Tonal
Readable text/icon color on tonal warning surfaces.
Aa
Preview
(unavailable)--fg-successSuccess
Success foreground.
Aa
Preview
(unavailable)--fg-success-tonalSuccess Tonal
Foreground on tonal success surfaces.
Aa
Preview
(unavailable)--fg-success-on-tonalSuccess On Tonal
Readable text/icon color on tonal success surfaces.
Aa
Preview
(unavailable)--fg-on-actionOn Action
High-contrast foreground on strong action backgrounds.
Aa
Preview
(unavailable)--fg-whiteWhite
White foreground role (for high-contrast cases).
Aa
Preview
(unavailable)--fg-disabledDisabled
Disabled text/icon foreground.
Aa
Preview
(unavailable)--fg-on-disabledOn Disabled
Foreground used on disabled surfaces (paired with disabled background).
Aa
Preview
(unavailable)Border
Stroke colors. Use these for outlines, dividers, and focus/active borders.
Token
Role
Preview
Resolved
Actions
--border-neutral-primaryNeutral Primary
Primary neutral border for controls and containers.
Aa
Preview
(unavailable)--border-neutral-secondaryNeutral Secondary
Secondary neutral border for subtle separation.
Aa
Preview
(unavailable)--border-neutral-tertiaryNeutral Tertiary
Tertiary border for light dividers.
Aa
Preview
(unavailable)--border-strongStrong
Strong outline for high emphasis separation.
Aa
Preview
(unavailable)--border-strong-100Strong 100
Strong border with alpha (light emphasis).
Aa
Preview
(unavailable)--border-strong-200Strong 200
Strong border with alpha (medium emphasis).
Aa
Preview
(unavailable)--border-primaryPrimary
Brand border for focused/active elements.
Aa
Preview
(unavailable)--border-primary-on-hoverPrimary Hover
Hover border for brand accents.
Aa
Preview
(unavailable)--border-primary-pressedPrimary Pressed
Pressed border for brand accents.
Aa
Preview
(unavailable)--border-primary-disabledPrimary Disabled
Disabled border for brand accents.
Aa
Preview
(unavailable)--border-primary-tonalPrimary Tonal
Border on tonal brand surfaces.
Aa
Preview
(unavailable)--border-successSuccess
Success border.
Aa
Preview
(unavailable)--border-success-tonalSuccess Tonal
Border on tonal success surfaces.
Aa
Preview
(unavailable)--border-warningWarning
Warning border.
Aa
Preview
(unavailable)--border-warning-tonalWarning Tonal
Border on tonal warning surfaces.
Aa
Preview
(unavailable)--border-criticalCritical
Critical border.
Aa
Preview
(unavailable)--border-critical-tonalCritical Tonal
Border on tonal critical surfaces.
Aa
Preview
(unavailable)--border-on-actionOn Action
Border/outline on strong action backgrounds (for contrast).
Aa
Preview
(unavailable)--border-whiteWhite
White border role (for high-contrast cases).
Aa
Preview
(unavailable)--border-disabledDisabled
Disabled borders.
Aa
Preview
(unavailable)Static
Non-adaptive colors for specific cases where theme switching must not change the output.
Token
Role
Preview
Resolved
Actions
--static-whiteStatic White
Absolute white (non-adaptive).
Aa
Preview
(unavailable)--static-blackStatic Black
Absolute black (non-adaptive).
Aa
Preview
(unavailable)--static-primaryStatic Primary
Absolute primary (non-adaptive).
Aa
Preview
(unavailable)--static-light-on-darkStatic Light on Dark
Light-on-dark role for static compositions.
Aa
Preview
(unavailable)Utilities
Overlay colors, pattern ink tokens, and utility roles (commonly for backdrops, focus lock, and CSS background patterns).
Token
Role
Preview
Resolved
Actions
--util-overlay-dullOverlay Dull
Dull overlay for subtle dimming.
Aa
Preview
(unavailable)--util-overlay-lightOverlay Light
Light overlay for dimming surfaces.
Aa
Preview
(unavailable)--util-overlay-mediumOverlay Medium
Medium overlay for modals/drawers.
Aa
Preview
(unavailable)--util-overlay-strongOverlay Strong
Strong overlay for focus/attention lock.
Aa
Preview
(unavailable)--util-pattern-ink-1Pattern Ink 1
Primary pattern color for CSS background patterns (strongest opacity).
Aa
Preview
(unavailable)--util-pattern-ink-2Pattern Ink 2
Secondary pattern color for CSS background patterns (medium opacity).
Aa
Preview
(unavailable)--util-pattern-ink-3Pattern Ink 3
Tertiary pattern color for CSS background patterns (light opacity).
Aa
Preview
(unavailable)--util-pattern-ink-4Pattern Ink 4
Quaternary pattern color for CSS background patterns (lightest opacity).
Aa
Preview
(unavailable)Shadows
Shadow color tokens used by effect tokens (e.g., drop shadows).
Token
Role
Preview
Resolved
Actions
--shadow-noneShadow None
Shadow color for no/transparent shadow.
Aa
Preview
(unavailable)--shadow-subtleShadow Subtle
Shadow color for subtle elevation.
Aa
Preview
(unavailable)--shadow-normalShadow Normal
Shadow color for normal elevation.
Aa
Preview
(unavailable)--shadow-mediumShadow Medium
Shadow color for medium elevation.
Aa
Preview
(unavailable)--shadow-strongShadow Strong
Shadow color for strong elevation.
Aa
Preview
(unavailable)Contrast ratio
This section computes contrast in the current theme/hue context and evaluates against WCAG AA (small text).
Contrast is calculated using the WCAG relative luminance formula and evaluated against WCAG 2.1 Level AA standards. 4.5:1 applies to normal text (body text, labels, paragraphs). 3:1 applies to large text (≥18pt regular or ≥14pt bold).
Pairing
Background
Foreground
Ratio
AA (3:1)
AA (4.5:1)
On-action text
Use for primary brand actions (buttons, strong emphasis).
--bg-primary(unavailable)
--fg-on-action(unavailable)
—
—
—
Body text on page
Default reading text on primary page background.
--bg-page-primary(unavailable)
--fg-neutral(unavailable)
—
—
—
Secondary text on page
Metadata/supporting text; verify AA for your font size.
--bg-page-primary(unavailable)
--fg-neutral-secondary(unavailable)
—
—
—
Tertiary text on page
Helper text, quiet labels; may not meet AA for small text.
--bg-page-primary(unavailable)
--fg-neutral-tertiary(unavailable)
—
—
—
Primary link on page
Brand links and accents on primary background.
--bg-page-primary(unavailable)
--fg-primary(unavailable)
—
—
—
Body text on secondary page
Default reading text on secondary page background.
--bg-page-secondary(unavailable)
--fg-neutral(unavailable)
—
—
—
Body text on tertiary page
Default reading text on tertiary page background.
--bg-page-tertiary(unavailable)
--fg-neutral(unavailable)
—
—
—
Primary tonal
Tonal brand surfaces (banners, subtle emphasis).
--bg-primary-tonal(unavailable)
--fg-primary-on-tonal(unavailable)
—
—
—
Success tonal
Tonal success surfaces (banners, callouts).
--bg-success-tonal(unavailable)
--fg-success-on-tonal(unavailable)
—
—
—
Success link on page
Success foreground on primary background.
--bg-page-primary(unavailable)
--fg-success(unavailable)
—
—
—
Warning tonal
Tonal warning surfaces (banners, callouts).
--bg-warning-tonal(unavailable)
--fg-warning-on-tonal(unavailable)
—
—
—
Warning link on page
Warning foreground on primary background.
--bg-page-primary(unavailable)
--fg-warning(unavailable)
—
—
—
Critical tonal
Tonal critical surfaces (banners, callouts).
--bg-critical-tonal(unavailable)
--fg-critical-on-tonal(unavailable)
—
—
—
Critical link on page
Critical foreground on primary background.
--bg-page-primary(unavailable)
--fg-critical(unavailable)
—
—
—
Disabled content
Disabled states should still be readable where required.
--bg-disabled(unavailable)
--fg-on-disabled(unavailable)
—
—
—
Disabled text on page
Disabled text on primary background.
--bg-page-primary(unavailable)
--fg-disabled(unavailable)
—
—
—
On-success action
Text on success action backgrounds (buttons).
--bg-success(unavailable)
--fg-on-action(unavailable)
—
—
—
On-warning action
Text on warning action backgrounds (buttons).
--bg-warning(unavailable)
--fg-on-action(unavailable)
—
—
—
On-critical action
Text on critical action backgrounds (buttons).
--bg-critical(unavailable)
--fg-on-action(unavailable)
—
—
—
On-primary dark
Text on high-contrast brand surfaces.
--bg-primary-dark(unavailable)
--fg-on-action(unavailable)
—
—
—
On-success dark
Text on high-contrast success surfaces.
--bg-success-dark(unavailable)
--fg-on-action(unavailable)
—
—
—
On-warning dark
Text on high-contrast warning surfaces.
--bg-warning-dark(unavailable)
--fg-on-action(unavailable)
—
—
—
On-critical dark
Text on high-contrast critical surfaces.
--bg-critical-dark(unavailable)
--fg-on-action(unavailable)
—
—
—
Usage guidance
Do
- Use role tokens for implementation (
--bg-*,--fg-*,--border-*). - Use paired "on" roles to preserve contrast (e.g.
--fg-on-actionon--bg-primary). - Use state-specific roles (hover/pressed/focus/disabled) instead of manually adjusting colors.
- Verify contrast for text sizes and contexts.
Don't
- Don't hardcode hex values in components.
- Don't pick palette tokens by appearance for UI roles.
- Don't rely on color alone to communicate meaning.
- Don't invent new colors outside the Figma token source.