Compare commits
3 Commits
e1ef10be6e
...
readme-wor
| Author | SHA1 | Date | |
|---|---|---|---|
| 89e6a58929 | |||
| 7fdb430c67 | |||
| f57921abad |
@ -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`).
|
||||
|
||||
179
.opencode/command/define-design.md
Normal file
179
.opencode/command/define-design.md
Normal file
@ -0,0 +1,179 @@
|
||||
---
|
||||
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)
|
||||
- Refine the design with /update-design <change> (or re-run /define-design) until approved — do this BEFORE generating code
|
||||
- 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)
|
||||
"
|
||||
```
|
||||
148
.opencode/command/generate-app.md
Normal file
148
.opencode/command/generate-app.md
Normal file
@ -0,0 +1,148 @@
|
||||
---
|
||||
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.
|
||||
4. This command generates from the design **as-is**. Refine the design first (re-run `/define-design` or use `/update-design <change>`) if anything needs to change — it is far easier to refine before code is generated than after.
|
||||
|
||||
## 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
90
.opencode/command/update-design.md
Normal file
@ -0,0 +1,90 @@
|
||||
---
|
||||
description: Refine the design before /generate-app, or update it when a feature changes the UI (blueprint first, then tokens, brief, and SVGs)
|
||||
agent: build
|
||||
---
|
||||
|
||||
# Update Design
|
||||
|
||||
This command updates the design specification. It is used in two situations: (1) to refine the UI/UX **before** running `/generate-app` (e.g. adjusting screens, tokens, or layout after reviewing the initial design), and (2) to update the design when a feature 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
137
.opencode/skills/design-tokens/SKILL.md
Normal 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
112
.opencode/skills/platform-ui-generation/SKILL.md
Normal 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
156
.opencode/skills/ui-design/SKILL.md
Normal 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.
|
||||
24
AGENTS.md
24
AGENTS.md
@ -78,6 +78,14 @@ Define "what to build" and "how to build it" for the entire application:
|
||||
- **development-guidelines.md** - Development guidelines
|
||||
- **glossary.md** - Ubiquitous language definitions
|
||||
|
||||
#### Design Documents (`docs/design/`)
|
||||
- **design-brief.md** - UI/UX direction
|
||||
- **design-tokens.json** - Styling tokens (source of values)
|
||||
- **ui-blueprint.json** - UI structure (source of truth for UI generation)
|
||||
- **platform-mapping.md** - How the design maps to Web / Flutter / WinUI 3
|
||||
- **screens/\*.svg** - Visual wireframes (references only)
|
||||
- Created by `/define-design`, updated by `/update-design`, consumed by `/generate-app` and `/add-feature`
|
||||
|
||||
### Work-Unit Documents (`.steering/`)
|
||||
|
||||
Define "what to do this time" for a specific development task:
|
||||
@ -89,16 +97,19 @@ Define "what to do this time" for a specific development task:
|
||||
### opencode Configuration (`.opencode/`)
|
||||
|
||||
- `.opencode/agent/` - Subagent definitions (doc-reviewer, implementation-validator)
|
||||
- `.opencode/command/` - Slash commands (setup-project, add-feature, review-docs)
|
||||
- `.opencode/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, steering)
|
||||
- `.opencode/command/` - Slash commands (setup-project, define-design, generate-app, update-design, add-feature, review-docs)
|
||||
- `.opencode/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, ui-design, design-tokens, platform-ui-generation, steering)
|
||||
|
||||
## Development Process
|
||||
|
||||
### Initial Setup
|
||||
|
||||
1. Use this template
|
||||
2. Create persistent documents with `/setup-project` (interactively creating six)
|
||||
3. Implement features with `/add-feature [feature]`
|
||||
2. Create persistent documents with `/setup-project` (automatically creating six)
|
||||
3. Define the UI/UX design with `/define-design` (creates `docs/design/`)
|
||||
4. Review and refine the UI/UX with `/update-design` (or re-run `/define-design`) until approved — before generating code
|
||||
5. Generate the initial app with `/generate-app web | flutter | winui3`
|
||||
6. Implement features with `/add-feature [feature]`
|
||||
|
||||
### Day-to-Day Usage
|
||||
|
||||
@ -113,6 +124,11 @@ Define "what to do this time" for a specific development task:
|
||||
# Adding features (use commands for the standard flow)
|
||||
> /add-feature edit user profile
|
||||
|
||||
# Design phase
|
||||
> /define-design
|
||||
> /generate-app web
|
||||
> /update-design add a profile screen
|
||||
|
||||
# Detailed review (when a detailed report is needed)
|
||||
> /review-docs docs/product-requirements.md
|
||||
```
|
||||
|
||||
157
README.md
157
README.md
@ -9,8 +9,63 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow (Step by Step)
|
||||
|
||||
How a project goes from idea to working code with this boilerplate:
|
||||
|
||||
```
|
||||
Idea → /setup-project → /define-design → refine design → /generate-app → /add-feature (repeat)
|
||||
```
|
||||
|
||||
### Step 1 — Write down your idea
|
||||
Put your brainstorming notes, requirements, and constraints into
|
||||
`docs/ideas/initial-requirements.md` (free-form; replace the sample content with your own).
|
||||
|
||||
### Step 2 — Create the specification: `/setup-project`
|
||||
Automatically creates the six persistent documents that define **what to build**:
|
||||
PRD, functional design, architecture, repository structure, development guidelines, and glossary
|
||||
(all under `docs/`). Review them and request edits in normal conversation if needed.
|
||||
|
||||
### Step 3 — Define the UI/UX design: `/define-design`
|
||||
Creates the design specification under `docs/design/`: design brief, design tokens,
|
||||
**`ui-blueprint.json` (the source of truth for UI generation)**, platform mapping, and SVG
|
||||
wireframes (visual references only). You'll be asked once about platform, style, screens,
|
||||
navigation, branding, and accessibility.
|
||||
|
||||
### Step 4 — Review and refine the design **before writing any code**
|
||||
This is the key design-decision gate: iterate on the design while it is still cheap to change.
|
||||
|
||||
- `/update-design <change>` — targeted refinements (e.g. `add a profile screen`)
|
||||
- Re-run `/define-design` — change the overall direction
|
||||
- Repeat until you approve the design (especially `ui-blueprint.json`)
|
||||
|
||||
### Step 5 — Generate the initial app: `/generate-app web | flutter | winui3`
|
||||
Scaffolds the app shell from the approved design: theme (from tokens), routes, screens, and
|
||||
reusable components. No feature logic yet.
|
||||
|
||||
### Step 6 — Implement features: `/add-feature <feature>`
|
||||
A fully autonomous loop, one feature at a time. Each run:
|
||||
|
||||
1. Creates `.steering/[YYYYMMDD]-[feature]/` (requirements, design, tasklist)
|
||||
2. Reads the design spec first — and updates it first if the feature changes the UI
|
||||
3. Implements every task in `tasklist.md`, checking items off as it goes
|
||||
4. Validates quality with the `implementation-validator` subagent
|
||||
5. Runs `npm test`, `npm run lint`, `npm run typecheck` until green
|
||||
6. Records a retrospective and reconciles all six `docs/` documents with the feature
|
||||
|
||||
### Step 7 — Repeat and maintain
|
||||
- More features → `/add-feature <feature>` (again and again)
|
||||
- UI changes → `/update-design <change>` first, then `/add-feature`
|
||||
- Document quality checks → `/review-docs <path>`
|
||||
|
||||
**A feature is "done" when**: all tasks in its tasklist are `[x]`, validation passes,
|
||||
test/lint/typecheck succeed, and the persistent documents are back in sync with the code.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Development Workflow (Step by Step)](#development-workflow-step-by-step)
|
||||
- [What Is Spec-Driven Development?](#what-is-spec-driven-development)
|
||||
- [Conversion Summary (Claude Code → opencode)](#conversion-summary-claude-code--opencode)
|
||||
- [Prerequisites](#prerequisites)
|
||||
@ -18,6 +73,7 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
|
||||
- [Directory Structure](#directory-structure)
|
||||
- [Configuration Overview](#configuration-overview)
|
||||
- [Usage Workflow](#usage-workflow)
|
||||
- [Design & App Generation](#design--app-generation)
|
||||
- [Commands Reference](#commands-reference)
|
||||
- [Skills Reference](#skills-reference)
|
||||
- [Agents Reference](#agents-reference)
|
||||
@ -123,9 +179,15 @@ opencode
|
||||
│ ├── example.ts
|
||||
│ └── example.test.ts
|
||||
│
|
||||
├── docs/ # Persistent design documents (created by /setup-project)
|
||||
│ └── ideas/
|
||||
│ └── initial-requirements.md # Brainstorming notes (pre-PRD)
|
||||
├── docs/ # Persistent design documents
|
||||
│ ├── ideas/
|
||||
│ │ └── initial-requirements.md # Brainstorming notes (pre-PRD)
|
||||
│ └── design/ # UI/UX design spec (created by /define-design)
|
||||
│ ├── design-brief.md
|
||||
│ ├── design-tokens.json
|
||||
│ ├── ui-blueprint.json # source of truth for UI
|
||||
│ ├── platform-mapping.md
|
||||
│ └── screens/*.svg # visual references only
|
||||
│
|
||||
├── .steering/ # Per-task steering files (created by /add-feature)
|
||||
│ └── .gitkeep
|
||||
@ -136,6 +198,9 @@ opencode
|
||||
│ └── implementation-validator.md
|
||||
├── command/ # Slash commands
|
||||
│ ├── setup-project.md
|
||||
│ ├── define-design.md
|
||||
│ ├── generate-app.md
|
||||
│ ├── update-design.md
|
||||
│ ├── add-feature.md
|
||||
│ └── review-docs.md
|
||||
└── skills/ # Task-specific skills
|
||||
@ -145,6 +210,9 @@ opencode
|
||||
├── repository-structure/ (SKILL.md + template.md + guide.md)
|
||||
├── development-guidelines/(SKILL.md + template.md + guides/)
|
||||
├── glossary-creation/ (SKILL.md + template.md + guide.md)
|
||||
├── ui-design/ (SKILL.md)
|
||||
├── design-tokens/ (SKILL.md)
|
||||
├── platform-ui-generation/(SKILL.md)
|
||||
└── steering/ (SKILL.md + templates/)
|
||||
```
|
||||
|
||||
@ -203,13 +271,13 @@ opencode surfaces the right skill when the task matches.
|
||||
|
||||
### 1. Initial project setup
|
||||
|
||||
Run the setup command to create all six persistent design documents interactively:
|
||||
Run the setup command to automatically create all six persistent design documents:
|
||||
|
||||
```
|
||||
> /setup-project
|
||||
```
|
||||
|
||||
This creates (one at a time, with your approval):
|
||||
This creates (automatically, end-to-end):
|
||||
1. `docs/product-requirements.md` (PRD)
|
||||
2. `docs/functional-design.md`
|
||||
3. `docs/architecture.md`
|
||||
@ -220,7 +288,37 @@ This creates (one at a time, with your approval):
|
||||
The PRD is based on the brainstorming notes in `docs/ideas/initial-requirements.md`. Edit that file
|
||||
first if you have your own idea, or replace it.
|
||||
|
||||
### 2. Add a feature
|
||||
### 2. Define the UI/UX design
|
||||
|
||||
```
|
||||
> /define-design
|
||||
```
|
||||
|
||||
Creates the design specification under `docs/design/` (design brief, design tokens, UI blueprint,
|
||||
platform mapping, and SVG wireframes). You'll be asked about target platform, visual style, main
|
||||
screens, navigation, branding, and accessibility; if you don't specify, sensible defaults are proposed.
|
||||
|
||||
Review and refine the UI/UX **before** generating the app — it is far easier to iterate on the design
|
||||
than on generated code:
|
||||
|
||||
- Re-run `/define-design` to change the overall direction.
|
||||
- Run `/update-design <change>` for targeted refinements (e.g. `/update-design make the home screen denser`).
|
||||
- Iterate until the design — especially `docs/design/ui-blueprint.json` — is approved.
|
||||
|
||||
**The design source of truth is `docs/design/ui-blueprint.json`.** SVG files are visual references only.
|
||||
|
||||
### 3. Generate the app
|
||||
|
||||
```
|
||||
> /generate-app web
|
||||
> /generate-app flutter
|
||||
> /generate-app winui3
|
||||
```
|
||||
|
||||
Scaffolds the initial application for the selected target from the design spec — app shell, theme
|
||||
(from tokens), routes, screens, and reusable components. No feature logic is implemented here.
|
||||
|
||||
### 4. Add a feature
|
||||
|
||||
```
|
||||
> /add-feature User authentication
|
||||
@ -228,13 +326,14 @@ first if you have your own idea, or replace it.
|
||||
|
||||
This fully autonomous workflow:
|
||||
1. Creates `.steering/[YYYYMMDD]-[feature-name]/` with `requirements.md`, `design.md`, `tasklist.md`
|
||||
2. Generates the steering files (planning mode of the steering skill)
|
||||
3. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
|
||||
4. Launches the `implementation-validator` subagent for quality review
|
||||
5. Runs `npm test`, `npm run lint`, `npm run typecheck`
|
||||
6. Records a retrospective in `tasklist.md`
|
||||
2. Reads the design spec (`docs/design/`) and updates it first if the feature changes the UI
|
||||
3. Generates the steering files (planning mode of the steering skill)
|
||||
4. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
|
||||
5. Launches the `implementation-validator` subagent for quality review
|
||||
6. Runs `npm test`, `npm run lint`, `npm run typecheck`
|
||||
7. Records a retrospective and reconciles all six persistent docs with the feature
|
||||
|
||||
### 3. Review a document
|
||||
### 5. Review a document
|
||||
|
||||
```
|
||||
> /review-docs docs/product-requirements.md
|
||||
@ -243,7 +342,7 @@ This fully autonomous workflow:
|
||||
Launches the `doc-reviewer` subagent to evaluate the document from five perspectives:
|
||||
completeness, clarity, consistency, implementability, and measurability.
|
||||
|
||||
### 4. Day-to-day editing
|
||||
### 6. Day-to-day editing
|
||||
|
||||
You don't always need a command — just ask in normal conversation:
|
||||
|
||||
@ -257,11 +356,38 @@ opencode loads the appropriate skill automatically.
|
||||
|
||||
---
|
||||
|
||||
## Design & App Generation
|
||||
|
||||
Recommended workflow:
|
||||
|
||||
1. Run `/setup-project`
|
||||
2. Run `/define-design`
|
||||
3. Review `docs/design/` and refine the UI/UX until approved:
|
||||
- Re-run `/define-design` to change direction, or
|
||||
- Run `/update-design <change>` for targeted refinements
|
||||
4. Run `/generate-app web`, `/generate-app flutter`, or `/generate-app winui3`
|
||||
5. Use `/add-feature` to add features
|
||||
6. Use `/update-design` whenever a feature changes the UI
|
||||
|
||||
Source of truth:
|
||||
|
||||
- The design source of truth is `docs/design/ui-blueprint.json`.
|
||||
- SVG files (`docs/design/screens/*.svg`) are only visual references.
|
||||
- Generated UI should follow `docs/design/design-tokens.json` — no hard-coded values.
|
||||
- No platform-specific implementation is generated before `/generate-app` is executed.
|
||||
|
||||
See [`docs/design/README.md`](docs/design/README.md) for the full structure.
|
||||
|
||||
---
|
||||
|
||||
## Commands Reference
|
||||
|
||||
| Command | Description | Example |
|
||||
|---|---|---|
|
||||
| `/setup-project` | Create the six persistent documents interactively | `/setup-project` |
|
||||
| `/setup-project` | Create the six persistent documents automatically | `/setup-project` |
|
||||
| `/define-design` | Create the UI/UX design spec under `docs/design/` | `/define-design` |
|
||||
| `/generate-app` | Scaffold the initial app for a target platform | `/generate-app web` |
|
||||
| `/update-design` | Update the design spec when a feature changes the UI | `/update-design add a profile screen` |
|
||||
| `/add-feature` | Implement a feature end-to-end (autonomous) | `/add-feature User profile editing` |
|
||||
| `/review-docs` | Detailed document review via subagent | `/review-docs docs/architecture.md` |
|
||||
|
||||
@ -277,6 +403,9 @@ opencode loads the appropriate skill automatically.
|
||||
| `repository-structure` | Defining the directory layout | `docs/repository-structure.md` |
|
||||
| `development-guidelines` | Creating coding conventions / implementing code | `docs/development-guidelines.md` |
|
||||
| `glossary-creation` | Creating a project glossary | `docs/glossary.md` |
|
||||
| `ui-design` | Creating the design brief, UI blueprint, and SVG wireframes | `docs/design/` files |
|
||||
| `design-tokens` | Creating and maintaining design tokens | `docs/design/design-tokens.json` |
|
||||
| `platform-ui-generation` | Converting design files into Web/Flutter/WinUI 3 code | generated app code |
|
||||
| `steering` | Planning, implementing, and retrospecting on a task | `.steering/[date]-[name]/` files |
|
||||
|
||||
Each skill folder contains a `SKILL.md` (instructions) plus `template.md` and/or `guide.md` (reference
|
||||
|
||||
62
docs/design/README.md
Normal file
62
docs/design/README.md
Normal 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.
|
||||
Reference in New Issue
Block a user