Foundations

Foundations are the layer below components. Before helix-ui has a Button, it has a blue, a 16px unit, an 8px corner, and a 180ms transition. These pages explain those decisions: what the values are, why they were picked, and when to use which.

One rule: tokens are the only style source

Every visual property in helix-ui resolves to a design token. There is no hex code, px value, or bezier curve written directly into component CSS — if a value is missing, we add a token, we don’t inline a literal. This is enforced by convention and by lint (@helix-ui/stylelint-plugin-helix-ui).

The tokens live in three layers:

primitive        →   semantic            →   component CSS
core.json            semantic.light.json     button.css
(brand.600,          semantic.dark.json      (uses color.bg.action.brand.default,
 space.4, …)         (bg.action.brand…)       never brand.600 directly)

• Primitives are raw values: color ramps, the spacing scale, radii, font sizes.
• Semantics are intents: “brand action background, hover state.” They alias primitives.
• Components consume semantics only. Dark mode is just the semantic layer re-aliasing the same names to different primitives — components never change.

In CSS, every token is a custom property prefixed --helix-ui-:

.my-panel {
  background: var(--helix-ui-color-bg-surface-subtle);
  padding: var(--helix-ui-space-6);
  border-radius: var(--helix-ui-radius-lg);
}

This guide is narrative — it tells you which token to reach for and why. The machine-readable reference (DTCG schema, build outputs, naming grammar) lives in Tokens.

What’s in this section

Page	Covers
Color	The five ramps, semantic roles, light/dark mapping, and the WCAG AA contrast pairs we measure on every build.
Typography	The Inter-first stack, CJK fallback strategy, the 8-step size scale, weights, and line-height rules.
Spacing	The 4px-grid space scale, the density gene, and how Box / Stack numeric props map to tokens.
Elevation, radius & motion	Corner radii, the three shadow levels, motion durations and easings, and reduced-motion behavior.

Foundations can move — via DNA

helix-ui’s theme engine (DNA) compresses these foundations into 8 genes: accent, chroma, lightness, radius, density, typography, surface, motion. Changing a gene re-derives the affected token values deterministically — density: compact shrinks the whole spacing scale, radius: rounded scales every corner. The values documented in this section are the wildtype preset: accent=blue, chroma=standard, radius=standard, density=comfortable, typography=sans, surface=elevated, motion=standard.

Because components only ever reference token names, none of them need to know a gene changed.