Skip to content

Design Workflow

Step-by-step guide for the NepWalk design process. Follow this order every time.

One-time setup after cloning nepwalk-design

After every git clone of the nepwalk-design repo — on any OS (Linux, macOS, WSL, or Windows via Git Bash) — run:

bash scripts/install-hooks.sh

This enables the project's git pre-commit hook. Once enabled, editing an agent file in any tool directory (.claude/agents/, .opencode/agents/, or .codex/agents/) produces a consistent commit on every OS — the hook auto-syncs the canonical .claude/agents/*.md files into the other two tool dirs before the commit is finalized.

Skip this step and your commits may drift — your .opencode/agents/ and .codex/agents/ could fall out of sync with .claude/agents/, breaking the experience for teammates using OpenCode or Codex.

Windows note: the bash interpreter is provided by Git Bash, which is installed automatically with Git for Windows. No extra setup is needed.

The verification block (how every step ends)

After every prefix command (design: system, design: component, design: page, etc.) the AI agent prints a verification block as its final output and then stops:

✅ Wrote: <path under nepwalk-docs>
🎨 Stitch URL: <url or "n/a (not a visual step)">
⏸  Verify both before the next step:
     1. Open the file above in nepwalk-docs and confirm contents.
     2. Open the Stitch URL and confirm the visual matches the spec.
   Reply "verified" to continue, or describe issues to iterate.

Your job at this point:

  1. Open the listed doc(s) in nepwalk-docs and read them end-to-end.
  2. Click the Stitch URL and confirm the visual matches the spec.
  3. Reply verified to move to the next step, or describe what to change.

The agent will not auto-chain to the next step. This is intentional — every step requires human verification before the next one runs.

Prerequisites

Before any design work starts, check that these exist in nepwalk-docs:

  • docs/management/mvp/v1/prd_v1.md — features, personas, user flows
  • docs/management/mvp/v1/user_story_v1.md — acceptance criteria

If missing: tell the team and wait. Design cannot start without these.

Where your tasks live

All design tasks live in a single, management-owned document:

docs/management/mvp/v1/task_division_v1.md

Open it and scroll to the ### Design section — those are your tasks.

Rules of engagement:

  • Management owns scope. They add/remove tasks and set deadlines.
  • Design owns status. You update pending → in_progress → done (or skipped with a reason) on rows in the ### Design section.
  • Edit your section only. Never modify rows in ### Backend, ### Frontend, ### QA, etc. — Brand Guardian flags cross-section edits as BLOCKED.
  • One PR per status batch. Mark the rows you've completed, open a PR to nepwalk-docs, get it reviewed, merge.

There is no design-local task_division copy. The management doc is the single source of truth.

Step 1 — Design System

Command: design: system [context]

What happens:

  1. AI interviews you about brand, colour, typography, spacing, motion
  2. AI writes three files:
  3. docs/design/mvp/design_system.md — human-readable spec
  4. docs/design/mvp/design_tokens.css — CSS custom properties for frontend to import
  5. docs/design/mvp/stitch_context.md — shared context block prepended to every Stitch prompt
  6. AI generates a token preview in Stitch
  7. You verify all three files look correct — confirm before proceeding

Done when: all three files are generated and you have confirmed them.

This step must be completed before anything else.

⚠️ Non-Claude users: After this step completes, you may need to manually confirm the three output files were created. If design_system.md is later updated, run design: sync-tokens manually to regenerate design_tokens.css and stitch_context.md.

⚠️ If tokens change later: Run design: sync-tokens to re-sync design_tokens.css and stitch_context.md without repeating the interview.

Step 2 — Component Catalog

Command: design: catalog [context]

What happens:

  1. AI reads PRD features and auto-derives required components
  2. AI interviews you: navigation pattern, form patterns, data display choices
  3. AI writes docs/design/mvp/component_catalog.md

Done when: all components are listed with variants, states, and atomic level (atom/molecule/organism).

No Stitch generation at this stage. That happens per-component in Step 3.

Step 3 — Component Screens

Command: design: component <name> or design: component all

What happens (per component):

  1. AI interviews you: variants needed, states, sizes, React props
  2. AI generates a Stitch component sheet prompt (with stitch_context.md prepended)
  3. AI invokes Stitch MCP → component sheet showing ALL variants × ALL states
  4. You verify the sheet looks correct — confirm before moving to next component
  5. URL recorded in component_catalog.md, exports/index.md, and stitch_library.md

Order matters:

  • Atoms first (Button, Input, Badge, Icon, Avatar, Toggle, Spinner, Toast)
  • Molecules second (FormField, TimelineItem, TripCard, etc.) — only after all atoms done
  • Organisms third (NavigationBar, ItineraryBuilder, etc.) — only after all molecules done

design: component all runs in the correct order automatically.

Done when: every component in the catalog has ✅ in stitch_library.md.

⚠️ Non-Claude users: After each design: component run, manually update stitch_library.md — find the component row and paste the Stitch URL.

Step 4 — User Flows (parallel with Step 3)

Command: design: flows

What happens:

  1. AI reads all user story epics from user_story_v1.md
  2. AI generates mermaid flow diagrams (one per epic)
  3. AI writes docs/design/mvp/user_flows_v1.md

Done when: every epic has a flow diagram with decision points and error paths.

Step 5 — Information Architecture (parallel with Step 3)

Command: design: ia [context]

What happens:

  1. AI checks if management already created an IA doc (in SRS or elsewhere)
  2. AI interviews you: pages, routes, nav structure, auth gates, deep links
  3. AI writes docs/design/mvp/information_architecture_v1.md

Done when: all pages are listed with routes, auth requirements, and nav hierarchy.

Step 6 — UX Research (optional, any time)

Command: design: ux-research [context]

What happens:

  1. UX researcher agent interviews you about research findings
  2. Agent writes docs/design/mvp/ux_research_v1.md

Run this before page specs if you have user research to incorporate.

Step 7 — Page Specs

Command: design: page <name> [context]

Prerequisites:

  • design_system.md exists (Step 1)
  • component_catalog.md exists (Step 2)
  • All organisms used on this page have Stitch URLs (Step 3)
  • user_flows_v1.md exists (Step 4)

What happens:

  1. AI interviews you: layout, states, interactions, validation rules
  2. AI writes the page spec: docs/design/mvp/pages/<name>_spec_v1.md
  3. AI generates a Stitch page prompt (stitch_context.md prepended; component URLs from stitch_library.md)
  4. AI invokes Stitch MCP → full mobile screen
  5. You verify the screen looks correct — confirm before moving to next page
  6. URL recorded in page spec frontmatter, exports/index.md, and stitch_library.md

Done when: page spec is written and page row in stitch_library.md shows ✅.

⚠️ Non-Claude users: After each design: page run, manually update stitch_library.md — find the page row and paste the Stitch URL.

Page order (recommended): Login → Dashboard → Trip Detail → Itinerary → Members → Share → Packages → Notifications → Profile → Settings

Step 8 — Publish

Command: design: publish <file>

What happens:

  1. Brand Guardian agent runs pre-publish checklist automatically
  2. If BLOCKED: you fix the issues listed, then re-run design: publish
  3. If APPROVED (or APPROVED WITH WARNINGS): doc status changes to review
  4. PR opened to nepwalk-docs

Done when: PR is merged.

Status Definitions

Status Meaning Who sets it
draft Work in progress AI (automatic on creation)
review Ready for human review AI via design: publish
approved Reviewed and signed off Human (never AI)

Quick Reference

Task Command
Step-by-step status + next action design_status: (aliases: what next?, next, ?)
Update PROJECT_STATE.md state:
Generate design system (3 outputs) design: system
Re-sync tokens without re-interview design: sync-tokens
Generate component catalog design: catalog
Generate one component screen design: component <name>
Generate all component screens design: component all
Refine a Stitch output with feedback design: refine <name> [feedback]
Generate user flows design: flows
Generate information architecture design: ia
Run UX research design: ux-research
Generate a page spec design: page <name>
Run Brand Guardian across all docs design: validate
Print page progress board design: status-board
Generate frontend developer brief design: export-brief <page>
Generate tailwind.config.ts tokens design: tailwind-config
Publish a doc design: publish <file>
Dispatch specialist agent design: agent <slug> <task>

Non-Claude tools — manual steps required

If you are using OpenCode, Codex, Cursor, or any tool without Claude Code hooks, these actions do NOT run automatically. Run them manually:

After this action Run manually
design: system completes Verify design_tokens.css and stitch_context.md were created
design_system.md is updated design: sync-tokens
design: component <name> completes Update stitch_library.md row with Stitch URL
design: page <name> completes Update stitch_library.md row with Stitch URL
Any spec file is saved design: validate (Brand Guardian pre-check)
Ready to share with frontend design: export-brief <page> for each page

Claude Code runs these automatically via hooks (configured in .claude/settings.json). Other tools do not have this file or do not execute shell hooks.