schema

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:

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.

---

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.
Repo maintainer schema doc: docs/schema.md.

---

Next steps

• Validation
• Agents & MCP
• CLI — add