Name: SpecUI
Author: SpecUI

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:

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

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 — hands-on
Scenarios — pick a workflow
Schema — every file in .specui/
Specification — normative standard summary

Concepts