Skip to the content

Semantic & Foundation Tokens

A theme exposes its colors in layers, each for a different audience. Product code names intent — danger, surface.paper, ink.secondary — and never a hex value, so a rebrand, a mode switch or an accessibility preset changes the output without touching the screen.
Theming

The rule

Layer
Who reads it
Example
Token props in JSX
product screens
color="danger", bgColor="surface.paper"
Foundation (theme.foundation.*)
product styled code
theme.foundation.bg.primary
Semantic (theme.semantic.*)
design-system components
theme.semantic.color.feedback.danger.bg
Scrolls sideways inside the table. The page does not.

Stay in the first two layers for product work. Reach for Semantic only when you build a component in the design system's own pattern.

How it works

Component props take token names that the theme resolves: the palettes (primary, danger, main, …, with steps such as danger.dark) and the surface ladder (surface.*, ink.*, edge.*, wash.*). The same JSX renders correctly in every mode and preset:

color="primary"
color="danger"
bgColor="surface.sunken"

In styled code, read Foundation: bg.* (primary, danger, brand, canvas, paper, …), text.* (onPrimary, onDanger, primary, muted, …) and edge.* (hairline, border, strong).

import styled from 'styled-components';

const Banner = styled.div`
  background: ${({ theme }) => theme.foundation.bg.danger};
  color: ${({ theme }) => theme.foundation.text.onDanger};
  border-bottom: 1px solid ${({ theme }) => theme.foundation.edge.border};
`;

Foundation aliases are views over Semantic, so a negative surface re-resolves them for its subtree.

Pitfalls

  • color="#E12712" for an error message → color="danger"; a literal skips the mode, preset and contrast guarantees.
  • if (isDark) branches in product code → name the token; the theme resolves it per mode.
  • Pointing at a palette step for a one-off → prefer an existing Foundation alias, and ask for a new one when none fits.

See also