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.