Design System

Token layers

Primitive tokens describe raw values such as color, spacing, typography, motion, and radius. Semantic tokens translate those values into product roles such as background, foreground, primary, border, and ring.

Components should consume semantic variables first. Raw primitives are useful for documentation, theme construction, and controlled escape hatches, but they should not become the default component API.

primitive tokens -> semantic tokens -> component styles -> docs and consuming apps

Component anatomy

Every component registry manifest owns an anatomy list. That keeps implementation, docs, accessibility review, and future visual tooling aligned around the same named parts.

Anatomy should describe stable composition slots, not incidental markup. If a part is named in the registry, it should be meaningful for docs, tests, and future component review.

States

Interactive components should define hover, focus-visible, disabled, invalid, and loading states through shared tokens where possible. This keeps state styling consistent as the component set grows.

The baseline exposes focus ring and disabled opacity variables, plus motion duration and easing variables for predictable interaction timing.

--focus-ring-width: 2px;
--disabled-opacity: 0.5;
--duration-fast: 120ms;
--ease-standard: cubic-bezier(0.2, 0, 0, 1);

Accessibility contract

Accessibility metadata lives in the registry so it can be shown in docs, validated by tests, and used by CLI or future review tooling.

The metadata does not replace behavior tests. It makes the expected behavior explicit before implementation details spread across components, examples, and prose.

• Use native semantics where practical
• Expose visible focus styles for keyboard users
• Keep foreground and background pairs contrast-aware
• Document screen reader expectations for non-obvious patterns