# SpecUI — Full Documentation

Source: https://logicplanes.github.io/specui/docs/ · Index: https://logicplanes.github.io/specui/llms.txt

All documentation pages concatenated as plain markdown, optimized for LLM ingestion.
Each page is preceded by its title and canonical URL.

---

# Agent prompts

> Two autonomous prompts to install SpecUI in an existing app or start a new one with a coding agent driving the design end to end.

URL: https://logicplanes.github.io/specui/docs/agent-prompts

---
title: Agent prompts
description: Two autonomous prompts to install SpecUI in an existing app or start a new one with a coding agent driving the design end to end.
---

Two prompts. Paste, change the `{{...}}` placeholders if you want (or leave them and let the agent pick sensible defaults), and hand them to your coding agent. **Neither asks questions** — the agent reads the repo, derives a sensible design system, and runs `validate --strict` until the contract is clean. You can review and override afterwards.

Both assume the agent can run `npx`/`npm` and read/write files in your repo.

---

## The one-liner versions

**Existing app** — paste this into Cursor, Claude Code, Codex, or any agentic tool that can run shell commands in your current repo:

```text
Install SpecUI (a .specui/ design contract + CLI) into this repo and build out the design system autonomously, without asking me any questions. Steps: (1) detect the framework from package.json and pick the closest preset (web-app, mobile-app, marketing-site, dashboard-data-dense, or design-system-library); (2) run `npx @logicplanes/specui@latest init --name "{{My Product}}" --preset <chosen> --agents-md --agent-tools cursor --ci github`; (3) run `specui doctor` and report the result; (4) scan the existing code under src/, app/, components/, or wherever the UI lives, infer the brand voice and accent color from existing styles, then fill in .specui/01-brand-and-product.md, .specui/02-foundations-tokens.md, and .specui/TOKENS.yaml with a complete token set (color, type, spacing, radius, shadow, motion) for light and dark themes; (5) for every UI component the app already ships, run `specui add component <name> --variants <…> --states <…>` and fill in each .specui/components/<name>/SPEC.md, STATES.md, VARIANTS.md from the actual implementation; (6) add any missing semantic tokens with `specui add token <path> <value> --theme light` (and `--theme dark`); (7) `specui sync` then `specui validate .specui --strict` — fix every finding and re-run until it prints "SpecUI valid — no findings." (8) Print a short summary of what you created, the token set, and the component list. From now on, never write or modify UI code without first registering the component in .specui/, always run `specui validate .specui --strict` before considering any UI task done, add missing tokens with `specui add token` before using them in code, and keep .specui/ and the implementing code in the same commit.
```

**New app** — paste this to start from scratch with the design system first:

```text
We are starting a brand-new application from scratch and the design system comes first. Build it autonomously, without asking me any questions, before any UI code is written. Steps: (1) scaffold the framework ({{Next.js + Tailwind | Vite + CSS modules | React Native | …}}) into ./{{my-product}}, cd in, git init; (2) run `npx @logicplanes/specui@latest init --name "{{My Product}}" --preset {{web-app | mobile-app | marketing-site | dashboard-data-dense | design-system-library}} --agents-md --agent-tools cursor --ci github`; (3) run `specui doctor` and report the result; (4) choose a coherent brand voice, accent color, typography stack, and density, then fill in .specui/01-brand-and-product.md, .specui/02-foundations-tokens.md, and .specui/TOKENS.yaml with a complete token set (color, type, spacing, radius, shadow, motion) for light and dark themes; (5) define the first three to five components we will actually need (e.g. button, input, dialog, card, navigation) — for each run `specui add component <name> --variants <…> --states <…>` and fill in .specui/components/<name>/SPEC.md, STATES.md, VARIANTS.md; (6) define one or two flow patterns (e.g. onboarding, destructive-confirmation) with `specui add pattern <name>` and fill them in; (7) `specui sync` then `specui validate .specui --strict` — fix every finding and re-run until it prints "SpecUI valid — no findings." (8) export tokens for the framework: `specui export --format {{tailwind | css | dtcg | json}}` and wire them into the framework config so code reads from the same source of truth; (9) commit .specui/, the framework scaffold, and the wiring in a single first commit. Print a short summary of what you created, the token set, and the component list. From now on, never write or modify UI code without first registering the component in .specui/, always run `specui validate .specui --strict` before considering any UI task done, add missing tokens with `specui add token` before using them in code, keep .specui/ and the implementing code in the same commit, and suggest a `specui add component` whenever I describe a UI feature that needs a new piece.
```

---

## Why these prompts work

Both prompts encode the SpecUI loop as a single instruction the agent can follow end to end: **register → validate → export → implement**. The contract leads; the code follows. Because they don't ask questions, the agent gets to a clean `validate --strict` pass in one session — you review and override afterwards, not in the middle.

A few things they do deliberately:

- **They pick the preset themselves.** The existing-app prompt scans the code to detect the framework and chooses the closest preset; the new-app prompt uses the `{{...}}` you set (or `web-app` if you leave it). You can override by editing the prompt.
- **They derive the brand from what's there.** On an existing app, the agent reads your styles, Tailwind config, CSS variables, or whatever your stack uses, and infers the accent color, typography, and density from real values rather than asking.
- **They register every component they find.** The existing-app prompt walks `src/` / `app/` / `components/` so your contract reflects what's actually shipped — not what you remember shipping.
- **They enforce strict validation as the gate.** `specui validate .specui --strict` is the last step before "done." If it's red, the task isn't done.
- **They install durable rules.** The trailing "from now on" sentence is what turns a one-shot install into a project-wide habit the agent keeps following on every future task.

---

## Tips

- **No `{{...}}` placeholders needed.** The existing-app prompt has only one (`{{My Product}}`) — the agent will infer everything else. The new-app prompt has a few you can fill, but leaving them works (the agent picks sensible defaults).
- **Prefer MCP?** If you've wired the SpecUI MCP server (`specui mcp install-hook cursor`), the agent can read the spec through the model context protocol directly — but these prompts work without it.
- **Already have a brand guide?** Add one sentence to the prompt: "Read `BRAND.md` and derive all tokens from it."
- **Want it to ask questions after all?** Delete the words "without asking me any questions" — the agent will interview you instead. The default is autonomous on purpose.
- **Pre-load the docs.** Before pasting either prompt, you can pre-load the SpecUI docs into the agent's context by pointing it at `https://logicplanes.github.io/specui/llms.txt` (the index) or `https://logicplanes.github.io/specui/llms-full.txt` (every page as one markdown file).

---

## Where to go next

- [Agents & MCP](/docs/agents-and-mcp) — how agents read `.specui/`, plus rules and skills
- [Quick start](/docs/quick-start) — the human-driven version of the same flow
- [Scenarios](/docs/scenarios) — monorepo, design-system repo, agent-first, shadcn
- [CI/CD](/docs/ci-cd) — make `validate --strict` fail the PR

---

# Agents & MCP

> AGENTS.md, the .specui agent docs, custom rules and skills, and the specui MCP server.

URL: https://logicplanes.github.io/specui/docs/agents-and-mcp

---
title: Agents & MCP
description: AGENTS.md, the .specui agent docs, custom rules and skills, and the specui MCP server.
---

Agents get the same gates humans use in CI, exposed in files they read first. If an agent can find the contract, it can follow it.

---

## File map (consumer project)

| File | Role |
|------|------|
| `AGENTS.md` (repo root) | Mandatory SpecUI block from `specui init` |
| `.specui/AGENTS-GUIDE.md` | CLI commands, workflow, rules/skills/MCP |
| `.specui/AGENT-DESIGN-RULES.md` | 7-step sync protocol (normative) |
| `.specui/DOS-DONTs.md` | High-leverage do / don't |
| `.specui/SPEC.md` + `readOrder` | Scope and reading sequence |
| `rules/*.md` | Custom design rules (`specui rules`) |
| `skills/*/SKILL.md` | Agent playbooks (`specui skills`) |

Per-editor stubs (optional, from `init --agent-tools`):

| Tool | File |
|------|------|
| Cursor | `.cursor/rules/specui.mdc` |
| Claude Code | `CLAUDE.md` |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Gemini | `GEMINI.md` |
| Windsurf | `.windsurfrules` |

Every stub points back to `AGENTS.md` and `.specui/AGENT-DESIGN-RULES.md`, so there is one canonical source no matter which editor is in play.

---

## Enable on init

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

| Flag | Effect |
|------|--------|
| `--agents-md` / `--no-agents-md` | Write SpecUI block to `AGENTS.md` (default: on) |
| `--agent-tools` | Comma list: `cursor`, `claude`, `codex`, `copilot`, `gemini`, `windsurf` |
| `--starter-kit` | Seed bundled rules + skills |
| `--seed-rules` / `--seed-skills` | Finer control over bundled templates |

To refresh a stale `AGENTS.md` block, the simplest path is to re-run `init` in a scratch directory and copy the block over, or open `.specui/AGENTS-GUIDE.md` and the canonical block from `templates/agent-blocks/` and paste it in. `init` against the current project will refuse to overwrite an existing `.specui/` unless you pass `--force` (which replaces the whole contract).

`validate` checks that the block is present and matches the current template.

---

## Agent workflow (summary)

1. Read `AGENTS.md` and `.specui/AGENTS-GUIDE.md`
2. Read the component/pattern folders for the task
3. `specui add` before any new UI
4. Implement using semantic tokens only
5. `specui validate .specui && specui sync`
6. Commit `.specui/` with the code

The full steps live in `.specui/AGENT-DESIGN-RULES.md`.

---

## Custom rules

List templates:

```bash
npx specui rules templates
```

Add from a template (works in a flat repo or a project with `.specui/`):

```bash
npx specui rules add no-raw-hex --from no-raw-hex
npx specui rules list
npx specui rules show no-raw-hex
```

Remove:

```bash
npx specui rules remove no-raw-hex
```

Rules live in `rules/` at the SpecUI root (flat repo) or as configured for your layout. `validate` can surface rule issues.

---

## Custom skills

Skills are multi-step procedures — register a component, sync design to code, and so on:

```bash
npx specui skills templates
npx specui skills add register-new-component --from register-new-component
npx specui skills list
```

Bundled examples: `register-new-component`, `sync-design-to-code`, `audit-color-contrast`, `audit-empty-states`, `generate-component-spec`, `theme-diff`, `tokenize-hardcoded-values`.

---

## MCP server

SpecUI ships a stdio MCP server so MCP-aware clients can call validate, sync, spec, and friends directly instead of shelling out.

Print the config JSON:

```bash
npx specui mcp config
```

Start the server (stdio):

```bash
npx specui mcp start
```

Install into an editor config:

```bash
npx specui mcp install-hook cursor
# also: claude, codeium, windsurf, continue
```

Restart the editor after `install-hook`.

HTTP transport is not implemented yet (`mcp start --http` errors).

---

## AI/LLM-friendly docs

The docs site is built so agents and crawlers can ingest every page without parsing HTML. Five pieces work together:

| Endpoint | What it is |
|----------|-----------|
| [`/llms.txt`](https://logicplanes.github.io/specui/llms.txt) | Index of every docs page plus a short project summary, grouped by section. This is the entry point LLMs should read first. |
| [`/llms-full.txt`](https://logicplanes.github.io/specui/llms-full.txt) | The whole docs site as one plain-markdown file — every page concatenated with its title and canonical URL. One fetch, no chrome. |
| `/docs-md/<slug>` | A single page as plain markdown. Append `.md` mentally to any docs URL — `/docs/install` → `/docs-md/install`. |
| `/robots.txt` | Explicitly allows GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, anthropic-ai, Google-Extended, PerplexityBot, Amazonbot, Bytespider, CCBot, and the standard search bots. |
| `/docs/<slug>/` HTML | Each rendered page carries JSON-LD `TechArticle` markup and a `<link rel="alternate" type="text/markdown" href="/docs-md/<slug>">` tag, so crawlers and agents can find the canonical markdown. |

`/llms.txt` is the recommended starting point; `/llms-full.txt` is for agents that want the entire corpus in one request. Point your agent at either:

```text
https://logicplanes.github.io/specui/llms.txt
https://logicplanes.github.io/specui/llms-full.txt
```

The MCP server above (`specui mcp start`) is the runtime counterpart — for agents that want to call `validate`, `sync`, `spec`, and friends directly instead of reading the docs. Read this page first, then point the agent at the endpoints above for an in-context copy of the standard.

---

## Machine-readable validate

For agents and CI parsers:

```bash
npx specui validate .specui --json --strict
```

Exit code 1 when findings include errors (or warnings with `--strict`).

---

## Print the normative standard

```bash
npx specui spec
npx specui spec --json
```

Handy when an agent needs the full SpecUI standard text without browsing the web.

---

## Next steps

- [Validation](/docs/validation) — finding types and `--strict`
- [CI/CD](/docs/ci-cd) — gate PRs
- [Scenarios — agent-first](/docs/scenarios#scenario-d--agent-first-team-cursor-claude-copilot)

---

# CI/CD

> Gate pull requests with specui validate, strict mode, and GitHub Actions.

URL: https://logicplanes.github.io/specui/docs/ci-cd

---
title: CI/CD
description: Gate pull requests with specui validate, strict mode, and GitHub Actions.
---

Treat `.specui/` like source code: CI should fail when the contract is broken or has drifted. A design system that isn't enforced in CI is a suggestion, not a contract.

---

## Minimal job (any CI)

```bash
npm ci   # or install @logicplanes/specui
npx specui validate .specui --strict
```

Pin the CLI for reproducibility:

```bash
npx -y @logicplanes/specui@2.0.2 validate .specui --strict
```

Exit codes:

| Code | Meaning |
|------|---------|
| 0 | No errors (and no warnings if `--strict`) |
| 1 | Validation failures |
| 2 | Bad path / usage |

---

## GitHub Actions (from `init --ci github`)

`specui init --ci github` adds a workflow that runs validate on push and PR. A typical version:

```yaml
name: SpecUI
on:
  pull_request:
  push:
    branches: [main, dev]

jobs:
  specui:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
      - run: npx -y @logicplanes/specui@latest validate .specui --strict
```

Adjust the branch names to your repo.

---

## JSON output for dashboards

```bash
npx specui validate .specui --json --strict > specui-findings.json
```

Parse `findings[]` in custom tooling or agent loops.

---

## Optional: sync in CI

If contributors tend to forget `sync` after manual edits:

```yaml
- run: npx specui sync
- run: git diff --exit-code .specui/manifests/registry.json
```

This fails the build when `registry.json` is out of date.

---

## Monorepo

Run validate per package that contains a `.specui/`:

```yaml
strategy:
  matrix:
    package: [apps/web, apps/admin]
steps:
  - run: npx specui validate ${{ matrix.package }}/.specui --strict
```

Or one job per app with `working-directory`.

---

## Pre-commit (local)

```yaml
# .pre-commit-config.yaml (example — use your hook runner)
- repo: local
  hooks:
    - id: specui-validate
      name: specui validate
      entry: npx specui validate .specui --strict
      language: system
      pass_filenames: false
```

---

## Release pipelines

Validate before publishing a design-system package to npm:

```bash
npx specui validate . --strict   # flat repo: SPEC.md at root
```

Consumer apps should not publish `.specui` as an npm app unless that is intentional.

---

## Next steps

- [Validation](/docs/validation) — what `--strict` enforces
- [Troubleshooting](/docs/troubleshooting) — fix common CI failures
- [Agents & MCP](/docs/agents-and-mcp) — `--json` for agents

---

# CLI reference

> Every specui command — create, manage, distribute, and agent tooling.

URL: https://logicplanes.github.io/specui/docs/cli

---
title: CLI reference
description: Every specui command — create, manage, distribute, and agent tooling.
---

Run `specui --help` for the in-terminal summary. This page documents every command, for both consumer projects (`.specui/`) and flat design-system repos.

**Path convention:** `[path]` defaults to `./.specui`, or the flat root where `SPEC.md` exists.

---

## Global

| Command | Description |
|---------|-------------|
| `specui --version` | Package version |
| `specui --help` | Command list |

---

## Create & scaffold

### `specui init`

Scaffold the consumer layout: `target/.specui/`, optional `AGENTS.md`, CI, rules/skills.

See the [init reference](/docs/init-reference) for all flags.

### `specui new <name>`

Create a flat publishable repo (`SPEC.md` at root). A wrapper around `init --flat`.

```bash
specui new ./acme-ds --preset design-system-library
```

---

## Register design (`specui add`)

Register before you write application code — that's the whole point of the contract.

### `specui add component <kebab-name>`

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

Creates `.specui/components/<name>/` with a manifest and spec stubs.

### `specui add asset <type> <name>`

Types: `icon`, `illustration`, `photo`, `logo`.

```bash
specui add asset logo acme-mark --link component:brand-mark
```

### `specui add token <group.path> <value>`

```bash
specui add token color.text.primary "#111111" --theme light
specui add token color.text.primary "#eeeeee" --theme dark
```

### `specui add pattern <kebab-name>`

```bash
specui add pattern empty-state
```

---

## Quality gate

### `specui validate [path]`

[Validation](/docs/validation) — schema, registry, contrast, AGENTS.md.

```bash
specui validate .specui --strict --json
```

### `specui sync [path]`

Rebuild `manifests/registry.json`; report broken links.

### `specui doctor [path]`

Readiness report + validate. Exits 1 if validate fails.

---

## Inspect

### `specui list [kind]`

| Kind | Shows |
|------|--------|
| `all` (default) | Components, assets, patterns summary |
| `components` | Component registry |
| `assets` | Asset registry |
| `patterns` | Pattern files |
| `sources` | `.specui-sources.yml` entries |
| `registries` | Built-in registry ids (e.g. shadcn) |

---

## Registries

### `specui get`

[Registries](/docs/registries) — shadcn and custom JSON URLs.

```bash
specui get --list
specui get button card
specui get --from https://example.com/r/item.json
```

---

## Distribution

See [Distribution](/docs/distribution) for the full guide.

| Command | Summary |
|---------|---------|
| `load <source> [--as name]` | Copy git/npm/dir into `.specui` |
| `link <source> [--as name]` | Symlink source |
| `unlink [--name name]` | Remove link |
| `push [--remote origin]` | Commit + push flat DS repo |
| `pull [--remote origin]` | Fetch flat DS repo |
| `import <tarball\|dir>` | Import into `.specui` |
| `export [--format …] [--to path]` | [Interop](/docs/interop) |
| `update [--name source]` | Re-fetch source + validate |
| `diff --from A --to B [--json]` | Token diff |

---

## Agents

[Agents & MCP](/docs/agents-and-mcp)

### `specui rules`

`templates` · `add <name> [--from template]` · `list` · `show <name>` · `remove <name>`

### `specui skills`

`templates` · `add <name> [--from template]` · `list` · `show <name>` · `remove <name>`

### `specui spec`

Print the normative SpecUI standard (`docs/SPEC.md` from the package).

```bash
specui spec --json
```

### `specui mcp`

`start` · `config` · `install-hook <cursor|claude|codeium|windsurf|continue>`

---

## Export formats (`specui export`)

| `--format` | Output |
|------------|--------|
| `tarball` (default) | `.tgz` archive |
| `dir` | Directory tree |
| `designmd` | DESIGN.md-style front matter |
| `dtcg` | DTCG JSON (`--theme`) |
| `tailwind` | JS theme extend (`--theme`) |
| `css` | CSS custom properties (`--theme`) |
| `json` | Flat JSON tokens |

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

---

## Exit codes (common)

| Code | Typical cause |
|------|----------------|
| **0** | Success |
| **1** | `validate` / `doctor` / `update` validation failure |
| **2** | Usage error, missing path, `die()` messages |

---

## Environment

- Node 18+
- Network required for `get` (unless you use `file://` / local JSON)
- Git required for `load`/`push`/`pull` from remotes

---

## Next steps

- [init reference](/docs/init-reference)
- [Scenarios](/docs/scenarios)
- [Troubleshooting](/docs/troubleshooting)

---

# Concepts

> The mental model — contract, registry, layouts, tokens, and the agent loop.

URL: https://logicplanes.github.io/specui/docs/concepts

---
title: Concepts
description: The mental model — contract, registry, layouts, tokens, and the agent loop.
---

Read this once before the deep how-to guides. It explains why SpecUI is shaped the way it is, which makes everything else easier to remember.

---

## Design contract

A SpecUI contract is a folder of markdown, YAML, and manifests that answers:

- What components exist and which states/variants they support
- What tokens (color, type, space, motion) are allowed
- What patterns (flows) agents must follow
- What assets (icons, logos) are registered

Code implements the contract — not the other way around. Changing UI without updating `.specui/` is a spec drift bug, and treating it as one is what keeps the whole thing trustworthy.

---

## Consumer vs flat layout

| | Consumer | Flat |
|---|----------|------|
| Use when | You build an app | You publish a design system |
| Root | `.specui/` in app repo | `SPEC.md` at repo root |
| Create with | `specui init` | `specui new <name>` |
| AGENTS.md | Yes (project root) | Optional; often rules at repo root |
| Distribute | `load` / `import` into apps | `push`, npm, git tag, `export` |

Apps consume flat repos with `specui load <git-url>`, or `specui link` for local development.

---

## Registry-first

Before a component exists in React, SwiftUI, or Compose, it should exist as:

```
.specui/components/<kebab-name>/
  MANIFEST.yaml
  SPEC.md
  VARIANTS.md
  STATES.md
```

`specui add component` scaffolds this. `specui sync` rebuilds `manifests/registry.json` — the machine-readable index agents and tools query.

`specui get` is a different animal: it installs vendor files from shadcn (or custom JSON) *into* an existing component folder, updating the manifest as it goes.

---

## Semantic tokens

`TOKENS.yaml` holds semantic names (`color.text.primary`), not ad-hoc hex values sprinkled through components. Primitives may exist in the YAML, but components reference semantics.

Adding a token:

```bash
specui add token color.brand.primary "#f54e00" --theme light
```

`validate` can run WCAG contrast checks unless you pass `--no-contrast`.

---

## Read order and narrative docs

`SPEC.md` front matter includes `readOrder`: `00-principles.md` through `11-platform-notes.md`, then `DOS-DONTs.md`, `AGENT-DESIGN-RULES.md`, `AGENTS-GUIDE.md`.

Humans and agents read the same files. The short rules live in the root `AGENTS.md`; the full protocol in `.specui/AGENT-DESIGN-RULES.md`; CLI details in `.specui/AGENTS-GUIDE.md`.

---

## Validation severity

`specui validate` emits error, warn, and info findings:

| Flag | Behavior |
|------|----------|
| (default) | Exit 1 only on errors |
| `--strict` | Warnings count as errors (use in CI) |
| `--json` | Machine-readable output for agents |

Checks include: required files, `readOrder`, registry links, required components/patterns from `SPEC.md`, the `AGENTS.md` block, custom rules, placeholders, and contrast.

---

## Distribution graph

```text
Flat DS repo ──load/link──► App .specui/
                │
                ├── export ──► tailwind | css | dtcg | designmd
                ├── get ──► vendor/ under components/
                └── update ──► refresh from recorded source
```

`.specui-sources.yml` at the project root records `load` / `link` sources and names.

---

## Presets

`specui init --preset` seeds `componentsRequired` and `patternsRequired` in `SPEC.md`:

| Preset | Typical use |
|--------|-------------|
| `web-app` | SaaS dashboard / product UI |
| `mobile-app` | iOS/Android scope in front matter |
| `marketing-site` | Landing pages, lighter component set |
| `dashboard-data-dense` | Data-heavy UI |
| `design-system-library` | Maximum catalog scaffolding |
| `blank` | Minimal; you choose everything |

Override the lists with `--components` and `--patterns`.

---

## Relationship to DESIGN.md and shadcn

- DESIGN.md — a single-file agent doc; SpecUI can export to it (`export --format designmd`) but `.specui/` stays canonical.
- shadcn — a component source; SpecUI records it under `vendor/` and keeps your spec (tokens, rules) separate.

---

## Next steps

- [Quick start](/docs/quick-start) — hands-on
- [Scenarios](/docs/scenarios) — pick a workflow
- [Schema](/docs/schema) — every file in `.specui/`
- [Specification](/docs/spec) — normative standard summary

---

# Contributing

> Contributing to the open-source specui CLI, and documenting your own SpecUI project.

URL: https://logicplanes.github.io/specui/docs/contributing

---
title: Contributing
description: Contributing to the open-source specui CLI, and documenting your own SpecUI project.
---

"Contributing" means two different things here, and it's worth keeping them apart:

| | This page (SpecUI project) | Your app with `.specui/` |
|---|-------------------------------|------------------------------|
| Goal | Improve `@logicplanes/specui` on GitHub | Onboard teammates to your design contract |
| Docs | Edit `wiki/*.md` here | Your README + `.specui/` + `AGENTS.md` |

---

## Contribute to SpecUI (open source)

Issues and pull requests are welcome on [logicplanes/specui](https://github.com/logicplanes/specui).

### Before you open a PR

1. Read the repo's [CONTRIBUTING.md](https://github.com/logicplanes/specui/blob/dev/CONTRIBUTING.md) and [AGENTS.md](https://github.com/logicplanes/specui/blob/dev/AGENTS.md) (maintainer/agent rules for this repo).
2. Run the tests:

```bash
npm test
npm run verify:repo-setup
npm run check:docs-sync
```

3. **User-facing docs:** edit files in `wiki/` only — `site/content/docs/*.mdx` is generated, and edits there will be overwritten. Then:

```bash
npm run sync:docs
```

4. For user-facing product changes, update `changelog.json` → `unreleased`.

### Branches

- Day-to-day work happens on `dev`
- Production docs site + releases come from `prod`

Maintainers: see [docs/RELEASING.md](https://github.com/logicplanes/specui/blob/dev/docs/RELEASING.md).

### Report bugs

- [Bug report template](https://github.com/logicplanes/specui/issues/new?template=bug_report.yml)
- Include: `specui --version` and `specui validate .specui --json` output (redact secrets)

### Ideas

- [Feature request](https://github.com/logicplanes/specui/issues/new?template=feature_request.yml)
- [Discussions](https://github.com/logicplanes/specui/discussions)

---

## Document your own SpecUI consumer project

Recommendations for your product repo:

1. **README** — link to the [SpecUI docs](https://logicplanes.github.io/specui/docs/), show `init` + `validate --strict`
2. **`AGENTS.md`** — keep the SpecUI block current (`specui init --agents-md`)
3. **`.specui/AGENTS-GUIDE.md`** — ships with init; point new agents there
4. **CI** — `npx specui validate .specui --strict` on every PR ([CI/CD](/docs/ci-cd))
5. **CONTRIBUTING.md** (your app) — one line goes a long way: "UI changes must update `.specui/` in the same PR"

You don't need to fork the SpecUI wiki for app docs — link to this site for CLI reference.

---

## Edit the public docs site

| Step | Action |
|------|--------|
| 1 | Change `wiki/<page>.md` |
| 2 | Update `wiki/meta.json` if adding/removing pages |
| 3 | `npm run sync:docs` |
| 4 | `cd site && npm run build` |
| 5 | PR to `dev`; the site publishes from `prod` |

The Wiki on GitHub is synced separately via a project workflow (see the repo's `sync-wiki`).

---

## Coding agents (this repo)

Maintainers use the repo's own [AGENTS.md](https://github.com/logicplanes/specui/blob/dev/AGENTS.md) — not the same thing as the consumer `AGENTS.md` block your app gets from `specui init`.

---

## Next steps

- [Install](/docs/install)
- [GitHub repository](https://github.com/logicplanes/specui)

---

# DESIGN.md bridge

> Keep SpecUI as the source of truth and export DESIGN.md for tools that expect it.

URL: https://logicplanes.github.io/specui/docs/designmd

---
title: DESIGN.md bridge
description: Keep SpecUI as the source of truth and export DESIGN.md for tools that expect it.
---

[DESIGN.md](https://github.com/google-labs-code/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/`:

```bash
npx specui export --format designmd --to ./DESIGN.md --from .specui
```

From a flat design-system repo:

```bash
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](/docs/interop)
- [Concepts](/docs/concepts)
- [FAQ — DESIGN.md](/docs/faq)

---

# Distribution

> Move SpecUI trees between repos with load, link, push, pull, import, export, update, and diff.

URL: https://logicplanes.github.io/specui/docs/distribution

---
title: Distribution
description: Move SpecUI trees between repos with load, link, push, pull, import, export, update, and diff.
---

These commands matter once your design system and your applications live in separate repos — or whenever you need to snapshot a contract and move it somewhere else.

---

## Mental model

| Command | Direction |
|---------|-----------|
| `load` | Copy remote SpecUI into `./.specui` |
| `link` | Symlink for live DS editing |
| `unlink` | Remove symlink metadata |
| `import` | Tarball or directory → `.specui` |
| `export` | `.specui` → tarball or interop formats |
| `push` / `pull` | Git publish for a flat DS repo |
| `update` | Re-fetch a recorded source |
| `diff` | Compare token sets between two roots |

Sources are recorded in `.specui-sources.yml` at the project root, so `update` knows where things came from.

---

## load — install a full SpecUI

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

Also supports:

- Local directory: `specui load ../acme-ds --as acme`
- npm package (packed SpecUI layout): `specui load @scope/acme-ds --as acme`

`--force` overwrites an existing `.specui/`.

---

## link — symlink for development

When you're editing the design system and the app at the same time, copying gets tedious. Symlink instead:

```bash
npx specui link ../acme-ds --as acme
# edit files in ../acme-ds
cd my-app && npx specui update --name acme
```

And `unlink` when done:

```bash
npx specui unlink --name acme
```

---

## push / pull — flat design-system repo

From a flat repo (`SPEC.md` at root, created with `specui new`):

```bash
npx specui push --remote origin --msg "chore: token updates"
npx specui pull --remote origin
```

`push` may `git init` if needed; it requires a configured remote or `--remote-url`.

---

## import / export archive

Export a tarball:

```bash
npx specui export --format tarball --to ./acme-specui.tgz --from .specui
```

Import into an app:

```bash
npx specui import ./acme-specui.tgz --force
```

Export a directory tree (no compression):

```bash
npx specui export --format dir --to ./snapshot --from .specui
```

Interop formats (Tailwind, CSS, …) are covered in [Interop](/docs/interop).

---

## update — refresh a consumed source

```bash
npx specui list sources
npx specui update --name acme
npx specui update --name acme --strict
```

Re-copies from the git or directory source, shows the token diff, and runs validate. Exits 1 if validate fails.

---

## diff — token comparison

```bash
npx specui diff --from ./design-system --to ./my-app/.specui
npx specui diff --from ./v1 --to ./v2 --json
```

Useful before and after DS upgrades or fork merges — you'll know exactly which tokens changed before anything lands.

---

## list sources

```bash
npx specui list sources
```

Shows installed and linked sources from `.specui-sources.yml`.

---

## Choosing load vs get

| Need | Command |
|------|---------|
| Entire `.specui/` tree from git/npm/dir | `load` |
| Single shadcn (or JSON) component + vendor files | `get` |

See [Registries](/docs/registries).

---

## Next steps

- [Scenarios — flat repo](/docs/scenarios#scenario-b--publish-a-design-system-flat-repo)
- [Interop](/docs/interop) — export formats
- [CLI reference](/docs/cli)

---

# FAQ

> Short answers about SpecUI, installation, agents, shadcn, and CI.

URL: https://logicplanes.github.io/specui/docs/faq

---
title: FAQ
description: Short answers about SpecUI, installation, agents, shadcn, and CI.
---

Short answers, with links to the longer ones.

---

## What is SpecUI?

A versioned design contract in your repo (`.specui/`) plus a CLI to scaffold it, validate it, sync a registry index, pull shadcn items, export tokens, and wire coding agents. See [Introduction](/docs).

---

## How is SpecUI different from shadcn/ui?

shadcn copies component source into your app. SpecUI holds the full spec (tokens, brand, patterns, rules, manifests) and can vendor shadcn files under `.specui/components/.../vendor/` via `specui get`. See [Registries](/docs/registries) and [Scenarios — shadcn](/docs/scenarios).

---

## How is SpecUI different from DESIGN.md?

[DESIGN.md](https://github.com/google-labs-code/design.md) is typically one file for agents. SpecUI is many files, CI-validated, with a registry. You can export to DESIGN.md: `specui export --format designmd`. See [DESIGN.md bridge](/docs/designmd).

---

## What do I install?

Only the npm package `@logicplanes/specui`. It provides the `specui` command. Your project gets `.specui/` when you run `specui init`. [Install](/docs/install).

---

## Do I need a global install?

No. `npx @logicplanes/specui@latest <command>` is enough. Global install is just a convenience.

---

## What is `.specui/` vs `specui new`?

| | `.specui/` in app | Flat repo |
|---|-------------------|-----------|
| Command | `specui init` | `specui new` |
| Use | Product codebase | Publishable design system |

[Concepts](/docs/concepts).

---

## What must agents read?

1. Root `AGENTS.md` (SpecUI block)
2. `.specui/AGENTS-GUIDE.md`, `AGENT-DESIGN-RULES.md`, `SPEC.md` / `readOrder`

[Agents & MCP](/docs/agents-and-mcp).

---

## What runs in CI?

```bash
npx specui validate .specui --strict
```

Optional: `sync` + diff on `registry.json`. [CI/CD](/docs/ci-cd).

---

## Why did validate fail?

Common causes: a required component missing from the preset, a stale `AGENTS.md` block, broken registry links, or contrast warnings under `--strict`. [Troubleshooting](/docs/troubleshooting) · [Validation](/docs/validation).

---

## Can I use SpecUI offline?

`init`, `add`, `validate`, `sync`, and `export` all work offline. `specui get` needs network unless you use `file://` JSON. [Install — offline](/docs/install).

---

## Where is the full command list?

[CLI reference](/docs/cli), or `specui --help` in the terminal.

---

## How do I contribute to the SpecUI project?

[Contributing](/docs/contributing) — edit `wiki/`, run tests, PR to `dev`.

---

## Docs 404 on GitHub Pages?

Use `https://logicplanes.github.io/specui/docs/` (not `/specui/specui/docs`). [Troubleshooting](/docs/troubleshooting).

---

## Next steps

[Documentation overview](/docs/overview) · [Scenarios](/docs/scenarios)

---

# Introduction

> What SpecUI is, the problem it solves, and how the documentation is organized.

URL: https://logicplanes.github.io/specui/docs

---
title: Introduction
description: What SpecUI is, the problem it solves, and how the documentation is organized.
---

SpecUI is a design system that lives in your repository: a `.specui/` folder holding tokens, components, patterns, assets, and rules, plus a `specui` CLI to scaffold it, keep it valid, pull registry components, export to Tailwind/CSS, and wire coding agents through `AGENTS.md`, rules, skills, and MCP.

Package: [`@logicplanes/specui`](https://www.npmjs.com/package/@logicplanes/specui) · CLI: `specui` · Docs: [logicplanes.github.io/specui](https://logicplanes.github.io/specui/)

New here? [Install](/docs/install) → [Quick start](/docs/quick-start). Full sitemap: [Documentation overview](/docs/overview). Short answers: [FAQ](/docs/faq).

---

## What problem SpecUI solves

Most teams keep design in Figma, Notion, or scattered markdown. That works fine for humans, less so for agents and CI — nothing can reliably enforce "use our button" or "no random hex colors" when the source of truth lives outside the repo. SpecUI moves that source of truth into the repository:

1. Register components, tokens, and patterns in `.specui/` before app code exists.
2. Validate structure, links, contrast, and agent files with `specui validate`.
3. Sync `manifests/registry.json` so tooling and agents query one index.
4. Export the same contract to Tailwind, CSS, DTCG, or DESIGN.md when other tools need it.

There is no separate checklist file — the numbered docs and the registry are the system. CI gates on `specui validate --strict`.

---

## How SpecUI compares

| You know | SpecUI is |
|----------|-----------|
| [shadcn/ui](https://ui.shadcn.com) | A full spec (brand, tokens, patterns, rules), not only copied React source |
| [DESIGN.md](https://github.com/google-labs-code/design.md) | Multi-file, versionable, registry-first, with validation and MCP |
| `AGENTS.md` (behavior) | Plus what the UI may look like — components, states, do's and don'ts in `.specui/` |

---

## Two layouts

| Layout | When | Root |
|--------|------|------|
| Consumer | App or product repo | `.specui/` + project `AGENTS.md` |
| Flat | Publishable design-system repo | `SPEC.md` at repo root (`specui new`) |

Installed foreign trees are tracked in `.specui-sources.yml` at the project root (not inside `.specui/`).

---

## Documentation map

The site follows a learn → do → look up structure (in the spirit of Stripe, Vercel, and Diátaxis-style docs):

| Section | Pages | You will… |
|---------|--------|-----------|
| Getting started | [Install](/docs/install), [Quick start](/docs/quick-start), [Concepts](/docs/concepts), [FAQ](/docs/faq) | Install the CLI, scaffold in minutes, learn the mental model |
| How-to guides | [Scenarios](/docs/scenarios), [Tokens & components](/docs/tokens-and-components), [Agents & MCP](/docs/agents-and-mcp), [CI/CD](/docs/ci-cd), [Distribution](/docs/distribution), [Registries](/docs/registries), [Interop](/docs/interop), [DESIGN.md bridge](/docs/designmd), [Validation](/docs/validation), [Troubleshooting](/docs/troubleshooting) | Complete real tasks end-to-end |
| Reference | [CLI](/docs/cli), [init flags](/docs/init-reference), [Schema](/docs/schema), [Specification](/docs/spec) | Look up commands, files, and normative rules |
| Community | [Contributing](/docs/contributing) | Contribute to the open-source project |

Complete page list: [Documentation overview](/docs/overview).

---

## The core loop (every project)

```bash
# 1) Scaffold (once)
npx @logicplanes/specui@latest init --name "My Product" --preset web-app

# 2) Register before code
npx specui add component primary-button --variants default,destructive

# 3) Gate + index
npx specui validate .specui --strict && npx specui sync
```

Optional: `specui get button` (registry), `specui export --format tailwind`, `specui mcp install-hook cursor`.

---

## Next steps

- New to SpecUI → [Install](/docs/install) then [Quick start](/docs/quick-start)
- Pick your situation → [Scenarios](/docs/scenarios) (web app, mobile, monorepo, design-system team, agents-only)
- Automate in CI → [CI/CD](/docs/ci-cd)
- Full command list → [CLI reference](/docs/cli)

---

# init reference

> Every flag and preset for specui init and specui new.

URL: https://logicplanes.github.io/specui/docs/init-reference

---
title: init reference
description: Every flag and preset for specui init and specui new.
---

`specui new <path>` is `specui init --flat` with a required target name. All flags below apply to `init`; `new` accepts the subset `--preset`, `--themes`, `--platforms`, `--agents-md`, `--git`, and `--force` (defaults for a flat repo: no `AGENTS.md`, no git).

---

## Presets (`--preset`)

| Preset | Description |
|--------|-------------|
| `web-app` | Default SaaS / product UI scaffolding |
| `mobile-app` | Mobile-first scope in front matter |
| `marketing-site` | Marketing / landing patterns |
| `dashboard-data-dense` | Dense data UI |
| `design-system-library` | Large catalog starter |
| `blank` | Minimal lists; you define components/patterns |

---

## Target and layout

| Flag | Description |
|------|-------------|
| `--target <dir>` | Write the contract here (default: `cwd`) |
| `--flat` | No `.specui/` wrapper — contract at `target` root (`new` sets this) |
| `--force` | Overwrite an existing `.specui` or flat `SPEC.md` |
| `--dry-run` | Print the plan only; no writes |

---

## Product metadata

| Flag | Description |
|------|-------------|
| `--name <string>` | Product name in `SPEC.md` |
| `--category <string>` | e.g. `web-app`, `marketing-site` |
| `--audience <string>` | Primary users |

---

## Scope

| Flag | Values |
|------|--------|
| `--themes` | `light`, `dark`, `high-contrast` (comma-separated) |
| `--platforms` | `web`, `ios`, `android`, `flutter`, `desktop`, `other` |
| `--density` | `comfortable`, `compact`, `dense` |
| `--components` | Comma list of required kebab component ids |
| `--patterns` | Comma list of required kebab pattern ids |
| `--imagery` | `photo`, `illustration`, `ai-allowed` |
| `--rtl` | Enable RTL requirement |
| `--no-rtl` | Disable RTL |
| `--data-viz` | Charts / data visualization in scope |
| `--no-data-viz` | Disable data viz |

---

## Agents and editor files

| Flag | Description |
|------|-------------|
| `--agents-md` | Inject SpecUI block into `AGENTS.md` (default) |
| `--no-agents-md` | Skip `AGENTS.md` |
| `--agent-tools <list>` | `cursor`, `claude`, `codex`, `copilot`, `gemini`, `windsurf` |
| `--no-agent-tools` | Skip per-tool stub files |
| `--starter-kit` | Seed 2 bundled rules + 2 skills |
| `--seed-rules` / `--no-seed-rules` | Bundled rules templates |
| `--seed-skills` / `--no-seed-skills` | Bundled skills templates |

If `--agents-md` is set and the tools list is empty, the default is `cursor`.

---

## CI and git

| Flag | Description |
|------|-------------|
| `--ci github` | Add GitHub Actions validate workflow (default when CI enabled) |
| `--no-ci` | Skip the CI template |
| `--git` | `git init` + initial commit in target |
| `--no-git` | Skip git (default) |

---

## Examples

**Minimal blank project:**

```bash
specui init --preset blank --target ./my-app --no-ci --no-git
```

**Full agent + CI setup:**

```bash
specui init \
  --name "Acme" \
  --preset web-app \
  --themes light,dark \
  --platforms web \
  --agents-md \
  --agent-tools cursor,claude,copilot \
  --starter-kit \
  --ci github
```

**Publishable design system:**

```bash
specui new ./acme-ds --preset design-system-library --git
```

**Preview the plan before committing to anything:**

```bash
specui init --dry-run --preset web-app --target /tmp/preview
```

---

## Exit codes

| Code | Cause |
|------|--------|
| **0** | Success or dry-run |
| **2** | Invalid flags, missing preset, existing contract without `--force` |

---

## Next steps

- [Quick start](/docs/quick-start)
- [CLI reference](/docs/cli) — all commands
- [Agents & MCP](/docs/agents-and-mcp)

---

# Install

> Install the specui CLI globally or per-project, and verify your environment.

URL: https://logicplanes.github.io/specui/docs/install

---
title: Install
description: Install the specui CLI globally or per-project, and verify your environment.
---

SpecUI ships as an npm package. There is no separate "SpecUI app" to install — you install the CLI, and it scaffolds `.specui/` inside your projects when you ask it to.

---

## Requirements

| Requirement | Detail |
|-------------|--------|
| Node.js | 18+ (22 recommended for CI templates from `init`) |
| npm, pnpm, or yarn | Any package manager that can run `npx` |
| Git | Optional; used by `init --git`, `push`, `pull`, `load` from git URLs |

---

## Recommended: run without installing (npx)

The easiest way to try SpecUI, and the right shape for CI one-liners:

```bash
npx @logicplanes/specui@latest --version
npx @logicplanes/specui@latest init --help
```

In CI, pin a version so builds stay reproducible:

```bash
npx -y @logicplanes/specui@2.0.2 validate .specui --strict
```

---

## Global install

Worth it if you run `specui` many times a day:

```bash
npm install -g @logicplanes/specui
specui --version
specui init --name "Acme" --preset web-app
```

Update:

```bash
npm update -g @logicplanes/specui
```

---

## Per-project devDependency

If your team pins tooling in `package.json`:

```bash
npm install -D @logicplanes/specui
```

```json
{
  "scripts": {
    "specui:validate": "specui validate .specui --strict",
    "specui:sync": "specui sync"
  }
}
```

```bash
npm run specui:validate
```

Use `npx specui` or `./node_modules/.bin/specui` in scripts.

---

## Verify installation

```bash
specui doctor          # from a repo that already has .specui/
specui --help          # full command list
specui spec            # print normative SpecUI standard (for agents)
```

After `init`, always run:

```bash
specui doctor
specui validate .specui
```

---

## What gets installed on disk

`npm install` / `npx` only installs the CLI package (bin, `src/`, templates). Nothing touches your repo — `.specui/` is not created until you run:

```bash
specui init    # consumer layout → ./.specui/
specui new     # flat layout → ./SPEC.md at repo root
```

---

## Editors and agents (optional)

`specui init` can also write:

- `AGENTS.md` — SpecUI contract block (default: on)
- `.cursor/rules/specui.mdc`, `CLAUDE.md`, etc. — via `--agent-tools`
- GitHub Actions workflow — via `--ci github`

See [Agents & MCP](/docs/agents-and-mcp) and [init reference](/docs/init-reference).

---

## Offline / air-gapped

1. On a connected machine: `npm pack @logicplanes/specui`
2. Copy the `.tgz` to the restricted environment
3. `npm install -g ./logicplanes-specui-*.tgz`
4. Scaffold with `specui init` (templates are inside the package)

Registry commands (`specui get`) need network unless you use `specui get --from file:///path/item.json`.

---

## Next steps

- [Quick start](/docs/quick-start) — scaffold your first `.specui/`
- [Concepts](/docs/concepts) — consumer vs flat, registry, validation
- [Scenarios](/docs/scenarios) — choose a preset and workflow for your repo type

---

# Interop

> Export SpecUI to DESIGN.md, DTCG, Tailwind, CSS, and JSON — and compare versions.

URL: https://logicplanes.github.io/specui/docs/interop

---
title: Interop
description: Export SpecUI to DESIGN.md, DTCG, Tailwind, CSS, and JSON — and compare versions.
---

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):

```bash
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:

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

Flat design-system repo:

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

---

## Format guide

| Format | Best for |
|--------|----------|
| `designmd` | Tools/agents that read [DESIGN.md](https://github.com/google-labs-code/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

```bash
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

```bash
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`:

```bash
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](/docs/distribution)
- [Scenarios — export](/docs/scenarios)
- [CLI — export](/docs/cli)

---

# Documentation overview

> A map of every page in the SpecUI docs and where to start.

URL: https://logicplanes.github.io/specui/docs/overview

---
title: Documentation overview
description: A map of every page in the SpecUI docs and where to start.
---

These docs follow a simple rule: tutorials teach, how-to guides solve one job, reference pages answer exact questions. Nothing here is filler — if a page exists, a command or workflow needed it.

Content is edited in [`wiki/*.md`](https://github.com/logicplanes/specui/tree/dev/wiki) in the repo; the site pages are generated from it.

---

## Where to start

| Your goal | Start here |
|-----------|------------|
| Install the CLI | [Install](/docs/install) |
| First `.specui/` in an app | [Quick start](/docs/quick-start) |
| Pick a workflow — monorepo, DS repo, agents, shadcn | [Scenarios](/docs/scenarios) |
| Understand the mental model | [Concepts](/docs/concepts) |
| Wire Cursor, Claude, or MCP | [Agents & MCP](/docs/agents-and-mcp) |
| Give the agent a ready prompt | [Agent prompts](/docs/agent-prompts) |
| Feed the docs to an LLM or crawler | [/llms.txt](https://logicplanes.github.io/specui/llms.txt) |
| Fail PRs when the spec breaks | [CI/CD](/docs/ci-cd) |
| Look up any command | [CLI reference](/docs/cli) |
| Look up any `init` flag | [init reference](/docs/init-reference) |
| Something broke | [Troubleshooting](/docs/troubleshooting) |
| Quick answers | [FAQ](/docs/faq) |

---

## How these docs are written

1. **Commands you can paste.** Examples use `npx @logicplanes/specui@latest` or `npx specui` from the project root unless a page says otherwise.
2. **Register before code.** Every how-to repeats the same loop: `specui add` → implement → `validate` → `sync` → commit `.specui/` with the code.
3. **One source of truth.** `.specui/` (or a flat `SPEC.md` repo) is canonical; exports are regenerated, never hand-edited.
4. **Agents are first-class.** `AGENTS.md`, `.specui/AGENTS-GUIDE.md`, rules, skills, and MCP get the same coverage as human workflows.
5. **Strict in CI.** `validate --strict` is the recommended production gate throughout.

---

## Every page

### Getting started

| Page | Covers |
|------|--------|
| [Introduction](/docs) | What SpecUI is, comparisons, layouts, doc map |
| [Install](/docs/install) | npx, global, devDependency, verifying, offline installs |
| [Quick start](/docs/quick-start) | Tutorial: `init` → `doctor` → `add` → `validate` → optional `get` |
| [Concepts](/docs/concepts) | The contract, consumer vs flat layout, registry, tokens, presets |

### How-to guides

| Page | Covers |
|------|--------|
| [Scenarios](/docs/scenarios) | Web app, flat DS, monorepo, agent-first, shadcn, export, migrate, upgrade, open source |
| [Tokens & components](/docs/tokens-and-components) | `add token/component/asset/pattern`, TOKENS.yaml, manifests |
| [Agents & MCP](/docs/agents-and-mcp) | AGENTS.md, AGENTS-GUIDE, rules, skills, MCP hooks |
| [Agent prompts](/docs/agent-prompts) | Copy-paste prompts to install SpecUI with a coding agent |
| [CI/CD](/docs/ci-cd) | validate in CI, GitHub Actions, JSON output, monorepos, pre-commit |
| [Distribution](/docs/distribution) | load, link, unlink, push, pull, import, export, update, diff |
| [Registries](/docs/registries) | `get`, shadcn, custom JSON registries, when to use `load` instead |
| [Interop](/docs/interop) | designmd, dtcg, tailwind, css, json, tarball, dir exports |
| [DESIGN.md bridge](/docs/designmd) | SpecUI as canonical source with DESIGN.md as an export |
| [Validation](/docs/validation) | validate, strict mode, JSON output, doctor, how sync relates |
| [Troubleshooting](/docs/troubleshooting) | install, init, validate, get, load, MCP, wiki, docs URLs |

### Reference

| Page | Covers |
|------|--------|
| [CLI reference](/docs/cli) | Every command, exit codes, environment variables |
| [init reference](/docs/init-reference) | Presets, flags, worked examples |
| [Schema](/docs/schema) | Files, folders, front matter, components, assets, patterns |
| [Specification](/docs/spec) | Normative summary, link to the full `docs/SPEC.md` |

### Community

| Page | Covers |
|------|--------|
| [Contributing](/docs/contributing) | Contributing to SpecUI vs documenting your own app |
| [FAQ](/docs/faq) | Short answers with links to the long ones |

---

## The whole CLI, mapped to docs

| Area | Commands | Primary doc |
|------|----------|-------------|
| Scaffold | `init`, `new` | [init reference](/docs/init-reference), [CLI](/docs/cli) |
| Register | `add component\|asset\|token\|pattern` | [Tokens & components](/docs/tokens-and-components) |
| Quality | `validate`, `sync`, `doctor` | [Validation](/docs/validation) |
| Inspect | `list` | [CLI](/docs/cli) |
| Registry | `get` | [Registries](/docs/registries) |
| Distribute | `load`, `link`, `unlink`, `push`, `pull`, `import`, `export`, `update`, `diff` | [Distribution](/docs/distribution), [Interop](/docs/interop) |
| Agents | `rules`, `skills`, `spec`, `mcp` | [Agents & MCP](/docs/agents-and-mcp) |
| Meta | `--help`, `--version` | [CLI](/docs/cli) |

---

## Docs that live in the repo instead

| Path | Audience |
|------|----------|
| [`docs/SPEC.md`](https://github.com/logicplanes/specui/blob/dev/docs/SPEC.md) | The normative standard (print it with `specui spec`) |
| [`docs/schema.md`](https://github.com/logicplanes/specui/blob/dev/docs/schema.md) | Maintainer-level schema detail |
| `.specui/AGENTS-GUIDE.md` in your app | Agent reference shipped by `specui init` |

---

## Next

New here? [Install](/docs/install), then the [quick start](/docs/quick-start). Know what you're building? Pick a [scenario](/docs/scenarios). Just have a question? Try the [FAQ](/docs/faq).

---

# Quick start

> Scaffold SpecUI, register a component, validate, and optionally pull from a registry — in about ten minutes.

URL: https://logicplanes.github.io/specui/docs/quick-start

---
title: Quick start
description: Scaffold SpecUI, register a component, validate, and optionally pull from a registry — in about ten minutes.
---

This tutorial assumes a consumer app repo (a `.specui/` folder inside your app). If you're building a publishable design-system repo, see [Scenarios — flat repo](/docs/scenarios#scenario-b--publish-a-design-system-flat-repo) instead.

---

## Prerequisites

- [Install](/docs/install) — Node 18+, `npx` or global `specui`
- A git repo (recommended) at your app root

---

## Step 1 — Scaffold `.specui/`

From your application root:

```bash
cd your-app-repo

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

What this creates:

| Output | Purpose |
|--------|---------|
| `.specui/` | Full contract (SPEC, tokens, numbered docs, manifests) |
| `AGENTS.md` | SpecUI block for coding agents |
| `.cursor/rules/specui.mdc` | Cursor rule (when `--agent-tools cursor`) |
| `.github/workflows/specui.yml` | CI validate job (when `--ci github`) |

Want to see what would happen without writing anything? Dry-run it:

```bash
npx specui init --dry-run --preset blank --target /tmp/preview
```

---

## Step 2 — Health check

```bash
npx specui doctor
npx specui validate .specui
```

`doctor` prints layout, `AGENTS.md` status, counts, and runs validate. Fix any errors before continuing — they only get harder to untangle later.

---

## Step 3 — Register before code

This is the core habit: add a component before implementing it in React/Vue/etc., so the contract leads and the code follows.

```bash
npx specui add component primary-button \
  --variants default,destructive \
  --states default,hover,focus,disabled
```

Add a semantic token:

```bash
npx specui add token color.brand.primary "#f54e00" --theme light
npx specui add token color.brand.primary "#ff6b2c" --theme dark
```

Add a flow pattern (pick a name the preset doesn't already ship — `specui list patterns` shows what's there):

```bash
npx specui add pattern onboarding-checklist
```

Rebuild the registry index:

```bash
npx specui sync
npx specui list all
```

---

## Step 4 — Strict validate (CI-style)

```bash
npx specui validate .specui --strict
```

A fresh init will show `state-row-empty` warnings from the preset's placeholder `STATES.md` files — these are expected. Fix them as you fill in each component, or run without `--strict` until you do.

Use `--strict` in GitHub Actions so warnings (contrast, placeholders) fail the build. See [CI/CD](/docs/ci-cd).

---

## Step 5 — Optional: registry components

Pull shadcn reference files into the spec. Pick a component the `web-app` preset doesn't already ship (the preset includes `button`, `card`, `dialog`, etc., so `get button` would error with "Component already exists" — `specui list components` shows what's already there):

```bash
npx specui get --list
npx specui get carousel
npx specui validate .specui && npx specui sync
```

Details: [Registries](/docs/registries).

---

## Step 6 — Implement UI in your app

1. Read `.specui/components/primary-button/` and `TOKENS.yaml`
2. Map tokens to your stack (CSS vars, Tailwind theme, etc.) — or use `specui export`
3. After code changes that touch design: run validate + sync again
4. Commit `.specui/` and code in the same commit

Agent protocol: [Agents & MCP](/docs/agents-and-mcp).

---

## What you learned

- `init` scaffolds the contract and agent wiring
- `add` registers design artifacts
- `validate` + `sync` keep the registry honest
- `get` optionally vendors registry implementations

---

## Next steps

- [Concepts](/docs/concepts) — deeper mental model
- [Scenarios](/docs/scenarios) — monorepo, flat DS, exports
- [CLI reference](/docs/cli) — every command
- [Troubleshooting](/docs/troubleshooting) — when validate fails

---

# Registries

> specui get — pulling shadcn/ui and custom registry items into your contract.

URL: https://logicplanes.github.io/specui/docs/registries

---
title: Registries
description: specui get — pulling shadcn/ui and custom registry items into your contract.
---

`specui get` downloads registry items into an existing SpecUI contract. It's not a replacement for `load`, which imports an entire tree — the two solve different problems:

| Command | Use when |
|---------|----------|
| `specui load` | You want an entire `.specui/` from git, npm, or a directory |
| `specui get` | You want one or more registry components plus their vendored source files |

---

## Prerequisites

You need a consumer project with a `.specui/` folder already in place:

```bash
npx specui init --preset web-app
npx specui validate .specui
```

---

## List available items (shadcn)

```bash
npx specui get --list
npx specui get --list --from shadcn
```

Listing needs network access to reach the registry.

---

## Install components

```bash
npx specui get button
npx specui get button card dialog
npx specui get --style default button
```

Here's what happens under the hood:

1. Registry metadata is resolved, including dependencies (installed automatically)
2. Files land under `.specui/components/<name>/vendor/`
3. The component manifest is updated
4. `sync` runs to refresh `registry.json`

If the component already exists and you want to replace it:

```bash
npx specui get button --force
```

---

## Custom registry URL

Any URL serving the same JSON shape as [shadcn registry items](https://ui.shadcn.com/docs/registry/registry-json) works:

```bash
npx specui get --from https://example.com/r/my-widget.json
npx specui get --url https://example.com/r/my-widget.json
```

Offline, point at a local file:

```bash
npx specui get --from file:///path/to/item.json
```

Platforms are inferred from file extensions (`.tsx`, `.vue`, `.dart`, …).

---

## Platform hint

```bash
npx specui get button --platform react
```

Useful when a registry serves multiple targets (`.tsx`, `.vue`, `.dart`) and you want to be explicit. Common values: `react`, `vue`, `flutter` — `get` infers from file paths by default.

---

## After `get`

Always verify what you just pulled in:

```bash
npx specui validate .specui --strict
npx specui list components
```

One thing worth being clear about: agents still have to follow the tokens and rules in `.specui/`. Vendor code is reference material, not permission to bypass the spec.

---

## vs application install (shadcn CLI)

| | shadcn CLI in app | `specui get` |
|---|-------------------|--------------|
| Output | `components/ui/` in app | `.specui/.../vendor/` + manifest |
| Purpose | Runnable UI | Design record + reference source |
| Validation | App tests | `specui validate` |

The two aren't mutually exclusive. SpecUI holds the contract; the app holds framework code, mapped to `syncTargets` in manifests.

---

## Troubleshooting

- **Network errors** — retry, or use `file://` JSON
- **Missing `.specui`** — run `init` first
- **Validate fails after get** — run `sync`; check manifest links

See [Troubleshooting](/docs/troubleshooting) for more.

---

## Next steps

- [Scenarios — shadcn](/docs/scenarios) (Scenario E)
- [Distribution](/docs/distribution)
- [CLI — get](/docs/cli#registries)

---

# Scenarios

> End-to-end workflows — new apps, design-system repos, monorepos, agent teams, and migrations.

URL: https://logicplanes.github.io/specui/docs/scenarios

---
title: Scenarios
description: End-to-end workflows — new apps, design-system repos, monorepos, agent teams, and migrations.
---

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](/docs/install) Node 18+ and run from the app root:

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

2. Confirm everything is healthy:

```bash
npx specui doctor
npx specui validate .specui
```

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

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

4. Optionally pull a shadcn reference implementation:

```bash
npx specui get button
```

5. Gate merges so the contract stays honest: [CI/CD](/docs/ci-cd).

Docs: [Quick start](/docs/quick-start) · [Registries](/docs/registries) · [Agents & MCP](/docs/agents-and-mcp)

---

## Scenario B — Publish a design system (flat repo)

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

```bash
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:

```bash
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:

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

Docs: [Distribution](/docs/distribution) · [Interop](/docs/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](/docs/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:

```bash
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:

```bash
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:

```bash
npx specui mcp config
npx specui mcp install-hook cursor
```

Docs: [Agents & MCP](/docs/agents-and-mcp) · [Validation](/docs/validation)

---

## Scenario E — shadcn + SpecUI together

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

```bash
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](/docs/registries)

---

## Scenario F — Export to Tailwind / CSS / design tools

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

```bash
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](/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:

```bash
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/`.

```bash
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](https://github.com/logicplanes/specui/blob/dev/CHANGELOG.md) 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](https://logicplanes.github.io/specui/docs/) and note that CI runs `specui validate --strict`
- See [Contributing](/docs/contributing) for this open-source CLI repo, as opposed to your own app's contributor guide

---

## Quick reference

| I need to… | Command / page |
|------------|----------------|
| Scaffold app | `specui init` · [init reference](/docs/init-reference) |
| Publish DS | `specui new` · [Distribution](/docs/distribution) |
| Add UI piece | `specui add` · [CLI](/docs/cli) |
| Pull shadcn | `specui get` · [Registries](/docs/registries) |
| Fail CI on drift | `validate --strict` · [CI/CD](/docs/ci-cd) |
| Wire Cursor | [Agents & MCP](/docs/agents-and-mcp) |
| Fix errors | [Troubleshooting](/docs/troubleshooting) |

---

# Schema

> Required files and folders in .specui/ — the reference both humans and validate use.

URL: https://logicplanes.github.io/specui/docs/schema

---
title: Schema
description: Required files and folders in .specui/ — the reference both humans and validate use.
---

A SpecUI contract is just a directory — usually `.specui/` inside an app, or the repo root in the flat layout. `specui validate` enforces the schema described here.

---

## Required files

| File | Purpose |
|------|---------|
| `COPYRIGHT` | Proprietary / attribution notice — do not remove |
| `LICENSE-SPECUI.md` | Human-readable SpecUI terms |
| `SPEC.md` | Index + YAML front matter (scope, `readOrder`, registry pointer) |
| `00-principles.md` … `11-platform-notes.md` | Numbered normative design narrative |
| `AGENT-DESIGN-RULES.md` | Agent sync protocol (7-step) |
| `AGENTS-GUIDE.md` | CLI + tooling for agents; pairs with root `AGENTS.md` |
| `DOS-DONTs.md` | Short do / don't rules for AI UI |
| `TOKENS.yaml` | Semantic tokens (themed colors, type, space, motion, …) |
| `manifests/registry.json` | Generated index — run `specui sync` |

Also expected in a healthy project:

| File | Purpose |
|------|---------|
| `DECISIONS-LOG.md` | Dated design decisions (ADR-style) |

---

## Front matter (`SPEC.md`)

The key fields:

```yaml
schema: specui
schemaVersion: 0.2.0
product:
  name: "My Product"
themes: ["light", "dark"]
platformsInScope: ["web"]
componentsRequired: [button, card, …]
patternsRequired: [empty-state, …]
readOrder:
  - SPEC.md
  - 00-principles.md
  # … through 11-platform-notes.md
  - DOS-DONTs.md
  - AGENT-DESIGN-RULES.md
  - AGENTS-GUIDE.md
registryIndex: manifests/registry.json
```

`validate` checks that `readOrder` matches the canonical list.

---

## Components

```
.specui/components/<kebab-name>/
  MANIFEST.yaml    # id, status, links, syncTargets
  SPEC.md          # behavior, anatomy, platform notes
  VARIANTS.md      # variant matrix
  STATES.md        # state coverage
  vendor/          # optional — from specui get
```

A component is not valid in code until this folder exists — see [Concepts](/docs/concepts).

---

## Assets

```
.specui/assets/<type>/<kebab-name>/
  MANIFEST.yaml
```

Types: `icon`, `illustration`, `photo`, `logo`.

---

## Patterns

```
.specui/patterns/<kebab-name>.md
```

Multi-step UX flows (confirmation, empty state, validation, …).

---

## Rules and skills (optional)

| Path | Created by |
|------|------------|
| `rules/<name>.md` | `specui rules add` |
| `skills/<name>/SKILL.md` | `specui skills add` |

Location may be at the SpecUI root (flat) or project-relative, depending on layout.

---

## Consumer vs flat

| Layout | Contract root |
|--------|----------------|
| Consumer | `<app>/.specui/` |
| Flat | `<ds-repo>/` ( `SPEC.md` at root ) |

`.specui-sources.yml` lives at the project root (apps only), not inside `.specui/`.

---

## Project root (not inside `.specui/`)

| File | Purpose |
|------|---------|
| `AGENTS.md` | SpecUI block — `specui init --agents-md` |
| `.specui-sources.yml` | Installed / linked sources |

---

## Generated vs hand-edited

Worth internalizing which files are yours and which belong to the tool:

| Hand-edit | Generate |
|-----------|----------|
| Markdown, YAML, manifests | `manifests/registry.json` via `specui sync` |
| `TOKENS.yaml` | Export formats via `specui export` |

---

## Deeper reference

Normative standard: [Specification](/docs/spec).  
Repo maintainer schema doc: [`docs/schema.md`](https://github.com/logicplanes/specui/blob/dev/docs/schema.md).

---

## Next steps

- [Validation](/docs/validation)
- [Agents & MCP](/docs/agents-and-mcp)
- [CLI — add](/docs/cli#register-design-specui-add)

---

# Specification

> The normative SpecUI standard — purpose, layouts, agent protocol, validation.

URL: https://logicplanes.github.io/specui/docs/spec

---
title: Specification
description: 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`](https://github.com/logicplanes/specui/blob/dev/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](https://github.com/google-labs-code/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](/docs/schema) for the full list. In short:

- Numbered `00`–`11`, `TOKENS.yaml`, `DOS-DONTs.md`
- `AGENT-DESIGN-RULES.md`, `AGENTS-GUIDE.md`
- `components/`, `assets/`, `patterns/`
- `manifests/registry.json` (via `sync`)

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)

1. Read the project root `AGENTS.md` (SpecUI block from `specui init`)
2. Read `.specui/SPEC.md` → `readOrder` → `DOS-DONTs.md` and the relevant numbered docs
3. Read `.specui/AGENTS-GUIDE.md` (CLI) and `.specui/AGENT-DESIGN-RULES.md` (sync protocol)
4. Register design before code: `specui add component|asset|token|pattern`
5. After changes: `specui validate && specui sync`
6. Commit `.specui/` with the code that realizes it

Details: [Agents & MCP](/docs/agents-and-mcp).

---

## Validation

`specui validate` reports `error` | `warn` | `info`:

- Missing files, registry integrity, catalog drift
- Optional WCAG contrast on tokens
- `AGENTS.md` block freshness

`--strict` promotes warnings to errors — use it in CI. See [Validation](/docs/validation).

---

## Distribution & interop

- **load / link / update** — consume design systems
- **get** — registry components (shadcn, JSON URLs)
- **export** — Tailwind, CSS, DTCG, DESIGN.md, JSON

[Distribution](/docs/distribution) · [Registries](/docs/registries) · [Interop](/docs/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](/docs/concepts) — tutorial-style mental model
- [Quick start](/docs/quick-start) — hands-on
- [CLI reference](/docs/cli)

---

# Tokens & components

> Register tokens, components, assets, and patterns before you write application code.

URL: https://logicplanes.github.io/specui/docs/tokens-and-components

---
title: Tokens & components
description: Register tokens, components, assets, and patterns before you write application code.
---

Registry-first means you run `specui add` before you write UI in React, Vue, SwiftUI, or anything else. It sounds bureaucratic; in practice it's the only thing that keeps the spec and the code from drifting apart. This guide covers every `add` kind and how they connect to `TOKENS.yaml` and `manifests/registry.json`.

---

## Prerequisites

- A `.specui/` from [Quick start](/docs/quick-start) or `specui init`
- A shell at the project root (the parent of `.specui/`), or pass `--specui <path>`

---

## Components

### Create

```bash
npx specui add component primary-button \
  --variants default,destructive,outline \
  --states default,hover,focus,disabled,loading
```

This creates:

```
.specui/components/primary-button/
  MANIFEST.yaml
  SPEC.md
  VARIANTS.md
  STATES.md
```

Names must be kebab-case. If you omit `--states`, you get the canonical default set.

### Fill in before coding

1. `SPEC.md` — behavior, anatomy, accessibility
2. `VARIANTS.md` — the variant matrix
3. `STATES.md` — every interactive state (required for parity across platforms)
4. `MANIFEST.yaml` — `syncTargets` notes per platform (web, ios, …)

### Vendor reference (optional)

```bash
npx specui get button --force
```

Adds a `vendor/` folder under the component — see [Registries](/docs/registries).

---

## Tokens

### Add semantic tokens

```bash
npx specui add token color.brand.primary "#f54e00" --theme light
npx specui add token color.brand.primary "#ff6b2c" --theme dark
npx specui add token space.section.md "24px"
```

Paths must be semantic (`color.text.primary`, not raw hex names). Themed colors use `--theme`.

### Edit `TOKENS.yaml`

`add token` merges into `.specui/TOKENS.yaml`. Editing the YAML by hand is fine too — just validate afterwards:

```bash
npx specui validate .specui --strict
```

Contrast checks run unless you pass `--no-contrast`. Document token roles in `02-foundations-tokens.md`.

### Export to code

```bash
npx specui export --format css --theme light --to ./src/specui.css --from .specui
npx specui export --format tailwind --theme light --to ./specui.theme.js --from .specui
```

More formats in [Interop](/docs/interop).

---

## Assets

Four types: `icon`, `illustration`, `photo`, `logo`.

```bash
npx specui add asset logo acme-mark \
  --sizes 16,24,32 \
  --modes color,mono \
  --link component:brand-mark
```

Register assets before code references them. Link each one to a component, or document it as `unassigned` in the manifest.

---

## Patterns

Patterns describe multi-step UX — confirmations, empty states, validation flows:

```bash
npx specui add pattern destructive-confirmation
npx specui add pattern empty-state
```

Edit `.specui/patterns/<name>.md` using the template from `AGENT-DESIGN-RULES.md`.

---

## After every `add`

```bash
npx specui sync
npx specui validate .specui --strict
npx specui list components
```

Commit `.specui/` together with the application code that implements the registration — one PR, one story.

---

## Required by preset

`SPEC.md` lists `componentsRequired` and `patternsRequired` from your `--preset`. `validate` fails until those folders exist — either `add` them, or adjust the front matter to match reality.

---

## Flat design-system repo

From the repo root where `SPEC.md` lives:

```bash
npx specui add component chip --variants default
npx specui validate .
```

Same `add` commands; path resolution uses the flat layout when `SPEC.md` is at the root.

---

## Next steps

- [Validation](/docs/validation)
- [Agents & MCP](/docs/agents-and-mcp) — agents must not skip registration
- [CLI — add](/docs/cli#register-design-specui-add)

---

# Troubleshooting

> Common specui errors, validate failures, and how to fix them.

URL: https://logicplanes.github.io/specui/docs/troubleshooting

---
title: Troubleshooting
description: Common specui errors, validate failures, and how to fix them.
---

Most problems here fall into a handful of buckets. Find yours below; if nothing matches, jump to the end.

---

## Installation

### `command not found: specui`

- Use `npx @logicplanes/specui@latest <cmd>`, or install globally with `npm install -g @logicplanes/specui`
- Check you're on Node 18+: `node -v`

### Wrong version in CI

Pin explicitly: `npx -y @logicplanes/specui@2.0.2 validate …`

---

## init

### `.specui already exists`

Use `--force` only if you genuinely intend to overwrite the contract — it's destructive.

### `init --dry-run` errors on themes

Update the CLI — preset list parsing was fixed in recent releases.

### No `AGENTS.md` block

Re-run with `--agents-md`. Check `validate` for `agents-md-block-missing`.

---

## validate

### Missing required component / pattern

`SPEC.md` lists `componentsRequired` / `patternsRequired` from your preset. Either add what's missing:

```bash
npx specui add component <name>
```

or edit the `SPEC.md` front matter to match what you actually ship, then validate again.

### `readOrder` mismatch

Make sure the `readOrder` in `SPEC.md` front matter matches the [Schema](/docs/schema) order, including `AGENTS-GUIDE.md`.

### AGENTS.md block stale

```bash
# Refresh block (avoid --force on .specui unless overwriting)
npx specui init --agents-md --target . 
```

If `.specui` exists, init refuses to overwrite it — use your team's documented refresh flow, or merge the block from the latest `specui` templates.

### Contrast warnings fail `--strict`

Fix the offending token pairs in `TOKENS.yaml`, or adjust the semantic roles in `02-foundations-tokens.md`. As a temporary escape hatch there's `--no-contrast` — but don't leave it in production CI.

### Placeholder values in foundations

Replace `TODO` / template placeholders in the numbered docs and token files.

---

## sync / registry

### Link errors after manual edits

```bash
npx specui sync
```

Fix broken paths in manifests, and make sure `components/<name>/` exists for every registered id.

### `registry.json` out of date in CI

Add a sync + diff check — see [CI/CD](/docs/ci-cd).

---

## get / registries

### Network / registry fetch failed

- Check outbound HTTPS
- Offline, use `specui get --from file:///path/item.json`
- `specui get --list` requires network for shadcn

### Component already exists

Use `--force` on `get` to replace the vendor tree (review the diff afterwards).

---

## load / link / update

### `load` refuses — `.specui` exists

Use `--force`, or `unlink` / remove `.specui` first (back it up with `export`).

### `update` fails validate

Run `specui update --name <source>` and read the validate JSON; fix the design system or your app overrides. `specui diff` shows exactly which tokens changed.

### `push` — not a flat SpecUI

`push` only works when `SPEC.md` is at the repo root (the `specui new` layout).

---

## GitHub Wiki sync

### Sync Wiki workflow: `repository not found` / `.wiki.git`

GitHub only creates the Wiki git backend after you save one page in the UI — until then there is nothing to push to. (The `wiki/` folder in this repo is the source; the Wiki tab is a mirror.)

1. Open https://github.com/logicplanes/specui/wiki/_new  
2. Title it **Home**, add any line, **Save**  
3. Re-run **Actions → Sync Wiki** (or push a change under `wiki/` on `dev`)

The workflow runs `node scripts/sync-wiki.mjs` (all doc pages + `_Sidebar.md`). If the push still fails, add the repo secret `WIKI_PUSH_TOKEN` (a classic PAT with **repo** scope).

---

## Docs site / links

### 404 on `/specui/specui/docs`

Use `/specui/docs/` — don't double the GitHub Pages base path. Fixed in site 2.0.2+.

---

## MCP

### `install-hook` wrote config but the editor ignores it

Restart the editor. If it still doesn't pick it up, run `specui mcp config` and merge the output manually.

### `HTTP transport not yet implemented`

Use the default stdio transport: `specui mcp start`.

---

## Still stuck?

1. `npx specui doctor`
2. `npx specui validate .specui --json --strict`
3. [GitHub issues](https://github.com/logicplanes/specui/issues) with redacted `validate --json` output

---

## Next steps

- [Validation](/docs/validation)
- [CLI reference](/docs/cli)
- [Scenarios](/docs/scenarios)

---

# Validation

> What specui validate checks, strict mode, JSON output, and the doctor command.

URL: https://logicplanes.github.io/specui/docs/validation

---
title: Validation
description: What specui validate checks, strict mode, JSON output, and the doctor command.
---

`specui validate` is the quality gate for every SpecUI contract. If it passes with `--strict`, the contract is in good shape; if it doesn't, the output tells you exactly what to fix.

---

## Basic usage

```bash
npx specui validate .specui
npx specui validate .specui --strict
npx specui validate .specui --json
```

The path can be:

- A directory: `.specui` or `./my-app/.specui`
- A file inside the contract: `validate` resolves to the parent folder

For a flat repo, validate from the root where `SPEC.md` lives:

```bash
npx specui validate .
```

---

## Flags

| Flag | Effect |
|------|--------|
| `--strict` | Treat warnings as errors (recommended in CI) |
| `--json` | Emit structured findings for tooling |
| `--no-contrast` | Skip WCAG contrast checks on `TOKENS.yaml` |
| `--no-agents-check` | Skip `AGENTS.md` block checks |
| `--target <path>` | Explicit contract root |

---

## What gets checked (overview)

| Area | Examples |
|------|----------|
| Required files | `SPEC.md`, numbered `00`–`11`, `AGENT-DESIGN-RULES.md`, `AGENTS-GUIDE.md`, legal files |
| readOrder | Front matter matches the expected file list |
| Registry | Component/asset/pattern folders, manifests, broken links |
| SPEC front matter | Required components/patterns from the preset exist |
| Tokens | Structure, placeholders, optional contrast |
| AGENTS.md | SpecUI block present, current, attribution intact |
| Custom rules | Project `rules/` consistency |
| Catalog drift | Lists in `04-components.md` vs the filesystem |

Findings come in three severities: error (fails the build), warn (fails with `--strict`), and info.

---

## sync vs validate

| Command | Purpose |
|---------|---------|
| `sync` | Rebuild `registry.json`, report link errors |
| `validate` | Full schema + policy checks |

Typical sequence after edits:

```bash
npx specui sync && npx specui validate .specui --strict
```

---

## doctor

A human-friendly summary before you dig into validate output:

```bash
npx specui doctor
npx specui doctor --json   # forwards JSON validate output
```

It reports the layout (consumer vs flat), AGENTS.md status, counts, rules/skills, sources — then runs validate.

Exits 1 if validate fails.

---

## CI recommendation

```bash
npx -y @logicplanes/specui@latest validate .specui --strict
```

See [CI/CD](/docs/ci-cd).

---

## Fixing failures

See [Troubleshooting](/docs/troubleshooting) for common codes and fixes.

---

## Next steps

- [Schema](/docs/schema) — file-level reference
- [Specification](/docs/spec) — normative rules
- [Agents & MCP](/docs/agents-and-mcp) — `--json` for agents

---

End of SpecUI documentation. See https://logicplanes.github.io/specui/docs/ for the rendered site.