Refactor documentation for UI Design Workflow (v4.2.1): Optimize explore-auto and imitate-auto commands, enhance clarity and maintainability, and reduce file sizes while preserving functionality. Remove CHANGELOG-v4.2.0.md as it is no longer needed. Update README and README_CN to reflect new version and features.

This commit is contained in:
catlog22
2025-10-09 15:51:23 +08:00
parent 561a04c193
commit c7e2d6f82f
12 changed files with 1611 additions and 2103 deletions

View File

@@ -1,71 +1,77 @@
---
name: update
description: Update brainstorming artifacts with finalized design system
description: Update brainstorming artifacts with finalized design system references
usage: /workflow:ui-design:update --session <session_id> [--selected-prototypes "<list>"]
argument-hint: "--session WFS-session-id [--selected-prototypes \"dashboard-variant-1,auth-variant-2\"]"
examples:
- /workflow:ui-design:update --session WFS-auth
- /workflow:ui-design:update --session WFS-dashboard --selected-prototypes "dashboard-variant-1"
allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*), Bash(*)
allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
---
# Design Update Command
## Overview
Synchronize finalized design system (tokens, style guide, selected prototypes) back to brainstorming artifacts, preparing for `/workflow:plan` phase consumption.
Synchronize finalized design system references to brainstorming artifacts, preparing them for `/workflow:plan` consumption. This command updates **references only** (via @ notation), not content duplication.
## Core Philosophy
- **Main Claude Execution**: Direct updates by main Claude (avoid Agent context loss, following synthesis pattern)
- **Reference-Based Integration**: Use @ references, not content duplication
- **Reference-Only Updates**: Use @ references, no content duplication
- **Main Claude Execution**: Direct updates by main Claude (no Agent handoff)
- **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section
- **UI Designer Sync**: Mirror design system to ui-designer/style-guide.md
- **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
- **Minimal Reading**: Verify file existence, don't read design content
## Execution Protocol
### Phase 1: Session & Design System Validation
### Phase 1: Session & Artifact Validation
```bash
# Validate session and verify design system completeness
# Validate session
CHECK: .workflow/.active-* marker files
VALIDATE: session_id matches active session
VERIFY required artifacts:
# Verify required design artifacts exist (file existence check only)
VERIFY:
- .design/style-consolidation/design-tokens.json
- .design/style-consolidation/style-guide.md
- .design/style-consolidation/tailwind.config.js
- .design/prototypes/*.html (at least one prototype)
# Prototype selection
IF --selected-prototypes provided:
VALIDATE: Specified prototypes exist
selected_list = parse_comma_separated(--selected-prototypes)
ELSE:
AUTO-SELECT: Use all generated prototypes
selected_list = Glob(.design/prototypes/*.html)
REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
```
### Phase 2: Load Design System Context
**Direct Claude Code Execution** (no Agent invocation)
### Phase 2: Load Target Artifacts Only
**What to Load**: Only the files we need to **update**, not the design files we're referencing.
```bash
# Load all design system artifacts
Read(.workflow/WFS-{session}/.design/style-consolidation/design-tokens.json)
Read(.workflow/WFS-{session}/.design/style-consolidation/style-guide.md)
Read(.workflow/WFS-{session}/.design/style-consolidation/tailwind.config.js)
Read(.workflow/WFS-{session}/.design/style-consolidation/validation-report.json)
# Load selected prototype files
FOR each selected_prototype IN selected_prototypes:
Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}.html)
Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}-notes.md)
# Load target brainstorming artifacts
# Load target brainstorming artifacts (files to be updated)
Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
Read(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md) [if exists]
# Optional: Read prototype notes for descriptions (minimal context)
FOR each selected_prototype IN selected_list:
Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}-notes.md)
# Extract: layout_strategy, page_name only
```
**Note**: We do **NOT** read design-tokens.json, style-guide.md, or prototype HTML. We only verify they exist and generate @ references to them.
### Phase 3: Update Synthesis Specification
**Direct Write by Main Claude**
Update `.brainstorming/synthesis-specification.md`:
Update `.brainstorming/synthesis-specification.md` with design system references.
**Target Section**: `## UI/UX Guidelines`
**Content Template**:
```markdown
## UI/UX Guidelines
@@ -74,24 +80,6 @@ Update `.brainstorming/synthesis-specification.md`:
**Style Guide**: @../.design/style-consolidation/style-guide.md
**Tailwind Configuration**: @../.design/style-consolidation/tailwind.config.js
### Design Philosophy
[Extract philosophy section from style-guide.md]
### Token System Overview
**Colors**: OKLCH-based color system with semantic naming
- Brand: primary, secondary, accent
- Surface: background, elevated, sunken
- Semantic: success, warning, error, info
**Typography**: {font_family_count} font families, {scale_count}-step scale
- Heading: {heading_font}
- Body: {body_font}
- Monospace: {mono_font}
**Spacing**: {scale_count}-step scale ({min}rem to {max}rem)
**Components**: Border radius, shadows, and component tokens defined
### Implementation Requirements
**Token Adherence**: All UI implementations MUST use design token CSS custom properties
**Accessibility**: WCAG AA compliance validated in design-tokens.json
@@ -99,21 +87,19 @@ Update `.brainstorming/synthesis-specification.md`:
**Component Patterns**: Follow patterns documented in style-guide.md
### Reference Prototypes
[For each selected prototype:]
{FOR each selected_prototype:
- **{page_name}**: @../.design/prototypes/{prototype}.html
- Layout: {layout_description from notes}
- Components: {component_list from notes}
- Token Usage: {token_usage_summary from notes}
- Layout: {layout_strategy from notes}
}
### Design System Assets (for task-generate consumption)
### Design System Assets
```json
{
"design_tokens": ".design/style-consolidation/design-tokens.json",
"style_guide": ".design/style-consolidation/style-guide.md",
"tailwind_config": ".design/style-consolidation/tailwind.config.js",
"prototypes": [
".design/prototypes/{prototype-1}.html",
".design/prototypes/{prototype-2}.html"
{FOR each: ".design/prototypes/{prototype}.html"}
]
}
```
@@ -121,46 +107,35 @@ Update `.brainstorming/synthesis-specification.md`:
**Implementation**:
```bash
# Edit synthesis-specification.md
# Option 1: Edit existing section
Edit(
file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
old_string="## UI/UX Guidelines\n[existing content or empty]",
new_string="## UI/UX Guidelines\n\n[new design system content with @ references]"
old_string="## UI/UX Guidelines\n[existing content]",
new_string="## UI/UX Guidelines\n\n[new design reference content]"
)
# Option 2: Append if section doesn't exist
IF section not found:
Edit(
file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
old_string="[end of document]",
new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]"
)
```
### Phase 4: Update UI Designer Analysis
**Create or update** `.brainstorming/ui-designer/style-guide.md`:
### Phase 4: Update UI Designer Style Guide
Create or update `.brainstorming/ui-designer/style-guide.md`:
```markdown
# UI Designer Style Guide
## Design System Integration
This style guide integrates the finalized design system from the design refinement phase.
This style guide references the finalized design system from the design refinement phase.
**Source Design Tokens**: @../../.design/style-consolidation/design-tokens.json
**Source Style Guide**: @../../.design/style-consolidation/style-guide.md
## Design Philosophy
[Extract philosophy section from source style-guide.md]
## Design Tokens Reference
For complete token definitions, see: @../../.design/style-consolidation/design-tokens.json
### Color System
[Summary of color tokens]
### Typography System
[Summary of typography tokens]
### Spacing System
[Summary of spacing tokens]
### Component Tokens
[Summary of component tokens: border-radius, shadows]
## Component Patterns
[Reference to style-guide.md component patterns]
**Design Tokens**: @../../.design/style-consolidation/design-tokens.json
**Style Guide**: @../../.design/style-consolidation/style-guide.md
**Tailwind Config**: @../../.design/style-consolidation/tailwind.config.js
## Implementation Guidelines
1. **Use CSS Custom Properties**: All styles reference design tokens
@@ -169,10 +144,17 @@ For complete token definitions, see: @../../.design/style-consolidation/design-t
4. **Responsive Design**: Mobile-first with token-based breakpoints
## Reference Prototypes
[Links to selected prototypes with descriptions]
{FOR each selected_prototype:
- **{page_name}**: @../../.design/prototypes/{prototype}.html
}
## Token System
For complete token definitions and usage examples, see:
- Design Tokens: @../../.design/style-consolidation/design-tokens.json
- Style Guide: @../../.design/style-consolidation/style-guide.md
---
*Auto-generated by /workflow:design:design-update*
*Auto-generated by /workflow:ui-design:update*
*Last updated: {timestamp}*
```
@@ -180,169 +162,155 @@ For complete token definitions, see: @../../.design/style-consolidation/design-t
```bash
Write(
file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
content="[generated style guide content with @ references]"
content="[generated content with @ references]"
)
```
### Phase 5: Create Design System Symlinks (Optional)
**For easier task-generate discovery**
### Phase 5: Completion
```bash
# Create read-only mirror of key design files in brainstorming space
bash(cd .workflow/WFS-{session}/.brainstorming && \
ln -s ../.design/style-consolidation/design-tokens.json design-tokens.json && \
ln -s ../.design/style-consolidation/style-guide.md design-style-guide.md)
```
### Phase 6: TodoWrite Integration
```javascript
TodoWrite({
todos: [
{
content: "Validate session and design system completeness",
status: "completed",
activeForm: "Validating design system"
},
{
content: "Load design tokens, style guide, and selected prototypes",
status: "completed",
activeForm: "Loading design artifacts"
},
{
content: "Update synthesis-specification.md with design system references",
status: "completed",
activeForm: "Updating synthesis specification"
},
{
content: "Create or update ui-designer/style-guide.md",
status: "completed",
activeForm: "Updating UI designer style guide"
},
{
content: "Create design system symlinks for task-generate discovery",
status: "completed",
activeForm: "Creating artifact symlinks"
}
{content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
{content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
{content: "Update synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"},
{content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"}
]
});
```
**Completion Message**:
```
✅ Design system references updated for session: WFS-{session}
Updated artifacts:
✓ synthesis-specification.md - UI/UX Guidelines section with @ references
✓ ui-designer/style-guide.md - Design system reference guide
Design system assets ready for /workflow:plan:
- design-tokens.json
- style-guide.md
- tailwind.config.js
- {prototype_count} reference prototypes
Next: /workflow:plan [--agent] "<task description>"
The plan phase will automatically discover and utilize the design system.
```
## Output Structure
**Updated Files**:
```
.workflow/WFS-{session}/.brainstorming/
├── synthesis-specification.md # Updated with UI/UX Guidelines section
── ui-designer/
└── style-guide.md # New or updated comprehensive style guide
├── design-tokens.json # Symlink to ../.design/style-consolidation/design-tokens.json
└── design-style-guide.md # Symlink to ../.design/style-consolidation/style-guide.md
── ui-designer/
└── style-guide.md # New or updated design reference guide
```
**Reference Structure** (@ references in synthesis-specification.md):
- `@../.design/style-consolidation/design-tokens.json`
- `@../.design/style-consolidation/style-guide.md`
- `@../.design/style-consolidation/tailwind.config.js`
- `@../.design/prototypes/{prototype}.html`
**@ Reference Format** (used in synthesis-specification.md):
```
@../.design/style-consolidation/design-tokens.json
@../.design/style-consolidation/style-guide.md
@../.design/style-consolidation/tailwind.config.js
@../.design/prototypes/{prototype}.html
```
## Integration with task-generate
**@ Reference Format** (used in ui-designer/style-guide.md):
```
@../../.design/style-consolidation/design-tokens.json
@../../.design/style-consolidation/style-guide.md
@../../.design/style-consolidation/tailwind.config.js
@../../.design/prototypes/{prototype}.html
```
After this update, `/workflow:tools:task-generate` will discover:
## Integration with /workflow:plan
**In context.artifacts**:
After this update, `/workflow:plan` will discover design assets through:
**Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`)
- Reads synthesis-specification.md
- Discovers @ references to design system files
- Includes design system context in ANALYSIS_RESULTS.md
**Phase 4: Task Generation** (`/workflow:tools:task-generate`)
- Reads ANALYSIS_RESULTS.md
- Discovers design assets from synthesis-specification.md
- Includes design system paths in task JSON files
**Example Task JSON** (generated by task-generate):
```json
{
"artifacts": [
{
"type": "synthesis_specification",
"path": ".brainstorming/synthesis-specification.md"
},
{
"type": "design_tokens",
"path": ".design/style-consolidation/design-tokens.json"
},
{
"type": "style_guide",
"path": ".design/style-consolidation/style-guide.md"
},
{
"type": "tailwind_config",
"path": ".design/style-consolidation/tailwind.config.js"
},
{
"type": "ui_prototypes",
"paths": [
".design/prototypes/dashboard-variant-1.html",
".design/prototypes/auth-variant-2.html"
]
"task_id": "IMPL-001",
"context": {
"design_system": {
"tokens": ".design/style-consolidation/design-tokens.json",
"style_guide": ".design/style-consolidation/style-guide.md",
"prototypes": [".design/prototypes/dashboard-variant-1.html"]
}
]
}
```
**In flow_control.pre_analysis** (for UI tasks):
```json
{
"step": "load_design_tokens",
"action": "Load design system tokens and style guide",
"commands": [
"bash(cat .workflow/WFS-{session}/.design/style-consolidation/design-tokens.json)",
"bash(cat .workflow/WFS-{session}/.design/style-consolidation/style-guide.md)"
],
"output_to": "design_system_context",
"on_error": "warn"
}
}
```
## Error Handling
- **Missing design tokens**: Error, run `/workflow:ui-design:consolidate` first
- **Missing prototypes**: Error, run `/workflow:ui-design:generate` first
- **synthesis-specification.md not found**: Warning, create minimal version
- **Edit conflicts**: Preserve existing content, append design system section
- **Symlink failures**: Warning only, continue with @ references
- **Missing design artifacts**: Error with message "Run /workflow:ui-design:consolidate and /workflow:ui-design:generate first"
- **synthesis-specification.md not found**: Warning, create minimal version with just UI/UX Guidelines
- **ui-designer/ directory missing**: Create directory and file
- **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section
- **Invalid prototype names**: Skip invalid entries, continue with valid ones
## Validation Checks
After update, verify:
- [ ] synthesis-specification.md contains UI/UX Guidelines section
- [ ] UI/UX Guidelines include @ references to design system files
- [ ] UI/UX Guidelines include @ references (not content duplication)
- [ ] ui-designer/style-guide.md created or updated
- [ ] design-tokens.json symlink created (if applicable)
- [ ] All referenced files exist and are readable
- [ ] All @ referenced files exist and are accessible
- [ ] @ reference paths are relative and correct
## Key Features
1. **Reference-Only Updates**
- Uses @ notation for file references
- No content duplication between design and brainstorming spaces
- Lightweight, maintainable approach
2. **Main Claude Direct Execution**
- No Agent handoff (preserves context)
- Simple reference generation (no complex synthesis)
- Reliable path resolution
3. **Plan-Ready Output**
- `/workflow:plan` Phase 3 can discover design system
- Task generation includes design asset paths
- Clear integration points for implementation tasks
4. **Minimal Reading**
- Only reads target files to update (synthesis-specification.md, ui-designer/analysis.md)
- Verifies design file existence (no content reading)
- Optional: reads prototype notes for descriptions
5. **Flexible Prototype Selection**
- Auto-select all prototypes (default)
- Manual selection via --selected-prototypes parameter
- Validates prototype existence before referencing
## Integration Points
- **Input**: design-tokens.json, style-guide.md, prototypes from design phase
- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md
- **Next Phase**: `/workflow:plan` can now discover and utilize design system
## Completion Message
- **Input**: Design system artifacts from `/workflow:ui-design:consolidate` and `/workflow:ui-design:generate`
- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md with @ references
- **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
```
Design system update complete for session: WFS-{session}
Updated artifacts:
✓ synthesis-specification.md - UI/UX Guidelines section added
✓ ui-designer/style-guide.md - Comprehensive style guide created
✓ Design system references: @ notation for all design files
Design system assets ready for task generation:
- design-tokens.json ({token_count} tokens)
- style-guide.md (comprehensive component patterns)
- tailwind.config.js (Tailwind theme extension)
- {prototype_count} reference prototypes
Next: /workflow:plan [--agent] "<task description>"
The plan phase will automatically discover and utilize the design system.
```
## Main Claude Direct Execution Rationale
## Why Main Claude Execution?
This command is executed directly by main Claude (not delegated to an Agent) because:
1. **Context Preservation**: Main Claude has full session context and conversation memory
2. **Integration Complexity**: Requires understanding multiple artifact relationships
3. **Reference Accuracy**: @ reference generation needs precise path resolution
4. **Synthesis Pattern**: Follows the same direct-execution pattern as `/workflow:brainstorm:synthesis`
5. **Minimal Transformation**: Primarily reference integration, not generative analysis
6. **Error Recovery**: Main Claude can better handle edit conflicts and missing files
1. **Simple Reference Generation**: Only generating file paths, not complex synthesis
2. **Context Preservation**: Main Claude has full session and conversation context
3. **Minimal Transformation**: Primarily updating references, not analyzing content
4. **Path Resolution**: Requires precise relative path calculation
5. **Edit Operations**: Better error recovery for Edit conflicts
6. **Synthesis Pattern**: Follows same direct-execution pattern as other reference updates
This approach ensures reliable, context-aware integration without Agent handoff overhead.
This ensures reliable, lightweight integration without Agent handoff overhead.