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.
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`).

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