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>
2.9 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 /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,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
/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.