Quick start

This tutorial assumes a consumer app repo (a .specui/ folder inside your app). If you're building a publishable design-system repo, see Scenarios — flat repo instead.

Prerequisites

• Install — Node 18+, npx or global specui
• A git repo (recommended) at your app root

Step 1 — Scaffold .specui/

From your application root:

cd your-app-repo

npx @logicplanes/specui@latest init \
  --name "Acme" \
  --preset web-app \
  --agents-md \
  --agent-tools cursor \
  --ci github

What this creates:

Want to see what would happen without writing anything? Dry-run it:

npx specui init --dry-run --preset blank --target /tmp/preview

Step 2 — Health check

npx specui doctor
npx specui validate .specui

doctor prints layout, AGENTS.md status, counts, and runs validate. Fix any errors before continuing — they only get harder to untangle later.

Step 3 — Register before code

This is the core habit: add a component before implementing it in React/Vue/etc., so the contract leads and the code follows.

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

Add a semantic token:

npx specui add token color.brand.primary "#f54e00" --theme light
npx specui add token color.brand.primary "#ff6b2c" --theme dark

Add a flow pattern (pick a name the preset doesn't already ship — specui list patterns shows what's there):

npx specui add pattern onboarding-checklist

Rebuild the registry index:

npx specui sync
npx specui list all

Step 4 — Strict validate (CI-style)

npx specui validate .specui --strict

A fresh init will show state-row-empty warnings from the preset's placeholder STATES.md files — these are expected. Fix them as you fill in each component, or run without --strict until you do.

Use --strict in GitHub Actions so warnings (contrast, placeholders) fail the build. See CI/CD.

Step 5 — Optional: registry components

Pull shadcn reference files into the spec. Pick a component the web-app preset doesn't already ship (the preset includes button, card, dialog, etc., so get button would error with "Component already exists" — specui list components shows what's already there):

npx specui get --list
npx specui get carousel
npx specui validate .specui && npx specui sync

Details: Registries.

Step 6 — Implement UI in your app

1. Read .specui/components/primary-button/ and TOKENS.yaml
2. Map tokens to your stack (CSS vars, Tailwind theme, etc.) — or use specui export
3. After code changes that touch design: run validate + sync again
4. Commit .specui/ and code in the same commit

Agent protocol: Agents & MCP.

What you learned

• init scaffolds the contract and agent wiring
• add registers design artifacts
• validate + sync keep the registry honest
• get optionally vendors registry implementations

Next steps

• Concepts — deeper mental model
• Scenarios — monorepo, flat DS, exports
• CLI reference — every command
• Troubleshooting — when validate fails