/gaia-create-ux

What it does

/gaia-create-ux creates UX design specifications from your PRD. It begins with design-system discovery (searching project artifacts and existing Claude Design projects), runs a stakeholder questionnaire when no design system is found, creates or binds the design-system project from the answers via DesignSync (create_project, finalize_plan, write_files), then creates or binds the product design project via the Design artifact surface (the Artifact tool). After both projects exist, it covers persona refinement, information architecture (sitemap and navigation), wireframes, interaction patterns, accessibility standards, and publishes screen specifications to the product design project and component specs to the design-system project. When the stack does not include React, the design system is built as a brand-style artifact (fonts, colors, guidelines); the product design project is created regardless.

When to use it

• Your PRD is complete and your product has a user interface.
• You want to define UX patterns and accessibility standards before architecture or implementation.

Prerequisites

• PRD must exist at .gaia/artifacts/planning-artifacts/prd.md.
• Claude Design integration available for design-system discovery and publication.
• Design artifact surface (Artifact tool) available for creating and publishing to the product design project.

Orchestration mode

When /gaia-create-ux starts in subagent mode (Mode A -- the default), the framework emits a one-shot warning to your conversation. The warning text:

────────────────────────────────────────────────────────────────────────────
GAIA orchestration: running in subagent mode (Mode A)

The skill you're invoking belongs to a class (heavy-procedural or
conversational) whose output benefits from cross-step context. Mode A
dispatches each sub-agent in its own forked context, so context may
be lossy between steps — sub-agents return summaries, not full reasoning.

For the full-fidelity experience, enable Mode B (Agent Teams):
  1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment.
  2. Add orchestration.mode: team to .gaia/config/project-config.yaml.

Mode B uses persistent teammates that preserve in-conversation state
across dispatches.

This warning is shown once per session.
────────────────────────────────────────────────────────────────────────────

Why Mode B is better for this command

The /gaia-create-ux skill declares orchestration_class: heavy-procedural in its SKILL.md frontmatter. Heavy-procedural skills produce output that benefits from cross-step context -- under Mode A every sub-agent dispatch runs in its own forked context and can only return a summary back to the orchestrator, losing the full reasoning trace of every prior step. Mode B uses persistent teammates that retain in-conversation state across dispatches, so each agent's contribution can build on what was said before instead of receiving only a summary.

How to enable Mode B

Both steps are required. If either is missing, the framework falls back silently to Mode A and the warning fires again on the next session.

Step 1 -- set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add this to your shell rc file to persist across sessions, or set it in Claude Code's settings.json.

Step 2 -- add the YAML block to .gaia/config/project-config.yaml:

orchestration:
  mode: team

One-shot semantics

The warning is emitted once per Claude Code session. A marker file at .gaia/memory/checkpoints/orchestration-warning-shown.<session-id> suppresses the warning for the rest of the session. Starting a new session re-emits the warning once.

How to invoke

/gaia-create-ux

What it does step by step

1. Load PRD Reads the PRD and extracts user personas, user journeys, and functional requirements.
2. Design-system discovery Searches project artifacts and existing Claude Design projects for a design system. Presents candidates for explicit user selection.
3. Stakeholder questionnaire When no design system is found, interviews the stakeholder on colors, logo, typography, spacing, style, components, and platforms. The questionnaire feeds only the design-system project. Skipped when a design system is already bound.
4. Project creation Creates or binds the design-system project via DesignSync from the questionnaire answers, then creates or binds the product design project via the Artifact tool. When binding an existing project, the user confirms with “Bind this project”. Records both project identities in the design record.
5. User personas Refines persona definitions from the PRD. Adds scenarios, goals, tech proficiency, and accessibility needs.
6. Information architecture Designs the sitemap and navigation structure. Maps each page to the functional requirements it serves.
7. Wireframes Creates text-based wireframe descriptions for key screens with layout, component placement, and interaction patterns.
8. Interaction patterns Defines common UI patterns, component library choices, form behaviors, validation, and error states.
9. Accessibility Defines WCAG compliance targets, keyboard navigation plan, screen reader support, and color contrast standards.
10. Screen specification publication Publishes screen specifications to the product design project via the Artifact tool and component specs to the design-system project via DesignSync, with read-before-write conflict detection. After publication, the design-system manifest is refreshed so published specs appear as cards in Claude Design. The last-published manifest is persisted for conflict detection on subsequent runs.
11. Generate output Writes the UX design document with the design record reference.
12. Val auto-fix loop Validates the artifact and applies fixes if needed.
13. Accessibility review (optional) Optionally reviews the design for WCAG 2.1 compliance.

Inputs

Outputs

Example session

> /gaia-create-ux

Loading PRD... 3 personas, 5 user journeys, 22 FRs.

Design-system discovery: no existing design record found.
Pass 2: 1 Claude Design project found.
  id:            proj-abc123
  name:          Acme Design System
  last_modified:  2026-09-20
> Bind this project
Design-system project bound.

Questionnaire skipped (design system already bound).

Product design project: no existing reference found.
1 existing Design artifact found:
  My App Screens (last modified 2026-09-22)
Pick an existing project, or create a new one?
> Create a new one
Product design project created.

Personas refined: added accessibility needs and tech proficiency.
Information architecture: 12-page sitemap mapped.
Wireframes: 8 key screens described.
Interaction patterns: 6 patterns defined.
Accessibility: WCAG 2.1 AA target set.

Components published to design-system project.
Screens published to product design project.
UX design written to: .gaia/artifacts/planning-artifacts/ux-design.md

What to run next

• /gaia-validate-design-a11y -- validate the design for accessibility.
• /gaia-create-arch -- design the system architecture.

Troubleshooting

"PRD not found"

Run /gaia-create-prd first.

I keep seeing the GAIA orchestration warning every time I start this command

The warning is shown once per session, so if it fires again that's a new session -- not a per-skill repeat. If you want to silence it entirely, enable Mode B (full-fidelity orchestration via Agent Teams). Both of these conditions must be true:

• echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS returns 1 (not empty)
• .gaia/config/project-config.yaml contains:

  orchestration:
    mode: team

If either is missing the framework silently uses Mode A and re-emits the warning each session.

Claude Design integration unavailable or unauthorized

The skill halts before any project call when the 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).

Design artifact surface unavailable or unauthorized

The product design project requires the Design artifact surface (Artifact tool). If missing: the skill halts with “The Design artifact surface (Artifact tool) could not be reached — ensure the Artifact tool is available in this session.” If unauthorized: the skill halts with “The Design artifact surface requires authorization — follow the authorization prompt and re-run.”

Related commands