Home

SpecUI is a design system that lives in your repository: a .specui/ folder holding tokens, components, patterns, assets, and rules, plus a specui CLI to scaffold it, keep it valid, pull registry components, export to Tailwind/CSS, and wire coding agents through AGENTS.md, rules, skills, and MCP.

Package: @logicplanes/specui · CLI: specui · Docs: logicplanes.github.io/specui

New here? Install → Quick start. Full sitemap: Documentation overview. Short answers: FAQ.

---

What problem SpecUI solves

Most teams keep design in Figma, Notion, or scattered markdown. That works fine for humans, less so for agents and CI — nothing can reliably enforce "use our button" or "no random hex colors" when the source of truth lives outside the repo. SpecUI moves that source of truth into the repository:

1. Register components, tokens, and patterns in .specui/ before app code exists.
2. Validate structure, links, contrast, and agent files with specui validate.
3. Sync manifests/registry.json so tooling and agents query one index.
4. Export the same contract to Tailwind, CSS, DTCG, or DESIGN.md when other tools need it.

There is no separate checklist file — the numbered docs and the registry are the system. CI gates on specui validate --strict.

---

How SpecUI compares

You know	SpecUI is
shadcn/ui	A full spec (brand, tokens, patterns, rules), not only copied React source
DESIGN.md	Multi-file, versionable, registry-first, with validation and MCP
AGENTS.md (behavior)	Plus what the UI may look like — components, states, do's and don'ts in .specui/

---

Two layouts

Layout	When	Root
Consumer	App or product repo	.specui/ + project AGENTS.md
Flat	Publishable design-system repo	SPEC.md at repo root (specui new)

Installed foreign trees are tracked in .specui-sources.yml at the project root (not inside .specui/).

---

Documentation map

The site follows a learn → do → look up structure (in the spirit of Stripe, Vercel, and Diátaxis-style docs):

Section	Pages	You will…
Getting started	Install, Quick start, Concepts, FAQ	Install the CLI, scaffold in minutes, learn the mental model
How-to guides	Scenarios, Tokens & components, Agents & MCP, CI/CD, Distribution, Registries, Interop, DESIGN.md bridge, Validation, Troubleshooting	Complete real tasks end-to-end
Reference	CLI, init flags, Schema, Specification	Look up commands, files, and normative rules
Community	Contributing	Contribute to the open-source project

Complete page list: Documentation overview.

---

The core loop (every project)

# 1) Scaffold (once)
npx @logicplanes/specui@latest init --name "My Product" --preset web-app

# 2) Register before code
npx specui add component primary-button --variants default,destructive

# 3) Gate + index
npx specui validate .specui --strict && npx specui sync

Optional: specui get button (registry), specui export --format tailwind, specui mcp install-hook cursor.

---

Next steps

• New to SpecUI → Install then Quick start
• Pick your situation → Scenarios (web app, mobile, monorepo, design-system team, agents-only)
• Automate in CI → CI/CD
• Full command list → CLI reference