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:
178
.claude/commands/define-design.md
Normal file
178
.claude/commands/define-design.md
Normal file
@ -0,0 +1,178 @@
|
||||
---
|
||||
description: Create the UI/UX design specification (design brief, tokens, UI blueprint, platform mapping, SVG wireframes)
|
||||
---
|
||||
|
||||
# Define Design (UI/UX Design Phase)
|
||||
|
||||
This command creates (or updates) the project's design specification under `docs/design/`. The design is **AI-readable and implementation-ready**: the source of truth is structured text/JSON, not visual images.
|
||||
|
||||
**Design source of truth**: `docs/design/ui-blueprint.json`
|
||||
**Visual references only**: `docs/design/screens/*.svg`
|
||||
|
||||
## How to Run
|
||||
|
||||
```bash
|
||||
claude
|
||||
> /define-design
|
||||
```
|
||||
|
||||
## Position in the Workflow
|
||||
|
||||
```
|
||||
/setup-project
|
||||
↓
|
||||
/define-design ← you are here
|
||||
↓
|
||||
/generate-app web | flutter | winui3
|
||||
↓
|
||||
/add-feature
|
||||
```
|
||||
|
||||
## Pre-Run Check
|
||||
|
||||
1. Confirm the persistent documents exist. If any of these are missing, stop and tell the user to run `/setup-project` first:
|
||||
- `docs/product-requirements.md`
|
||||
- `docs/functional-design.md`
|
||||
- `docs/architecture.md`
|
||||
2. Create the design directory if it does not exist:
|
||||
```bash
|
||||
mkdir -p docs/design/screens
|
||||
```
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 0: Read the Inputs
|
||||
|
||||
Read all of the following to understand what is being built:
|
||||
|
||||
- `docs/product-requirements.md`
|
||||
- `docs/functional-design.md`
|
||||
- `docs/architecture.md`
|
||||
- `docs/repository-structure.md`
|
||||
- `docs/development-guidelines.md`
|
||||
- `docs/glossary.md`
|
||||
- `docs/ideas/*` (if present)
|
||||
|
||||
### Step 1: Gather Design Preferences (ask the user once)
|
||||
|
||||
Ask the user about the following. If the user does not provide detailed preferences, **propose a sensible default** derived from the product requirements and confirm it before proceeding.
|
||||
|
||||
- **Target platform**: `web`, `flutter`, `winui3`, or `multi`
|
||||
- **Visual style** (e.g. friendly/modern/rounded/calm, dark or light, density)
|
||||
- **Main screens** the app must have
|
||||
- **Navigation style** (e.g. tab bar, drawer, sidebar, stack)
|
||||
- **Branding preferences** (name, colors, tone)
|
||||
- **Accessibility requirements** (e.g. WCAG level, minimum contrast, large-touch targets)
|
||||
|
||||
Collect the answers in a single round; do not pause again until generation is complete.
|
||||
|
||||
### Step 2: Load the Design Skills
|
||||
|
||||
- Load the **ui-design skill** (`Skill('ui-design')`) to create `design-brief.md`, `ui-blueprint.json`, and the SVG wireframes.
|
||||
- Load the **design-tokens skill** (`Skill('design-tokens')`) to create `design-tokens.json`.
|
||||
|
||||
### Step 3: Create the Design Brief
|
||||
|
||||
Create `docs/design/design-brief.md` covering:
|
||||
|
||||
- Target users
|
||||
- Design concept
|
||||
- Visual mood
|
||||
- Layout principles
|
||||
- Navigation principles
|
||||
- Accessibility considerations
|
||||
- Platform-specific notes
|
||||
- Examples of preferred UI style
|
||||
- Examples of UI style to avoid
|
||||
|
||||
### Step 4: Create the Design Tokens
|
||||
|
||||
Create `docs/design/design-tokens.json` using a JSON structure inspired by the Design Tokens Community Group format (each token has `$type` and `$value`). Include:
|
||||
|
||||
- Colors (semantic names: background, text, accent, border, state, etc.)
|
||||
- Typography (font families, sizes, weights, line heights)
|
||||
- Spacing scale
|
||||
- Border radius
|
||||
- Shadows / elevation
|
||||
- Animation durations / easings
|
||||
- Breakpoints (if the target includes web)
|
||||
|
||||
### Step 5: Create the UI Blueprint (source of truth)
|
||||
|
||||
Create `docs/design/ui-blueprint.json`. This is **the** source of truth for UI generation. It must describe:
|
||||
|
||||
- App name and target platforms
|
||||
- Overall style summary
|
||||
- Routes
|
||||
- Screens (each with id, title, route, layout, and component tree)
|
||||
- Layouts
|
||||
- Components (variants and states)
|
||||
- Component hierarchy
|
||||
- User actions and navigation behavior
|
||||
|
||||
### Step 6: Create the Platform Mapping
|
||||
|
||||
Create `docs/design/platform-mapping.md` describing how the design spec is converted to each platform:
|
||||
|
||||
```text
|
||||
Web:
|
||||
- design-tokens.json → CSS variables or Tailwind theme
|
||||
- ui-blueprint.json → pages, routes, React components, layout components
|
||||
|
||||
Flutter:
|
||||
- design-tokens.json → ThemeData, ColorScheme, constants
|
||||
- ui-blueprint.json → Widget tree, routes, reusable widgets
|
||||
|
||||
WinUI 3:
|
||||
- design-tokens.json → ResourceDictionary
|
||||
- ui-blueprint.json → XAML pages, UserControls, styles
|
||||
```
|
||||
|
||||
### Step 7: Generate SVG Wireframes (visual references only)
|
||||
|
||||
For each screen in `ui-blueprint.json`, generate a corresponding SVG wireframe under `docs/design/screens/`:
|
||||
|
||||
- `docs/design/screens/home.svg`
|
||||
- `docs/design/screens/settings.svg`
|
||||
- `docs/design/screens/[screen-id].svg`
|
||||
|
||||
**Important rule**: SVG files are **not** the source of truth. They are generated as visual references for human review only. The source of truth is `ui-blueprint.json`. If the blueprint and an SVG ever disagree, the blueprint wins and the SVG must be regenerated.
|
||||
|
||||
### Step 8: Consistency Check
|
||||
|
||||
Re-read all generated files and confirm:
|
||||
|
||||
- Every screen in `ui-blueprint.json` has a matching SVG in `screens/`.
|
||||
- Token names referenced in `ui-blueprint.json` exist in `design-tokens.json`.
|
||||
- `platform-mapping.md` covers all target platforms selected in Step 1.
|
||||
- The design is consistent with `docs/product-requirements.md` and `docs/functional-design.md`.
|
||||
|
||||
Fix any inconsistencies found before finishing.
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
- `docs/design/design-brief.md` exists
|
||||
- `docs/design/design-tokens.json` exists and is valid JSON
|
||||
- `docs/design/ui-blueprint.json` exists and is valid JSON
|
||||
- `docs/design/platform-mapping.md` exists
|
||||
- One SVG per screen exists under `docs/design/screens/`
|
||||
|
||||
Completion message:
|
||||
```
|
||||
"Design phase is complete!
|
||||
|
||||
Design documents created:
|
||||
✅ docs/design/design-brief.md
|
||||
✅ docs/design/design-tokens.json
|
||||
✅ docs/design/ui-blueprint.json (source of truth)
|
||||
✅ docs/design/platform-mapping.md
|
||||
✅ docs/design/screens/*.svg (visual references)
|
||||
|
||||
Next steps:
|
||||
- Review docs/design/ (especially ui-blueprint.json)
|
||||
- Refine the design with /update-design <change> (or re-run /define-design) until approved — do this BEFORE generating code
|
||||
- Run /generate-app web | flutter | winui3 to generate the initial app
|
||||
- Use /update-design when a feature changes the UI
|
||||
- Use /add-feature to add features (it respects the design spec)
|
||||
"
|
||||
```
|
||||
Reference in New Issue
Block a user