FAQ

Short answers, with links to the longer ones.

What is SpecUI?

A versioned design contract in your repo (.specui/) plus a CLI to scaffold it, validate it, sync a registry index, pull shadcn items, export tokens, and wire coding agents. See Introduction.

How is SpecUI different from shadcn/ui?

shadcn copies component source into your app. SpecUI holds the full spec (tokens, brand, patterns, rules, manifests) and can vendor shadcn files under .specui/components/.../vendor/ via specui get. See Registries and Scenarios — shadcn.

How is SpecUI different from DESIGN.md?

DESIGN.md is typically one file for agents. SpecUI is many files, CI-validated, with a registry. You can export to DESIGN.md: specui export --format designmd. See DESIGN.md bridge.

What do I install?

Only the npm package @logicplanes/specui. It provides the specui command. Your project gets .specui/ when you run specui init. Install.

Do I need a global install?

No. npx @logicplanes/specui@latest <command> is enough. Global install is just a convenience.

What is .specui/ vs specui new?

Concepts.

What must agents read?

1. Root AGENTS.md (SpecUI block)
2. .specui/AGENTS-GUIDE.md, AGENT-DESIGN-RULES.md, SPEC.md / readOrder

Agents & MCP.

What runs in CI?

npx specui validate .specui --strict

Optional: sync + diff on registry.json. CI/CD.

Why did validate fail?

Common causes: a required component missing from the preset, a stale AGENTS.md block, broken registry links, or contrast warnings under --strict. Troubleshooting · Validation.

Can I use SpecUI offline?

init, add, validate, sync, and export all work offline. specui get needs network unless you use file:// JSON. Install — offline.

Where is the full command list?

CLI reference, or specui --help in the terminal.

How do I contribute to the SpecUI project?

Contributing — edit wiki/, run tests, PR to dev.

Docs 404 on GitHub Pages?

Use https://logicplanes.github.io/specui/docs/ (not /specui/specui/docs). Troubleshooting.

Next steps

Documentation overview · Scenarios