Ken Yasue
1649a71781
The initial app is no longer generated by a separate command. /plan-milestones now always makes milestone 01 'App Shell Generation' (target platform asked in the single question round): theme from design tokens, one screen per blueprint entry, routes, reusable components — no feature logic — plus Playwright setup and the e2e/app-shell.spec.ts smoke spec. It is executed like any other milestone via /execute-milestones (which follows platform-ui-generation for it) or /add-feature. Milestone 02 becomes the MVP core. All workflow diagrams, skills, docs READMEs, AGENTS.md, and README updated; docs/design README also gains the screen-inventory.md entry. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
67 lines
3.4 KiB
Markdown
67 lines
3.4 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 the App Shell milestone (milestone 01) 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/
|
||
├── screen-inventory.md # Exhaustive screen checklist derived from the PRD (built first)
|
||
├── 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
|
||
|
||
### `screen-inventory.md`
|
||
The exhaustive checklist of every screen the requirements imply — built first, before any other design file. Derived from every PRD user story walked end-to-end, CRUD coverage per entity (list/detail/create/edit/delete, modals included), and supporting screens, ending with a story→screen traceability table. Every entry must exist in `ui-blueprint.json`.
|
||
|
||
### `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
|
||
/plan-milestones → milestone 01 (App Shell) 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 milestone planning/execution will warn you to run `/define-design` first.
|