# Design Specification (`docs/design/`)

This directory holds the project's **UI/UX design specification**. It is created and maintained by the `/define-design` and `/update-design` commands and consumed by `/generate-app` and `/add-feature`.

## Source of truth

```
docs/design/ui-blueprint.json   ← THE source of truth for UI generation
```

SVG files are **visual references only**. If an SVG and the blueprint disagree, the blueprint wins and the SVG must be regenerated.

Generated UI must follow `design-tokens.json` — no hard-coded values.

## Structure

```
docs/design/
├── design-brief.md         # UI/UX direction (human-readable, concrete)
├── design-tokens.json      # Styling values (color, type, spacing, radius, …)
├── ui-blueprint.json        # Source of truth: screens, components, routes, actions
├── platform-mapping.md      # How the design maps to Web / Flutter / WinUI 3
└── screens/                 # SVG wireframes (one per blueprint screen)
    ├── home.svg
    ├── settings.svg
    └── [screen-id].svg
```

## File purposes

### `design-brief.md`
Overall UI/UX direction: target users, design concept, visual mood, layout/navigation principles, accessibility, platform-specific notes, preferred styles, and styles to avoid.

### `design-tokens.json`
Design tokens in a Design Tokens Community Group–inspired JSON format (`$type` / `$value`). Covers color, typography, spacing, radius, shadow, motion, and breakpoints. Platform code reads from these tokens and never hard-codes values.

### `ui-blueprint.json`
The source of truth for UI generation. Describes the app name, target platforms, routes, screens (each with a layout and component tree), reusable components (variants and states), and user actions/navigation.

### `platform-mapping.md`
Documents how `design-tokens.json` and `ui-blueprint.json` are converted to each target platform:

- **Web**: tokens → CSS variables / Tailwind theme; blueprint → pages, routes, components.
- **Flutter**: tokens → `ThemeData` / `ColorScheme` / constants; blueprint → widgets, routes.
- **WinUI 3**: tokens → `ResourceDictionary`; blueprint → XAML pages, `UserControl`s, navigation.

### `screens/*.svg`
Low-fidelity wireframes, one per screen in `ui-blueprint.json`, named `<screen-id>.svg`. Generated for human review only — never the source of truth.

## Workflow

```
/setup-project   → product/architecture docs
/define-design   → creates the files above
/generate-app web | flutter | winui3   → scaffolds the app from these files
/update-design   → updates these files when a feature changes the UI
/add-feature     → reads these files before implementing; updates them first if the UI changes
```

## Status

This directory is populated by running `/define-design`. Until then, the files above do not exist and `/generate-app` will ask you to run `/define-design` first.