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
• 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: 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 4: 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 5: 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

Step 6: 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 7: 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 8: Consistency Check

Re-read all generated files and confirm:

• 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/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/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)
"