Name: SpecUI
Author: SpecUI

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:

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.

Schema