ken/opencode-boilerplate
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add design phase and platform app generation phase

Browse Source 
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
This commit is contained in:
Ken Yasue
2026-06-28 18:41:01 +02:00
parent e1ef10be6e
commit f57921abad
10 changed files with 1004 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
.opencode/command/add-feature.md
View File

@ -33,6 +33,30 @@ agent: build
1. Use the grep tool to search the source code (`src/`) for keywords related to the feature name. 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. 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) ## 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`). 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`).

178
.opencode/command/define-design.md Normal file
View File

@ -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)
"
```

147
.opencode/command/generate-app.md Normal file
View File

@ -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
"
```

90
.opencode/command/update-design.md Normal file
View File

@ -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.
"
```

137
.opencode/skills/design-tokens/SKILL.md Normal file
View File

@ -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.

112
.opencode/skills/platform-ui-generation/SKILL.md Normal file
View File

@ -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.

156
.opencode/skills/ui-design/SKILL.md Normal file
View File

@ -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.

23
AGENTS.md
View File

@ -78,6 +78,14 @@ Define "what to build" and "how to build it" for the entire application:
- **development-guidelines.md** - Development guidelines - **development-guidelines.md** - Development guidelines
- **glossary.md** - Ubiquitous language definitions - **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/`) ### Work-Unit Documents (`.steering/`)
Define "what to do this time" for a specific development task: 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 Configuration (`.opencode/`)
- `.opencode/agent/` - Subagent definitions (doc-reviewer, implementation-validator) - `.opencode/agent/` - Subagent definitions (doc-reviewer, implementation-validator)
- `.opencode/command/` - Slash commands (setup-project, add-feature, review-docs) - `.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, steering) - `.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 ## Development Process
### Initial Setup ### Initial Setup
1. Use this template 1. Use this template
2. Create persistent documents with `/setup-project` (interactively creating six) 2. Create persistent documents with `/setup-project` (automatically creating six)
3. Implement features with `/add-feature [feature]` 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 ### 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) # Adding features (use commands for the standard flow)
> /add-feature edit user profile > /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) # Detailed review (when a detailed report is needed)
> /review-docs docs/product-requirements.md > /review-docs docs/product-requirements.md
``` ```

93
README.md
View File

@ -18,6 +18,7 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
- [Directory Structure](#directory-structure) - [Directory Structure](#directory-structure)
- [Configuration Overview](#configuration-overview) - [Configuration Overview](#configuration-overview)
- [Usage Workflow](#usage-workflow) - [Usage Workflow](#usage-workflow)
- [Design & App Generation](#design--app-generation)
- [Commands Reference](#commands-reference) - [Commands Reference](#commands-reference)
- [Skills Reference](#skills-reference) - [Skills Reference](#skills-reference)
- [Agents Reference](#agents-reference) - [Agents Reference](#agents-reference)
@ -123,9 +124,15 @@ opencode
│ ├── example.ts │ ├── example.ts
│ └── example.test.ts │ └── example.test.ts
│ │
├── docs/ # Persistent design documents (created by /setup-project) ├── docs/ # Persistent design documents
│ └── ideas/ │ ├── ideas/
│ └── initial-requirements.md # Brainstorming notes (pre-PRD) │ │ └── 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) ├── .steering/ # Per-task steering files (created by /add-feature)
│ └── .gitkeep │ └── .gitkeep
@ -136,6 +143,9 @@ opencode
│ └── implementation-validator.md │ └── implementation-validator.md
├── command/ # Slash commands ├── command/ # Slash commands
│ ├── setup-project.md │ ├── setup-project.md
│ ├── define-design.md
│ ├── generate-app.md
│ ├── update-design.md
│ ├── add-feature.md │ ├── add-feature.md
│ └── review-docs.md │ └── review-docs.md
└── skills/ # Task-specific skills └── skills/ # Task-specific skills
@ -145,6 +155,9 @@ opencode
├── repository-structure/ (SKILL.md + template.md + guide.md) ├── repository-structure/ (SKILL.md + template.md + guide.md)
├── development-guidelines/(SKILL.md + template.md + guides/) ├── development-guidelines/(SKILL.md + template.md + guides/)
├── glossary-creation/ (SKILL.md + template.md + guide.md) ├── 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/) └── steering/ (SKILL.md + templates/)
``` ```
@ -203,13 +216,13 @@ opencode surfaces the right skill when the task matches.
### 1. Initial project setup ### 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 > /setup-project
``` ```
This creates (one at a time, with your approval): This creates (automatically, end-to-end):
1. `docs/product-requirements.md` (PRD) 1. `docs/product-requirements.md` (PRD)
2. `docs/functional-design.md` 2. `docs/functional-design.md`
3. `docs/architecture.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 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. 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 > /add-feature User authentication
@ -228,13 +264,14 @@ first if you have your own idea, or replace it.
This fully autonomous workflow: This fully autonomous workflow:
1. Creates `.steering/[YYYYMMDD]-[feature-name]/` with `requirements.md`, `design.md`, `tasklist.md` 1. Creates `.steering/[YYYYMMDD]-[feature-name]/` with `requirements.md`, `design.md`, `tasklist.md`
2. Generates the steering files (planning mode of the steering skill) 2. Reads the design spec (`docs/design/`) and updates it first if the feature changes the UI
3. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes 3. Generates the steering files (planning mode of the steering skill)
4. Launches the `implementation-validator` subagent for quality review 4. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
5. Runs `npm test`, `npm run lint`, `npm run typecheck` 5. Launches the `implementation-validator` subagent for quality review
6. Records a retrospective in `tasklist.md` 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 > /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: Launches the `doc-reviewer` subagent to evaluate the document from five perspectives:
completeness, clarity, consistency, implementability, and measurability. 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: 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 ## Commands Reference
| Command | Description | Example | | 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` | | `/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` | | `/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` | | `repository-structure` | Defining the directory layout | `docs/repository-structure.md` |
| `development-guidelines` | Creating coding conventions / implementing code | `docs/development-guidelines.md` | | `development-guidelines` | Creating coding conventions / implementing code | `docs/development-guidelines.md` |
| `glossary-creation` | Creating a project glossary | `docs/glossary.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 | | `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 Each skill folder contains a `SKILL.md` (instructions) plus `template.md` and/or `guide.md` (reference

62
docs/design/README.md Normal file
View File

@ -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.