~/your-app/.specui
Your design system, checked into the repo.
Where your agent can actually read it.
SpecUI is a .specui/ folder and a small CLI. You write down what your UI is allowed to look like — then specui validate holds everyone to it, humans and coding agents alike.
Hand it to your agent.
Two autonomous prompts. No questions, no back-and-forth — the agent reads the repo, derives a design system, registers everything it finds, and runs validate --strict until the contract is clean. You review afterwards.
A. existing app
Install SpecUI (a .specui/ design contract + CLI) into this repo and build out the design system autonomously, without asking me any questions. Steps: (1) detect the framework from package.json and pick the closest preset (web-app, mobile-app, marketing-site, dashboard-data-dense, or design-system-library); (2) run `npx @logicplanes/specui@latest init --name "My Product" --preset <chosen> --agents-md --agent-tools cursor --ci github`; (3) run `specui doctor` and report the result; (4) scan the existing code under src/, app/, components/, or wherever the UI lives, infer the brand voice and accent color from existing styles, then fill in .specui/01-brand-and-product.md, .specui/02-foundations-tokens.md, and .specui/TOKENS.yaml with a complete token set (color, type, spacing, radius, shadow, motion) for light and dark themes; (5) for every UI component the app already ships, run `specui add component <name> --variants <…> --states <…>` and fill in each .specui/components/<name>/SPEC.md, STATES.md, VARIANTS.md from the actual implementation; (6) add any missing semantic tokens with `specui add token <path> <value> --theme light` (and `--theme dark`); (7) `specui sync` then `specui validate .specui --strict` — fix every finding and re-run until it prints "SpecUI valid — no findings." (8) Print a short summary of what you created, the token set, and the component list. From now on, never write or modify UI code without first registering the component in .specui/, always run `specui validate .specui --strict` before considering any UI task done, add missing tokens with `specui add token` before using them in code, and keep .specui/ and the implementing code in the same commit.
annotated version: /docs/agent-prompts
B. new app
We are starting a brand-new application from scratch and the design system comes first. Build it autonomously, without asking me any questions, before any UI code is written. Steps: (1) scaffold the framework (Next.js + Tailwind, Vite + CSS modules, React Native, …) into ./my-product, cd in, git init; (2) run `npx @logicplanes/specui@latest init --name "My Product" --preset web-app --agents-md --agent-tools cursor --ci github`; (3) run `specui doctor` and report the result; (4) choose a coherent brand voice, accent color, typography stack, and density, then fill in .specui/01-brand-and-product.md, .specui/02-foundations-tokens.md, and .specui/TOKENS.yaml with a complete token set (color, type, spacing, radius, shadow, motion) for light and dark themes; (5) define the first three to five components we will actually need (e.g. button, input, dialog, card, navigation) — for each run `specui add component <name> --variants <…> --states <…>` and fill in .specui/components/<name>/SPEC.md, STATES.md, VARIANTS.md; (6) define one or two flow patterns (e.g. onboarding, destructive-confirmation) with `specui add pattern <name>` and fill them in; (7) `specui sync` then `specui validate .specui --strict` — fix every finding and re-run until it prints "SpecUI valid — no findings." (8) export tokens for the framework: `specui export --format tailwind` (or css/dtcg/json) and wire them into the framework config so code reads from the same source of truth; (9) commit .specui/, the framework scaffold, and the wiring in a single first commit. Print a short summary of what you created, the token set, and the component list. From now on, never write or modify UI code without first registering the component in .specui/, always run `specui validate .specui --strict` before considering any UI task done, add missing tokens with `specui add token` before using them in code, keep .specui/ and the implementing code in the same commit, and suggest a `specui add component` whenever I describe a UI feature that needs a new piece.
annotated version: /docs/agent-prompts
an agent session, supervised by the spec
$ specui validate .specui --strict
ok tokens · 42 checked
ok components · button, input, dialog
ok contrast · all pairs pass
$ specui get button
installed → .specui/components/button
$ specui export --format tailwind
wrote tailwind.tokens.css01
One folder, one truth
Tokens, components, patterns, logos, and rules live in .specui/ — versioned next to your code, readable by humans and greppable by agents.
02
A CLI that keeps it honest
init scaffolds it, validate gates it, get pulls registry components in, export turns it into Tailwind, CSS variables, or DTCG JSON.
03
Agents behave
AGENTS.md wiring, rules, skills, and an MCP server mean your coding agent reads the spec before it invents a fourth shade of gray.
Five minutes, honestly.
One command scaffolds the folder, wires AGENTS.md, and drops a CI check. The second one tells you if anything drifts.
npx @logicplanes/specui@latest init --name "My Product" --preset web-app
specui validate .specui --strict