From f57921abadf0df95239422c3910f166c2057439e Mon Sep 17 00:00:00 2001 From: Ken Yasue Date: Sun, 28 Jun 2026 18:41:01 +0200 Subject: [PATCH] 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 --- .opencode/command/add-feature.md | 24 +++ .opencode/command/define-design.md | 178 ++++++++++++++++++ .opencode/command/generate-app.md | 147 +++++++++++++++ .opencode/command/update-design.md | 90 +++++++++ .opencode/skills/design-tokens/SKILL.md | 137 ++++++++++++++ .../skills/platform-ui-generation/SKILL.md | 112 +++++++++++ .opencode/skills/ui-design/SKILL.md | 156 +++++++++++++++ AGENTS.md | 23 ++- README.md | 93 +++++++-- docs/design/README.md | 62 ++++++ 10 files changed, 1004 insertions(+), 18 deletions(-) create mode 100644 .opencode/command/define-design.md create mode 100644 .opencode/command/generate-app.md create mode 100644 .opencode/command/update-design.md create mode 100644 .opencode/skills/design-tokens/SKILL.md create mode 100644 .opencode/skills/platform-ui-generation/SKILL.md create mode 100644 .opencode/skills/ui-design/SKILL.md create mode 100644 docs/design/README.md diff --git a/.opencode/command/add-feature.md b/.opencode/command/add-feature.md index c825d02..69b1723 100644 --- 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`). diff --git a/.opencode/command/define-design.md b/.opencode/command/define-design.md new file mode 100644 index 0000000..05288a5 --- /dev/null +++ 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) +" +``` diff --git a/.opencode/command/generate-app.md b/.opencode/command/generate-app.md new file mode 100644 index 0000000..a30b24b --- /dev/null +++ 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 +" +``` diff --git a/.opencode/command/update-design.md b/.opencode/command/update-design.md new file mode 100644 index 0000000..c66a049 --- /dev/null +++ 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. +" +``` diff --git a/.opencode/skills/design-tokens/SKILL.md b/.opencode/skills/design-tokens/SKILL.md new file mode 100644 index 0000000..cabe0c5 --- /dev/null +++ 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. diff --git a/.opencode/skills/platform-ui-generation/SKILL.md b/.opencode/skills/platform-ui-generation/SKILL.md new file mode 100644 index 0000000..fe4d29d --- /dev/null +++ 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:` → 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** (`
`, `
`, `