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

name	description	allowed-tools
platform-ui-generation	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.	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 /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 → UserControls, 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.