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>
3.4 KiB
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,UserControls, 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.