claudecode-boilerplate/.claude/skills/platform-ui-generation/SKILL.md

---
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 executing the App Shell milestone (milestone 01) or implementing UI against the design spec.
allowed-tools: Read, Write, Edit, Bash
---

# Platform UI Generation Skill

This skill explains how to convert the design files under `docs/design/` into application code. It is used by the **App Shell milestone** (milestone 01 — planned by `/plan-milestones`, executed by `/execute-milestones` or `/add-feature`) 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**: the App Shell milestone creates the shell, theme, routes, screens, and shared components only. Features come from the later milestones.
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 the App Shell milestone 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.