Name: SpecUI
Author: SpecUI

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

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:

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:

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

doctor

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

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

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

See CI/CD.

Fixing failures

See Troubleshooting for common codes and fixes.

Next steps

Schema — file-level reference
Specification — normative rules
Agents & MCP — --json for agents

Validation