Files

Ken Yasue f57921abad feat: add design phase and platform app generation phase

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

2026-06-28 18:41:01 +02:00

2.9 KiB

Raw Blame History

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.

2.9 KiB Raw Blame History Unescape Escape

Design Specification (docs/design/)