Enhance UI Design Workflow: Parameter Validation and Documentation Improvements

- Added validation for --style-variants in generate command to ensure it matches actual style directories, preventing errors during prototype generation. - Updated ui-instantiate-prototypes.sh script to validate style variants against existing directories, providing warnings and auto-correcting when necessary. - Improved clarity in generate.md documentation regarding parameters, default values, and auto-detection mechanisms. - Created a comprehensive UI Design Workflow Parameter Clarity Report to address inconsistencies in parameter naming and documentation across extract, consolidate, and generate commands. - Unified parameter naming conventions to reduce confusion and improve user experience. - Enhanced user guidance with a new README.md for the UI Design Workflow, outlining best practices and common mistakes.
2026-02-10 02:24:35 +08:00 · 2025-10-09 22:37:20 +08:00
parent f0bed9e072
commit 29dfd49c90
5 changed files with 951 additions and 618 deletions
--- a/ui-workflow-parameter-clarity-report.md
+++ b/ui-workflow-parameter-clarity-report.md
@@ -0,0 +1,425 @@
+# UI设计工作流参数清晰度分析报告
+
+## 📋 执行摘要
+
+**问题来源**：用户手动调用 `/workflow:ui-design:generate` 时传入了 `--style-variants 4`，但实际只有3个样式目录存在，导致生成了引用不存在CSS文件的 `style-4` 原型。
+
+**根本原因**：工作流命令链中参数命名不一致、验证缺失、文档说明不清晰。
+
+## 🔍 关键发现
+
+### 1. 参数命名不一致
+
+| 命令 | 参数名称 | 默认值 | 说明 |
+|------|---------|--------|------|
+| `extract` | `--variants` | 1 | ⚠️ 未在文档中明确说明默认值 |
+| `consolidate` | `--variants` | 所有变体 | ⚠️ 与extract同名但语义不同 |
+| `generate` | `--style-variants` | 3 | ⚠️ 名称不一致，默认值说明不清晰 |
+
+**问题**：
+- `extract` 和 `consolidate` 使用 `--variants`，但 `generate` 使用 `--style-variants`
+- `--variants` 在两个命令中含义不同：
+  - `extract`：生成多少个变体
+  - `consolidate`：处理多少个变体
+
+### 2. 命名转换混淆
+
+```
+extract 输出        → consolidate 处理      → generate 使用
+variant-1           → style-1/              → login-style-1-layout-1.html
+variant-2           → style-2/              → login-style-2-layout-1.html
+variant-3           → style-3/              → login-style-3-layout-1.html
+```
+
+**问题**：
+- `variant-N` 到 `style-N` 的转换没有文档说明
+- 增加了用户的认知负担
+- 容易造成混淆和错误
+
+### 3. 验证缺失
+
+#### ❌ 当前状态（generate.md 第79-82行）
+
+```bash
+# Phase 1: Path Resolution & Context Loading
+style_variants = --style-variants OR 3  # Default to 3
+VALIDATE: 1 <= style_variants <= 5
+```
+
+**问题**：
+- ✅ 验证范围（1-5）
+- ❌ 不验证是否匹配实际目录数量
+- ❌ 允许传入 `4` 但实际只有 `3` 个目录
+
+#### ✅ 应有的验证
+
+```bash
+style_variants = --style-variants OR 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 <= actual_styles
+```
+
+### 4. 文档清晰度问题
+
+#### extract.md
+
+**问题点**：
+- ⚠️ 默认值 `1` 未在 `usage` 或 `argument-hint` 中说明
+- ⚠️ 输出的 `variant-N` 命名未解释后续转换为 `style-N`
+
+**当前文档**（第580行附近）：
+```
+"id": "variant-2"  # 缺少说明这会成为 style-2 目录
+```
+
+#### consolidate.md
+
+**问题点**：
+- ⚠️ `--variants` 与 `extract` 同名但语义不同
+- ⚠️ 默认行为（处理所有变体）不够突出
+- ⚠️ `variant-N` → `style-N` 转换未文档化
+
+#### generate.md
+
+**问题点**：
+- ⚠️ `--style-variants` 名称与前置命令不一致
+- ⚠️ 默认值 `3` 的来源和意义不清晰
+- ⚠️ 自动检测机制未说明
+- ❌ 手动覆盖无验证
+
+**当前文档**（第79-82行）：
+```bash
+style_variants = --style-variants OR 3  # Default to 3
+VALIDATE: 1 <= style_variants <= 5
+```
+
+## 💡 改进方案
+
+### 方案1：代码层面改进（推荐）
+
+#### 1.1 统一参数命名
+
+```diff
+# extract.md
+- usage: /workflow:ui-design:extract [--variants <count>]
+ usage: /workflow:ui-design:extract [--style-variants <count>]
+
+# consolidate.md
+- usage: /workflow:ui-design:consolidate [--variants <count>]
+ usage: /workflow:ui-design:consolidate [--style-variants <count>]
+
+# generate.md (保持不变)
+  usage: /workflow:ui-design:generate [--style-variants <count>]
+```
+
+**优点**：
+- ✅ 全链路参数名称统一
+- ✅ 语义清晰（style-variants）
+- ✅ 降低混淆风险
+
+#### 1.2 添加验证逻辑（关键）
+
+##### generate.md 改进
+
+```bash
+# Phase 1: Path Resolution & Context Loading
+style_variants = --style-variants OR 3  # Default to 3
+
+# 🆕 添加验证逻辑
+actual_styles = count_directories({base_path}/style-consolidation/style-*)
+
+IF actual_styles == 0:
+    ERROR: "No style directories found in {base_path}/style-consolidation/"
+    SUGGEST: "Run /workflow:ui-design:consolidate first"
+    EXIT 1
+
+IF style_variants > actual_styles:
+    WARN: "⚠️ Requested {style_variants} style variants, but only {actual_styles} directories exist"
+    REPORT: "   Auto-correcting to {actual_styles} style variants"
+    REPORT: "   Available styles: {list_directories(style-consolidation/style-*)}"
+    style_variants = actual_styles
+
+VALIDATE: 1 <= style_variants <= actual_styles
+```
+
+##### ui-instantiate-prototypes.sh 改进
+
+在脚本第239行之后添加：
+
+```bash
+# Validate STYLE_VARIANTS matches actual directories
+if [ "$STYLE_VARIANTS" -gt 0 ]; then
+    actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" 2>/dev/null | wc -l)
+
+    if [ "$actual_styles" -eq 0 ]; then
+        log_error "No style directories found in style-consolidation/"
+        log_info "Run /workflow:ui-design:consolidate first"
+        exit 1
+    fi
+
+    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
+fi
+```
+
+#### 1.3 统一命名约定
+
+##### extract.md 改进
+
+修改输出格式（第580行附近）：
+
+```diff
+# style-cards.json 格式
+{
+  "style_cards": [
+    {
+-     "id": "variant-1",
+     "id": "style-1",
+      "name": "Modern Minimalist",
+      ...
+    }
+  ]
+}
+```
+
+### 方案2：文档层面改进
+
+#### 2.1 extract.md 文档改进
+
+```markdown
+## Parameters
+
+- `--style-variants <count>`: Number of style variants to extract. **Default: 1**
+  - Range: 1-5
+  - Each variant will become an independent design system (style-1, style-2, etc.)
+  - Output IDs use `style-N` format for consistency across the workflow
+
+## Output Format
+
+style-cards.json uses `style-N` IDs that directly correspond to directory names
+created by the consolidate command:
+
+- `style-1` → `style-consolidation/style-1/`
+- `style-2` → `style-consolidation/style-2/`
+```
+
+#### 2.2 consolidate.md 文档改进
+
+```markdown
+## Parameters
+
+- `--style-variants <count>`: Number of style variants to process from style-cards.json.
+  **Default: all available variants**
+  - Processes the first N variants from the style-cards array
+  - Creates separate `style-{n}` directories for each variant
+  - Range: 1 to count available in style-cards.json
+
+## Naming Convention
+
+Variants from extraction are materialized into style directories:
+- Input: `style-cards.json` with `style-1`, `style-2`, `style-3`
+- Output: `style-consolidation/style-1/`, `style-2/`, `style-3/` directories
+```
+
+#### 2.3 generate.md 文档改进
+
+```markdown
+## Parameters
+
+- `--style-variants <count>`: Number of style variants to generate prototypes for.
+  **Default: 3** (can be overridden)
+  - Range: 1-5
+  - ⚠️ **IMPORTANT**: This value MUST match the number of style-* directories in style-consolidation/
+  - If mismatched, the command will auto-correct to the actual directory count
+  - Use auto-detection (omit parameter) for safety
+
+## Auto-Detection vs Manual Override
+
+The command uses intelligent auto-detection:
+
+1. **Auto-Detection** (Recommended):
+   ```bash
+   /workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+   # Automatically counts style-1/, style-2/, style-3/ → uses 3
+   ```
+
+2. **Manual Override** (Use with caution):
+   ```bash
+   /workflow:ui-design:generate --style-variants 4
+   # If only 3 styles exist, auto-corrects to 3 with warning
+   ```
+
+3. **Safety Check**:
+   - Command validates against actual `style-consolidation/style-*` directories
+   - Prevents generation of prototypes referencing non-existent styles
+   - Displays warning and auto-corrects if mismatch detected
+```
+
+### 方案3：用户指南改进
+
+创建 `.claude/commands/workflow/ui-design/README.md`：
+
+```markdown
+# UI Design Workflow Parameter Guide
+
+## Style Variant Count Flow
+
+### 1. Extract Phase
+```bash
+/workflow:ui-design:extract --style-variants 3
+# Generates: style-cards.json with 3 style variants (style-1, style-2, style-3)
+```
+
+### 2. Consolidate Phase
+```bash
+/workflow:ui-design:consolidate --style-variants 3
+# Creates: style-consolidation/style-1/, style-2/, style-3/
+```
+
+### 3. Generate Phase
+```bash
+# ✅ Recommended: Let it auto-detect
+/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+
+# ⚠️ Manual: Must match consolidation output
+/workflow:ui-design:generate --style-variants 3
+```
+
+## ⚠️ Common Mistakes
+
+### Mistake 1: Mismatched Counts
+```bash
+# ❌ Wrong: Request 4 styles when only 3 exist
+/workflow:ui-design:generate --style-variants 4
+# Only 3 directories in style-consolidation/ → ERROR
+
+# ✅ Correct: Omit parameter for auto-detection
+/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+```
+
+### Mistake 2: Naming Confusion
+```bash
+# ❌ Don't confuse variant-N with style-N
+# variant-N was old naming in style-cards.json
+# style-N is the current standard across all commands
+```
+
+## 🎯 Best Practices
+
+1. **Use auto-detection**: Omit `--style-variants` in generate command
+2. **Verify consolidation**: Check `consolidation-report.json` before generating
+3. **Use explore-auto**: Automated workflow prevents parameter mismatches
+4. **Check directories**: `ls .workflow/.design/run-xxx/style-consolidation/`
+```
+
+## 🎯 实施优先级
+
+### 🔴 高优先级（立即实施）
+
+1. **generate.md 添加验证逻辑**
+   - 防止参数不匹配问题再次发生
+   - 影响范围：所有手动调用 generate 命令的场景
+
+2. **ui-instantiate-prototypes.sh 添加验证**
+   - 脚本层面的最后防线
+   - 影响范围：所有原型生成操作
+
+3. **文档说明默认值和验证机制**
+   - 降低用户误用风险
+   - 影响范围：所有新用户和手动操作场景
+
+### 🟡 中优先级（短期改进）
+
+4. **统一参数命名为 --style-variants**
+   - 提高一致性，减少混淆
+   - 影响范围：需要更新多个命令文件
+
+5. **extract.md 统一使用 style-N 命名**
+   - 消除命名转换混淆
+   - 影响范围：需要更新 style-cards.json 格式
+
+### 🟢 低优先级（长期优化）
+
+6. **创建用户指南 README.md**
+   - 提供完整的参数使用指南
+   - 影响范围：文档层面，不影响功能
+
+## 📊 改进效果预测
+
+### 实施前
+
+```
+用户手动调用: /workflow:ui-design:generate --style-variants 4
+实际目录数: 3
+结果: ❌ 生成 login-style-4-layout-1.html 引用不存在的 CSS
+```
+
+### 实施后
+
+```
+用户手动调用: /workflow:ui-design:generate --style-variants 4
+实际目录数: 3
+
+验证检查:
+⚠️ Requested 4 style variants, but only 3 directories exist
+   Available: style-1, style-2, style-3
+   Auto-correcting to 3 style variants
+
+结果: ✅ 生成正确的 style-1, style-2, style-3 原型，避免错误
+```
+
+## 🔧 快速修复指南（针对当前问题）
+
+### 立即修复生成的错误文件
+
+```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
+```
+
+### 预防未来错误
+
+```bash
+# ✅ 推荐：使用自动检测
+/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+
+# ⚠️ 如果必须手动指定，先验证
+jq '.variant_count' .workflow/.design/run-xxx/style-consolidation/consolidation-report.json
+# 输出: 3
+# 然后使用该数字
+/workflow:ui-design:generate --style-variants 3
+```
+
+## 📝 总结
+
+**核心问题**：
+- 参数命名不统一（`--variants` vs `--style-variants`）
+- 命名转换混淆（`variant-N` → `style-N`）
+- 验证缺失（不检查参数是否匹配实际目录）
+- 文档不清晰（默认值、自动检测机制说明不足）
+
+**关键改进**：
+1. ✅ 添加参数验证逻辑（防止不匹配）
+2. ✅ 统一参数命名（提高一致性）
+3. ✅ 完善文档说明（降低误用风险）
+4. ✅ 提供清晰的用户指南
+
+**预期效果**：
+- 🔒 杜绝参数不匹配问题
+- 📈 提高工作流鲁棒性
+- 🎓 降低用户学习成本
+- 🚀 提升整体用户体验