Ken Yasue
a579d90113
- New commands: /define-design, /update-design, /generate-app (web | flutter | winui3) - New skills: ui-design, design-tokens, platform-ui-generation - /add-feature: check design spec before implementation (Step 3.5) and reconcile all six persistent docs after implementation (Step 8) - /setup-project: automatic document creation with self-check checkpoints - CLAUDE.md: document docs/design/, .claude/ configuration, and the design phase in the development process - Enrich subagent descriptions; allowlist new skills in settings.json - Add docs/design/README.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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.
|