/gaia-design-review

What it does

/gaia-design-review reads the design-system project back through DesignSync and the product design project through the Artifact tool, reviews screens and components against the UX design document and accessibility rules, and drives an iterative stakeholder approval loop. A combined verdict covers both projects -- a failure in either project fails the review. Findings are severity-tagged. Verdicts are recorded through the sole design-record writer. When a stakeholder comment implies a requirement change, the loop halts and routes through the feature intake workflow. When product_design_project is null, the review skips the product-project read and notes the absence.

When to use it

• After a design project has been created and published via /gaia-create-ux.
• When stakeholder review and approval of the design is needed.
• To reconcile designer-side changes back into the derived UX design document.

Prerequisites

• UI-present gate. compliance.ui_present must be true in project config.
• Design record. A design record must exist at .gaia/state/design-record.yaml.
• UX design document. The UX design must exist at .gaia/artifacts/planning-artifacts/ux-design.md.

How to invoke

/gaia-design-review

What it does step by step

1. Read-back If the design record is stale, the review first transitions it to review, starting a new approval round; the iteration counter bumps so earlier approvals no longer count. Reads the design-system project through DesignSync and the product design project through the Artifact tool as the authoritative sources, wrapping content in data boundary markers.
2. Findings Compares project content against the UX design document and accessibility rules. Emits severity-tagged findings (high, medium, low, info). Missing required components are findings in this same pass. A failure in either project fails the review.
3. Internal review Records an internal verdict before any stakeholder sees the findings. High-severity findings block stakeholder delivery unless the user explicitly accepts them.
4. Stakeholder delivery Re-reads both projects for current state. Presents findings to each stakeholder. Records their verdict (approved, changes-requested, or escalated) through the sole writer.
5. Convergence and transition Checks convergence before transition. On full approval: transitions to approved. On changes requested: bumps iteration. On escalation: halts and routes to feature intake.
6. Delta sync Reconciles designer-side component changes from the design-system project into the derived UX design document. Matches the template's components heading (both & and and variants, case-insensitive). Screen changes are read from the product design project, reported with their full content for manual review, not auto-edited. A design-system token change that affects a published screen produces a reconciliation finding flagging the product design project for update.
7. Iteration loop Returns to Step 1 for each new iteration until the design is approved or escalated.

Inputs

Outputs

Example session

> /gaia-design-review

Reading design-system project via DesignSync... 12 components loaded.
Reading product design project via Artifact tool... 3 screens loaded.

Findings (4 total):
  [high] Missing UX-required component: navigation-drawer
  [medium] Spacing inconsistency on the settings screen
  [low] Button border radius differs from design system token
  [info] Consider adding hover states to card components

Internal review: changes-requested (1 high-severity finding)
High-severity findings block stakeholder delivery.
Accept findings and proceed? [y/n]

What to run next

• /gaia-create-ux — create or update the UX design document.
• /gaia-validate-design-a11y — run an accessibility audit against the design.
• /gaia-add-feature — process an escalated requirement change.

Troubleshooting

Skill skips with "compliance.ui_present is not true"

Set compliance.ui_present: true in project config via /gaia-config-compliance.

No design record found

Create a design project first with /gaia-create-ux, which initializes the design record.

Convergence reports "vacuous"

No stakeholders are tagged with design or ux tags. The review halts — a design/ux-tagged approver is required. Create one with /gaia-create-stakeholder using a design or ux tag. The roster is read from .gaia/custom/stakeholders/ and custom/stakeholders/ (both locations are merged, with .gaia/ taking precedence per slug).

Integration unavailable or unauthorized

The review halts before any record transition or read-back when the Claude Design integration cannot be reached or is not authorized. If missing, use a Claude Code session that exposes the DesignSync tool surface. If unauthorized, run /design-login (API-token sessions), or grant design access when prompted (claude.ai sessions).

Artifact read fails or returns a summary

When a per-file read of the product design project fails or returns a summary instead of structured content, the review halts with a diagnostic naming the Artifact surface. No partial verdict is recorded.

Design Lifecycle

For the full design lifecycle including discovery, publication, and the approval gate, see the design lifecycle overview.

Related commands

• /gaia-create-ux — creates the UX design and initializes the design record.
• /gaia-validate-design-a11y — accessibility validation for the design.
• /gaia-review-all — runs all review workflows including this one.