feat: add design phase and platform app generation phase

Add a UI/UX design phase (/define-design, /update-design) and a platform app generation phase (/generate-app web|flutter|winui3) to the workflow, positioned between /setup-project and /add-feature. - commands: define-design, generate-app, update-design - add-feature: check docs/design/ before implementation; update design files first when a feature changes the UI - skills: ui-design, design-tokens, platform-ui-generation - docs/design/ structure documented (source of truth = ui-blueprint.json; SVGs are references only; generated UI follows design-tokens.json) - README and AGENTS.md updated with the new workflow
2026-06-28 18:41:01 +02:00
parent e1ef10be6e
commit f57921abad
10 changed files with 1004 additions and 18 deletions
--- a/.opencode/command/add-feature.md
+++ b/.opencode/command/add-feature.md
@ -33,6 +33,30 @@ agent: build
 1. Use the grep tool to search the source code (`src/`) for keywords related to the feature name.
 2. Analyze the search results to identify existing implementation patterns, naming conventions, and how components are used.

+## Step 3.5: Check the Design Specification (Before Implementation)
+
+Before implementing any feature, respect the UI/UX design specification.
+
+1. Check whether the design files exist:
+   - `docs/design/design-brief.md`
+   - `docs/design/design-tokens.json`
+   - `docs/design/ui-blueprint.json`
+   - `docs/design/platform-mapping.md`
+
+2. **If the design files do not exist**, warn the user and suggest running `/define-design` before continuing. Do not silently proceed without a design spec.
+
+3. **If the design files exist**, read all four of them before implementation:
+   1. `docs/design/design-brief.md`
+   2. `docs/design/design-tokens.json`
+   3. `docs/design/ui-blueprint.json` (source of truth)
+   4. `docs/design/platform-mapping.md`
+
+4. **If the feature changes the UI**, update the design files first, following the `/update-design` order:
+   - `ui-blueprint.json` → `design-tokens.json` → `design-brief.md` → `platform-mapping.md` → regenerate affected `screens/*.svg`
+   - The blueprint is the source of truth; SVGs are visual references only.
+
+5. Then implement the feature according to the selected platform mapping in `platform-mapping.md`, using tokens from `design-tokens.json` (no hard-coded values) and the component tree from `ui-blueprint.json`.
+
 ## Step 4: Planning Phase (Automatic Generation of Steering Files)

 1. Follow the **steering** skill (loaded automatically) in **planning mode** to generate the contents of the three files created in Step 1 (`requirements.md`, `design.md`, `tasklist.md`).
--- a/.opencode/command/define-design.md
+++ b/.opencode/command/define-design.md
@ -0,0 +1,178 @@
+---
+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
+  ↓
+/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
+
+- 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: 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)
+- 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)
+"
+```
--- a/.opencode/command/generate-app.md
+++ b/.opencode/command/generate-app.md
@ -0,0 +1,147 @@
+---
+description: Generate the initial application for a target platform (web | flutter | winui3) from the design spec
+agent: build
+---
+
+# Generate App (Platform App Generation Phase)
+
+This command generates the **initial application** for the selected target platform, using the design files in `docs/design/` as the source of truth. It creates the app shell, theme, routes, screens, and reusable components — **not** feature logic. Features are added later with `/add-feature`.
+
+**Target platform**: `$ARGUMENTS` — must be one of `web`, `flutter`, `winui3`.
+
+## How to Run
+
+```
+opencode
+> /generate-app web
+> /generate-app flutter
+> /generate-app winui3
+```
+
+## Position in the Workflow
+
+```
+/setup-project
+  ↓
+/define-design
+  ↓
+/generate-app web | flutter | winui3   ← you are here
+  ↓
+/add-feature
+```
+
+## Pre-Run Check
+
+1. Validate the target:
+   - If `$ARGUMENTS` is not one of `web`, `flutter`, `winui3`, stop and ask the user to provide a valid target.
+2. Confirm the design files exist. If any of these are missing, stop and tell the user to run `/define-design` first:
+   - `docs/design/design-brief.md`
+   - `docs/design/design-tokens.json`
+   - `docs/design/ui-blueprint.json`
+   - `docs/design/platform-mapping.md`
+3. **Important**: Do **not** generate any platform-specific implementation before this command is executed. This command is the only place initial app scaffolding is created.
+
+## Procedure
+
+### Step 0: Read the Inputs
+
+Read all of the following:
+
+- `docs/product-requirements.md`
+- `docs/functional-design.md`
+- `docs/architecture.md`
+- `docs/repository-structure.md`
+- `docs/development-guidelines.md`
+- `docs/design/design-brief.md`
+- `docs/design/design-tokens.json`
+- `docs/design/ui-blueprint.json`
+- `docs/design/platform-mapping.md`
+
+### Step 1: Load the Platform Generation Skill
+
+Follow the **platform-ui-generation** skill (loaded automatically) for the mapping rules from design files to the selected platform's code.
+
+### Step 2: Generate the App Shell
+
+Generate the initial application for the selected target. In all cases:
+
+- Respect the design tokens and the UI blueprint exactly.
+- Create reusable UI components (do not inline everything into screens).
+- Create the initial screen structure (one screen per entry in `ui-blueprint.json`).
+- Create the initial route/navigation structure.
+- Use semantic, accessible markup/semantics where the platform supports it.
+- **Do not implement features that are not described in the current project documents.** Only the app shell, theme, routes, screens, and shared components.
+
+### Step 3: Platform-Specific Requirements
+
+Apply the requirements for the selected target:
+
+#### `/generate-app web`
+- Generate a Web app using the technology defined in `docs/architecture.md`.
+- If no framework is specified, ask the user or choose a simple default suitable for the repository.
+- Convert `design-tokens.json` into CSS variables, a Tailwind config, or an equivalent styling system.
+- Convert `ui-blueprint.json` into pages, layouts, and components.
+- Use semantic HTML where possible.
+- Respect responsive layout requirements (use breakpoints from the tokens).
+
+#### `/generate-app flutter`
+- Generate a Flutter app.
+- Convert `design-tokens.json` into:
+  - `ThemeData`
+  - `ColorScheme`
+  - spacing constants
+  - radius constants
+  - text styles
+- Convert `ui-blueprint.json` into:
+  - routes
+  - screens
+  - reusable widgets
+- Keep clean separation between: `screens`, `widgets`, `theme`, `models`, `services`.
+
+#### `/generate-app winui3`
+- Generate a WinUI 3 application structure.
+- Convert `design-tokens.json` into:
+  - `ResourceDictionary`
+  - theme resources
+  - styles
+- Convert `ui-blueprint.json` into:
+  - XAML pages
+  - `UserControl`s
+  - navigation structure
+- Use C# and XAML.
+- Keep UI logic separated from business logic where possible.
+
+### Step 4: Update Repository Structure Document
+
+If new directories/files were created, update `docs/repository-structure.md` so it reflects the generated layout.
+
+### Step 5: Verify
+
+- If the target is `web` and the repo has `npm test`, `npm run lint`, `npm run typecheck`, run them and fix any errors caused by the generated code.
+- For `flutter` / `winui3`, run the platform's available static checks if the toolchain is present; otherwise note what should be checked manually.
+
+## Completion Criteria
+
+- The initial app shell exists for the selected target.
+- Design tokens are converted into the platform's styling system.
+- The UI blueprint is converted into screens, routes, and reusable components.
+- No feature logic beyond what the project documents describe has been implemented.
+- `docs/repository-structure.md` has been updated if the layout changed.
+
+Completion message:
+```
+"App generation is complete for target: [target]
+
+Generated:
+✅ App shell + entry point
+✅ Theme / styling system (from design-tokens.json)
+✅ Routes / navigation (from ui-blueprint.json)
+✅ Screens (one per blueprint screen)
+✅ Reusable components
+
+Next steps:
+- Run the app and verify the shell renders
+- Use /add-feature to implement features (they will respect the design spec)
+- Use /update-design when a feature changes the UI
+"
+```
--- a/.opencode/command/update-design.md
+++ b/.opencode/command/update-design.md
@ -0,0 +1,90 @@
+---
+description: Update the design spec when a feature request changes the UI (blueprint first, then tokens, brief, and SVGs)
+agent: build
+---
+
+# Update Design
+
+This command updates the design specification when a feature request changes the UI. It updates the structured design files **only** — it does **not** implement application code unless explicitly requested.
+
+**Change description**: `$ARGUMENTS` (e.g. `/update-design add a profile screen with avatar and edit form`)
+
+## How to Run
+
+```
+opencode
+> /update-design add a profile screen with avatar and edit form
+```
+
+## Pre-Run Check
+
+Confirm the design files exist. If they are missing, stop and tell the user to run `/define-design` first:
+
+- `docs/design/design-brief.md`
+- `docs/design/design-tokens.json`
+- `docs/design/ui-blueprint.json`
+- `docs/design/platform-mapping.md`
+
+## Procedure
+
+### Step 0: Read the Inputs
+
+Read:
+
+- The existing design files listed above
+- `docs/product-requirements.md` and `docs/functional-design.md` for context
+- The change description provided in `$ARGUMENTS`
+
+### Step 1: Update `ui-blueprint.json` First
+
+The blueprint is the source of truth, so it is always updated first. Add/modify screens, components, variants, states, routes, and actions to reflect the requested change. Keep the JSON valid and consistent with the existing schema.
+
+### Step 2: Update `design-tokens.json` (if needed)
+
+If the change introduces new colors, spacing, typography, radius, shadows, or animations, add the corresponding tokens here. Reuse existing tokens where possible; do not duplicate. Use semantic names. No hard-coded values should be needed downstream.
+
+### Step 3: Update `design-brief.md` (if the direction changes)
+
+If the change affects the overall design direction (visual mood, layout principles, navigation principles, accessibility), update the brief. If it is a localized screen/component change, leave the brief unchanged.
+
+### Step 4: Update `platform-mapping.md` (if needed)
+
+If the change introduces a new platform target or a new kind of mapping (e.g. a new component family that maps differently per platform), update the mapping. Otherwise leave it unchanged.
+
+### Step 5: Regenerate Affected SVG Wireframes
+
+For every screen added or modified in `ui-blueprint.json`, generate or regenerate the corresponding SVG under `docs/design/screens/`. Remember: SVGs are visual references only — the blueprint is the source of truth.
+
+### Step 6: Consistency Check
+
+- Every screen in `ui-blueprint.json` has a matching SVG.
+- Token names referenced in the blueprint exist in `design-tokens.json`.
+- The brief and mapping remain consistent with the blueprint.
+
+### Step 7: Do Not Implement Code
+
+Do **not** modify application code in this command. If the user also wants the code updated, they should run `/add-feature` (which reads the updated design files) or ask explicitly.
+
+## Completion Criteria
+
+- `ui-blueprint.json` has been updated (source of truth).
+- `design-tokens.json` updated only if new tokens were needed.
+- `design-brief.md` updated only if the direction changed.
+- `platform-mapping.md` updated only if mappings changed.
+- Affected SVG wireframes regenerated.
+- No application code was changed.
+
+Completion message:
+```
+"Design has been updated.
+
+Updated:
+✅ docs/design/ui-blueprint.json   (source of truth)
+✅ docs/design/design-tokens.json   (if new tokens were needed)
+✅ docs/design/design-brief.md      (if the direction changed)
+✅ docs/design/platform-mapping.md  (if mappings changed)
+✅ docs/design/screens/*.svg        (regenerated as needed)
+
+Note: application code was not changed. Run /add-feature to implement the change, respecting the updated design.
+"
+```
--- a/.opencode/skills/design-tokens/SKILL.md
+++ b/.opencode/skills/design-tokens/SKILL.md
@ -0,0 +1,137 @@
+---
+name: design-tokens
+description: Guide for creating and maintaining design-tokens.json, the single source of styling values for Web, Flutter, and WinUI 3. Use when creating or updating design tokens.
+---
+
+# Design Tokens Skill
+
+This skill explains how to create and maintain `docs/design/design-tokens.json` — the single source of truth for all styling values (color, typography, spacing, radius, shadow, motion, breakpoints). Generated platform code must read from these tokens and must never hard-code values.
+
+## Core Principle
+
+> One token definition → many platform outputs. Never hard-code a color, size, or spacing in generated code.
+
+## Format
+
+Use a JSON structure inspired by the Design Tokens Community Group format. Every token is an object with `$type` and `$value`:
+
+```json
+{
+  "color": {
+    "background": {
+      "primary": { "$type": "color", "$value": "#0F172A" }
+    }
+  },
+  "spacing": {
+    "md": { "$type": "dimension", "$value": "16px" }
+  }
+}
+```
+
+Supported `$type` values: `color`, `dimension`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `number`, `strokeStyle`.
+
+## Token Groups
+
+`design-tokens.json` should include these groups (omit a group only if it truly does not apply):
+
+- **color** — semantic color tokens
+- **typography** — font families, sizes, weights, line heights
+- **spacing** — spacing scale (xs, sm, md, lg, xl, …)
+- **radius** — border radius scale
+- **shadow** / **elevation** — box-shadow / elevation tokens
+- **motion** — animation durations and easings
+- **breakpoint** — responsive breakpoints (include when `web` is a target)
+
+## Rules
+
+### Naming tokens
+
+- Use **semantic names**, not descriptive names. `color.text.primary` (good) vs `color.slate-900` (bad).
+- Use a consistent scale for numeric families: `sm`, `md`, `lg`, `xl` — or numeric `4`, `8`, `12` — pick one and stick to it.
+- Group by role then by emphasis: `color.background.primary`, `color.background.muted`, `color.text.primary`, `color.text.secondary`, `color.accent.primary`, `color.state.success`, `color.state.danger`.
+- Token names are referenced verbatim in `ui-blueprint.json` (e.g. `"padding": "lg"`). They must match exactly.
+
+### Using semantic color names
+
+- Define colors by **role** (background, text, accent, border, state, overlay) and **emphasis** (primary, secondary, muted).
+- Do not expose raw hex scales as the only option. If you need a raw scale, keep it in a separate `color.palette` group and reference it from semantic tokens.
+- Provide both light and dark values where the app supports them: `color.background.primary` (light) and `color.background.primary-dark`, or a `dark` sub-object — pick one convention and document it in `platform-mapping.md`.
+
+### Avoiding hard-coded values in generated code
+
+- Generated Web code uses CSS variables / Tailwind theme keys / theme objects derived from tokens.
+- Generated Flutter code uses `ThemeData`, `ColorScheme`, and constants derived from tokens.
+- Generated WinUI 3 code uses `ResourceDictionary` entries derived from tokens.
+- **Never** inline `#0F172A` or `16px` in generated source. Always reference the token-derived variable/resource.
+- If a value is needed that has no token, add the token to `design-tokens.json` first, then use it.
+
+### Mapping tokens to platform-specific code
+
+`design-tokens.json` is platform-agnostic. The conversion to each platform is documented in `docs/design/platform-mapping.md` and performed by the **platform-ui-generation** skill. This skill only defines and maintains the tokens.
+
+## Example
+
+```json
+{
+  "color": {
+    "background": {
+      "primary": { "$type": "color", "$value": "#0F172A" },
+      "muted": { "$type": "color", "$value": "#1E293B" }
+    },
+    "text": {
+      "primary": { "$type": "color", "$value": "#F8FAFC" },
+      "secondary": { "$type": "color", "$value": "#94A3B8" }
+    },
+    "accent": {
+      "primary": { "$type": "color", "$value": "#38BDF8" }
+    },
+    "state": {
+      "success": { "$type": "color", "$value": "#22C55E" },
+      "danger": { "$type": "color", "$value": "#EF4444" }
+    }
+  },
+  "typography": {
+    "fontFamily": {
+      "base": { "$type": "fontFamily", "$value": "Inter, system-ui, sans-serif" }
+    },
+    "size": {
+      "sm": { "$type": "dimension", "$value": "14px" },
+      "md": { "$type": "dimension", "$value": "16px" },
+      "lg": { "$type": "dimension", "$value": "20px" }
+    }
+  },
+  "spacing": {
+    "sm": { "$type": "dimension", "$value": "8px" },
+    "md": { "$type": "dimension", "$value": "16px" },
+    "lg": { "$type": "dimension", "$value": "24px" }
+  },
+  "radius": {
+    "card": { "$type": "dimension", "$value": "16px" },
+    "pill": { "$type": "dimension", "$value": "9999px" }
+  },
+  "shadow": {
+    "card": { "$type": "shadow", "$value": "0 4px 12px rgba(0,0,0,0.15)" }
+  },
+  "motion": {
+    "duration": {
+      "fast": { "$type": "duration", "$value": "120ms" },
+      "base": { "$type": "duration", "$value": "200ms" }
+    }
+  },
+  "breakpoint": {
+    "sm": { "$type": "dimension", "$value": "640px" },
+    "md": { "$type": "dimension", "$value": "768px" },
+    "lg": { "$type": "dimension", "$value": "1024px" }
+  }
+}
+```
+
+## Maintenance Checklist
+
+When updating tokens:
+
+- [ ] JSON is valid.
+- [ ] Token names referenced in `ui-blueprint.json` still exist (no broken references after a rename).
+- [ ] New tokens follow the naming and semantic-name rules.
+- [ ] No duplicate tokens (same role under two names).
+- [ ] `platform-mapping.md` still covers how every token group maps to each target platform.
--- a/.opencode/skills/platform-ui-generation/SKILL.md
+++ b/.opencode/skills/platform-ui-generation/SKILL.md
@ -0,0 +1,112 @@
+---
+name: platform-ui-generation
+description: Guide for converting the design files (design-tokens.json + ui-blueprint.json) into application code for Web, Flutter, or WinUI 3. Use when running /generate-app or implementing UI against the design spec.
+---
+
+# Platform UI Generation Skill
+
+This skill explains how to convert the design files under `docs/design/` into application code. It is used by `/generate-app` and by `/add-feature` when implementing UI.
+
+## Core Principles
+
+1. **Source of truth**: `docs/design/ui-blueprint.json` defines structure; `docs/design/design-tokens.json` defines values.
+2. **No hard-coded values**: every color, size, spacing, radius, and duration in generated code must come from a token.
+3. **Reusable components first**: extract reusable components; do not inline the entire tree into screens.
+4. **No feature logic during scaffolding**: `/generate-app` creates the shell, theme, routes, screens, and shared components only. Features come from `/add-feature`.
+5. **Respect the platform mapping**: `docs/design/platform-mapping.md` documents how each artifact maps to each platform.
+
+## Inputs
+
+- `docs/design/design-brief.md` — direction
+- `docs/design/design-tokens.json` — values
+- `docs/design/ui-blueprint.json` — structure (source of truth)
+- `docs/design/platform-mapping.md` — per-platform conversion rules
+- `docs/architecture.md` — technology choices (framework, language)
+
+## General Conversion Rules
+
+- One screen in the blueprint → one screen/page in the target platform.
+- One route in the blueprint → one route entry in the navigation config.
+- A reusable component referenced in multiple screens → a shared component file/widget/control.
+- Component `variant` → a variant/style modifier on the shared component.
+- Component `state` → visual states the component must support (default, hover, pressed, disabled, etc.).
+- `action: navigate:<screen-id>` → navigation to the corresponding route.
+- Other `action:` values → wire to a handler/placeholder; do not implement feature logic.
+
+## Web Mapping
+
+- **design tokens →** CSS variables, a Tailwind config, or a theme object.
+  - `color.*` → CSS custom properties (`--color-background-primary`) or Tailwind theme colors.
+  - `spacing.*`, `radius.*`, `typography.*` → CSS variables / Tailwind theme keys.
+  - `breakpoint.*` → responsive breakpoints.
+- **ui-blueprint →**
+  - `screens` → pages/routes.
+  - `layout` → layout components (vertical/horizontal stack, grid).
+  - `components` → React (or framework) components, one file per reusable component.
+- Use **semantic HTML** (`<header>`, `<main>`, `<nav>`, `<button>`, `<label>`) where possible.
+- Respect responsive layout requirements using the breakpoint tokens.
+- If no framework is specified in `architecture.md`, choose a simple default suitable for the repository and note the choice.
+
+## Flutter Mapping
+
+- **design tokens →**
+  - `color.*` → `ColorScheme` + a color constants file.
+  - `typography.*` → `TextTheme` / text styles.
+  - `spacing.*`, `radius.*` → constants (`spacing_md`, `radiusCard`).
+  - `shadow.*` → `BoxShadow` / elevation.
+  - `motion.duration.*` → `Duration` constants.
+  - Assemble into a `ThemeData`.
+- **ui-blueprint →**
+  - `screens` → `Screen` widgets + routes (named routes or a router).
+  - `layout.type` → `Column` / `Row` / `Wrap` / `ListView` with `padding` and `SizedBox` gaps from spacing tokens.
+  - `components` → reusable widgets, one file per widget.
+- Keep clean separation between: `screens/`, `widgets/`, `theme/`, `models/`, `services/`.
+
+## WinUI 3 Mapping
+
+- **design tokens →**
+  - `color.*`, `spacing.*`, `radius.*`, `typography.*` → a `ResourceDictionary` (`.xaml`) with `Color`, `Thickness`, `CornerRadius`, `FontFamily`, `Style` resources.
+  - Assemble theme resources and styles keyed by the token names.
+- **ui-blueprint →**
+  - `screens` → XAML pages (`Page`).
+  - `layout.type` → `StackPanel` / `Grid` with `Padding`/`Margin` from token resources.
+  - `components` → `UserControl`s, one file per reusable component.
+  - Navigation → `Frame` + navigation entries per route.
+- Use **C# and XAML**.
+- Keep UI logic separated from business logic (code-behind stays thin; logic goes to services/viewmodels).
+
+## Shared Component Contract
+
+Each generated reusable component must:
+
+- Accept the `variant` as a parameter/prop/style modifier.
+- Support the `states` declared in the blueprint (default, hover, pressed, disabled).
+- Reference tokens for all visual values — no hard-coded literals.
+- Stay presentational: no feature/business logic.
+
+## Scaffolding Scope (what `/generate-app` creates)
+
+- App entry point and shell
+- Theme/styling system from tokens
+- Router/navigation config from routes
+- One screen per blueprint screen (layout + components wired, but no feature logic)
+- One shared component file per reusable component in `components`
+
+## Out of Scope (handled by `/add-feature`)
+
+- Feature/business logic
+- Data fetching and state management for features
+- Form validation and submission behavior
+- Anything not described in the current project documents
+
+## Generation Checklist
+
+Before finishing a generation:
+
+- [ ] Every screen in the blueprint has a corresponding generated screen.
+- [ ] Every route is wired in the navigation config.
+- [ ] Every reusable component in `components` has a generated file.
+- [ ] No hard-coded color/size/spacing in generated code — all from tokens.
+- [ ] Components accept `variant` and support declared `states`.
+- [ ] No feature logic was implemented beyond the project documents.
+- [ ] `docs/repository-structure.md` updated if the layout changed.
--- a/.opencode/skills/ui-design/SKILL.md
+++ b/.opencode/skills/ui-design/SKILL.md
@ -0,0 +1,156 @@
+---
+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/.
+---
+
+# 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.