Claude-Code-Workflow/.claude/commands/workflow/ui-design/update.md

---
name: update
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(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
---

# Design Update Command

## Overview
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
- **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
- **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 & Artifact Validation

```bash
# Validate session
CHECK: .workflow/.active-* marker files
VALIDATE: session_id matches active session

# Verify required design artifacts exist in latest design run
latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")

# Detect design system structure (unified vs separate)
IF exists({latest_design}/style-consolidation/design-tokens.json):
    # Unified mode (single design system)
    design_system_mode = "unified"
    design_tokens_path = "style-consolidation/design-tokens.json"
    style_guide_path = "style-consolidation/style-guide.md"
ELSE IF exists({latest_design}/style-consolidation/style-1/design-tokens.json):
    # Separate mode (per-style design systems)
    design_system_mode = "separate"
    design_tokens_path = "style-consolidation/style-1/design-tokens.json"
    style_guide_path = "style-consolidation/style-1/style-guide.md"
ELSE:
    ERROR: "No design tokens found. Run /workflow:ui-design:consolidate first"

VERIFY:
- {latest_design}/{design_tokens_path}
- {latest_design}/{style_guide_path}
- {latest_design}/prototypes/*.html (at least one prototype)

REPORT: "📋 Design system mode: {design_system_mode}"
REPORT: "   Tokens: {design_tokens_path}"

# 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({latest_design}/prototypes/*.html)

REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
```

### 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 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

Update `.brainstorming/synthesis-specification.md` with design system references.

**Target Section**: `## UI/UX Guidelines`

**Content Template**:
```markdown
## UI/UX Guidelines

### Design System Reference
**Finalized Design Tokens**: @../design-{run_id}/{design_tokens_path}
**Style Guide**: @../design-{run_id}/{style_guide_path}
**Design System Mode**: {design_system_mode}

### Implementation Requirements
**Token Adherence**: All UI implementations MUST use design token CSS custom properties
**Accessibility**: WCAG AA compliance validated in design-tokens.json
**Responsive**: Mobile-first design using token-based breakpoints
**Component Patterns**: Follow patterns documented in style-guide.md

### Reference Prototypes
{FOR each selected_prototype:
- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html
  - Layout: {layout_strategy from notes}
}

### Design System Assets
```json
{
  "design_tokens": "design-{run_id}/{design_tokens_path}",
  "style_guide": "design-{run_id}/{style_guide_path}",
  "design_system_mode": "{design_system_mode}",
  "prototypes": [
    {FOR each: "design-{run_id}/prototypes/{prototype}.html"}
  ]
}
```
```

**Implementation**:
```bash
# Option 1: Edit existing section
Edit(
  file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
  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 Style Guide

Create or update `.brainstorming/ui-designer/style-guide.md`:

```markdown
# UI Designer Style Guide

## Design System Integration
This style guide references the finalized design system from the design refinement phase.

**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
**Style Guide**: @../../design-{run_id}/{style_guide_path}
**Design System Mode**: {design_system_mode}

## Implementation Guidelines
1. **Use CSS Custom Properties**: All styles reference design tokens
2. **Follow Semantic HTML**: Use HTML5 semantic elements
3. **Maintain Accessibility**: WCAG AA compliance required
4. **Responsive Design**: Mobile-first with token-based breakpoints

## Reference Prototypes
{FOR each selected_prototype:
- **{page_name}**: @../../design-{run_id}/prototypes/{prototype}.html
}

## Token System
For complete token definitions and usage examples, see:
- Design Tokens: @../../design-{run_id}/{design_tokens_path}
- Style Guide: @../../design-{run_id}/{style_guide_path}

---
*Auto-generated by /workflow:ui-design:update*
*Last updated: {timestamp}*
```

**Implementation**:
```bash
Write(
  file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
  content="[generated content with @ references]"
)
```

### Phase 5: Completion

```javascript
TodoWrite({
  todos: [
    {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
- {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 design reference guide
```

**@ Reference Format** (used in synthesis-specification.md):
```
@../design-{run_id}/style-consolidation/design-tokens.json
@../design-{run_id}/style-consolidation/style-guide.md
@../design-{run_id}/prototypes/{prototype}.html
```

**@ Reference Format** (used in ui-designer/style-guide.md):
```
@../../design-{run_id}/style-consolidation/design-tokens.json
@../../design-{run_id}/style-consolidation/style-guide.md
@../../design-{run_id}/prototypes/{prototype}.html
```

## Integration with /workflow:plan

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
{
  "task_id": "IMPL-001",
  "context": {
    "design_system": {
      "tokens": "design-{run_id}/style-consolidation/design-tokens.json",
      "style_guide": "design-{run_id}/style-consolidation/style-guide.md",
      "prototypes": ["design-{run_id}/prototypes/dashboard-variant-1.html"]
    }
  }
}
```

## Error Handling

- **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 (not content duplication)
- [ ] ui-designer/style-guide.md created or updated
- [ ] 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 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

## Why Main Claude Execution?

This command is executed directly by main Claude (not delegated to an Agent) because:

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 ensures reliable, lightweight integration without Agent handoff overhead.