DESIGN.md bridge
Keep SpecUI as the source of truth and export DESIGN.md for tools that expect it.
DESIGN.md is a single-file pattern for telling coding agents how UI should look. SpecUI is a multi-file, validated contract in .specui/. They coexist happily as long as one rule holds: SpecUI stays canonical, and DESIGN.md is an export.
When to use which
| Approach | Best for |
|---|---|
| SpecUI only | Teams + CI + registry + multi-platform specs |
| DESIGN.md only | The smallest possible agent doc, no CLI |
| SpecUI → DESIGN.md | Agents/tools that only read DESIGN.md; SpecUI still gates in CI |
Export
From an app with .specui/:
npx specui export --format designmd --to ./DESIGN.md --from .specuiFrom a flat design-system repo:
npx specui export --format designmd --to ./DESIGN.md --from .Re-run after every contract change. Whatever you do, don't start hand-editing the exported DESIGN.md — that's how you end up with two conflicting sources of truth.
Workflow
- Register and document in
.specui/(add, numbered docs,TOKENS.yaml) specui validate .specui --strictin CI- Optional build step:
specui export --format designmd --to DESIGN.md - Point legacy agent prompts at
DESIGN.mdwhile you migrate them to.specui/+AGENTS.md
What the export includes
A DESIGN.md-oriented summary derived from SpecUI front matter and the token/component index. It's enough for an agent to orient itself, but it doesn't replace the per-component SPEC.md / STATES.md files in .specui/.
For the full agent protocol, use .specui/AGENT-DESIGN-RULES.md and AGENTS.md.
Compare with specui spec
Easy to mix these up:
| Command | Output |
|---|---|
specui spec | The normative SpecUI standard (tooling contract) |
specui export --format designmd | Your product’s design summary for DESIGN.md consumers |
Next steps
Interop
Export SpecUI to DESIGN.md, DTCG, Tailwind, CSS, and JSON — and compare versions.
Validation
What specui validate checks, strict mode, JSON output, and the doctor command.