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 23 genes across colour, typography, shape, space and 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.

The genome is not the whole story. DNA.platform — deliberately not a gene, because it is not inherited — decides which operating system’s conventions the theme is expressed under: focus ring geometry, the minimum hit target, where dark mode anchors, how fast motion runs. It defaults to auto, so the foundations below already adapt to the device you are reading them on.

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