f57921abad
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
113 lines
5.6 KiB
Markdown
113 lines
5.6 KiB
Markdown
---
|
|
name: platform-ui-generation
|
|
description: Guide for converting the design files (design-tokens.json + ui-blueprint.json) into application code for Web, Flutter, or WinUI 3. Use when running /generate-app or implementing UI against the design spec.
|
|
---
|
|
|
|
# Platform UI Generation Skill
|
|
|
|
This skill explains how to convert the design files under `docs/design/` into application code. It is used by `/generate-app` and by `/add-feature` when implementing UI.
|
|
|
|
## Core Principles
|
|
|
|
1. **Source of truth**: `docs/design/ui-blueprint.json` defines structure; `docs/design/design-tokens.json` defines values.
|
|
2. **No hard-coded values**: every color, size, spacing, radius, and duration in generated code must come from a token.
|
|
3. **Reusable components first**: extract reusable components; do not inline the entire tree into screens.
|
|
4. **No feature logic during scaffolding**: `/generate-app` creates the shell, theme, routes, screens, and shared components only. Features come from `/add-feature`.
|
|
5. **Respect the platform mapping**: `docs/design/platform-mapping.md` documents how each artifact maps to each platform.
|
|
|
|
## Inputs
|
|
|
|
- `docs/design/design-brief.md` — direction
|
|
- `docs/design/design-tokens.json` — values
|
|
- `docs/design/ui-blueprint.json` — structure (source of truth)
|
|
- `docs/design/platform-mapping.md` — per-platform conversion rules
|
|
- `docs/architecture.md` — technology choices (framework, language)
|
|
|
|
## General Conversion Rules
|
|
|
|
- One screen in the blueprint → one screen/page in the target platform.
|
|
- One route in the blueprint → one route entry in the navigation config.
|
|
- A reusable component referenced in multiple screens → a shared component file/widget/control.
|
|
- Component `variant` → a variant/style modifier on the shared component.
|
|
- Component `state` → visual states the component must support (default, hover, pressed, disabled, etc.).
|
|
- `action: navigate:<screen-id>` → navigation to the corresponding route.
|
|
- Other `action:` values → wire to a handler/placeholder; do not implement feature logic.
|
|
|
|
## Web Mapping
|
|
|
|
- **design tokens →** CSS variables, a Tailwind config, or a theme object.
|
|
- `color.*` → CSS custom properties (`--color-background-primary`) or Tailwind theme colors.
|
|
- `spacing.*`, `radius.*`, `typography.*` → CSS variables / Tailwind theme keys.
|
|
- `breakpoint.*` → responsive breakpoints.
|
|
- **ui-blueprint →**
|
|
- `screens` → pages/routes.
|
|
- `layout` → layout components (vertical/horizontal stack, grid).
|
|
- `components` → React (or framework) components, one file per reusable component.
|
|
- Use **semantic HTML** (`<header>`, `<main>`, `<nav>`, `<button>`, `<label>`) where possible.
|
|
- Respect responsive layout requirements using the breakpoint tokens.
|
|
- If no framework is specified in `architecture.md`, choose a simple default suitable for the repository and note the choice.
|
|
|
|
## Flutter Mapping
|
|
|
|
- **design tokens →**
|
|
- `color.*` → `ColorScheme` + a color constants file.
|
|
- `typography.*` → `TextTheme` / text styles.
|
|
- `spacing.*`, `radius.*` → constants (`spacing_md`, `radiusCard`).
|
|
- `shadow.*` → `BoxShadow` / elevation.
|
|
- `motion.duration.*` → `Duration` constants.
|
|
- Assemble into a `ThemeData`.
|
|
- **ui-blueprint →**
|
|
- `screens` → `Screen` widgets + routes (named routes or a router).
|
|
- `layout.type` → `Column` / `Row` / `Wrap` / `ListView` with `padding` and `SizedBox` gaps from spacing tokens.
|
|
- `components` → reusable widgets, one file per widget.
|
|
- Keep clean separation between: `screens/`, `widgets/`, `theme/`, `models/`, `services/`.
|
|
|
|
## WinUI 3 Mapping
|
|
|
|
- **design tokens →**
|
|
- `color.*`, `spacing.*`, `radius.*`, `typography.*` → a `ResourceDictionary` (`.xaml`) with `Color`, `Thickness`, `CornerRadius`, `FontFamily`, `Style` resources.
|
|
- Assemble theme resources and styles keyed by the token names.
|
|
- **ui-blueprint →**
|
|
- `screens` → XAML pages (`Page`).
|
|
- `layout.type` → `StackPanel` / `Grid` with `Padding`/`Margin` from token resources.
|
|
- `components` → `UserControl`s, one file per reusable component.
|
|
- Navigation → `Frame` + navigation entries per route.
|
|
- Use **C# and XAML**.
|
|
- Keep UI logic separated from business logic (code-behind stays thin; logic goes to services/viewmodels).
|
|
|
|
## Shared Component Contract
|
|
|
|
Each generated reusable component must:
|
|
|
|
- Accept the `variant` as a parameter/prop/style modifier.
|
|
- Support the `states` declared in the blueprint (default, hover, pressed, disabled).
|
|
- Reference tokens for all visual values — no hard-coded literals.
|
|
- Stay presentational: no feature/business logic.
|
|
|
|
## Scaffolding Scope (what `/generate-app` creates)
|
|
|
|
- App entry point and shell
|
|
- Theme/styling system from tokens
|
|
- Router/navigation config from routes
|
|
- One screen per blueprint screen (layout + components wired, but no feature logic)
|
|
- One shared component file per reusable component in `components`
|
|
|
|
## Out of Scope (handled by `/add-feature`)
|
|
|
|
- Feature/business logic
|
|
- Data fetching and state management for features
|
|
- Form validation and submission behavior
|
|
- Anything not described in the current project documents
|
|
|
|
## Generation Checklist
|
|
|
|
Before finishing a generation:
|
|
|
|
- [ ] Every screen in the blueprint has a corresponding generated screen.
|
|
- [ ] Every route is wired in the navigation config.
|
|
- [ ] Every reusable component in `components` has a generated file.
|
|
- [ ] No hard-coded color/size/spacing in generated code — all from tokens.
|
|
- [ ] Components accept `variant` and support declared `states`.
|
|
- [ ] No feature logic was implemented beyond the project documents.
|
|
- [ ] `docs/repository-structure.md` updated if the layout changed.
|