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-05 01:50:27 +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}
--- a/ui-instantiate-analysis.md
+++ b/ui-instantiate-analysis.md
@@ -0,0 +1,231 @@
+# UI原型实例化脚本分析报告
+
+## 问题现象
+
+在执行 `ui-instantiate-prototypes.sh` 脚本时，生成了 `style-4` 的原型文件（如 `login-style-4-layout-1.html`），但实际上 `style-consolidation` 目录下只有3个样式目录（style-1, style-2, style-3）。
+
+## 调查结果
+
+### 1. 目录结构验证
+
+```bash
+# 实际存在的样式目录
+.workflow/.design/run-20251009-210559/style-consolidation/
+├── style-1/
+├── style-2/
+└── style-3/
+
+# 生成的原型文件包含
+prototypes/login-style-4-layout-1.html  ❌ 引用不存在的 ../style-consolidation/style-4/tokens.css
+prototypes/sidebar-style-4-layout-1.html  ❌ 引用不存在的 ../style-consolidation/style-4/tokens.css
+```
+
+### 2. consolidation-report.json 确认
+
+```json
+{
+  "variant_count": 3,  // 明确显示只有3个变体
+  "variants": [
+    {"id": "style-1"},
+    {"id": "style-2"},
+    {"id": "style-3"}
+  ]
+}
+```
+
+### 3. PREVIEW.md 显示异常
+
+```markdown
+- **Style Variants:** 4  ⚠️ 与实际不符
+- **Total Prototypes:** 24  (4 × 3 × 2 = 24)
+```
+
+### 4. 脚本auto_detect_style_variants()函数
+
+```bash
+# 位置：.claude/scripts/ui-instantiate-prototypes.sh 第52-71行
+auto_detect_style_variants() {
+    local base_path="$1"
+    local style_dir="$base_path/../style-consolidation"
+
+    # 统计style-*目录数量
+    local count=$(find "$style_dir" -maxdepth 1 -type d -name "style-*" | wc -l)
+    echo "$count"
+}
+```
+
+**验证测试**：
+```bash
+cd .workflow/.design/run-20251009-210559/style-consolidation
+find . -maxdepth 1 -type d -name "style-*" | wc -l
+# 输出：3 ✅ 函数逻辑正确
+```
+
+## 根本原因分析
+
+### ⚠️ 参数覆盖问题
+
+脚本虽然有自动检测功能，但**允许手动参数覆盖**：
+
+```bash
+# 自动检测模式（正确）
+ui-instantiate-prototypes.sh prototypes/  # 会自动检测到3个样式
+
+# 手动模式（错误来源）
+ui-instantiate-prototypes.sh prototypes/ "login,sidebar" 4 3  # 强制指定4个样式变体 ❌
+```
+
+### 🔍 实际调用场景
+
+根据工作流命令 `.claude/commands/workflow/ui-design/generate.md` 第79-82行：
+
+```bash
+# Phase 1: Path Resolution & Context Loading
+style_variants = --style-variants OR 3  # 默认为3
+```
+
+**推断的问题来源**：
+1. 工作流命令被手动调用时，传入了 `--style-variants 4`
+2. 这个参数被直接传递给 `ui-instantiate-prototypes.sh` 脚本
+3. 脚本没有验证参数值与实际目录数量是否匹配
+4. 导致生成了引用不存在的style-4目录的HTML文件
+
+## 问题影响
+
+### 生成的style-4文件问题
+
+所有 `*-style-4-*.html` 文件都会出现CSS加载失败：
+
+```html
+<!-- 文件中的CSS引用 -->
+<link rel="stylesheet" href="../style-consolidation/style-4/tokens.css">
+<!-- ❌ 该路径不存在，导致样式无法加载 -->
+```
+
+### 影响范围
+
+- `login-style-4-layout-{1,2,3}.html` - 3个文件 ❌
+- `sidebar-style-4-layout-{1,2,3}.html` - 3个文件 ❌
+- 对应的 `*-notes.md` 文件 - 6个说明文件（内容错误）
+
+## 解决方案
+
+### 方案1：重新生成（推荐）
+
+```bash
+cd .workflow/.design/run-20251009-210559/prototypes
+
+# 删除错误的style-4文件
+rm -f *-style-4-*
+
+# 重新运行脚本（使用自动检测）
+~/.claude/scripts/ui-instantiate-prototypes.sh . --session-id run-20251009-210559
+```
+
+### 方案2：脚本增强（预防）
+
+在 `ui-instantiate-prototypes.sh` 中添加参数验证：
+
+```bash
+# 在第239行之后添加
+# Validate STYLE_VARIANTS matches actual directories
+actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" | wc -l)
+if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
+    log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
+    log_info "Auto-correcting to $actual_styles style variants"
+    STYLE_VARIANTS=$actual_styles
+fi
+```
+
+### 方案3：工作流命令修复
+
+在 `.claude/commands/workflow/ui-design/generate.md` 中添加验证：
+
+```bash
+# Phase 1: Path Resolution & Context Loading (第79-82行之后)
+style_variants = --style-variants OR 3  # Default to 3
+
+# 添加验证逻辑
+actual_styles = count_directories({base_path}/style-consolidation/style-*)
+IF style_variants > actual_styles:
+    WARN: "Requested {style_variants} styles, but only {actual_styles} exist"
+    REPORT: "Auto-correcting to {actual_styles} style variants"
+    style_variants = actual_styles
+
+VALIDATE: 1 <= style_variants <= 5
+```
+
+## 预防措施
+
+1. **优先使用自动检测**：
+   ```bash
+   # ✅ 推荐：让脚本自动检测
+   ui-instantiate-prototypes.sh prototypes/
+
+   # ⚠️ 谨慎：手动指定参数（需确保正确）
+   ui-instantiate-prototypes.sh prototypes/ "login,sidebar" 3 3
+   ```
+
+2. **验证consolidation输出**：
+   ```bash
+   # 生成原型前，先确认样式数量
+   jq '.variant_count' style-consolidation/consolidation-report.json
+   ```
+
+3. **使用工作流命令**：
+   ```bash
+   # 工作流命令会自动处理参数验证
+   /workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+   ```
+
+## 技术细节
+
+### 自动检测逻辑流程
+
+```mermaid
+graph TD
+    A[调用脚本] --> B{检查参数数量}
+    B -->|1个参数| C[自动检测模式]
+    B -->|4个参数| D[手动模式]
+    C --> E[检测style目录]
+    D --> F[使用传入参数]
+    E --> G[验证目录存在]
+    F --> G
+    G -->|不匹配| H[⚠️ 生成错误文件]
+    G -->|匹配| I[✅ 正常生成]
+```
+
+### find命令行为
+
+```bash
+# 正确的检测命令
+find style-consolidation -maxdepth 1 -type d -name "style-*"
+# 输出：
+# style-consolidation/style-1
+# style-consolidation/style-2
+# style-consolidation/style-3
+
+# wc -l 统计行数 = 3 ✅
+
+# 注意：style-extraction 不会被匹配（它在父目录）
+# find . -maxdepth 1 -type d -name "style-*"
+# 只会在当前目录搜索，不会递归到子目录
+```
+
+## 总结
+
+### 问题根源
+✅ **确认**：脚本被手动调用时传入了错误的 `--style-variants 4` 参数，但实际只有3个样式目录存在。
+
+### 脚本行为
+✅ **确认**：`auto_detect_style_variants()` 函数逻辑正确，能够正确检测到3个样式目录。
+
+### 修复优先级
+1. 🔴 **立即**：删除错误的style-4文件，重新生成
+2. 🟡 **短期**：在脚本中添加参数验证逻辑
+3. 🟢 **长期**：在工作流命令中添加防护验证
+
+### 最佳实践
+- 优先使用脚本的自动检测模式
+- 在手动指定参数前，先验证 `consolidation-report.json`
+- 使用工作流命令而非直接调用脚本