---
name: ui-design
description: Guide for creating the UI/UX design specification (design brief, UI blueprint JSON, and SVG wireframes). Use when defining or updating the design under docs/design/.
allowed-tools: Read, Write, Edit
---

# UI Design Skill

This skill explains how to create an **AI-readable, implementation-ready** UI/UX design specification. It prefers structured, machine-consumable descriptions over vague visual descriptions.

## Core Principle

> The source of truth is structured text/JSON. Visual images (SVG) are references for humans, not inputs for code generation.

Prefer describing **what a component is and how it behaves** over describing **what it looks like**. "A primary button with label 'Save' that triggers `action:save`" is better than "a nice blue button in the corner".

## Outputs

This skill produces three kinds of artifacts under `docs/design/`:

1. `design-brief.md` — the UI/UX direction (human-readable, but concrete)
2. `ui-blueprint.json` — the source of truth for UI generation (machine-readable)
3. `screens/*.svg` — visual wireframes for human review (derived from the blueprint)

## Prerequisites

Before creating the design, read:

- `docs/product-requirements.md`
- `docs/functional-design.md`
- `docs/architecture.md`

The design must serve the product requirements and stay consistent with the functional design.

## Creating `design-brief.md`

A concrete, opinionated document. Avoid vague phrases like "modern and clean" without elaboration. Include every section below:

- **Target users** — who the UI is for, and their key contexts/constraints
- **Design concept** — the one-paragraph idea the UI embodies
- **Visual mood** — concrete descriptors (density, light/dark, rounding, motion amount)
- **Layout principles** — grid, alignment, content width, spacing rhythm
- **Navigation principles** — primary navigation pattern, depth, back behavior
- **Accessibility considerations** — target contrast, touch-target sizes, focus visibility, font scaling
- **Platform-specific notes** — how the design adapts to web / Flutter / WinUI 3
- **Examples of preferred UI style** — concrete references and why they fit
- **Examples of UI style to avoid** — anti-patterns to stay away from

## Creating `ui-blueprint.json` (source of truth)

This is the most important file. It must be valid JSON and fully describe the app's UI structure so that a generator can produce Web, Flutter, or WinUI 3 code without guessing.

### Required top-level fields

- `app.name`
- `app.platformTargets` — e.g. `["web", "flutter", "winui3"]`
- `app.style` — short style summary string
- `screens` — array of screen objects
- `components` — map of reusable component definitions

### Screen object shape

Each screen has:

- `id` — stable identifier (used as the SVG filename)
- `title`
- `route`
- `layout` — type + spacing tokens (e.g. `{ "type": "vertical", "padding": "lg", "gap": "md" }`)
- `components` — a tree of component nodes

### Component node shape

Each node has:

- `type` — e.g. `header`, `card`, `text`, `button`, `list`, `input`, `image`, `nav`
- `variant` — optional, must exist in the component's `variants`
- `role` — optional semantic role (e.g. `title`, `subtitle`, `body`)
- `content` / `label` — text content where applicable
- `action` — user action, e.g. `navigate:details`, `submit`, `toggle:filters`
- `children` — nested component nodes

### Reusable component definition

```json
"components": {
  "button": {
    "variants": ["primary", "secondary", "ghost"],
    "states": ["default", "hover", "pressed", "disabled"]
  }
}
```

### Example (excerpt)

```json
{
  "app": {
    "name": "Example App",
    "platformTargets": ["web", "flutter", "winui3"],
    "style": "friendly, modern, rounded, calm"
  },
  "screens": [
    {
      "id": "home",
      "title": "Home",
      "route": "/",
      "layout": { "type": "vertical", "padding": "lg", "gap": "md" },
      "components": [
        { "type": "header", "title": "Dashboard", "subtitle": "Welcome back" },
        {
          "type": "card",
          "variant": "primary",
          "children": [
            { "type": "text", "role": "title", "content": "Start here" },
            { "type": "button", "label": "Open", "action": "navigate:details" }
          ]
        }
      ]
    }
  ],
  "components": {
    "button": {
      "variants": ["primary", "secondary", "ghost"],
      "states": ["default", "hover", "pressed", "disabled"]
    },
    "card": {
      "variants": ["primary", "secondary", "danger"]
    }
  }
}
```

### Rules

- Every `variant` referenced in a screen must exist in `components[type].variants`.
- Every spacing/radius/color name referenced in layout/components must exist in `design-tokens.json`.
- Use `action:` prefixes consistently: `navigate:<screen-id>`, `submit`, `toggle:<id>`, `open:<id>`, etc.
- One screen = one route. Do not overload a screen with multiple routes.
- Keep the blueprint free of hard-coded pixel values; reference token names instead.

## Creating SVG wireframes (`screens/*.svg`)

- Generate **one SVG per screen**, named `<screen-id>.svg`.
- The SVG is a **low-fidelity wireframe**, not a pixel-perfect mock. Use boxes, labels, and placeholders.
- It must reflect the component tree of its screen in `ui-blueprint.json`.
- **If the blueprint and an SVG disagree, the blueprint wins.** Regenerate the SVG.
- SVGs exist only so humans can review the design at a glance.

## Consistency Checklist

Before finishing:

- [ ] Every screen in the blueprint has a matching SVG.
- [ ] Every `variant` used in a screen is declared in `components`.
- [ ] Every token name used in the blueprint exists in `design-tokens.json`.
- [ ] The brief and the blueprint describe the same app (same screens, same navigation).
- [ ] No hard-coded values in the blueprint.