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.
--- a/AGENTS.md
+++ b/AGENTS.md
@ -78,6 +78,14 @@ Define "what to build" and "how to build it" for the entire application:
 - **development-guidelines.md** - Development guidelines
 - **glossary.md** - Ubiquitous language definitions

+#### Design Documents (`docs/design/`)
+- **design-brief.md** - UI/UX direction
+- **design-tokens.json** - Styling tokens (source of values)
+- **ui-blueprint.json** - UI structure (source of truth for UI generation)
+- **platform-mapping.md** - How the design maps to Web / Flutter / WinUI 3
+- **screens/\*.svg** - Visual wireframes (references only)
+- Created by `/define-design`, updated by `/update-design`, consumed by `/generate-app` and `/add-feature`
+
 ### Work-Unit Documents (`.steering/`)

 Define "what to do this time" for a specific development task:
@ -89,16 +97,18 @@ Define "what to do this time" for a specific development task:
 ### opencode Configuration (`.opencode/`)

 - `.opencode/agent/` - Subagent definitions (doc-reviewer, implementation-validator)
- `.opencode/command/` - Slash commands (setup-project, add-feature, review-docs)
- `.opencode/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, steering)
+- `.opencode/command/` - Slash commands (setup-project, define-design, generate-app, update-design, add-feature, review-docs)
+- `.opencode/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, ui-design, design-tokens, platform-ui-generation, steering)

 ## Development Process

 ### Initial Setup

 1. Use this template
-2. Create persistent documents with `/setup-project` (interactively creating six)
-3. Implement features with `/add-feature [feature]`
+2. Create persistent documents with `/setup-project` (automatically creating six)
+3. Define the UI/UX design with `/define-design` (creates `docs/design/`)
+4. Generate the initial app with `/generate-app web | flutter | winui3`
+5. Implement features with `/add-feature [feature]`

 ### Day-to-Day Usage

@ -113,6 +123,11 @@ Define "what to do this time" for a specific development task:
 # Adding features (use commands for the standard flow)
 > /add-feature edit user profile

+# Design phase
+> /define-design
+> /generate-app web
+> /update-design add a profile screen
+
 # Detailed review (when a detailed report is needed)
 > /review-docs docs/product-requirements.md
 ```
--- a/README.md
+++ b/README.md
@ -18,6 +18,7 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
 - [Directory Structure](#directory-structure)
 - [Configuration Overview](#configuration-overview)
 - [Usage Workflow](#usage-workflow)
+- [Design & App Generation](#design--app-generation)
 - [Commands Reference](#commands-reference)
 - [Skills Reference](#skills-reference)
 - [Agents Reference](#agents-reference)
@ -123,9 +124,15 @@ opencode
 │   ├── example.ts
 │   └── example.test.ts
 │
-├── docs/                      # Persistent design documents (created by /setup-project)
-│   └── ideas/
-│       └── initial-requirements.md   # Brainstorming notes (pre-PRD)
+├── docs/                      # Persistent design documents
+│   ├── ideas/
+│   │   └── initial-requirements.md   # Brainstorming notes (pre-PRD)
+│   └── design/                # UI/UX design spec (created by /define-design)
+│       ├── design-brief.md
+│       ├── design-tokens.json
+│       ├── ui-blueprint.json         # source of truth for UI
+│       ├── platform-mapping.md
+│       └── screens/*.svg             # visual references only
 │
 ├── .steering/                 # Per-task steering files (created by /add-feature)
 │   └── .gitkeep
@ -136,6 +143,9 @@ opencode
    │   └── implementation-validator.md
    ├── command/               # Slash commands
    │   ├── setup-project.md
+    │   ├── define-design.md
+    │   ├── generate-app.md
+    │   ├── update-design.md
    │   ├── add-feature.md
    │   └── review-docs.md
    └── skills/                # Task-specific skills
@ -145,6 +155,9 @@ opencode
        ├── repository-structure/  (SKILL.md + template.md + guide.md)
        ├── development-guidelines/(SKILL.md + template.md + guides/)
        ├── glossary-creation/     (SKILL.md + template.md + guide.md)
+        ├── ui-design/             (SKILL.md)
+        ├── design-tokens/         (SKILL.md)
+        ├── platform-ui-generation/(SKILL.md)
        └── steering/              (SKILL.md + templates/)
 ```

@ -203,13 +216,13 @@ opencode surfaces the right skill when the task matches.

 ### 1. Initial project setup

-Run the setup command to create all six persistent design documents interactively:
+Run the setup command to automatically create all six persistent design documents:

 ```
 > /setup-project
 ```

-This creates (one at a time, with your approval):
+This creates (automatically, end-to-end):
 1. `docs/product-requirements.md` (PRD)
 2. `docs/functional-design.md`
 3. `docs/architecture.md`
@ -220,7 +233,30 @@ This creates (one at a time, with your approval):
 The PRD is based on the brainstorming notes in `docs/ideas/initial-requirements.md`. Edit that file
 first if you have your own idea, or replace it.

-### 2. Add a feature
+### 2. Define the UI/UX design
+
+```
+> /define-design
+```
+
+Creates the design specification under `docs/design/` (design brief, design tokens, UI blueprint,
+platform mapping, and SVG wireframes). You'll be asked about target platform, visual style, main
+screens, navigation, branding, and accessibility; if you don't specify, sensible defaults are proposed.
+
+**The design source of truth is `docs/design/ui-blueprint.json`.** SVG files are visual references only.
+
+### 3. Generate the app
+
+```
+> /generate-app web
+> /generate-app flutter
+> /generate-app winui3
+```
+
+Scaffolds the initial application for the selected target from the design spec — app shell, theme
+(from tokens), routes, screens, and reusable components. No feature logic is implemented here.
+
+### 4. Add a feature

 ```
 > /add-feature User authentication
@ -228,13 +264,14 @@ first if you have your own idea, or replace it.

 This fully autonomous workflow:
 1. Creates `.steering/[YYYYMMDD]-[feature-name]/` with `requirements.md`, `design.md`, `tasklist.md`
-2. Generates the steering files (planning mode of the steering skill)
-3. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
-4. Launches the `implementation-validator` subagent for quality review
-5. Runs `npm test`, `npm run lint`, `npm run typecheck`
-6. Records a retrospective in `tasklist.md`
+2. Reads the design spec (`docs/design/`) and updates it first if the feature changes the UI
+3. Generates the steering files (planning mode of the steering skill)
+4. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
+5. Launches the `implementation-validator` subagent for quality review
+6. Runs `npm test`, `npm run lint`, `npm run typecheck`
+7. Records a retrospective and reconciles all six persistent docs with the feature

-### 3. Review a document
+### 5. Review a document

 ```
 > /review-docs docs/product-requirements.md
@ -243,7 +280,7 @@ This fully autonomous workflow:
 Launches the `doc-reviewer` subagent to evaluate the document from five perspectives:
 completeness, clarity, consistency, implementability, and measurability.

-### 4. Day-to-day editing
+### 6. Day-to-day editing

 You don't always need a command — just ask in normal conversation:

@ -257,11 +294,36 @@ opencode loads the appropriate skill automatically.

 ---

+## Design & App Generation
+
+Recommended workflow:
+
+1. Run `/setup-project`
+2. Run `/define-design`
+3. Review `docs/design/`
+4. Run `/generate-app web`, `/generate-app flutter`, or `/generate-app winui3`
+5. Use `/add-feature` to add features
+6. Use `/update-design` whenever a feature changes the UI
+
+Source of truth:
+
+- The design source of truth is `docs/design/ui-blueprint.json`.
+- SVG files (`docs/design/screens/*.svg`) are only visual references.
+- Generated UI should follow `docs/design/design-tokens.json` — no hard-coded values.
+- No platform-specific implementation is generated before `/generate-app` is executed.
+
+See [`docs/design/README.md`](docs/design/README.md) for the full structure.
+
+---
+
 ## Commands Reference

 | Command | Description | Example |
 |---|---|---|
-| `/setup-project` | Create the six persistent documents interactively | `/setup-project` |
+| `/setup-project` | Create the six persistent documents automatically | `/setup-project` |
+| `/define-design` | Create the UI/UX design spec under `docs/design/` | `/define-design` |
+| `/generate-app` | Scaffold the initial app for a target platform | `/generate-app web` |
+| `/update-design` | Update the design spec when a feature changes the UI | `/update-design add a profile screen` |
 | `/add-feature` | Implement a feature end-to-end (autonomous) | `/add-feature User profile editing` |
 | `/review-docs` | Detailed document review via subagent | `/review-docs docs/architecture.md` |

@ -277,6 +339,9 @@ opencode loads the appropriate skill automatically.
 | `repository-structure` | Defining the directory layout | `docs/repository-structure.md` |
 | `development-guidelines` | Creating coding conventions / implementing code | `docs/development-guidelines.md` |
 | `glossary-creation` | Creating a project glossary | `docs/glossary.md` |
+| `ui-design` | Creating the design brief, UI blueprint, and SVG wireframes | `docs/design/` files |
+| `design-tokens` | Creating and maintaining design tokens | `docs/design/design-tokens.json` |
+| `platform-ui-generation` | Converting design files into Web/Flutter/WinUI 3 code | generated app code |
 | `steering` | Planning, implementing, and retrospecting on a task | `.steering/[date]-[name]/` files |

 Each skill folder contains a `SKILL.md` (instructions) plus `template.md` and/or `guide.md` (reference
--- a/docs/design/README.md
+++ b/docs/design/README.md
@ -0,0 +1,62 @@
+# 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.