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:
@ -1,6 +1,6 @@
|
||||
---
|
||||
name: doc-reviewer
|
||||
description: A subagent that reviews document quality and provides improvement suggestions
|
||||
description: A subagent that reviews document quality and provides improvement suggestions. Use when reviewing project documents (PRD, functional design, architecture, etc.) for completeness, clarity, consistency, implementability, and measurability.
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
name: implementation-validator
|
||||
description: A subagent that validates implementation code quality and confirms consistency with the spec
|
||||
description: A subagent that validates implementation code quality and confirms consistency with the spec. Use when verifying that implemented code meets spec requirements, coding standards, test coverage, security, and performance targets.
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
|
||||
@ -6,14 +6,14 @@ description: Implement a new feature following existing patterns, fully autonomo
|
||||
|
||||
**Important:** This workflow is designed to run fully automatically from start to finish without user intervention. After completing each step, immediately move on to the next step. Do not ask the user for confirmation mid-thought or interrupt the work.
|
||||
|
||||
**Argument:** feature name (e.g. `/add-feature User profile editing`)
|
||||
**Feature name**: `$ARGUMENTS` (e.g. `/add-feature User profile editing`)
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Preparation and Context Setup
|
||||
|
||||
1. Establish the current task context:
|
||||
- Feature name: `[the feature name given as an argument]`
|
||||
- Feature name: `$ARGUMENTS`
|
||||
- Date: `[get the current date in YYYYMMDD format]`
|
||||
- Steering directory path: `.steering/[date]-[feature name]/`
|
||||
2. Create the steering directory above.
|
||||
@ -35,6 +35,30 @@ description: Implement a new feature following existing patterns, fully autonomo
|
||||
```
|
||||
2. Analyze the search results to identify existing implementation patterns, naming conventions, and how components are used.
|
||||
|
||||
## Step 3.5: Check the Design Specification (Before Implementation)
|
||||
|
||||
Before implementing any feature, respect the UI/UX design specification.
|
||||
|
||||
1. Check whether the design files exist:
|
||||
- `docs/design/design-brief.md`
|
||||
- `docs/design/design-tokens.json`
|
||||
- `docs/design/ui-blueprint.json`
|
||||
- `docs/design/platform-mapping.md`
|
||||
|
||||
2. **If the design files do not exist**, warn the user and suggest running `/define-design` before continuing. Do not silently proceed without a design spec.
|
||||
|
||||
3. **If the design files exist**, read all four of them before implementation:
|
||||
1. `docs/design/design-brief.md`
|
||||
2. `docs/design/design-tokens.json`
|
||||
3. `docs/design/ui-blueprint.json` (source of truth)
|
||||
4. `docs/design/platform-mapping.md`
|
||||
|
||||
4. **If the feature changes the UI**, update the design files first, following the `/update-design` order:
|
||||
- `ui-blueprint.json` → `design-tokens.json` → `design-brief.md` → `platform-mapping.md` → regenerate affected `screens/*.svg`
|
||||
- The blueprint is the source of truth; SVGs are visual references only.
|
||||
|
||||
5. Then implement the feature according to the selected platform mapping in `platform-mapping.md`, using tokens from `design-tokens.json` (no hard-coded values) and the component tree from `ui-blueprint.json`.
|
||||
|
||||
## Step 4: Planning Phase (Automatic Generation of Steering Files)
|
||||
|
||||
1. Run `Skill('steering')` in **planning mode** to generate the contents of the three files created in Step 1 (`requirements.md`, `design.md`, `tasklist.md`).
|
||||
@ -116,9 +140,18 @@ If any of the following situations occur while the implementation loop is runnin
|
||||
- Lessons learned
|
||||
- Improvement suggestions for next time
|
||||
|
||||
2. Determine whether this change affects the project's fundamental design or architecture.
|
||||
2. **Reconcile all six persistent documents in `docs/` with the feature just implemented.** For each document, read its current content, then use the `Edit` tool to update it so it reflects the new feature. An update may be skipped **only** when the document genuinely requires no change for this feature — in that case, leave the document untouched and note the skip reason in the retrospective.
|
||||
|
||||
3. If there is an impact, use the `Edit` tool to update the relevant persistent documents in `docs/`.
|
||||
- ✅ `docs/product-requirements.md` — add/update user stories, acceptance criteria, non-functional requirements, and success metrics for the feature
|
||||
- ✅ `docs/functional-design.md` — add/update functional modules, screens, data flows, and state changes introduced by the feature
|
||||
- ✅ `docs/architecture.md` — add/update components, layers, data models, APIs, and non-functional decisions affected by the feature
|
||||
- ✅ `docs/repository-structure.md` — add/update any new directories, files, or modules created for the feature
|
||||
- ✅ `docs/development-guidelines.md` — add/update any new conventions, patterns, or standards established during the feature
|
||||
- ✅ `docs/glossary.md` — add/update any new domain terms introduced by the feature
|
||||
|
||||
3. **Consistency check**: re-read each updated document and confirm it is consistent with the other documents and with the implemented code. Fix any inconsistencies found.
|
||||
|
||||
4. **Once this step completes successfully, never stop; immediately proceed to the Completion Criteria.**
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
@ -126,6 +159,6 @@ This workflow completes automatically once all of the following conditions are m
|
||||
- Step 5: All tasks in `tasklist.md` are complete (`[x]` or skipped for a valid reason).
|
||||
- Step 6: The `implementation-validator` subagent's validation passes.
|
||||
- Step 7: The `test`, `lint`, and `typecheck` commands all succeed without errors.
|
||||
- Step 8: Handover notes are recorded in `tasklist.md`.
|
||||
- Step 8: Handover notes are recorded in `tasklist.md`, and all six persistent documents in `docs/` have been reconciled with the feature (updates applied, or a skip reason noted for each).
|
||||
|
||||
Until these completion criteria are met, continue to think autonomously, solve problems, and carry on the work.
|
||||
|
||||
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)
|
||||
"
|
||||
```
|
||||
147
.claude/commands/generate-app.md
Normal file
147
.claude/commands/generate-app.md
Normal file
@ -0,0 +1,147 @@
|
||||
---
|
||||
description: Generate the initial application for a target platform (web | flutter | winui3) from the design spec
|
||||
---
|
||||
|
||||
# Generate App (Platform App Generation Phase)
|
||||
|
||||
This command generates the **initial application** for the selected target platform, using the design files in `docs/design/` as the source of truth. It creates the app shell, theme, routes, screens, and reusable components — **not** feature logic. Features are added later with `/add-feature`.
|
||||
|
||||
**Target platform**: `$ARGUMENTS` — must be one of `web`, `flutter`, `winui3`.
|
||||
|
||||
## How to Run
|
||||
|
||||
```bash
|
||||
claude
|
||||
> /generate-app web
|
||||
> /generate-app flutter
|
||||
> /generate-app winui3
|
||||
```
|
||||
|
||||
## Position in the Workflow
|
||||
|
||||
```
|
||||
/setup-project
|
||||
↓
|
||||
/define-design
|
||||
↓
|
||||
/generate-app web | flutter | winui3 ← you are here
|
||||
↓
|
||||
/add-feature
|
||||
```
|
||||
|
||||
## Pre-Run Check
|
||||
|
||||
1. Validate the target:
|
||||
- If `$ARGUMENTS` is not one of `web`, `flutter`, `winui3`, stop and ask the user to provide a valid target.
|
||||
2. Confirm the design files exist. If any of these are missing, stop and tell the user to run `/define-design` first:
|
||||
- `docs/design/design-brief.md`
|
||||
- `docs/design/design-tokens.json`
|
||||
- `docs/design/ui-blueprint.json`
|
||||
- `docs/design/platform-mapping.md`
|
||||
3. **Important**: Do **not** generate any platform-specific implementation before this command is executed. This command is the only place initial app scaffolding is created.
|
||||
4. This command generates from the design **as-is**. Refine the design first (re-run `/define-design` or use `/update-design <change>`) if anything needs to change — it is far easier to refine before code is generated than after.
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 0: Read the Inputs
|
||||
|
||||
Read all of the following:
|
||||
|
||||
- `docs/product-requirements.md`
|
||||
- `docs/functional-design.md`
|
||||
- `docs/architecture.md`
|
||||
- `docs/repository-structure.md`
|
||||
- `docs/development-guidelines.md`
|
||||
- `docs/design/design-brief.md`
|
||||
- `docs/design/design-tokens.json`
|
||||
- `docs/design/ui-blueprint.json`
|
||||
- `docs/design/platform-mapping.md`
|
||||
|
||||
### Step 1: Load the Platform Generation Skill
|
||||
|
||||
Load the **platform-ui-generation skill** (`Skill('platform-ui-generation')`) for the mapping rules from design files to the selected platform's code.
|
||||
|
||||
### Step 2: Generate the App Shell
|
||||
|
||||
Generate the initial application for the selected target. In all cases:
|
||||
|
||||
- Respect the design tokens and the UI blueprint exactly.
|
||||
- Create reusable UI components (do not inline everything into screens).
|
||||
- Create the initial screen structure (one screen per entry in `ui-blueprint.json`).
|
||||
- Create the initial route/navigation structure.
|
||||
- Use semantic, accessible markup/semantics where the platform supports it.
|
||||
- **Do not implement features that are not described in the current project documents.** Only the app shell, theme, routes, screens, and shared components.
|
||||
|
||||
### Step 3: Platform-Specific Requirements
|
||||
|
||||
Apply the requirements for the selected target:
|
||||
|
||||
#### `/generate-app web`
|
||||
- Generate a Web app using the technology defined in `docs/architecture.md`.
|
||||
- If no framework is specified, ask the user or choose a simple default suitable for the repository.
|
||||
- Convert `design-tokens.json` into CSS variables, a Tailwind config, or an equivalent styling system.
|
||||
- Convert `ui-blueprint.json` into pages, layouts, and components.
|
||||
- Use semantic HTML where possible.
|
||||
- Respect responsive layout requirements (use breakpoints from the tokens).
|
||||
|
||||
#### `/generate-app flutter`
|
||||
- Generate a Flutter app.
|
||||
- Convert `design-tokens.json` into:
|
||||
- `ThemeData`
|
||||
- `ColorScheme`
|
||||
- spacing constants
|
||||
- radius constants
|
||||
- text styles
|
||||
- Convert `ui-blueprint.json` into:
|
||||
- routes
|
||||
- screens
|
||||
- reusable widgets
|
||||
- Keep clean separation between: `screens`, `widgets`, `theme`, `models`, `services`.
|
||||
|
||||
#### `/generate-app winui3`
|
||||
- Generate a WinUI 3 application structure.
|
||||
- Convert `design-tokens.json` into:
|
||||
- `ResourceDictionary`
|
||||
- theme resources
|
||||
- styles
|
||||
- Convert `ui-blueprint.json` into:
|
||||
- XAML pages
|
||||
- `UserControl`s
|
||||
- navigation structure
|
||||
- Use C# and XAML.
|
||||
- Keep UI logic separated from business logic where possible.
|
||||
|
||||
### Step 4: Update Repository Structure Document
|
||||
|
||||
If new directories/files were created, update `docs/repository-structure.md` so it reflects the generated layout.
|
||||
|
||||
### Step 5: Verify
|
||||
|
||||
- If the target is `web` and the repo has `npm test`, `npm run lint`, `npm run typecheck`, run them and fix any errors caused by the generated code.
|
||||
- For `flutter` / `winui3`, run the platform's available static checks if the toolchain is present; otherwise note what should be checked manually.
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
- The initial app shell exists for the selected target.
|
||||
- Design tokens are converted into the platform's styling system.
|
||||
- The UI blueprint is converted into screens, routes, and reusable components.
|
||||
- No feature logic beyond what the project documents describe has been implemented.
|
||||
- `docs/repository-structure.md` has been updated if the layout changed.
|
||||
|
||||
Completion message:
|
||||
```
|
||||
"App generation is complete for target: [target]
|
||||
|
||||
Generated:
|
||||
✅ App shell + entry point
|
||||
✅ Theme / styling system (from design-tokens.json)
|
||||
✅ Routes / navigation (from ui-blueprint.json)
|
||||
✅ Screens (one per blueprint screen)
|
||||
✅ Reusable components
|
||||
|
||||
Next steps:
|
||||
- Run the app and verify the shell renders
|
||||
- Use /add-feature to implement features (they will respect the design spec)
|
||||
- Use /update-design when a feature changes the UI
|
||||
"
|
||||
```
|
||||
@ -4,7 +4,7 @@ description: Run a detailed document review using a subagent
|
||||
|
||||
# Document Review
|
||||
|
||||
Argument: document path (e.g. `/review-docs docs/product-requirements.md`)
|
||||
**Document path**: `$ARGUMENTS` (e.g. `/review-docs docs/product-requirements.md`)
|
||||
|
||||
## How to Run
|
||||
|
||||
@ -26,7 +26,7 @@ Launch the doc-reviewer subagent to run the review:
|
||||
Use the Task tool to launch the doc-reviewer subagent:
|
||||
- subagent_type: "doc-reviewer"
|
||||
- description: "Document detailed review"
|
||||
- prompt: "Please review [document path] in detail.\n\nEvaluate it from the following perspectives:\n1. Completeness: Are all required items included?\n2. Specificity: Are there any ambiguous expressions?\n3. Consistency: Is it consistent with other documents?\n4. Measurability: Are success metrics measurable? (for a PRD)\n\nPlease produce a review report."
|
||||
- prompt: "Please review $ARGUMENTS in detail.\n\nEvaluate it from the following perspectives:\n1. Completeness: Are all required items included?\n2. Specificity: Are there any ambiguous expressions?\n3. Consistency: Is it consistent with other documents?\n4. Measurability: Are success metrics measurable? (for a PRD)\n\nPlease produce a review report."
|
||||
|
||||
### Step 3: Summarize the Review Results
|
||||
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
---
|
||||
description: "Initial setup: interactively create the six persistent documents"
|
||||
description: "Initial setup: automatically create the six persistent documents"
|
||||
---
|
||||
|
||||
# Initial Project Setup
|
||||
|
||||
This command interactively creates the project's six persistent documents.
|
||||
This command automatically creates the project's six persistent documents without pausing for human feedback between steps.
|
||||
|
||||
## How to Run
|
||||
|
||||
@ -26,7 +26,7 @@ ls docs/ideas/
|
||||
|
||||
# If no files exist
|
||||
⚠️ No files found in docs/ideas/
|
||||
The PRD will be created interactively
|
||||
The PRD will be created from the project context
|
||||
```
|
||||
|
||||
## Procedure
|
||||
@ -38,21 +38,21 @@ ls docs/ideas/
|
||||
|
||||
### Step 1: Create the Product Requirements Document
|
||||
|
||||
1. Load the **prd-writing skill**
|
||||
1. Load the **prd-writing skill** to guide PRD creation
|
||||
2. Create `docs/product-requirements.md` based on the contents of `docs/ideas/`
|
||||
3. Flesh out the ideas raised during brainstorming:
|
||||
- Detailed user stories
|
||||
- Acceptance criteria
|
||||
- Non-functional requirements
|
||||
- Success metrics
|
||||
4. Ask the user for confirmation and **wait until approved**
|
||||
4. Run the skill's self-check checkpoints; if issues are found, fix them inline, then proceed immediately to the next step
|
||||
|
||||
**The subsequent steps are based on the Product Requirements Document, so they are created automatically**
|
||||
**All subsequent steps run automatically without waiting for human feedback.**
|
||||
|
||||
### Step 2: Create the Functional Design Document
|
||||
|
||||
1. Load the **functional-design skill**
|
||||
1. Read `docs/product-requirements.md`
|
||||
2. Read `docs/product-requirements.md`
|
||||
3. Create `docs/functional-design.md` following the skill's template and guide
|
||||
|
||||
### Step 3: Create the Architecture Design Document
|
||||
|
||||
89
.claude/commands/update-design.md
Normal file
89
.claude/commands/update-design.md
Normal file
@ -0,0 +1,89 @@
|
||||
---
|
||||
description: Refine the design before /generate-app, or update it when a feature changes the UI (blueprint first, then tokens, brief, and SVGs)
|
||||
---
|
||||
|
||||
# Update Design
|
||||
|
||||
This command updates the design specification. It is used in two situations: (1) to refine the UI/UX **before** running `/generate-app` (e.g. adjusting screens, tokens, or layout after reviewing the initial design), and (2) to update the design when a feature changes the UI. It updates the structured design files **only** — it does **not** implement application code unless explicitly requested.
|
||||
|
||||
**Change description**: `$ARGUMENTS` (e.g. `/update-design add a profile screen with avatar and edit form`)
|
||||
|
||||
## How to Run
|
||||
|
||||
```bash
|
||||
claude
|
||||
> /update-design add a profile screen with avatar and edit form
|
||||
```
|
||||
|
||||
## Pre-Run Check
|
||||
|
||||
Confirm the design files exist. If they are missing, stop and tell the user to run `/define-design` first:
|
||||
|
||||
- `docs/design/design-brief.md`
|
||||
- `docs/design/design-tokens.json`
|
||||
- `docs/design/ui-blueprint.json`
|
||||
- `docs/design/platform-mapping.md`
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 0: Read the Inputs
|
||||
|
||||
Read:
|
||||
|
||||
- The existing design files listed above
|
||||
- `docs/product-requirements.md` and `docs/functional-design.md` for context
|
||||
- The change description provided in `$ARGUMENTS`
|
||||
|
||||
### Step 1: Update `ui-blueprint.json` First
|
||||
|
||||
The blueprint is the source of truth, so it is always updated first. Add/modify screens, components, variants, states, routes, and actions to reflect the requested change. Keep the JSON valid and consistent with the existing schema.
|
||||
|
||||
### Step 2: Update `design-tokens.json` (if needed)
|
||||
|
||||
If the change introduces new colors, spacing, typography, radius, shadows, or animations, add the corresponding tokens here. Reuse existing tokens where possible; do not duplicate. Use semantic names. No hard-coded values should be needed downstream.
|
||||
|
||||
### Step 3: Update `design-brief.md` (if the direction changes)
|
||||
|
||||
If the change affects the overall design direction (visual mood, layout principles, navigation principles, accessibility), update the brief. If it is a localized screen/component change, leave the brief unchanged.
|
||||
|
||||
### Step 4: Update `platform-mapping.md` (if needed)
|
||||
|
||||
If the change introduces a new platform target or a new kind of mapping (e.g. a new component family that maps differently per platform), update the mapping. Otherwise leave it unchanged.
|
||||
|
||||
### Step 5: Regenerate Affected SVG Wireframes
|
||||
|
||||
For every screen added or modified in `ui-blueprint.json`, generate or regenerate the corresponding SVG under `docs/design/screens/`. Remember: SVGs are visual references only — the blueprint is the source of truth.
|
||||
|
||||
### Step 6: Consistency Check
|
||||
|
||||
- Every screen in `ui-blueprint.json` has a matching SVG.
|
||||
- Token names referenced in the blueprint exist in `design-tokens.json`.
|
||||
- The brief and mapping remain consistent with the blueprint.
|
||||
|
||||
### Step 7: Do Not Implement Code
|
||||
|
||||
Do **not** modify application code in this command. If the user also wants the code updated, they should run `/add-feature` (which reads the updated design files) or ask explicitly.
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
- `ui-blueprint.json` has been updated (source of truth).
|
||||
- `design-tokens.json` updated only if new tokens were needed.
|
||||
- `design-brief.md` updated only if the direction changed.
|
||||
- `platform-mapping.md` updated only if mappings changed.
|
||||
- Affected SVG wireframes regenerated.
|
||||
- No application code was changed.
|
||||
|
||||
Completion message:
|
||||
```
|
||||
"Design has been updated.
|
||||
|
||||
Updated:
|
||||
✅ docs/design/ui-blueprint.json (source of truth)
|
||||
✅ docs/design/design-tokens.json (if new tokens were needed)
|
||||
✅ docs/design/design-brief.md (if the direction changed)
|
||||
✅ docs/design/platform-mapping.md (if mappings changed)
|
||||
✅ docs/design/screens/*.svg (regenerated as needed)
|
||||
|
||||
Note: application code was not changed. Run /add-feature to implement the change, respecting the updated design.
|
||||
"
|
||||
```
|
||||
@ -6,7 +6,11 @@
|
||||
"Skill(architecture-design)",
|
||||
"Skill(repository-structure)",
|
||||
"Skill(development-guidelines)",
|
||||
"Skill(glossary-creation)"
|
||||
"Skill(glossary-creation)",
|
||||
"Skill(ui-design)",
|
||||
"Skill(design-tokens)",
|
||||
"Skill(platform-ui-generation)",
|
||||
"Skill(steering)"
|
||||
],
|
||||
"deny": [],
|
||||
"ask": []
|
||||
|
||||
138
.claude/skills/design-tokens/SKILL.md
Normal file
138
.claude/skills/design-tokens/SKILL.md
Normal file
@ -0,0 +1,138 @@
|
||||
---
|
||||
name: design-tokens
|
||||
description: Guide for creating and maintaining design-tokens.json, the single source of styling values for Web, Flutter, and WinUI 3. Use when creating or updating design tokens.
|
||||
allowed-tools: Read, Write, Edit
|
||||
---
|
||||
|
||||
# Design Tokens Skill
|
||||
|
||||
This skill explains how to create and maintain `docs/design/design-tokens.json` — the single source of truth for all styling values (color, typography, spacing, radius, shadow, motion, breakpoints). Generated platform code must read from these tokens and must never hard-code values.
|
||||
|
||||
## Core Principle
|
||||
|
||||
> One token definition → many platform outputs. Never hard-code a color, size, or spacing in generated code.
|
||||
|
||||
## Format
|
||||
|
||||
Use a JSON structure inspired by the Design Tokens Community Group format. Every token is an object with `$type` and `$value`:
|
||||
|
||||
```json
|
||||
{
|
||||
"color": {
|
||||
"background": {
|
||||
"primary": { "$type": "color", "$value": "#0F172A" }
|
||||
}
|
||||
},
|
||||
"spacing": {
|
||||
"md": { "$type": "dimension", "$value": "16px" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Supported `$type` values: `color`, `dimension`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `number`, `strokeStyle`.
|
||||
|
||||
## Token Groups
|
||||
|
||||
`design-tokens.json` should include these groups (omit a group only if it truly does not apply):
|
||||
|
||||
- **color** — semantic color tokens
|
||||
- **typography** — font families, sizes, weights, line heights
|
||||
- **spacing** — spacing scale (xs, sm, md, lg, xl, …)
|
||||
- **radius** — border radius scale
|
||||
- **shadow** / **elevation** — box-shadow / elevation tokens
|
||||
- **motion** — animation durations and easings
|
||||
- **breakpoint** — responsive breakpoints (include when `web` is a target)
|
||||
|
||||
## Rules
|
||||
|
||||
### Naming tokens
|
||||
|
||||
- Use **semantic names**, not descriptive names. `color.text.primary` (good) vs `color.slate-900` (bad).
|
||||
- Use a consistent scale for numeric families: `sm`, `md`, `lg`, `xl` — or numeric `4`, `8`, `12` — pick one and stick to it.
|
||||
- Group by role then by emphasis: `color.background.primary`, `color.background.muted`, `color.text.primary`, `color.text.secondary`, `color.accent.primary`, `color.state.success`, `color.state.danger`.
|
||||
- Token names are referenced verbatim in `ui-blueprint.json` (e.g. `"padding": "lg"`). They must match exactly.
|
||||
|
||||
### Using semantic color names
|
||||
|
||||
- Define colors by **role** (background, text, accent, border, state, overlay) and **emphasis** (primary, secondary, muted).
|
||||
- Do not expose raw hex scales as the only option. If you need a raw scale, keep it in a separate `color.palette` group and reference it from semantic tokens.
|
||||
- Provide both light and dark values where the app supports them: `color.background.primary` (light) and `color.background.primary-dark`, or a `dark` sub-object — pick one convention and document it in `platform-mapping.md`.
|
||||
|
||||
### Avoiding hard-coded values in generated code
|
||||
|
||||
- Generated Web code uses CSS variables / Tailwind theme keys / theme objects derived from tokens.
|
||||
- Generated Flutter code uses `ThemeData`, `ColorScheme`, and constants derived from tokens.
|
||||
- Generated WinUI 3 code uses `ResourceDictionary` entries derived from tokens.
|
||||
- **Never** inline `#0F172A` or `16px` in generated source. Always reference the token-derived variable/resource.
|
||||
- If a value is needed that has no token, add the token to `design-tokens.json` first, then use it.
|
||||
|
||||
### Mapping tokens to platform-specific code
|
||||
|
||||
`design-tokens.json` is platform-agnostic. The conversion to each platform is documented in `docs/design/platform-mapping.md` and performed by the **platform-ui-generation** skill. This skill only defines and maintains the tokens.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
{
|
||||
"color": {
|
||||
"background": {
|
||||
"primary": { "$type": "color", "$value": "#0F172A" },
|
||||
"muted": { "$type": "color", "$value": "#1E293B" }
|
||||
},
|
||||
"text": {
|
||||
"primary": { "$type": "color", "$value": "#F8FAFC" },
|
||||
"secondary": { "$type": "color", "$value": "#94A3B8" }
|
||||
},
|
||||
"accent": {
|
||||
"primary": { "$type": "color", "$value": "#38BDF8" }
|
||||
},
|
||||
"state": {
|
||||
"success": { "$type": "color", "$value": "#22C55E" },
|
||||
"danger": { "$type": "color", "$value": "#EF4444" }
|
||||
}
|
||||
},
|
||||
"typography": {
|
||||
"fontFamily": {
|
||||
"base": { "$type": "fontFamily", "$value": "Inter, system-ui, sans-serif" }
|
||||
},
|
||||
"size": {
|
||||
"sm": { "$type": "dimension", "$value": "14px" },
|
||||
"md": { "$type": "dimension", "$value": "16px" },
|
||||
"lg": { "$type": "dimension", "$value": "20px" }
|
||||
}
|
||||
},
|
||||
"spacing": {
|
||||
"sm": { "$type": "dimension", "$value": "8px" },
|
||||
"md": { "$type": "dimension", "$value": "16px" },
|
||||
"lg": { "$type": "dimension", "$value": "24px" }
|
||||
},
|
||||
"radius": {
|
||||
"card": { "$type": "dimension", "$value": "16px" },
|
||||
"pill": { "$type": "dimension", "$value": "9999px" }
|
||||
},
|
||||
"shadow": {
|
||||
"card": { "$type": "shadow", "$value": "0 4px 12px rgba(0,0,0,0.15)" }
|
||||
},
|
||||
"motion": {
|
||||
"duration": {
|
||||
"fast": { "$type": "duration", "$value": "120ms" },
|
||||
"base": { "$type": "duration", "$value": "200ms" }
|
||||
}
|
||||
},
|
||||
"breakpoint": {
|
||||
"sm": { "$type": "dimension", "$value": "640px" },
|
||||
"md": { "$type": "dimension", "$value": "768px" },
|
||||
"lg": { "$type": "dimension", "$value": "1024px" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Maintenance Checklist
|
||||
|
||||
When updating tokens:
|
||||
|
||||
- [ ] JSON is valid.
|
||||
- [ ] Token names referenced in `ui-blueprint.json` still exist (no broken references after a rename).
|
||||
- [ ] New tokens follow the naming and semantic-name rules.
|
||||
- [ ] No duplicate tokens (same role under two names).
|
||||
- [ ] `platform-mapping.md` still covers how every token group maps to each target platform.
|
||||
113
.claude/skills/platform-ui-generation/SKILL.md
Normal file
113
.claude/skills/platform-ui-generation/SKILL.md
Normal file
@ -0,0 +1,113 @@
|
||||
---
|
||||
name: platform-ui-generation
|
||||
description: 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.
|
||||
allowed-tools: 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` → `UserControl`s, 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.
|
||||
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.
|
||||
30
CLAUDE.md
30
CLAUDE.md
@ -15,7 +15,7 @@
|
||||
2. **Work planning**: Plan "what to do this time" in steering files (`.steering/`)
|
||||
3. **Implementation**: Implement according to tasklist.md and update progress as you go
|
||||
4. **Verification**: Testing and operation checks
|
||||
5. **Update**: Update documents as needed
|
||||
5. **Update**: Reconcile all `docs/` documents with the implemented feature (see `/add-feature` Step 8)
|
||||
|
||||
### Important Rules
|
||||
|
||||
@ -78,6 +78,14 @@ Define "what to build" and "how to build it" for the entire application:
|
||||
- **development-guidelines.md** - Development guidelines
|
||||
- **glossary.md** - Ubiquitous language definitions
|
||||
|
||||
#### Design Documents (`docs/design/`)
|
||||
- **design-brief.md** - UI/UX direction
|
||||
- **design-tokens.json** - Styling tokens (source of values)
|
||||
- **ui-blueprint.json** - UI structure (source of truth for UI generation)
|
||||
- **platform-mapping.md** - How the design maps to Web / Flutter / WinUI 3
|
||||
- **screens/\*.svg** - Visual wireframes (references only)
|
||||
- Created by `/define-design`, updated by `/update-design`, consumed by `/generate-app` and `/add-feature`
|
||||
|
||||
### Work-Unit Documents (`.steering/`)
|
||||
|
||||
Define "what to do this time" for a specific development task:
|
||||
@ -86,13 +94,22 @@ Define "what to do this time" for a specific development task:
|
||||
- `design.md`: The design of the changes
|
||||
- `tasklist.md`: The task list
|
||||
|
||||
### Claude Code Configuration (`.claude/`)
|
||||
|
||||
- `.claude/agents/` - Subagent definitions (doc-reviewer, implementation-validator)
|
||||
- `.claude/commands/` - Slash commands (setup-project, define-design, generate-app, update-design, add-feature, review-docs)
|
||||
- `.claude/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, ui-design, design-tokens, platform-ui-generation, steering)
|
||||
|
||||
## Development Process
|
||||
|
||||
### Initial Setup
|
||||
|
||||
1. Use this template
|
||||
2. Create persistent documents with `/setup-project` (interactively creating six)
|
||||
3. Implement features with `/add-feature [feature]`
|
||||
2. Create persistent documents with `/setup-project` (automatically creating six)
|
||||
3. Define the UI/UX design with `/define-design` (creates `docs/design/`)
|
||||
4. Review and refine the UI/UX with `/update-design` (or re-run `/define-design`) until approved — before generating code
|
||||
5. Generate the initial app with `/generate-app web | flutter | winui3`
|
||||
6. Implement features with `/add-feature [feature]`
|
||||
|
||||
### Day-to-Day Usage
|
||||
|
||||
@ -107,6 +124,11 @@ Define "what to do this time" for a specific development task:
|
||||
# Adding features (use commands for the standard flow)
|
||||
> /add-feature edit user profile
|
||||
|
||||
# Design phase
|
||||
> /define-design
|
||||
> /generate-app web
|
||||
> /update-design add a profile screen
|
||||
|
||||
# Detailed review (when a detailed report is needed)
|
||||
> /review-docs docs/product-requirements.md
|
||||
```
|
||||
@ -118,8 +140,8 @@ Define "what to do this time" for a specific development task:
|
||||
### Persistent Documents (`docs/`)
|
||||
|
||||
- Describe the fundamental design
|
||||
- Not updated frequently
|
||||
- The "north star" for the entire project
|
||||
- **Kept in sync with every feature**: at the end of `/add-feature` (Step 8), all six documents are reconciled with the implemented feature (product-requirements, functional-design, architecture, repository-structure, development-guidelines, glossary)
|
||||
|
||||
### Work-Unit Documents (`.steering/`)
|
||||
|
||||
|
||||
62
docs/design/README.md
Normal file
62
docs/design/README.md
Normal file
@ -0,0 +1,62 @@
|
||||
# Design Specification (`docs/design/`)
|
||||
|
||||
This directory holds the project's **UI/UX design specification**. It is created and maintained by the `/define-design` and `/update-design` commands and consumed by `/generate-app` and `/add-feature`.
|
||||
|
||||
## Source of truth
|
||||
|
||||
```
|
||||
docs/design/ui-blueprint.json ← THE source of truth for UI generation
|
||||
```
|
||||
|
||||
SVG files are **visual references only**. If an SVG and the blueprint disagree, the blueprint wins and the SVG must be regenerated.
|
||||
|
||||
Generated UI must follow `design-tokens.json` — no hard-coded values.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
docs/design/
|
||||
├── design-brief.md # UI/UX direction (human-readable, concrete)
|
||||
├── design-tokens.json # Styling values (color, type, spacing, radius, …)
|
||||
├── ui-blueprint.json # Source of truth: screens, components, routes, actions
|
||||
├── platform-mapping.md # How the design maps to Web / Flutter / WinUI 3
|
||||
└── screens/ # SVG wireframes (one per blueprint screen)
|
||||
├── home.svg
|
||||
├── settings.svg
|
||||
└── [screen-id].svg
|
||||
```
|
||||
|
||||
## File purposes
|
||||
|
||||
### `design-brief.md`
|
||||
Overall UI/UX direction: target users, design concept, visual mood, layout/navigation principles, accessibility, platform-specific notes, preferred styles, and styles to avoid.
|
||||
|
||||
### `design-tokens.json`
|
||||
Design tokens in a Design Tokens Community Group–inspired JSON format (`$type` / `$value`). Covers color, typography, spacing, radius, shadow, motion, and breakpoints. Platform code reads from these tokens and never hard-codes values.
|
||||
|
||||
### `ui-blueprint.json`
|
||||
The source of truth for UI generation. Describes the app name, target platforms, routes, screens (each with a layout and component tree), reusable components (variants and states), and user actions/navigation.
|
||||
|
||||
### `platform-mapping.md`
|
||||
Documents how `design-tokens.json` and `ui-blueprint.json` are converted to each target platform:
|
||||
|
||||
- **Web**: tokens → CSS variables / Tailwind theme; blueprint → pages, routes, components.
|
||||
- **Flutter**: tokens → `ThemeData` / `ColorScheme` / constants; blueprint → widgets, routes.
|
||||
- **WinUI 3**: tokens → `ResourceDictionary`; blueprint → XAML pages, `UserControl`s, navigation.
|
||||
|
||||
### `screens/*.svg`
|
||||
Low-fidelity wireframes, one per screen in `ui-blueprint.json`, named `<screen-id>.svg`. Generated for human review only — never the source of truth.
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
/setup-project → product/architecture docs
|
||||
/define-design → creates the files above
|
||||
/generate-app web | flutter | winui3 → scaffolds the app from these files
|
||||
/update-design → updates these files when a feature changes the UI
|
||||
/add-feature → reads these files before implementing; updates them first if the UI changes
|
||||
```
|
||||
|
||||
## Status
|
||||
|
||||
This directory is populated by running `/define-design`. Until then, the files above do not exist and `/generate-app` will ask you to run `/define-design` first.
|
||||
Reference in New Issue
Block a user