Skip to content

Review Process

How design docs move from draft to approved.

Stages

draft  →  review  →  approved
Stage Who sets it What it means
draft AI (automatic on creation) Work in progress. May be incomplete.
review AI via design: publish <file> Complete, passed Brand Guardian check, PR open
approved Human reviewer only Reviewed, signed off, ready for frontend

AI cannot set approved. Only a human reviewer can do that.

How to publish a doc (move to review)

Run: design: publish <file>

What happens automatically:

  1. Brand Guardian agent runs the full pre-publish checklist
  2. If BLOCKED: you see a list of issues to fix. Fix them, then re-run design: publish.
  3. If APPROVED WITH WARNINGS: doc moves to review. Warnings appear in the PR description.
  4. If APPROVED: doc moves to review. PR opened to nepwalk-docs.

Brand Guardian checklist (what gets checked)

See Accessibility and the full list in design_skill.md.

Quick summary:

  • Token discipline: no raw hex in specs, all tokens valid
  • Accessibility: contrast, touch targets, labels, aria
  • Mobile-first: 375px layout first, bottom nav always visible
  • Completeness: all 5 page states, Stitch URL filled, user story IDs real

Who reviews what

Doc Reviewer Notes
design_system.md Design lead + one frontend lead Frontend must agree on token names before they start
component_catalog.md Design lead All components confirmed before Stitch generation
user_flows_v1.md Design lead + product manager Flows must match user stories
information_architecture_v1.md Design lead + product manager Routes agreed with frontend before page specs start
ux_research_v1.md Design lead Research findings reviewed for accuracy
pages/<page>_spec_v1.md Design lead + relevant developer Dev confirms data requirements and API match

PR rules

  • One PR per doc (or a batch of closely related docs)
  • PR title format: design: <doc-name> v<N> (e.g., design: design_system v1)
  • PR description: include what changed, any Brand Guardian warnings, Stitch URL
  • Do not bundle design doc PRs with code PRs
  • Merge only after approved status is set

What to do when a doc changes after approval

  1. Make the change in the doc.
  2. Update last_updated in the frontmatter.
  3. Reset status: draft.
  4. Run design: publish <file> again.
  5. Open a new PR.

For page specs: if the spec changes, the Stitch URL is likely stale. Regenerate the Stitch screen too.