diff --git a/.claude/commands/workflow/design/ui-generate.md b/.claude/commands/workflow/design/ui-generate.md index f99d792e..02fba33a 100644 --- 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 + + + + + + UI Prototypes Preview - WFS-{session} + + + +

🎨 UI Prototypes Preview

+

Session: WFS-{session} | Generated: {timestamp}

+ +
+ 📊 Compare All Variants + 📖 Preview Instructions +
+ +
+ +
+

Dashboard - Variant 1

+
Generated: {timestamp}
+ View Prototype → + Implementation Notes +
+
+ + +``` + +### Comparison View Template (compare.html) +```html + + + + + + Side-by-Side Comparison - WFS-{session} + + + +
+

📊 Side-by-Side Comparison

+
+
+ + + +
+ + + ← Back to Index +
+
+ +
+
+
Variant 1
+ +
+
+
Variant 2
+ +
+
+ + + + +``` + +### 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 `` 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" ``` diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d606f50..b747231e 100644 --- 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 --images ""` +- **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 --variants ""` +- **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 --pages "" [--variants ] [--style-overrides ""]` +- **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 [--selected-prototypes ""]` +- **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 --images "" --pages "" [--variants ] [--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**: diff --git a/README.md b/README.md index 56392e41..43da8637 100644 --- 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 | diff --git a/README_CN.md b/README_CN.md index dc5a629a..02b91931 100644 --- 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`: 带视口控制的并排对比（桌面/平板/移动） +- 同步滚动用于布局对比 +- 动态页面切换 +- 实时响应式测试 + +--- + ### **任务与内存命令** | 命令 | 描述 |