Every design decision, named once.

Tokens as a Contract

Every token is authored as data, not CSS, in the W3C Design Tokens Community Group format: a JSON object with a reserved $value and a $type like color or dimension. One authored decision publishes to CSS, TypeScript, and native from the same source. The JSON is the contract, and everything downstream honors it. It runs in two tiers.

Style Dictionary reads that JSON, resolves the aliases, and formats each target. The CSS output is a flat block of custom properties on :root, a parallel TypeScript output exposes the same values as typed constants. Both carry a do-not-edit banner: they are build output, not source.

Tier 1: Primitive Palette

The raw material. These ramps are Tailwind CSS's open-source (MIT) default palette, adopted hex-for-hex as the primitive layer; what this system owns sits on top, the mono-indigo constraint and the semantic mapping. Indigo is the brand ramp and the single action accent of the whole system. Slate carries text, surfaces, and borders. The four status ramps, emerald and green for success, amber for warning, red for error, blue for info, feed the feedback tokens. Violet backs the secondary role, a decorative accent only, never for action. Click any shade to copy its variable.

Tier 2: Semantic Color

The layer product code consumes. Each token names a role and aliases a primitive. Build with these, never with raw palette shades, so a theme change stays a one-line edit at the alias.

Spacing Scale

A single scale for margin, padding, and gap. One --space-* step in, one step out, so rhythm stays consistent across every component.

Shadow and Elevation

Three elevation levels plus a focus ring. Each level is two soft, indigo-tinted layers rather than one hard black drop. Shadow means height, never state. See Foundations / Shadows for the full rationale.

Typography

Three families, eight weights, a ten-step size scale, and the line-height and letter-spacing tokens that pair with them. Rubik carries UI and body, Red Hat Display carries headings.

Taxonomy Rules

Three rules keep the system coherent: how to consume a token, how to name a new one, and how a change reaches the screen.

How to consume a token

Reference the variable, never the literal. Reach for the semantic tier first, because it carries the meaning and stays stable across themes. Drop to a primitive only when no semantic token fits, and if you find yourself wanting a raw hex, that is the signal a semantic token is missing, not that you should hardcode.

/* Yes: reference the semantic token */
.card {
    background: var(--color-surface);
    color: var(--color-text-body);
    border-radius: var(--radius-lg);
    box-shadow: var(--shadow-sm);
}

/* No: a hardcoded value drifts from the system on the next theme change */
.card {
    background: #ffffff;
    border-radius: 12px;
}

How to name a new token

How a change propagates

A change starts in the JSON and ends on the screen without a single manual edit downstream. Edit the $value in packages/tokens/src/tokens/, run the Style Dictionary build, and the generated tokens.css and tokens.ts update together. Because every consumer references the variable, the new value reaches every product surface at once. Never edit the generated files: they carry a do-not-edit banner and the next build overwrites them.

Sources

• Design Tokens Community Group, format specification. The open standard, developed under the W3C, that defines a token as a JSON object with a reserved $value and $type, and the alias syntax the semantic tier relies on. design-tokens.org and tr.designtokens.org/format
• Style Dictionary. The build tool that reads the token source, resolves aliases, applies transforms, and formats the CSS and TypeScript outputs this system ships. styledictionary.com
• Salesforce, primitive and semantic token tiers. The two-tier model, raw primitive values referenced by role-named semantic aliases, popularized for design systems at scale.
• Every token name, value, and description in this page is quoted from this system's source JSON and generated CSS. SPA The elevation ceiling and the pill-as-accent-only rule are house rules specific to this system.