Your design system, checked into the repo —
where your coding agent can actually read it.
npx @logicplanes/specui
·
docs
·
github
SpecUI is a .specui/ folder plus a small CLI. You write down what your UI is allowed to look like — tokens, components, patterns, logos, rules — and specui validate holds everyone to it. Humans and coding agents read the same files before any UI ships.
npx @logicplanes/specui@latest init --name "My Product" --preset web-app
npx specui validate .specui --strict
npx specui get buttonThat's the whole pitch. The contract lives in your repo, the CLI guards it in CI, and your agent reads it before writing UI code. Drift fails the PR before review.
Documentation · Quick start · CLI reference · npm
Two autonomous prompts — one for an existing app, one for a new repo. Neither asks you questions: the agent reads the repo, derives a sensible design system, registers every component it finds, and runs validate --strict until the contract is clean. You review and override afterwards.
Agents can also pre-load the docs at logicplanes.github.io/specui/llms.txt (or /llms-full.txt for one big markdown file) before running either prompt — every page is also reachable as plain markdown at /docs-md/<slug>.
A. Existing app — drop .specui/ into a repo that already exists:
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.
B. New app — design system first, before the first component is written:
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.
Full versions, the new-app variant, and tips at Agent prompts.
Most teams keep design decisions in Figma, Notion, or somebody's head. That works fine until a coding agent — or a new teammate — ships a button with its own border radius and a fourth shade of gray. Nothing in the repo said they couldn't.
SpecUI moves the contract into the repository:
- Register first. Components, tokens, and patterns go into
.specui/before app code. - Validate always.
specui validatechecks structure, links, contrast, and agent files. Run it with--strictin CI and drift fails the PR. - One index.
specui synckeepsmanifests/registry.jsoncurrent so tools and agents see the same list. - Export when needed. The same record becomes Tailwind config, CSS variables, DTCG JSON, or a
DESIGN.md— regenerated, never hand-maintained.
specui init gives you structured markdown and YAML: design principles, TOKENS.yaml, per-component specs with states and variants, patterns, logos and icons, and agent-facing rules. specui get can pull registry components (shadcn included) into the spec, with reference source under vendor/. specui init also wires AGENTS.md, editor rules, an optional MCP server, and a small GitHub Action.
The loop we designed for: define in .specui/ first, implement in your framework, validate before merge.
We use it ourselves — brand/ holds SpecUI's own design contract: the tokens, the logo, and the retro components on the docs site, all registered and validated with the same CLI you just installed.
| If you know… | SpecUI is… |
|---|---|
| shadcn/ui — component source copied into the app | the full spec: tokens, brand, components, logos, and rules in .specui/ |
| DESIGN.md — one agent-facing file | many versioned files with a registry index, validation, and optional MCP |
AGENTS.md — how the agent should behave |
what the UI may look like — components, states, do's and don'ts |
Node 18 or newer. The package is @logicplanes/specui; the command it installs is specui.
npx @logicplanes/specui@latest init # scaffold in the current project
npm install -g @logicplanes/specui # optional global CLIcd your-app
npx @logicplanes/specui@latest init \
--name "Acme" \
--preset web-app \
--agents-md \
--ci github
specui doctor
specui add component primary-button --variants default,destructive
specui validate .specui --strict && specui syncPull a registry component into the spec when you want one:
specui get buttonGate CI on the spec:
- run: npx -y @logicplanes/specui@latest validate .specui --strictThe full documentation — install options, nine worked scenarios, agent wiring, CI recipes, and a complete CLI reference — lives at logicplanes.github.io/specui/docs.
| If you want to… | Read this |
|---|---|
| See all the commands and flags | CLI reference |
| Pick a workflow (monorepo, design-system repo, shadcn, agents) | Scenarios |
| Wire Cursor, Claude, or MCP | Agents & MCP |
| Fail PRs when the spec breaks | CI/CD |
| Export to Tailwind, CSS, DTCG, DESIGN.md | Interop |
| Prompts to hand your coding agent | Agent prompts |
Contributions welcome — see CONTRIBUTING.md or open an issue. MIT licensed.