Design Tokens

Tokens are the executable contract for visual identity. If a value changes the product's look or feel, it should be named, typed, compiled, and consumed through a stable variable.

Design Position

Design tokens are how Kevin prevents agent-authored UI from becoming scattered class soup. They move design decisions out of individual components and into a system an agent can edit, diff, validate, and reuse.

Philosophy

Tokenize anything that carries identity or repeatable interaction behavior:

• color, including surface, text, border, state, and accent roles
• spacing and layout rhythm
• radii and border widths
• typography, weights, line heights, tracking, and mono rules
• shadows, glows, blur, and elevation
• z-index layers
• motion duration, easing, spring constants, delay, and reduced-motion fallbacks
• component-specific dimensions only when a component truly needs its own semantic slot

The failure mode is not "too many tokens." The failure mode is meaningless tokens. A token should explain intent, not merely wrap a literal.

Preferred Transport Layer

Default stack:

1. A human/agent-editable source file (DESIGN.md in Sigil-style systems).
2. Typed token model in TypeScript.
3. CSS custom properties at runtime.
4. Tailwind CSS v4 @theme for utility access.
5. W3C design-token JSON for interchange.

Tailwind v4 is useful because the theme is CSS-first: values become runtime variables that can feed CSS, React, Motion, shaders, canvas, and inline styles without translation glue.

The Design Tokens Community Group format is the closest thing to a cross-tool interchange target: tokens have names, values, types, groups, and references so design tools, codegen, and registries can exchange intent instead of only pixels. Use it as an export format, not as an excuse to make the authored source unreadable. Source: DTCG Format Module, https://www.designtokens.org/TR/2025.10/format/, 2026-06-19

Three-Layer Architecture

Semantic tokens are the heart of the system. Components should usually consume semantic tokens. Primitive tokens should rarely appear directly in application code.

Sigil as the Current Reference

Sigil UI is the strongest local implementation:

• DESIGN.md is the agent-editable source of truth.
• 519 tokens across 33 categories compile to CSS variables, Tailwind v4 @theme, W3C JSON, and TS.
• 46 presets swap identity as a unit.
• 350+ components consume var(--s-*) values.
• Doctors validate preset completeness, TypeScript guarantees, WCAG AA contrast, component conventions, and design-system rules.

This is the target pattern for new agent-first UI systems: edit the spec, compile tokens, let components inherit, then run doctors.

Color Rules

• Build the neutral ladder first.
• Use OKLCH for authored palettes and semantic lightness control.
• Keep at most three active colors plus neutrals.
• Reserve the loudest accent for actions, status, or a deliberate motif.
• Give gradients a material role; do not use them as empty atmosphere.
• Validate contrast in both light and dark modes.

Near-black palettes should come from Deep Black Palette or a project token, not raw #000. State colors need semantic variants: foreground, background, border, and muted.

Spacing, Radius, and Layout Tokens

Use 4px granularity internally and 8px rhythm for page layout. Tokenize repeated dimensions: toolbar height, sidebar width, rail gap, content max width, card padding, grid cell, and touch target size.

Radius should be a family, not a roulette wheel. Define the outer/inner relationship for nested components so surfaces look optically related.

Motion Tokens

Motion belongs in tokens when it repeats:

• duration.instant, duration.fast, duration.normal, duration.slow
• ease.out, ease.in, ease.spring
• spring.snappy, spring.gentle
• delay.stagger

Do not hide complex choreography in a token. Tokens name reusable timing; animation code still owns sequencing.

Enforcement

Hardcoded values should fail review when they represent system identity. Acceptable exceptions: one-off mathematical layout (calc()), browser fallback, external embed constraints, or truly local measurement after the value has no design meaning.

Check for:

• hex/rgb literals in components
• arbitrary spacing like 37px
• unscoped z-index values
• hardcoded shadows
• font-family literals outside the global/theme layer
• magic transition durations
• components bypassing semantic tokens to hit primitives directly

Agent Usage

When asked to "make it look better," agents should first inspect or create the token layer. Editing 40 components individually is usually the wrong move. The correct move is often one token or preset change plus a browser verification pass.

Registry implication

Design tokens are the source side of Source-Code Registry Pattern. A component registry without tokens installs shapes but not identity. A token registry without components installs vocabulary but not behavior. The useful package is both: source components consuming semantic tokens, with verification that the two stay aligned.

Tokens also participate in Performance Budgets: variable fonts, shadows, blur, animation timing, and dark-mode palettes can all add weight or frame cost. The design system owns those tradeoffs before they leak into components.

---

Timeline

• 2026-07-01 | Design category refresh added this page to the Identity, tokens, and visual grammar family, linked it to Design System Map, and kept it standalone because Design Tokens owns a distinct design decision surface in this family. Source: User request, 2026-07-01
• 2026-06-19 | Added DTCG interchange context plus registry/performance implications for tokenized design systems. Source: whole-wiki concept review, 2026-06-19; DTCG format spec
• 2026-06-18 | Rewrote around the current Sigil-style token pipeline, three-layer architecture, Tailwind v4 transport, enforcement checks, and agent usage rules. Source: User request, 2026-06-18; Sigil Token Architecture; Sigil UI