interop

The SpecUI contract in .specui/ (or a flat repo) is canonical. Everything else — Tailwind config, CSS variables, DESIGN.md — is an export. Regenerate exports whenever the contract changes, and never let one of them drift into being treated as the source of truth. That way lies sadness.

---

Export commands

From the project root (adjust --from to taste):

npx specui export --format designmd --to ./DESIGN.md --from .specui
npx specui export --format dtcg --theme light --to ./tokens.dtcg.json --from .specui
npx specui export --format tailwind --theme light --to ./specui.tailwind.js --from .specui
npx specui export --format css --theme light --to ./src/specui-tokens.css --from .specui
npx specui export --format json --to ./specui-tokens.json --from .specui

Archive layouts:

npx specui export --format tarball --to ./backup.tgz --from .specui
npx specui export --format dir --to ./snapshot --from .specui

Flat design-system repo:

npx specui export --format tailwind --theme light --to ./tw.js --from .

---

Format guide

Format	Best for
designmd	Tools/agents that read DESIGN.md
dtcg	Design Tokens Community Group pipelines, Style Dictionary
tailwind	theme.extend module for Tailwind v3+
css	Variables such as --specui-color-text-primary
json	Scripts, custom tooling, MCP
tarball / dir	Backup, import, migration

Themed exports (dtcg, tailwind, css) take --theme light|dark|…, resolved from TOKENS.yaml.

---

Import back

npx specui import ./backup.tgz --force
npx specui import ./snapshot-dir --force

Reach for import when restoring or cloning a contract — not for day-to-day token edits. For those, edit TOKENS.yaml directly.

---

Compare two contracts

npx specui diff --from ./acme-ds --to ./my-app/.specui
npx specui diff --from ./v1.0 --to ./v2.0 --json

You get token-level added/changed/removed — handy before running update or upgrading a design system.

---

Refresh a consumed design system

When apps use load / link:

npx specui update --name acme
npx specui update --name acme --strict

This re-fetches the source, shows the token diff, and runs validate.

---

CI tip

Don't commit generated Tailwind/CSS unless your team explicitly wants vendored artifacts. The pattern that ages better:

1. Commit .specui/ only
2. Generate exports in the build step: specui export --format css …

---

Next steps

• Distribution
• Scenarios — export
• CLI — export