project-design

Works with the dual-diamond architecture: reads brand system from .design/branding/{brand}/system/ via brand.ref, reads/writes project assets in .design/projects/{project}/.

Input: Research + brief + brand system + project BRIEF.md Output: {project}/design/ (screen chunks + shared/ + INDEX.md) + exports/INDEX.md update Agent: gsp-designer

<execution_context> @${CLAUDE_SKILL_DIR}/../../prompts/03-ui-ux-pattern-master.md @${CLAUDE_SKILL_DIR}/../../templates/phases/design.md @${CLAUDE_SKILL_DIR}/../../references/apple-hig-patterns.md </execution_context>

Scan .design/projects/ for project directories. If only one project exists, use it. If multiple, ask the user which project to work on.

Set PROJECT_PATH = .design/projects/{project}

Read {PROJECT_PATH}/brand.ref to resolve brand path:

• Set BRAND_PATH = .design/branding/{brand}

Step 1: Load context

Read {PROJECT_PATH}/config.json — get implementation_target, design_scope, codebase_type. Read {PROJECT_PATH}/BRIEF.md — app type, audience, goals.

Revision mode

Check {PROJECT_PATH}/STATE.md for design status. If status is needs-revision:

1. Read {PROJECT_PATH}/critique/prioritized-fixes.md — design issues to address
2. Read {PROJECT_PATH}/critique/accessibility-fixes.md — accessibility issues to address
3. Log: "🔄 Revision mode — addressing critique issues from prioritized-fixes.md"
4. Pass critique fixes to designer agent in Step 3

Custom references

If {PROJECT_PATH}/references/ exists, scan for files (images, PDFs, markdown, URLs). Pass any found references to the designer agent as additional context.

Brand system (chunk-first)

Read {BRAND_PATH}/system/INDEX.md. If it exists, load all foundation chunks + selective component chunks.

Fallback: read {BRAND_PATH}/system/SYSTEM.md (legacy monolith). Log: "⚠️ Legacy system format detected — consider re-running /gsp:brand-patterns for chunk output."

If neither exists, tell the user to run /gsp:brand-patterns first.

Brand context (selective)

Read {BRAND_PATH}/identity/INDEX.md. If it exists, load color-system.md and typography.md. Fallback: read {BRAND_PATH}/identity/IDENTITY.md.

Brief (chunk-first)

Read {PROJECT_PATH}/brief/INDEX.md. If it exists, load scope.md and target-adaptations.md.

If brief doesn't exist, proceed without it (brief is informative, not blocking).

Research (chunk-first)

Read {PROJECT_PATH}/research/INDEX.md. If it exists, load ux-patterns.md, recommendations.md, and reference-specs.md.

If research doesn't exist, proceed without it (research is informative, not blocking).

Step 1.5: Scope check

If design_scope is tokens:

1. Update {PROJECT_PATH}/STATE.md — set Phase 3 (Design) status to skipped
2. Display: "Design phase skipped — design scope is tokens."
3. Route: "Run /gsp:project-build."
4. Stop here.

If design_scope is partial: Read BRIEF.md "Target screens" to get the specific screen list.

Step 2: Load existing design system context

When implementation_target is not figma:

• If .design/system/COMPONENTS.md and .design/system/TOKENS.md exist, read them. Pass to the agent.
• If not, fall back to scanning the codebase.

Step 3: Spawn designer

Spawn the gsp-designer agent with all prior artifacts, the UI/UX Pattern Master prompt (03), design output template, Apple HIG patterns reference, implementation_target, design_scope, codebase_type, target screens (when partial), existing components inventory, custom references (when available), and critique fixes (when in revision mode).

Output path: {PROJECT_PATH}/design/

The agent writes chunks directly:

• design/screen-{NN}-{name}.md (one per screen)
• design/shared/ (personas, IA, navigation, micro-interactions, responsive, component-plan)
• design/preview.html (self-contained wireframe preview)
• design/INDEX.md
• Updates {PROJECT_PATH}/exports/INDEX.md (design section)

Step 4: Update state

Update {PROJECT_PATH}/STATE.md:

• Set Phase 3 (Design) status to complete
• Record completion date

Step 5: Phase transition output

Render the phase transition screen (see references/phase-transitions.md for styling):

  ◆ design complete — screens designed

    design/
    ├── {actual screen chunks}
    ├── shared/
    │   ├── {shared chunks}
    │   └── component-plan.md
    ├── preview.html
    └── INDEX.md

  ──────────────────────────────

Then use AskUserQuestion with 3 options:

• Continue to critique — "critique designs + accessibility audit"
• View progress — "see the full dashboard"
• Done for now — "pick up later with /gsp:start"