opencode-boilerplate/.opencode/command/define-design.md

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

# 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

```
opencode
> /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 (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

- Follow the **ui-design** skill (loaded automatically) to create `design-brief.md`, `ui-blueprint.json`, and the SVG wireframes.
- Follow the **design-tokens** skill (loaded automatically) 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:

```markdown
- [ ] `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:

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