f57921abad
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
63 lines
2.9 KiB
Markdown
63 lines
2.9 KiB
Markdown
# 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.
|