claudecode-boilerplate/.claude/commands/define-design.md

description
Create the UI/UX design specification (design brief, tokens, UI blueprint, platform mapping, SVG wireframes)

Define Design (UI/UX Design Phase)

This command creates (or updates) the project's design specification under docs/design/. The design is AI-readable and implementation-ready: the source of truth is structured text/JSON, not visual images.

Design source of truth: docs/design/ui-blueprint.json Visual references only: docs/design/screens/*.svg

How to Run

claude
> /define-design

Position in the Workflow

/setup-project
  ↓
/define-design        ← you are here
  ↓
/generate-app web | flutter | winui3
  ↓
/plan-milestones
  ↓
/add-feature

Pre-Run Check

1. Confirm the persistent documents exist. If any of these are missing, stop and tell the user to run /setup-project first:
   • docs/product-requirements.md
   • docs/functional-design.md
   • docs/architecture.md
2. Create the design directory if it does not exist:

   mkdir -p docs/design/screens
   

Procedure

Step 0: Read the Inputs

Read all of the following to understand what is being built:

• docs/product-requirements.md
• docs/functional-design.md
• docs/architecture.md
• docs/repository-structure.md
• docs/development-guidelines.md
• docs/glossary.md
• docs/ideas/* (if present)

Step 1: Gather Design Preferences (ask the user once)

Ask the user about the following. If the user does not provide detailed preferences, propose a sensible default derived from the product requirements and confirm it before proceeding.

• Target platform: web, flutter, winui3, or multi
• Visual style (e.g. friendly/modern/rounded/calm, dark or light, density)
• Main screens the app must have (treat the answer as additions and constraints — the complete screen list is derived from the PRD in Step 3, never limited to what the user names here)
• Navigation style (e.g. tab bar, drawer, sidebar, stack)
• Branding preferences (name, colors, tone)
• Accessibility requirements (e.g. WCAG level, minimum contrast, large-touch targets)

Collect the answers in a single round; do not pause again until generation is complete.

Step 2: Load the Design Skills

• Load the ui-design skill (Skill('ui-design')) to create design-brief.md, ui-blueprint.json, and the SVG wireframes.
• Load the design-tokens skill (Skill('design-tokens')) to create design-tokens.json.

Step 3: Build the Screen Inventory (exhaustive — before designing anything)

The most common design failure is a missing screen — e.g. a todo app with a list screen but no screen for adding a new item. To prevent it, enumerate every screen the requirements imply and write the list to docs/design/screen-inventory.md before creating any other design file.

Derive the inventory from the documents read in Step 0. The user's Step 1 answer about main screens is input, never the ceiling.

1. Walk every user story and requirement in docs/product-requirements.md, and every flow in docs/functional-design.md. For each one, write down every screen the user passes through to complete it end-to-end. If a story cannot be completed with the screens listed so far, the missing screens go on the list.
2. Apply CRUD coverage to every entity the user manages (e.g. todo item, project, profile). For each entity, explicitly decide each of: list/overview, detail, create/add, edit, delete confirmation. Include each as an inventory entry unless the requirements clearly exclude it. If create/edit happens in a modal, dialog, or inline form rather than a full page, it is still an inventory entry (record its presentation) — it still needs a blueprint entry and a wireframe.
3. Add the supporting screens the requirements imply: authentication (sign in / sign up / password reset), settings, onboarding, search/filter results, empty states, error / not-found.

Write each entry in this format:

- [ ] `screen-id` — Title
  - Purpose: what the user accomplishes here
  - Source: the PRD user story / functional-design section it comes from
  - Reached from: the screens/actions that navigate here
  - Presentation: page | modal | drawer
  - Key elements: main components, inputs, and actions on the screen

End the file with a traceability table: one row per user story, listing the screen ids that fulfill it. Every user story must map to at least one screen, and every screen must trace back to at least one requirement. Do not proceed to Step 4 until both directions are fully covered.

Step 4: Create the Design Brief

Create docs/design/design-brief.md covering:

• Target users
• Design concept
• Visual mood
• Layout principles
• Navigation principles
• Accessibility considerations
• Platform-specific notes
• Examples of preferred UI style
• Examples of UI style to avoid

Step 5: Create the Design Tokens

Create docs/design/design-tokens.json using a JSON structure inspired by the Design Tokens Community Group format (each token has $type and $value). Include:

• Colors (semantic names: background, text, accent, border, state, etc.)
• Typography (font families, sizes, weights, line heights)
• Spacing scale
• Border radius
• Shadows / elevation
• Animation durations / easings
• Breakpoints (if the target includes web)

Step 6: Create the UI Blueprint (source of truth)

Create docs/design/ui-blueprint.json. This is the source of truth for UI generation. It must describe:

• App name and target platforms
• Overall style summary
• Routes
• Screens (each with id, title, route, layout, and component tree)
• Layouts
• Components (variants and states)
• Component hierarchy
• User actions and navigation behavior

Coverage rule: the blueprint must contain one screen entry for every entry in docs/design/screen-inventory.md — including modal/drawer entries. As each screen is added, check it off ([ ] → [x]) in the inventory. Do not finish this step while any inventory entry is unchecked.

Step 7: Create the Platform Mapping

Create docs/design/platform-mapping.md describing how the design spec is converted to each platform:

Web:
- design-tokens.json → CSS variables or Tailwind theme
- ui-blueprint.json → pages, routes, React components, layout components

Flutter:
- design-tokens.json → ThemeData, ColorScheme, constants
- ui-blueprint.json → Widget tree, routes, reusable widgets

WinUI 3:
- design-tokens.json → ResourceDictionary
- ui-blueprint.json → XAML pages, UserControls, styles

Step 8: Generate SVG Wireframes (visual references only)

For each screen in ui-blueprint.json, generate a corresponding SVG wireframe under docs/design/screens/:

• docs/design/screens/home.svg
• docs/design/screens/settings.svg
• docs/design/screens/[screen-id].svg

Important rule: SVG files are not the source of truth. They are generated as visual references for human review only. The source of truth is ui-blueprint.json. If the blueprint and an SVG ever disagree, the blueprint wins and the SVG must be regenerated.

Step 9: Consistency Check

Re-read all generated files and confirm:

• Every entry in docs/design/screen-inventory.md is checked off and has a matching screen (same id) in ui-blueprint.json.
• Every user story in the PRD can be completed end-to-end using only the screens and actions in the blueprint — in particular, every entity the user can create, edit, or delete has a screen (or modal) for each of those operations.
• Every screen in ui-blueprint.json has a matching SVG in screens/.
• Token names referenced in ui-blueprint.json exist in design-tokens.json.
• platform-mapping.md covers all target platforms selected in Step 1.
• The design is consistent with docs/product-requirements.md and docs/functional-design.md.

Fix any inconsistencies found before finishing.

Completion Criteria

• docs/design/screen-inventory.md exists and every entry is checked off
• docs/design/design-brief.md exists
• docs/design/design-tokens.json exists and is valid JSON
• docs/design/ui-blueprint.json exists and is valid JSON
• docs/design/platform-mapping.md exists
• One SVG per screen exists under docs/design/screens/

Completion message:

"Design phase is complete!

Design documents created:
✅ docs/design/screen-inventory.md  (exhaustive screen list — all entries covered)
✅ docs/design/design-brief.md
✅ docs/design/design-tokens.json
✅ docs/design/ui-blueprint.json   (source of truth)
✅ docs/design/platform-mapping.md
✅ docs/design/screens/*.svg        (visual references)

Next steps:
- Review docs/design/ (especially ui-blueprint.json)
- Refine the design with /update-design <change> (or re-run /define-design) until approved — do this BEFORE generating code
- Run /generate-app web | flutter | winui3 to generate the initial app
- Use /update-design when a feature changes the UI
- Use /add-feature to add features (it respects the design spec)
"