feat: add interactive preview system for UI prototypes

🌐 Preview Enhancement System - Auto-generate index.html for master navigation - Auto-generate compare.html for side-by-side comparison - Auto-generate PREVIEW.md with setup instructions 📊 Preview Features - Master navigation with grid layout of all prototypes - Side-by-side comparison with iframe-based variants - Responsive viewport toggles (Desktop/Tablet/Mobile 100%/768px/375px) - Synchronized scrolling for layout comparison - Dynamic page switching dropdown - Quick links to implementation notes 🛠️ Preview Options - Direct browser opening (simplest - double-click index.html) - Local server (recommended - Python/Node.js/PHP/VS Code Live Server) - Complete standalone prototypes with no external dependencies 📚 Documentation Updates - Add detailed UI design commands section to README.md - Add Chinese UI design commands section to README_CN.md - Update CHANGELOG.md with comprehensive preview system documentation - Add usage examples and preview workflow guide - Update ui-generate.md with preview file templates 🎯 Integration - Phase 4 in ui-generate command generates all preview files - Updated TodoWrite to track preview file generation - Updated output structure to show new preview files - Enhanced "Next Steps" section with preview instructions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-05 01:50:27 +08:00 · 2025-10-06 00:13:33 +08:00
parent 25951ac9b0
commit 0e16c6ba4b
4 changed files with 594 additions and 28 deletions
--- a/.claude/commands/workflow/design/ui-generate.md
+++ b/.claude/commands/workflow/design/ui-generate.md
@@ -150,27 +150,56 @@ For each page in {page_list}:
 "
 ```

-### Phase 4: Gemini Variant Suggestions (Optional)
+### Phase 4: Generate Preview Enhancement Files
+**Direct Execution**: Create preview index and comparison view
+
+```bash
+# Generate preview index page
+Write(.workflow/WFS-{session}/.design/prototypes/index.html):
+  - List all generated prototypes with thumbnails
+  - Quick navigation to individual variants
+  - Metadata: page name, variant count, generation timestamp
+  - Direct links to HTML files
+
+# Generate side-by-side comparison view
+Write(.workflow/WFS-{session}/.design/prototypes/compare.html):
+  - Iframe-based comparison for all variants of same page
+  - Responsive viewport toggles (mobile, tablet, desktop)
+  - Synchronized scrolling option
+  - Variant labels and quick switching
+
+# Generate preview server instructions
+Write(.workflow/WFS-{session}/.design/prototypes/PREVIEW.md):
+  - How to open files directly in browser
+  - Local server setup commands (Python, Node.js, PHP)
+  - Port and access instructions
+  - Browser compatibility notes
+```
+
+**Output**:
+- `index.html`: Master index page for all prototypes
+- `compare.html`: Side-by-side comparison view
+- `PREVIEW.md`: Preview instructions and server setup guide
+
+### Phase 5: Gemini Variant Suggestions (Optional)
 **Conditional Execution**: Only if --variants > 1

 ```bash
 IF variants_count > 1:
-  Task(conceptual-planning-agent): "
-  Generate semantic layout variation suggestions using Gemini
-
-  TASK: Analyze synthesis-specification.md and suggest {variants_count} layout approaches
-  CONTEXT: synthesis-specification.md, ui-designer/analysis.md
-  OUTPUT: variant-suggestions.md with layout rationale for each variant
-
-  Use Gemini to explore:
-  - Different information hierarchy approaches
-  - Alternative component compositions
-  - Varied user flow emphasis
-  - Diverse layout patterns (sidebar, top-nav, card-grid, list-detail)
-  "
+  bash(cd .workflow/WFS-{session}/.design/prototypes && \
+    ~/.claude/scripts/gemini-wrapper -p "
+    PURPOSE: Generate semantic layout variation rationale
+    TASK: Analyze synthesis-specification.md and explain {variants_count} layout approaches
+    MODE: analysis
+    CONTEXT: @{../../.brainstorming/synthesis-specification.md,../../.brainstorming/ui-designer/analysis.md}
+    EXPECTED: variant-suggestions.md with layout rationale for each variant
+    RULES: Focus on information hierarchy, component composition, user flow emphasis, layout patterns
+    ")
 ```

-### Phase 5: TodoWrite Integration
+**Output**: `variant-suggestions.md` with Gemini's layout rationale
+
+### Phase 6: TodoWrite Integration
 ```javascript
 TodoWrite({
  todos: [
@@ -189,6 +218,11 @@ TodoWrite({
      status: "completed",
      activeForm: "Generating UI prototypes"
    },
+    {
+      content: "Generate preview enhancement files (index, compare, instructions)",
+      status: "completed",
+      activeForm: "Generating preview files"
+    },
    {
      content: "Generate layout variant suggestions using Gemini (optional)",
      status: "completed",
@@ -207,6 +241,9 @@ TodoWrite({

 ```
 .workflow/WFS-{session}/.design/prototypes/
+├── index.html                     # 🆕 Preview index page (master navigation)
+├── compare.html                   # 🆕 Side-by-side comparison view
+├── PREVIEW.md                     # 🆕 Preview instructions and server setup
 ├── dashboard-variant-1.html
 ├── dashboard-variant-1.css
 ├── dashboard-variant-1-notes.md
@@ -277,6 +314,247 @@ TodoWrite({
 }
 ```

+### Preview Index Page Template (index.html)
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>UI Prototypes Preview - WFS-{session}</title>
+  <style>
+    body { font-family: system-ui; max-width: 1200px; margin: 2rem auto; padding: 0 1rem; }
+    h1 { color: #2563eb; }
+    .prototype-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 1.5rem; margin-top: 2rem; }
+    .prototype-card { border: 1px solid #e5e7eb; border-radius: 0.5rem; padding: 1rem; transition: box-shadow 0.2s; }
+    .prototype-card:hover { box-shadow: 0 4px 12px rgba(0,0,0,0.1); }
+    .prototype-card h3 { margin: 0 0 0.5rem; color: #1f2937; }
+    .prototype-card .meta { font-size: 0.875rem; color: #6b7280; margin-bottom: 1rem; }
+    .prototype-card a { display: inline-block; margin-right: 0.5rem; color: #2563eb; text-decoration: none; }
+    .prototype-card a:hover { text-decoration: underline; }
+    .actions { margin-top: 2rem; padding: 1rem; background: #f3f4f6; border-radius: 0.5rem; }
+    .actions a { margin-right: 1rem; color: #2563eb; }
+  </style>
+</head>
+<body>
+  <h1>🎨 UI Prototypes Preview</h1>
+  <p><strong>Session:</strong> WFS-{session} | <strong>Generated:</strong> {timestamp}</p>
+
+  <div class="actions">
+    <a href="compare.html">📊 Compare All Variants</a>
+    <a href="PREVIEW.md">📖 Preview Instructions</a>
+  </div>
+
+  <div class="prototype-grid">
+    <!-- Auto-generated for each page-variant -->
+    <div class="prototype-card">
+      <h3>Dashboard - Variant 1</h3>
+      <div class="meta">Generated: {timestamp}</div>
+      <a href="dashboard-variant-1.html" target="_blank">View Prototype →</a>
+      <a href="dashboard-variant-1-notes.md">Implementation Notes</a>
+    </div>
+  </div>
+</body>
+</html>
+```
+
+### Comparison View Template (compare.html)
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Side-by-Side Comparison - WFS-{session}</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: system-ui; }
+    .header { background: #1f2937; color: white; padding: 1rem 2rem; display: flex; justify-content: space-between; align-items: center; }
+    .controls { display: flex; gap: 1rem; align-items: center; }
+    select, button { padding: 0.5rem 1rem; border-radius: 0.25rem; border: 1px solid #d1d5db; background: white; cursor: pointer; }
+    button:hover { background: #f3f4f6; }
+    .comparison-container { display: flex; height: calc(100vh - 60px); }
+    .variant-panel { flex: 1; border-right: 2px solid #e5e7eb; position: relative; }
+    .variant-panel:last-child { border-right: none; }
+    .variant-label { position: absolute; top: 0; left: 0; right: 0; background: rgba(37,99,235,0.9); color: white; padding: 0.5rem; text-align: center; z-index: 10; font-weight: 600; }
+    iframe { width: 100%; height: 100%; border: none; padding-top: 2.5rem; }
+    .viewport-toggle { display: flex; gap: 0.5rem; }
+    .viewport-btn { padding: 0.25rem 0.75rem; font-size: 0.875rem; }
+    .viewport-btn.active { background: #2563eb; color: white; border-color: #2563eb; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>📊 Side-by-Side Comparison</h1>
+    <div class="controls">
+      <div class="viewport-toggle">
+        <button class="viewport-btn active" data-width="100%">Desktop</button>
+        <button class="viewport-btn" data-width="768px">Tablet</button>
+        <button class="viewport-btn" data-width="375px">Mobile</button>
+      </div>
+      <select id="page-select">
+        <option value="dashboard">Dashboard</option>
+        <option value="auth">Auth</option>
+      </select>
+      <label><input type="checkbox" id="sync-scroll"> Sync Scroll</label>
+      <a href="index.html" style="color: white;">← Back to Index</a>
+    </div>
+  </div>
+
+  <div class="comparison-container">
+    <div class="variant-panel">
+      <div class="variant-label">Variant 1</div>
+      <iframe id="frame1" src="dashboard-variant-1.html"></iframe>
+    </div>
+    <div class="variant-panel">
+      <div class="variant-label">Variant 2</div>
+      <iframe id="frame2" src="dashboard-variant-2.html"></iframe>
+    </div>
+  </div>
+
+  <script>
+    // Viewport switching
+    document.querySelectorAll('.viewport-btn').forEach(btn => {
+      btn.addEventListener('click', () => {
+        document.querySelectorAll('.viewport-btn').forEach(b => b.classList.remove('active'));
+        btn.classList.add('active');
+        const width = btn.dataset.width;
+        document.querySelectorAll('iframe').forEach(frame => {
+          frame.style.width = width;
+          frame.style.margin = width === '100%' ? '0' : '0 auto';
+        });
+      });
+    });
+
+    // Synchronized scrolling
+    const syncCheckbox = document.getElementById('sync-scroll');
+    const frames = [document.getElementById('frame1'), document.getElementById('frame2')];
+
+    syncCheckbox.addEventListener('change', () => {
+      if (syncCheckbox.checked) {
+        frames.forEach(frame => {
+          frame.contentWindow.addEventListener('scroll', () => {
+            const scrollTop = frame.contentWindow.scrollY;
+            frames.forEach(f => {
+              if (f !== frame) f.contentWindow.scrollTo(0, scrollTop);
+            });
+          });
+        });
+      }
+    });
+
+    // Page switching
+    document.getElementById('page-select').addEventListener('change', (e) => {
+      const page = e.target.value;
+      document.getElementById('frame1').src = `${page}-variant-1.html`;
+      document.getElementById('frame2').src = `${page}-variant-2.html`;
+    });
+  </script>
+</body>
+</html>
+```
+
+### Preview Instructions Template (PREVIEW.md)
+```markdown
+# UI Prototypes Preview Guide
+
+## Session Information
+- **Session ID**: WFS-{session}
+- **Generated**: {timestamp}
+- **Pages**: {page_list}
+- **Variants per page**: {variants_count}
+
+## Quick Preview Options
+
+### Option 1: Direct Browser Opening (Simplest)
+1. Navigate to `.workflow/WFS-{session}/.design/prototypes/`
+2. Double-click `index.html` to open the preview index
+3. Click any prototype link to view in browser
+
+### Option 2: Local Development Server (Recommended)
+
+#### Python (Built-in)
+```bash
+cd .workflow/WFS-{session}/.design/prototypes
+python -m http.server 8080
+# Visit: http://localhost:8080
+```
+
+#### Node.js (npx)
+```bash
+cd .workflow/WFS-{session}/.design/prototypes
+npx http-server -p 8080
+# Visit: http://localhost:8080
+```
+
+#### PHP (Built-in)
+```bash
+cd .workflow/WFS-{session}/.design/prototypes
+php -S localhost:8080
+# Visit: http://localhost:8080
+```
+
+#### VS Code Live Server
+1. Install "Live Server" extension
+2. Right-click `index.html`
+3. Select "Open with Live Server"
+
+## Preview Features
+
+### Index Page (`index.html`)
+- **Master navigation** for all prototypes
+- **Quick links** to individual variants
+- **Metadata display**: timestamps, page info
+- **Direct access** to implementation notes
+
+### Comparison View (`compare.html`)
+- **Side-by-side** variant comparison
+- **Viewport toggles**: Desktop (100%), Tablet (768px), Mobile (375px)
+- **Synchronized scrolling** option
+- **Page switching** dropdown
+- **Real-time** comparison
+
+## Browser Compatibility
+- ✅ Chrome/Edge (Recommended)
+- ✅ Firefox
+- ✅ Safari
+- ⚠️ Some CSS features may require modern browsers (OKLCH colors)
+
+## Files Overview
+```
+prototypes/
+├── index.html          ← Start here
+├── compare.html        ← Side-by-side comparison
+├── PREVIEW.md          ← This file
+├── {page}-variant-{n}.html  ← Individual prototypes
+├── {page}-variant-{n}.css   ← Styles (token-driven)
+├── design-tokens.css   ← CSS custom properties
+└── {page}-variant-{n}-notes.md  ← Implementation guidance
+```
+
+## Next Steps
+1. **Review prototypes**: Open index.html
+2. **Compare variants**: Use compare.html for side-by-side view
+3. **Select preferred**: Note variant IDs for design-update command
+4. **Continue workflow**: Run design-update with selected prototypes
+
+## Troubleshooting
+
+**Styles not loading?**
+- Ensure `design-tokens.css` is in the same directory
+- Check browser console for CSS errors
+- Verify file paths in HTML `<link>` tags
+
+**OKLCH colors not displaying?**
+- Use Chrome/Edge 111+ or Firefox 113+
+- Fallback colors should work in older browsers
+
+**Local server CORS issues?**
+- Use one of the recommended local servers
+- Avoid opening HTML files with `file://` protocol for best results
+```
+
+
 ## Error Handling
 - **No design tokens found**: Run `/workflow:design:style-consolidate` first
 - **Invalid page names**: List available pages from synthesis-specification.md
@@ -300,17 +578,35 @@ After generation, verify:
 ## Next Steps
 After successful generation:
 ```
-UI prototypes generated for session: WFS-{session}
+✅ UI prototypes generated for session: WFS-{session}
 Pages: {page_list}
 Variants per page: {variants_count}

 Generated files:
- {count} HTML prototypes
+- {count} HTML prototypes (complete, standalone)
 - {count} CSS files (token-driven)
 - {count} implementation notes
+- 🆕 index.html (preview navigation)
+- 🆕 compare.html (side-by-side comparison)
+- 🆕 PREVIEW.md (preview instructions)

-Review prototypes and select preferred variants:
-Location: .workflow/WFS-{session}/.design/prototypes/
+📂 Location: .workflow/WFS-{session}/.design/prototypes/

-Next: /workflow:design:design-update --session WFS-{session}
+🌐 Preview Options:
+1. Quick: Open index.html in browser
+2. Full: Start local server and visit http://localhost:8080
+   - Python: cd prototypes && python -m http.server 8080
+   - Node.js: cd prototypes && npx http-server -p 8080
+
+📊 Compare Variants:
+- Open compare.html for side-by-side view
+- Toggle viewports: Desktop / Tablet / Mobile
+- Switch between pages dynamically
+- Synchronized scrolling option
+
+Review prototypes and select preferred variants, then run:
+/workflow:design:design-update --session WFS-{session} --selected-prototypes "{page-variant-ids}"
+
+Example:
+/workflow:design:design-update --session WFS-{session} --selected-prototypes "dashboard-variant-1,auth-variant-2"
 ```
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,9 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [3.5.0] - 2025-10-06

-### 🎨 UI Design Workflow with Triple Vision Analysis
+### 🎨 UI Design Workflow with Triple Vision Analysis & Interactive Preview

-This release introduces a comprehensive UI design workflow system with triple vision analysis capabilities, interactive user checkpoints, and zero agent overhead for improved performance.
+This release introduces a comprehensive UI design workflow system with triple vision analysis capabilities, interactive user checkpoints, zero agent overhead, and enhanced preview tools for real-time prototype comparison.

 #### Added

@@ -34,29 +34,84 @@ This release introduces a comprehensive UI design workflow system with triple vi
  - Conflict resolution: Majority vote or synthesis-specification.md context

 **Individual Design Commands**:
- **`/workflow:design:style-extract`**: Extract design styles from reference images
+
+**`/workflow:design:style-extract`** - Extract design styles from reference images
+- **Usage**: `/workflow:design:style-extract --session <session_id> --images "<glob_pattern>"`
+- **Examples**:
+  ```bash
+  /workflow:design:style-extract --session WFS-auth --images "design-refs/*.png"
+  /workflow:design:style-extract --session WFS-dashboard --images "refs/dashboard-*.jpg"
+  ```
+- **Features**:
  - Triple vision analysis (Claude Code + Gemini + Codex)
  - Generates `semantic_style_analysis.json`, `design-tokens.json`, `style-cards.json`
  - Outputs multiple style variant cards for user selection
  - Direct bash execution (no agent wrappers)
+  - Supports PNG, JPG, WebP image formats
+- **Output**: `.design/style-extraction/` with analysis files and 2-3 style variant cards

- **`/workflow:design:style-consolidate`**: Consolidate selected style variants
-  - Validates and merges design tokens
+**`/workflow:design:style-consolidate`** - Consolidate selected style variants
+- **Usage**: `/workflow:design:style-consolidate --session <session_id> --variants "<variant_ids>"`
+- **Examples**:
+  ```bash
+  /workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+  /workflow:design:style-consolidate --session WFS-dashboard --variants "variant-2"
+  ```
+- **Features**:
+  - Validates and merges design tokens from selected variants
  - Generates finalized `design-tokens.json`, `style-guide.md`, `tailwind.config.js`
-  - WCAG AA compliance validation
+  - WCAG AA compliance validation (contrast ≥4.5:1 for text)
  - Token coverage ≥90% requirement
+  - OKLCH color format with fallback
+- **Output**: `.design/style-consolidation/` with validated design system files

- **`/workflow:design:ui-generate`**: Generate production-ready UI prototypes
+**`/workflow:design:ui-generate`** - Generate production-ready UI prototypes *(NEW: with preview enhancement)*
+- **Usage**: `/workflow:design:ui-generate --session <session_id> --pages "<page_list>" [--variants <count>] [--style-overrides "<path_or_json>"]`
+- **Examples**:
+  ```bash
+  /workflow:design:ui-generate --session WFS-auth --pages "login,register"
+  /workflow:design:ui-generate --session WFS-dashboard --pages "dashboard" --variants 3
+  /workflow:design:ui-generate --session WFS-auth --pages "login" --style-overrides "overrides.json"
+  ```
+- **Features**:
  - Token-driven HTML/CSS generation with Codex
  - Support for `--style-overrides` parameter for runtime customization
  - Generates `{page}-variant-{n}.html`, `{page}-variant-{n}.css` per page
+  - **🆕 Auto-generates preview files**: `index.html`, `compare.html`, `PREVIEW.md`
  - Semantic HTML5 with ARIA attributes
  - Responsive design with token-based breakpoints
+  - Complete standalone prototypes (no external dependencies)
+- **Output**: `.design/prototypes/` with HTML/CSS files and preview tools
+- **Preview**: Open `index.html` in browser or start local server for interactive preview

- **`/workflow:design:design-update`**: Integrate design system into brainstorming
+**`/workflow:design:design-update`** - Integrate design system into brainstorming
+- **Usage**: `/workflow:design:design-update --session <session_id> [--selected-prototypes "<prototype_ids>"]`
+- **Examples**:
+  ```bash
+  /workflow:design:design-update --session WFS-auth
+  /workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+  ```
+- **Features**:
  - Updates `synthesis-specification.md` with UI/UX guidelines section
  - Creates/updates `ui-designer/style-guide.md`
  - Makes design tokens available for task generation phase
+  - Merges selected prototype recommendations into brainstorming artifacts
+- **Output**: Updated brainstorming files with design system integration
+
+**`/workflow:design:auto`** - Semi-autonomous orchestrator with interactive checkpoints
+- **Usage**: `/workflow:design:auto --session <session_id> --images "<glob>" --pages "<list>" [--variants <count>] [--batch-plan]`
+- **Examples**:
+  ```bash
+  /workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register"
+  /workflow:design:auto --session WFS-dashboard --images "refs/*.jpg" --pages "dashboard" --variants 3 --batch-plan
+  ```
+- **Features**:
+  - Orchestrates entire design workflow with pause-and-continue checkpoints
+  - Checkpoint 1: User selects style variants after extraction
+  - Checkpoint 2: User confirms prototypes before design-update
+  - Optional `--batch-plan` for automatic task generation after design-update
+  - Progress tracking with TodoWrite integration
+- **Workflow**: style-extract → [USER SELECTS] → style-consolidate → ui-generate → [USER CONFIRMS] → design-update → [optional batch-plan]

 **Interactive Checkpoint System**:
 - **Checkpoint 1 (After style-extract)**: User selects preferred style variants
@@ -74,6 +129,45 @@ This release introduces a comprehensive UI design workflow system with triple vi
 - **Batch Task Generation**: Automatic `/workflow:plan` invocation for each page
 - **Accessibility Validation**: WCAG 2.1 AA compliance checks

+**Preview Enhancement System** *(NEW)*:
+- **`index.html`**: Master preview navigation page
+  - Grid layout of all generated prototypes
+  - Quick links to individual variants
+  - Metadata display (session ID, timestamps, page info)
+  - Direct access to implementation notes
+
+- **`compare.html`**: Interactive side-by-side comparison
+  - Iframe-based comparison for multiple variants
+  - Responsive viewport toggles (Desktop 100%, Tablet 768px, Mobile 375px)
+  - Synchronized scrolling option
+  - Dynamic page switching dropdown
+  - Real-time variant comparison
+
+- **`PREVIEW.md`**: Comprehensive preview instructions
+  - Direct browser opening guide
+  - Local server setup (Python, Node.js, PHP, VS Code Live Server)
+  - Browser compatibility notes
+  - Troubleshooting guide
+  - File structure overview
+
+**Preview Workflow**:
+```bash
+# After ui-generate completes:
+cd .workflow/WFS-{session}/.design/prototypes
+
+# Option 1: Direct browser (simplest)
+open index.html  # or double-click
+
+# Option 2: Local server (recommended)
+python -m http.server 8080  # Visit http://localhost:8080
+
+# Features:
+- index.html: Browse all prototypes
+- compare.html: Side-by-side comparison with viewport controls
+- Responsive preview: Test mobile, tablet, desktop views
+- Synchronized scrolling: Compare layouts in sync
+```
+
 #### Changed

 **Agent Architecture Simplification**:
--- a/README.md
+++ b/README.md
@@ -260,6 +260,13 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 /workflow:design:style-extract --session WFS-auth --images "refs/*.png"
 /workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
 /workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
+
+# Preview generated prototypes (NEW!)
+# Option 1: Open .workflow/WFS-auth/.design/prototypes/index.html in browser
+# Option 2: Start local server
+cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
+# Visit http://localhost:8080 for interactive preview with comparison tools
+
 /workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
 ```

@@ -370,6 +377,87 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 | `/workflow:tools:test-concept-enhanced` | Generate test strategy and requirements analysis using Gemini. |
 | `/workflow:tools:test-task-generate` | Generate test task JSON with test-fix-cycle specification. |

+### **UI Design Workflow Commands (`/workflow:design:*`)** *(v3.5.0+)*
+
+The design workflow system provides complete UI design refinement from style extraction to prototype generation with interactive preview tools.
+
+#### Core Commands
+
+**`/workflow:design:auto`** - Complete workflow orchestrator
+```bash
+# Semi-autonomous workflow with user checkpoints
+/workflow:design:auto --session WFS-auth --images "refs/*.png" --pages "login,register"
+/workflow:design:auto --session WFS-dash --images "refs/*.jpg" --pages "dashboard" --variants 3 --batch-plan
+```
+- **Checkpoints**: User selects style variants (Phase 1) and confirms prototypes (Phase 3)
+- **Optional**: `--batch-plan` for automatic task generation
+
+**`/workflow:design:style-extract`** - Triple vision style analysis
+```bash
+# Extract design from reference images
+/workflow:design:style-extract --session WFS-auth --images "design-refs/*.png"
+```
+- **Vision Sources**: Claude Code + Gemini + Codex
+- **Output**: Style variant cards for user selection
+
+**`/workflow:design:style-consolidate`** - Validate and merge tokens
+```bash
+# Consolidate selected style variants
+/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+```
+- **Features**: WCAG AA validation, OKLCH colors, W3C token format
+- **Output**: `design-tokens.json`, `style-guide.md`, `tailwind.config.js`
+
+**`/workflow:design:ui-generate`** - Generate HTML/CSS prototypes
+```bash
+# Generate prototypes with preview tools
+/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
+/workflow:design:ui-generate --session WFS-auth --pages "dashboard" --style-overrides "custom.json"
+```
+- **🆕 Preview Files**: `index.html` (navigation), `compare.html` (side-by-side), `PREVIEW.md` (instructions)
+- **Features**: Token-driven CSS, semantic HTML5, ARIA attributes, responsive design
+
+**`/workflow:design:design-update`** - Integrate design system
+```bash
+# Update brainstorming artifacts with design system
+/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+```
+- **Updates**: `synthesis-specification.md`, `ui-designer/style-guide.md`
+- **Makes design tokens available for task generation**
+
+#### Preview System
+
+After running `ui-generate`, you get interactive preview tools:
+
+**Quick Preview** (Direct Browser):
+```bash
+# Navigate to prototypes directory
+cd .workflow/WFS-auth/.design/prototypes
+# Open index.html in browser (double-click or):
+open index.html  # macOS
+start index.html  # Windows
+xdg-open index.html  # Linux
+```
+
+**Full Preview** (Local Server - Recommended):
+```bash
+cd .workflow/WFS-auth/.design/prototypes
+# Choose one:
+python -m http.server 8080      # Python
+npx http-server -p 8080         # Node.js
+php -S localhost:8080           # PHP
+# Visit: http://localhost:8080
+```
+
+**Preview Features**:
+- `index.html`: Master navigation with all prototypes
+- `compare.html`: Side-by-side comparison with viewport controls (Desktop/Tablet/Mobile)
+- Synchronized scrolling for layout comparison
+- Dynamic page switching
+- Real-time responsive testing
+
+---
+
 ### **Task & Memory Commands**

 | Command | Description |
--- a/README_CN.md
+++ b/README_CN.md
@@ -260,6 +260,13 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 /workflow:design:style-extract --session WFS-auth --images "refs/*.png"
 /workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
 /workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
+
+# 预览生成的原型（新功能！）
+# 选项1：在浏览器中打开 .workflow/WFS-auth/.design/prototypes/index.html
+# 选项2：启动本地服务器
+cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
+# 访问 http://localhost:8080 获取交互式预览和对比工具
+
 /workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
 ```

@@ -370,6 +377,87 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 | `/workflow:tools:test-concept-enhanced` | 使用 Gemini 生成测试策略和需求分析。 |
 | `/workflow:tools:test-task-generate` | 生成测试任务 JSON，包含 test-fix-cycle 规范。 |

+### **UI 设计工作流命令 (`/workflow:design:*`)** *(v3.5.0+)*
+
+设计工作流系统提供从风格提取到原型生成的完整 UI 设计精炼，配备交互式预览工具。
+
+#### 核心命令
+
+**`/workflow:design:auto`** - 完整工作流编排器
+```bash
+# 带用户检查点的半自主工作流
+/workflow:design:auto --session WFS-auth --images "refs/*.png" --pages "login,register"
+/workflow:design:auto --session WFS-dash --images "refs/*.jpg" --pages "dashboard" --variants 3 --batch-plan
+```
+- **检查点**: 用户选择风格变体（阶段1）和确认原型（阶段3）
+- **可选**: `--batch-plan` 用于自动任务生成
+
+**`/workflow:design:style-extract`** - 三重视觉风格分析
+```bash
+# 从参考图像提取设计
+/workflow:design:style-extract --session WFS-auth --images "design-refs/*.png"
+```
+- **视觉来源**: Claude Code + Gemini + Codex
+- **输出**: 用于用户选择的风格变体卡片
+
+**`/workflow:design:style-consolidate`** - 验证和合并令牌
+```bash
+# 整合选定的风格变体
+/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+```
+- **功能**: WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
+- **输出**: `design-tokens.json`、`style-guide.md`、`tailwind.config.js`
+
+**`/workflow:design:ui-generate`** - 生成 HTML/CSS 原型
+```bash
+# 生成带预览工具的原型
+/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
+/workflow:design:ui-generate --session WFS-auth --pages "dashboard" --style-overrides "custom.json"
+```
+- **🆕 预览文件**: `index.html`（导航）、`compare.html`（并排对比）、`PREVIEW.md`（说明）
+- **功能**: 令牌驱动的 CSS、语义化 HTML5、ARIA 属性、响应式设计
+
+**`/workflow:design:design-update`** - 集成设计系统
+```bash
+# 使用设计系统更新头脑风暴产物
+/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+```
+- **更新**: `synthesis-specification.md`、`ui-designer/style-guide.md`
+- **使设计令牌可用于任务生成**
+
+#### 预览系统
+
+运行 `ui-generate` 后，您将获得交互式预览工具：
+
+**快速预览**（直接浏览器）:
+```bash
+# 导航到原型目录
+cd .workflow/WFS-auth/.design/prototypes
+# 在浏览器中打开 index.html（双击或执行）:
+open index.html  # macOS
+start index.html  # Windows
+xdg-open index.html  # Linux
+```
+
+**完整预览**（本地服务器 - 推荐）:
+```bash
+cd .workflow/WFS-auth/.design/prototypes
+# 选择一个:
+python -m http.server 8080      # Python
+npx http-server -p 8080         # Node.js
+php -S localhost:8080           # PHP
+# 访问: http://localhost:8080
+```
+
+**预览功能**:
+- `index.html`: 包含所有原型的主导航
+- `compare.html`: 带视口控制的并排对比（桌面/平板/移动）
+- 同步滚动用于布局对比
+- 动态页面切换
+- 实时响应式测试
+
+---
+
 ### **任务与内存命令**

 | 命令 | 描述 |