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

```bash
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:
   ```bash
   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:

```text
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)
"
```