Scenarios

Pick the scenario that matches your repo and follow it top to bottom. Each one links to a deeper guide when you want the details.

Scenario A — New web application (consumer)

You have an app repo and you want a governed design system in it, not a wiki page nobody reads.

1. Install Node 18+ and run from the app root:

npx @logicplanes/specui@latest init \
  --name "Acme Console" \
  --preset web-app \
  --agents-md \
  --agent-tools cursor \
  --ci github

2. Confirm everything is healthy:

npx specui doctor
npx specui validate .specui

3. Register your first real component before writing any UI code:

npx specui add component primary-button --variants default,destructive --states default,hover,disabled

4. Optionally pull a shadcn reference implementation:

npx specui get button

5. Gate merges so the contract stays honest: CI/CD.

Docs: Quick start · Registries · Agents & MCP

Scenario B — Publish a design system (flat repo)

You want a standalone repo that other apps load or link.

mkdir acme-ds && cd acme-ds
npx @logicplanes/specui@latest new . --preset design-system-library --git
npx specui validate .
npx specui push --remote origin   # after adding remote

Consumers install it like this:

cd ../my-app
npx specui load git+https://github.com/your-org/acme-ds.git --as acme
npx specui validate .specui --strict

While you're actively developing the design system, symlink instead of copying:

npx specui link ../acme-ds --as acme
# edit ../acme-ds, then in app:
npx specui update --name acme

Docs: Distribution · Interop

Scenario C — Monorepo (app + packages)

One .specui/ per app package, or one shared design-system package — both work. Pick based on how many brands you actually have.

Option 1 — a design-system package that apps load:

• Flat DS in packages/design-system/ (specui new)
• Each app: specui load ../packages/design-system --as ds (or specui load file://../packages/design-system --as ds)

Option 2 — a .specui/ per app:

• Run specui init in each app that needs its own brand

Option 3 — symlink during development:

• specui link from app to local DS folder

In CI, run validate in each package that owns a .specui/. See CI/CD.

Scenario D — Agent-first team (Cursor, Claude, Copilot)

The goal here is that agents read the spec before writing UI, not after you catch the drift in review.

1. init with --agents-md and tool files:

npx specui init --agents-md --agent-tools cursor,claude,copilot --starter-kit

2. Make sure agents read, in order: AGENTS.md → .specui/AGENTS-GUIDE.md → AGENT-DESIGN-RULES.md → the relevant components/ folders.

3. Add project rules:

npx specui rules add no-raw-hex --from no-raw-hex
npx specui skills add sync-design-to-code --from sync-design-to-code

4. Optionally wire up MCP:

npx specui mcp config
npx specui mcp install-hook cursor

Docs: Agents & MCP · Validation

Scenario E — shadcn + SpecUI together

Keep shadcn components in the repo and a full spec alongside them.

npx specui init --preset web-app
npx specui get --list
npx specui get button card dialog
npx specui validate .specui && npx specui sync

SpecUI stores vendor files under components/<name>/vendor/. Your tokens and rules still live in TOKENS.yaml and DOS-DONTs.md — agents don't get to bypass them just "because shadcn did it."

Docs: Registries

Scenario F — Export to Tailwind / CSS / design tools

Feed existing pipelines from .specui/ instead of maintaining two sources of truth.

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

Re-run export after every contract change. Never edit the exports directly — they are generated output, not the source of truth.

Docs: Interop

Scenario G — Import / migrate existing markdown

You have loose design docs and want them under SpecUI's governance.

1. specui init --preset blank
2. Manually move principles and tokens into the numbered files and TOKENS.yaml
3. specui add component for each component you already ship
4. specui import if you have a tarball from another SpecUI project:

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

5. Run validate --strict until it's clean

Use specui diff to compare old and new token sets along the way.

Scenario H — Upgrade SpecUI CLI version

New CLI, existing .specui/.

npm install -D @logicplanes/specui@latest
npx specui doctor
npx specui validate .specui --strict

There is no AGENTS.md-only refresh path. specui init refuses without --force (which overwrites the whole contract — destructive). To refresh the canonical AGENTS.md block without touching .specui/, either:

• Re-run specui init in a scratch directory and copy the block into your existing AGENTS.md, or
• Copy the canonical block from the CLI's templates/agent-blocks/ into your AGENTS.md by hand.

Watch the changelog for breaking schema notes.

Scenario I — Open source app with SpecUI

Contributors should see the design rules in the repo, not in a private doc.

• Commit .specui/, AGENTS.md, and the optional .github/workflows/specui.yml from init --ci github
• In your README, link to the docs and note that CI runs specui validate --strict
• See Contributing for this open-source CLI repo, as opposed to your own app's contributor guide

Quick reference