Design Lifecycle

1. Discovery

Discovery is the initial exploration of user needs, existing patterns, and design constraints. During this stage the UX designer gathers research inputs — personas, user journeys, competitive benchmarks — and identifies the key interaction surfaces the project will need. Discovery feeds directly into the questionnaire that captures concrete design parameters.

Run /gaia-create-ux to begin the discovery process. The command creates or binds two Claude Design projects: the design-system project managed through DesignSync (tokens, reusable components, reusable page templates), and the product design project managed through the Design artifact surface (screens, flows, the /design command). Discovery walks through a structured conversation that covers user research, information architecture, and interaction patterns.

2. Questionnaire

The questionnaire stage collects the structured inputs that drive the design specification: target devices, accessibility requirements, brand constraints, component library preferences, and interaction patterns. The questionnaire output becomes the authoritative design brief that the rest of the lifecycle works against.

The questionnaire runs as part of /gaia-create-ux. Its answers feed only the design-system project; the product design project receives no content during this phase. The questionnaire answers are recorded in the design specification artifact and referenced by downstream stages.

3. Publication

Publication is the act of writing the design specification and making it available for review. The specification covers wireframes, interaction flows, component inventories, accessibility annotations, and responsive breakpoints. Once published, the design record tracks the specification's provenance and version.

The design record at .gaia/state/design-record.yaml captures who created the specification, when it was published, and which version of the source it was built from.

Each publication pass persists the file set and content hashes at .gaia/state/design-last-published.json. This persisted manifest is read on subsequent publications for conflict detection and orphan identification. The design-system manifest (_ds_manifest.json) is rebuilt after each publication so that every published specification appears as a browsable card.

Screens are published to the product design project via the Artifact tool. Component specs remain in the design-system project. Each published screen carries the design-system token values as :root{--token:value} CSS custom-property blocks (the token-by-value model). Because every screen carries the full resolved token block, a token change also republishes the screens of the product design project, after the design-system project. The canvas designSystems list stays empty — this is the expected state. A reserved future mode (artifact-installed) would install a Design System artifact into the canvas instead. After the first screens are published, the framework verifies the canvas index read to confirm the expected state.

When the stack does not include React, the design system is built as a brand-style artifact (fonts, colors, guidelines) instead of a compiled component bundle. The product design project is created regardless of sync mode.

4. Review

Review is a structured walkthrough of the published design with stakeholders. The /gaia-design-review command drives this stage: it loads the design specification, runs a rubric-guided review, and records the reviewer's findings. Review can iterate — each round produces a new set of findings that the designer addresses before requesting another review.

During review, designer-side component changes are read from the design-system project and reconciled into the derived UX design document via delta sync. Screen-level changes are read from the product design project, detected by comparing content hashes against the persisted publication manifest, and reported to the user with full content — screen prose is not auto-edited.

The dev agent and reviewers read tokens and components from the design-system project and screens from the product design project. When there is no product design project, they report “no screens available”.

5. Approval

Approval marks the point where stakeholders agree the design is ready for implementation. The approval verdict is recorded in the design record as design_state: approved with a timestamp and the approver's identity in the approvals list. Once approved, the design becomes the binding contract that solutioning works against.

An approved design unlocks the solutioning phase: architecture, threat modelling, infrastructure design, and epic decomposition can proceed. Without approval, every solutioning entry point refuses to start.

Approval requires at least one design/ux-tagged stakeholder in the roster. The convergence check reads the stakeholder roster from both .gaia/custom/stakeholders/ and custom/stakeholders/ (merged, with .gaia/ taking precedence per slug). Without a tagged approver, the gate halts with a remediation naming /gaia-create-stakeholder. An empty or missing roster never satisfies convergence. The roster reader refuses symlinked roster directories, files, and parent path components. A stakeholder file whose name contains a tab or newline character is skipped with a warning.

6. Gate and Override

The design approval gate is enforced at every solutioning entry point. A single composite approval state covers both the design-system project and the product design project. The gate reads only local state (zero integration calls) and checks three conditions: the design record must be in the approved state, stakeholder convergence must be satisfied, and review coverage must include every project the design record references. When a review did not cover a referenced project, the gate halts with a remediation directing the user to run /gaia-design-review. Remediation names both projects and their surfaces (DesignSync for the design-system project, the Design artifact surface for the product design project).

In exceptional cases the gate can be overridden using the force-design flag. An override is an audited event: the design record logs the override reason (control characters in the reason text are neutralised before storage), the person who authorised it, the timestamp, and the sprint scope (sprint_id). When the override succeeds, a notice is surfaced to the developer with the current design state, the reason, and a warning that the UX document may be outdated. Overrides are visible in the sprint review and in the design record history.

Note: the two-record consistency check that compares the gate classification against the implementation-status ledger is a drift detector. It catches cases where one record was updated without the other, but it does not prove either record is correct. Both records can agree and still be wrong. Treat its output as a quality signal, not a proof of correctness.

7. Stale on Change

A design that was approved can become stale if the project changes in ways that affect the design assumptions. When a design-affecting change lands — a new user journey, a modified data model, a revised set of target devices — the framework marks the design record as stale. Stale transitions are triggered by /gaia-edit-ux (always, since a direct UX edit is design-affecting) and by /gaia-add-feature (when the feature is design-affecting or ambiguous). A stale design blocks solutioning just as an unapproved design does: the gate fires with the same halt as any other non-approved state, and the design must be re-approved through a review round.

To clear the stale state, run /gaia-design-review again. The review stage examines whether the change invalidates the existing design or whether the design still holds. If it still holds, the reviewer re-approves it and the gate clears.

When the stale transition completes with the Claude Design integration available, the changed specifications are republished based on scope: a token or component change republishes to the design-system project, a screen or flow change republishes to the product design project, and when both are affected the design-system project is republished first. Because each screen carries the full resolved token block, a token change also refreshes the screens of the product design project. The republish step reads the last-published manifest for conflict detection: files changed by both the framework and a designer are surfaced as conflicts rather than silently overwritten. When the manifest does not exist (projects published before manifest tracking), every differing remote file is treated as a conflict to confirm.

Both /gaia-create-ux and /gaia-design-review check whether the Claude Design integration is available before their first project call. A missing integration halts with a remediation naming the DesignSync tool surface. An unauthorized integration halts with a remediation covering both /design-login (API-token sessions) and granting design access when prompted (claude.ai sessions).