Tokens & components

Registry-first means you run specui add before you write UI in React, Vue, SwiftUI, or anything else. It sounds bureaucratic; in practice it's the only thing that keeps the spec and the code from drifting apart. This guide covers every add kind and how they connect to TOKENS.yaml and manifests/registry.json.

Prerequisites

• A .specui/ from Quick start or specui init
• A shell at the project root (the parent of .specui/), or pass --specui <path>

Components

Create

npx specui add component primary-button \
  --variants default,destructive,outline \
  --states default,hover,focus,disabled,loading

This creates:

.specui/components/primary-button/
  MANIFEST.yaml
  SPEC.md
  VARIANTS.md
  STATES.md

Names must be kebab-case. If you omit --states, you get the canonical default set.

Fill in before coding

1. SPEC.md — behavior, anatomy, accessibility
2. VARIANTS.md — the variant matrix
3. STATES.md — every interactive state (required for parity across platforms)
4. MANIFEST.yaml — syncTargets notes per platform (web, ios, …)

Vendor reference (optional)

npx specui get button --force

Adds a vendor/ folder under the component — see Registries.

Tokens

Add semantic tokens

npx specui add token color.brand.primary "#f54e00" --theme light
npx specui add token color.brand.primary "#ff6b2c" --theme dark
npx specui add token space.section.md "24px"

Paths must be semantic (color.text.primary, not raw hex names). Themed colors use --theme.

Edit TOKENS.yaml

add token merges into .specui/TOKENS.yaml. Editing the YAML by hand is fine too — just validate afterwards:

npx specui validate .specui --strict

Contrast checks run unless you pass --no-contrast. Document token roles in 02-foundations-tokens.md.

Export to code

npx specui export --format css --theme light --to ./src/specui.css --from .specui
npx specui export --format tailwind --theme light --to ./specui.theme.js --from .specui

More formats in Interop.

Assets

Four types: icon, illustration, photo, logo.

npx specui add asset logo acme-mark \
  --sizes 16,24,32 \
  --modes color,mono \
  --link component:brand-mark

Register assets before code references them. Link each one to a component, or document it as unassigned in the manifest.

Patterns

Patterns describe multi-step UX — confirmations, empty states, validation flows:

npx specui add pattern destructive-confirmation
npx specui add pattern empty-state

Edit .specui/patterns/<name>.md using the template from AGENT-DESIGN-RULES.md.

After every add

npx specui sync
npx specui validate .specui --strict
npx specui list components

Commit .specui/ together with the application code that implements the registration — one PR, one story.

Required by preset

SPEC.md lists componentsRequired and patternsRequired from your --preset. validate fails until those folders exist — either add them, or adjust the front matter to match reality.

Flat design-system repo

From the repo root where SPEC.md lives:

npx specui add component chip --variants default
npx specui validate .

Same add commands; path resolution uses the flat layout when SPEC.md is at the root.

Next steps

• Validation
• Agents & MCP — agents must not skip registration
• CLI — add