opencode-boilerplate/.opencode/skills/platform-ui-generation/SKILL.md

name	description
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 executing the App Shell milestone (milestone 01) 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 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 → 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 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.