Add design-first workflow aligned with opencode boilerplate
- New commands: /define-design, /update-design, /generate-app (web | flutter | winui3) - New skills: ui-design, design-tokens, platform-ui-generation - /add-feature: check design spec before implementation (Step 3.5) and reconcile all six persistent docs after implementation (Step 8) - /setup-project: automatic document creation with self-check checkpoints - CLAUDE.md: document docs/design/, .claude/ configuration, and the design phase in the development process - Enrich subagent descriptions; allowlist new skills in settings.json - Add docs/design/README.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
157
.claude/skills/ui-design/SKILL.md
Normal file
157
.claude/skills/ui-design/SKILL.md
Normal file
@ -0,0 +1,157 @@
|
||||
---
|
||||
name: ui-design
|
||||
description: 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/.
|
||||
allowed-tools: Read, Write, Edit
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
```json
|
||||
"components": {
|
||||
"button": {
|
||||
"variants": ["primary", "secondary", "ghost"],
|
||||
"states": ["default", "hover", "pressed", "disabled"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example (excerpt)
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user