Refactor UI design workflow scripts and documentation

- Removed the generation of a unified consolidation report in the consolidate.md file, streamlining the output structure. - Updated the extract.md file to prioritize the --base-path argument for session management and improved error handling for style variant detection. - Enhanced generate.md to enforce critical requirements for layout templates, ensuring independence from other targets. - Added a comprehensive analysis report for the ui-instantiate-prototypes.sh script, detailing issues with style variant mismatches and proposing solutions for validation and prevention.
2026-02-11 02:33:51 +08:00 · 2025-10-09 22:10:22 +08:00
parent a7153dfc6d
commit f0bed9e072
5 changed files with 731 additions and 625 deletions
--- a/.claude/agents/ui-design-agent.md
+++ b/.claude/agents/ui-design-agent.md
--- a/.claude/commands/workflow/ui-design/consolidate.md
+++ b/.claude/commands/workflow/ui-design/consolidate.md
@@ -318,29 +318,6 @@ FOR variant_id IN range(1, variants_count + 1):
    Write({base_path}/style-consolidation/style-{variant_id}/style-guide.md, style_guide_section)

    REPORT: "  ✅ style-{variant_id}/ written"
-
-# Generate unified consolidation report for all variants
-consolidation_report = {
-  "session_id": session_id,
-  "consolidation_mode": "separate",
-  "timestamp": ISO_timestamp,
-  "style_systems": {
-    "variant_count": variants_count,
-    "variants": []
-  },
-  "layout_strategies": Read({base_path}/style-consolidation/layout-strategies.json)
-}
-
-# Aggregate validation data from all style variants
-FOR variant_id IN range(1, variants_count + 1):
-    design_tokens = Read({base_path}/style-consolidation/style-{variant_id}/design-tokens.json)
-    validation_data = validate_design_tokens(design_tokens)
-    consolidation_report.style_systems.variants.append({
-      "id": "style-{variant_id}",
-      "validation": validation_data
-    })
-
-Write({base_path}/style-consolidation/consolidation-report.json, JSON.stringify(consolidation_report, null, 2))
 ```

 **Output Structure**:
@@ -353,8 +330,7 @@ Write({base_path}/style-consolidation/consolidation-report.json, JSON.stringify(
 │   └── ... (same structure)
 ├── style-N/
 │   └── ... (same structure)
-├── layout-strategies.json       # Layout variant definitions
-└── consolidation-report.json    # Unified validation for all styles + layout plan
+└── layout-strategies.json       # Layout variant definitions
 ```

 ### Phase 6: Completion & Reporting
@@ -367,8 +343,7 @@ TodoWrite({
    {content: "Plan layout strategies", status: "completed", activeForm: "Planning layout strategies"},
    {content: "Load design context from brainstorming", status: "completed", activeForm: "Loading context"},
    {content: "Generate design systems via agent", status: "completed", activeForm: "Generating design systems"},
-    {content: "Process agent results and write files", status: "completed", activeForm: "Writing output files"},
-    {content: "Generate consolidation report", status: "completed", activeForm: "Generating report"}
+    {content: "Process agent results and write files", status: "completed", activeForm: "Writing output files"}
  ]
 });
 ```
@@ -387,8 +362,7 @@ Layout Strategies Planned: {layout_variants}
 ├── style-1/ (design-tokens.json, style-guide.md)
 ├── style-2/ (same structure)
 ├── style-{variants_count}/ (same structure)
-├── layout-strategies.json
-└── consolidation-report.json
+└── layout-strategies.json

 Next: /workflow:ui-design:generate --session {session_id} --style-variants {variants_count} --layout-variants {layout_variants} --pages "dashboard,auth"

@@ -538,7 +512,6 @@ Complete token structure with OKLCH colors and semantic naming:
   - design-tokens.json (CSS tokens per variant)
   - style-guide.md (documentation per variant)
   - layout-strategies.json (dynamic layout plans)
-   - consolidation-report.json (unified validation & planning)

 6. **Production-Ready Quality**
   - WCAG AA accessibility validation
@@ -561,7 +534,6 @@ Complete token structure with OKLCH colors and semantic naming:
 - **Output**:
  - Style Systems: `style-consolidation/style-{n}/design-tokens.json` for matrix mode generation
  - Layout Planning: `layout-strategies.json` consumed by `/workflow:ui-design:generate`
-  - Unified Reporting: `consolidation-report.json` for audit and validation
 - **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md`
 - **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
 - **Next Command**: `/workflow:ui-design:generate --style-variants N --layout-variants M` reads design tokens and layout strategies
--- a/.claude/commands/workflow/ui-design/extract.md
+++ b/.claude/commands/workflow/ui-design/extract.md
@@ -1,12 +1,13 @@
 ---
 name: extract
 description: Extract design style from reference images or text prompts using Claude's analysis
-usage: /workflow:ui-design:extract [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>]
-argument-hint: "[--session WFS-xxx] [--images \"refs/*.png\"] [--prompt \"Modern minimalist\"] [--variants 3]"
+usage: /workflow:ui-design:extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>]
+argument-hint: "[--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--session WFS-xxx] [--images \"refs/*.png\"] [--prompt \"Modern minimalist\"] [--variants 3]"
 examples:
  - /workflow:ui-design:extract --images "design-refs/*.png" --variants 3
  - /workflow:ui-design:extract --prompt "Modern minimalist blog, dark theme" --variants 3
  - /workflow:ui-design:extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --variants 2
+  - /workflow:ui-design:extract --base-path ".workflow/WFS-auth/design-run-20250109-143022" --images "refs/*.png" --variants 3
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
 ---

@@ -37,16 +38,26 @@ ELSE IF --prompt:
 ELSE:
    ERROR: "Must provide --images or --prompt"

-# Detect session mode and generate run ID
-run_id = "run-" + timestamp()
-
-IF --session:
-    session_mode = "integrated"
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/design-{run_id}/"
+# Determine base path (PRIORITY: --base-path > --session > standalone)
+IF --base-path provided:
+    base_path = {provided_base_path}
+    session_mode = "integrated"  # Assume integrated if path is passed
+    # Extract session_id if possible from path pattern
+    IF base_path matches ".workflow/WFS-*/design-*":
+        session_id = extract_from_path(base_path, pattern="WFS-([^/]+)")
+    ELSE:
+        session_id = "standalone"
 ELSE:
-    session_mode = "standalone"
-    base_path = ".workflow/.design/{run_id}/"
+    # Generate a new run_id and base_path only if not provided
+    run_id = "run-" + timestamp()
+
+    IF --session:
+        session_mode = "integrated"
+        session_id = {provided_session}
+        base_path = ".workflow/WFS-{session_id}/design-{run_id}/"
+    ELSE:
+        session_mode = "standalone"
+        base_path = ".workflow/.design/{run_id}/"

 # Set variant count
 variants_count = --variants provided ? {count} : 1
--- a/.claude/commands/workflow/ui-design/generate.md
+++ b/.claude/commands/workflow/ui-design/generate.md
@@ -282,12 +282,20 @@ FOR layout_id IN range(1, layout_variants + 1):
        Task(ui-design-agent): "
          [UI_LAYOUT_TEMPLATE_GENERATION]

+          🚨 **CRITICAL: TARGET INDEPENDENCE REQUIREMENT** 🚨
+          You are generating a template for EXACTLY ONE target: '{target}'.
+          - Do NOT include content from other targets in the workflow
+          - This template is for '{target}' ONLY - treat it as a standalone UI entity
+          - Even if '{target}' might coexist with other targets in a final application,
+            your task is to create an INDEPENDENT, REUSABLE template for '{target}' alone
+
          Generate a **style-agnostic** layout template for a specific {target_type} and layout strategy, informed by modern web development best practices.

          🎯 **CRITICAL REQUIREMENTS**:
          ✅ **ADAPTIVE**: Multi-device responsive design (mobile, tablet, desktop)
          ✅ **STYLE-SWITCHABLE**: Support runtime theme/style switching via CSS variables
          ✅ **TOKEN-DRIVEN**: 100% CSS variable usage, zero hardcoded values
+          ✅ **INDEPENDENT**: Template for '{target}' only, no other targets included

          ## Context
          LAYOUT_ID: {layout_id}
@@ -709,7 +717,7 @@ IF len(target_list) <= 1 OR target_type == "component":
 # For multi-page workflows, validate cross-page consistency → @ui-design-agent
 FOR style_id IN range(1, style_variants + 1):
    FOR layout_id IN range(1, layout_variants + 1):
-        Task(ui-design-agent): "
+        Task(@ui-design-agent): "
          [CROSS_PAGE_CONSISTENCY_VALIDATION]

          Validate design consistency across multiple {target_type}s for Style-{style_id} Layout-{layout_id}