Name: SpecUI
Author: SpecUI

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)

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

Pin the CLI for reproducibility:

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:

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

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:

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

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)

# .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:

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 — what --strict enforces
Troubleshooting — fix common CI failures
Agents & MCP — --json for agents

CI/CD