opencode-boilerplate/.opencode/skills/ui-design/SKILL.md

name	description
ui-design	Guide for creating the UI/UX design specification (design brief, UI blueprint JSON, and SVG wireframes). Use when defining or updating the design under docs/design/.

UI Design Skill

This skill explains how to create an AI-readable, implementation-ready UI/UX design specification. It prefers structured, machine-consumable descriptions over vague visual descriptions.

Core Principle

The source of truth is structured text/JSON. Visual images (SVG) are references for humans, not inputs for code generation.

Prefer describing what a component is and how it behaves over describing what it looks like. "A primary button with label 'Save' that triggers action:save" is better than "a nice blue button in the corner".

Outputs

This skill produces three kinds of artifacts under docs/design/:

1. design-brief.md — the UI/UX direction (human-readable, but concrete)
2. ui-blueprint.json — the source of truth for UI generation (machine-readable)
3. screens/*.svg — visual wireframes for human review (derived from the blueprint)

Prerequisites

Before creating the design, read:

• docs/product-requirements.md
• docs/functional-design.md
• docs/architecture.md

The design must serve the product requirements and stay consistent with the functional design.

Creating design-brief.md

A concrete, opinionated document. Avoid vague phrases like "modern and clean" without elaboration. Include every section below:

• Target users — who the UI is for, and their key contexts/constraints
• Design concept — the one-paragraph idea the UI embodies
• Visual mood — concrete descriptors (density, light/dark, rounding, motion amount)
• Layout principles — grid, alignment, content width, spacing rhythm
• Navigation principles — primary navigation pattern, depth, back behavior
• Accessibility considerations — target contrast, touch-target sizes, focus visibility, font scaling
• Platform-specific notes — how the design adapts to web / Flutter / WinUI 3
• Examples of preferred UI style — concrete references and why they fit
• Examples of UI style to avoid — anti-patterns to stay away from

Creating ui-blueprint.json (source of truth)

This is the most important file. It must be valid JSON and fully describe the app's UI structure so that a generator can produce Web, Flutter, or WinUI 3 code without guessing.

Required top-level fields

• app.name
• app.platformTargets — e.g. ["web", "flutter", "winui3"]
• app.style — short style summary string
• screens — array of screen objects
• components — map of reusable component definitions

Screen object shape

Each screen has:

• id — stable identifier (used as the SVG filename)
• title
• route
• layout — type + spacing tokens (e.g. { "type": "vertical", "padding": "lg", "gap": "md" })
• components — a tree of component nodes

Component node shape

Each node has:

• type — e.g. header, card, text, button, list, input, image, nav
• variant — optional, must exist in the component's variants
• role — optional semantic role (e.g. title, subtitle, body)
• content / label — text content where applicable
• action — user action, e.g. navigate:details, submit, toggle:filters
• children — nested component nodes

Reusable component definition

"components": {
  "button": {
    "variants": ["primary", "secondary", "ghost"],
    "states": ["default", "hover", "pressed", "disabled"]
  }
}

Example (excerpt)

{
  "app": {
    "name": "Example App",
    "platformTargets": ["web", "flutter", "winui3"],
    "style": "friendly, modern, rounded, calm"
  },
  "screens": [
    {
      "id": "home",
      "title": "Home",
      "route": "/",
      "layout": { "type": "vertical", "padding": "lg", "gap": "md" },
      "components": [
        { "type": "header", "title": "Dashboard", "subtitle": "Welcome back" },
        {
          "type": "card",
          "variant": "primary",
          "children": [
            { "type": "text", "role": "title", "content": "Start here" },
            { "type": "button", "label": "Open", "action": "navigate:details" }
          ]
        }
      ]
    }
  ],
  "components": {
    "button": {
      "variants": ["primary", "secondary", "ghost"],
      "states": ["default", "hover", "pressed", "disabled"]
    },
    "card": {
      "variants": ["primary", "secondary", "danger"]
    }
  }
}

Rules

• Every variant referenced in a screen must exist in components[type].variants.
• Every spacing/radius/color name referenced in layout/components must exist in design-tokens.json.
• Use action: prefixes consistently: navigate:<screen-id>, submit, toggle:<id>, open:<id>, etc.
• One screen = one route. Do not overload a screen with multiple routes.
• Keep the blueprint free of hard-coded pixel values; reference token names instead.

Creating SVG wireframes (screens/*.svg)

• Generate one SVG per screen, named <screen-id>.svg.
• The SVG is a low-fidelity wireframe, not a pixel-perfect mock. Use boxes, labels, and placeholders.
• It must reflect the component tree of its screen in ui-blueprint.json.
• If the blueprint and an SVG disagree, the blueprint wins. Regenerate the SVG.
• SVGs exist only so humans can review the design at a glance.

Consistency Checklist

Before finishing:

• Every screen in the blueprint has a matching SVG.
• Every variant used in a screen is declared in components.
• Every token name used in the blueprint exists in design-tokens.json.
• The brief and the blueprint describe the same app (same screens, same navigation).
• No hard-coded values in the blueprint.