designmd

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 .specui

From 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

1. Register and document in .specui/ (add, numbered docs, TOKENS.yaml)
2. specui validate .specui --strict in CI
3. Optional build step: specui export --format designmd --to DESIGN.md
4. Point legacy agent prompts at DESIGN.md while 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
• Concepts
• FAQ — DESIGN.md