Skip to content

quick start

Jump to bottom
github-actions[bot] edited this page Jul 4, 2026 · 3 revisions

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:

Output Purpose
.specui/ Full contract (SPEC, tokens, numbered docs, manifests)
AGENTS.md SpecUI block for coding agents
.cursor/rules/specui.mdc Cursor rule (when --agent-tools cursor)
.github/workflows/specui.yml CI validate job (when --ci github)

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

Getting started

How-to guides

Reference

Community

Clone this wiki locally