Specification
The normative SpecUI standard — purpose, layouts, agent protocol, validation.
At its core, SpecUI is an agent-enforced design contract for software products: tech-agnostic, multi-file, registry-first, validated in CI.
Schema id: specui (schema: specui in SPEC.md front matter)
Tooling: @logicplanes/specui CLI + optional MCP
The full normative text lives in the repository: docs/SPEC.md.
Print it locally: specui spec · specui spec --json
Purpose
| Property | Meaning |
|---|---|
| Tech-agnostic | Web, mobile, desktop — same contract |
| Versionable | Git-friendly markdown + YAML |
| Registry-first | Components/assets registered before code |
| Agent-native | AGENTS.md, rules, skills, MCP share human gates |
SpecUI interoperates with DESIGN.md via export --format designmd, but nothing replaces .specui/ as the source of truth.
Layouts
| Layout | Root | Create |
|---|---|---|
| Consumer | .specui/ + AGENTS.md | specui init |
| Flat | SPEC.md at repo root | specui new |
Installed sources are tracked in .specui-sources.yml at the project root.
Required artifacts
See Schema for the full list. In short:
- Numbered
00–11,TOKENS.yaml,DOS-DONTs.md AGENT-DESIGN-RULES.md,AGENTS-GUIDE.mdcomponents/,assets/,patterns/manifests/registry.json(viasync)
There's deliberately no separate checklist file — the content is the system.
Registry
| Kind | Path |
|---|---|
| Components | .specui/components/<kebab>/ |
| Patterns | .specui/patterns/<kebab>.md |
| Assets | .specui/assets/<type>/<kebab>/ |
| Tokens | TOKENS.yaml — semantic layer |
| Index | manifests/registry.json |
Agent protocol (required)
- Read the project root
AGENTS.md(SpecUI block fromspecui init) - Read
.specui/SPEC.md→readOrder→DOS-DONTs.mdand the relevant numbered docs - Read
.specui/AGENTS-GUIDE.md(CLI) and.specui/AGENT-DESIGN-RULES.md(sync protocol) - Register design before code:
specui add component|asset|token|pattern - After changes:
specui validate && specui sync - Commit
.specui/with the code that realizes it
Details: Agents & MCP.
Validation
specui validate reports error | warn | info:
- Missing files, registry integrity, catalog drift
- Optional WCAG contrast on tokens
AGENTS.mdblock freshness
--strict promotes warnings to errors — use it in CI. See Validation.
Distribution & interop
- load / link / update — consume design systems
- get — registry components (shadcn, JSON URLs)
- export — Tailwind, CSS, DTCG, DESIGN.md, JSON
Distribution · Registries · Interop
Licensing & attribution
Every consumer .specui/ includes COPYRIGHT and LICENSE-SPECUI.md. Preserve the Logicplanes (logicplanes.com) / specui attribution in SPEC.md and the AGENTS.md block — it's part of the license terms, not decoration.
Next steps
- Concepts — tutorial-style mental model
- Quick start — hands-on
- CLI reference
Schema
Required files and folders in .specui/ — the reference both humans and validate use.
Contributing
Contributing to the open-source specui CLI, and documenting your own SpecUI project.