Tokens

The contract every app inherits

Tokens are the interface between the system and your app. Two tiers, one consumption path. Get these right and a Webzenia app cannot drift off-brand.

Two-tier model

Primitive

Raw values: the full scales (--neutral-975, --blue-600, oklch literals). Never referenced directly by components.

Semantic

What components consume: --color-surface-base, --color-text-strong, --color-accent-fill. Re-points per theme.

css

/* the chain — a component never sees a primitive */
.button        { background: var(--color-accent-fill); }   /* semantic */
--color-accent-fill: var(--blue-600);                       /* → primitive */
--blue-600:    oklch(0.528 0.217 262.236);                  /* raw value */

The laws

Components consume semantics onlyNo primitive refs, no hex/rgb/oklch literals, no raw Tailwind spacing/type utilities in component code. Enforced by audit:system.

Spacing → step tokensvar(--space-step-N) for micro-spacing; semantic layout tokens for structure. Never raw px.

Type → roles<Text role="…"> only. Never inline font-size / weight / leading / tracking.

One brand hue262.236°. Blue is the scarce accent. Spend it on the one thing that must be seen.

Theming

:root is the dark surface. Light values re-point the same semantic tokens under [data-theme="light"]— components don’t change, only the scope does.

tsx

<section data-theme="light"> … </section>   /* a light island inside a dark page */

Gotcha: a light island needs the data-theme="light" attribute, or the <Text> roles resolve to light-on-light and render invisible.

How to consume

One import gives you every token + the generated Tailwind utilities + the fonts.

css

@import "tailwindcss";
@import "@webzenia/tokens/tokens.css";   /* surfaces, text, borders, accents, spacing, type, motion */

Full walkthrough on Adopt. Source of truth: @webzenia/tokens.

Design ↔ code parity

One source feeds both code and Figma. The export parses tokens.css into a W3C design-tokens file; designers import it into Figma variables via Tokens Studio. Change a value once and both sides update — the design file can’t drift from the build.

shell

pnpm tokens:export    # → tokens/design-tokens.json (W3C Design Tokens)

code

"color": { "blue": { "600": {
  "$type": "color",
  "$value": "#1a5de6",
  "$extensions": { "com.webzenia.source": "oklch(0.528 0.217 262.236)" }
} } }

Figma-ready hex, with the oklch source preserved · 72 colours · 27 spacing · 11 radius.