diff --git a/src/modules/wds/docs/wds-workflows-guide.md b/src/modules/wds/README.md similarity index 95% rename from src/modules/wds/docs/wds-workflows-guide.md rename to src/modules/wds/README.md index a9ea141f..e73055e7 100644 --- a/src/modules/wds/docs/wds-workflows-guide.md +++ b/src/modules/wds/README.md @@ -48,8 +48,8 @@ WDS creates an alphabetized folder structure in the user's `docs/` folder: 1. **Product Exploration** → `A-Product-Brief/` 2. **User Research** → `B-Trigger-Map/` 3. **Requirements** → `D-PRD/` -4. **Conceptual Design** → `C-Scenarios/` -5. **Component Design** → `D-Design-System/` +4. **Conceptual Design** → `C-Scenarios/` (with optional Figma visual refinement) +5. **Component Design** → `D-Design-System/` (grows organically via Figma integration) 6. **Dev Integration** → `E-UI-Roadmap/` ## Agents - The Norse Pantheon 🏔️ diff --git a/src/modules/wds/agents/freya-ux.agent.yaml b/src/modules/wds/agents/freya-ux.agent.yaml index 27c2d70a..339cbb8e 100644 --- a/src/modules/wds/agents/freya-ux.agent.yaml +++ b/src/modules/wds/agents/freya-ux.agent.yaml @@ -47,7 +47,7 @@ agent: - Specification Quality → data/agent-guides/freya/specification-quality.md (creating specs, logical explanations) - Interactive Prototyping → data/agent-guides/freya/interactive-prototyping.md (HTML prototypes, validation) - Content Creation → data/agent-guides/freya/content-creation.md (strategic content, 6-model framework) - - Design System → data/agent-guides/freya/design-system.md (Phase 5, organic growth) + - Design System → data/agent-guides/freya/design-system.md (Phase 5, organic growth, Figma integration) **Workflow Management:** - On activation: Check conversations (conversation-persistence/check-conversations.md) @@ -66,6 +66,7 @@ agent: - Prototypes validate before production (micro-guide: interactive-prototyping.md) - Content is strategic, not decorative (micro-guide: content-creation.md) - Design systems grow organically (micro-guide: design-system.md if Phase 5) + - Visual refinement via Figma when design system incomplete (automated MCP integration) **Project Tracking:** - Update project outline when completing work diff --git a/src/modules/wds/docs/README.md b/src/modules/wds/docs/docs-guide.md similarity index 100% rename from src/modules/wds/docs/README.md rename to src/modules/wds/docs/docs-guide.md diff --git a/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/agent-log-2026-01-08-html-to-design.md b/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/agent-log-2026-01-08-html-to-design.md new file mode 100644 index 00000000..518bdc5a --- /dev/null +++ b/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/agent-log-2026-01-08-html-to-design.md @@ -0,0 +1,124 @@ +# Agent Log: WDS HTML to Design Tools & Implementation + +**Session Date**: 2026-01-08 +**Agent**: Cascade +**Focus**: HTML to Design workflow tools and implementation +**Project**: WDS v6 Conversion - BMAD-METHOD-WDS-ALPHA + +## Session Overview +This session focused on documenting the HTML to Design work in WDS v6, specifically the tools (MagicPatterns, NanoBanana, html.to.design) and the implementation of interactive prototype components. + +## Key Topics Discussed + +### 1. Tools Exploration +- **MagicPatterns**: UI pattern generation for design systems +- **NanoBanana**: Design-to-code conversion tool +- **html.to.design**: HTML to design file conversion (primary focus) + +### 2. HTML to Design Implementation +- **Dev Mode Component**: Interactive JavaScript tool for prototype interaction +- **Area Tag System**: HTML `` tags for precise region mapping +- **Work File Template**: Comprehensive YAML template for implementation planning + +### 3. Technical Architecture +- Component-based approach with isolated JavaScript +- Event-driven architecture for user interactions +- Bidirectional workflow between design and implementation + +## Files Created/Modified + +### Created Files +1. `html-to-design-tools-summary.md` - Comprehensive tools and work summary +2. `html-to-design-work-summary.md` - Original work summary (created earlier) + +### Key Implementation Files +1. `dev-mode.js` - Interactive prototype dev mode component +2. `work-file-template.yaml` - Implementation planning template +3. Various YAML template files (fixed for lint compliance) + +## Technical Decisions Made + +### Area Tag Integration +- Added HTML `` tag system for precise region mapping +- Integration with dev-mode.js for interactive region selection +- Enables exact coordinate mapping for design-to-code translation + +### Workflow Enhancement +- Updated design to implementation path to include area mapping +- Dev mode extracts both Object IDs and area coordinates +- Documentation includes region mappings for precise specs + +### Tool Strategy +- No single tool solves all problems +- Combination approach for comprehensive solution +- Integration points crucial for seamless workflow + +## Key Insights + +### 1. Bidirectional Workflow Value +- Traditional unidirectional design-to-code flow is limiting +- WDS benefits from code-to-design feedback loops +- Interactive prototypes serve as living specifications + +### 2. Area Tag System Benefits +- Enables precise click mapping on complex UI elements +- Supports image-based prototypes with interactive hotspots +- Facilitates design-to-code translation with exact coordinates + +### 3. Tool Ecosystem Understanding +- MagicPatterns for pattern library generation +- NanoBanana for automated code generation +- html.to.design for reverse engineering design from implementation + +## Implementation Status + +### Completed +- Dev-mode.js component with full functionality +- Work-file-template.yaml with comprehensive structure +- Area tag system documentation and integration +- Basic integration with WDS workflow + +### In Progress +- Tool integration testing +- Workflow documentation +- Performance optimization + +### Planned +- MagicPatterns integration +- NanoBanana exploration +- html.to.design implementation + +## Next Steps for Future Sessions + +### 1. Tool Integration +- Implement MagicPatterns for design system automation +- Explore NanoBanana for rapid prototyping +- Integrate html.to.design for design recovery + +### 2. Workflow Enhancement +- Build automated extraction tools +- Implement version control for design-implementation changes +- Enable real-time collaboration features + +### 3. Technical Improvements +- Optimize dev-mode performance for large prototypes +- Enhance accessibility for all users +- Create plugin architecture for custom tools + +## User Feedback +- User specifically requested to remember the area tag system +- Emphasized importance of tools discussion over error fixing +- Wanted comprehensive summary for continuation in new chat + +## Session Outcome +Successfully documented the HTML to Design tools and implementation work, with special focus on the area tag system and tool ecosystem. Created comprehensive summary files for future reference and continuation of the work. + +## Files for Reference +- `html-to-design-tools-summary.md` - Main summary document +- `dev-mode.js` - Core implementation component +- `work-file-template.yaml` - Planning template +- Various YAML template files in WDS module + +--- +**Session End**: 2026-01-08 15:30 UTC +**Status**: Complete - Ready for continuation in new chat diff --git a/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/html-to-design-tools-summary.md b/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/html-to-design-tools-summary.md new file mode 100644 index 00000000..2663115a --- /dev/null +++ b/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/html-to-design-tools-summary.md @@ -0,0 +1,148 @@ +# WDS HTML to Design Tools & Work Summary + +## Overview +This document summarizes the conversation about tools (MagicPatterns, NanoBanana, html.to.design) and the HTML to Design work in the WDS v6 conversion. + +## Tools Discussed + +### 1. MagicPatterns +- **Purpose**: UI pattern generation and design system tools +- **Context**: Discussed as potential tool for WDS design system integration +- **Status**: Explored for possible integration with WDS component library + +### 2. NanoBanana +- **Purpose**: Design-to-code conversion tool +- **Context**: Mentioned in relation to automated design implementation +- **Status**: Considered for potential workflow integration + +### 3. html.to.design +- **Purpose**: Convert HTML/CSS to design files (Figma, etc.) +- **Context**: Key tool discussed for bridging development to design workflow +- **Status**: Primary focus for WDS integration discussions + +## HTML to Design Work + +### Core Concept +The HTML to Design workflow focuses on: +- Converting implemented prototypes back to design specifications +- Creating bidirectional workflow between design and development +- Supporting WDS methodology's iterative approach + +### Key Components Built + +#### 1. Dev Mode JavaScript Component +- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js` +- **Purpose**: Interactive tool for extracting Object IDs from live prototypes +- **Features**: + - Toggle dev mode with button or Ctrl+E + - Hold Shift + Click to copy Object IDs + - Visual highlights (green when Shift held) + - Tooltip display on hover + - Success feedback when copied + - Form field protection (Shift disabled when typing) + +#### 2. Work File Template +- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/work-file-template.yaml` +- **Purpose**: Complete planning document for section-by-section implementation +- **Structure**: + - Metadata and device compatibility + - Design tokens (Tailwind config) + - Page requirements and demo data + - Object ID mapping + - Section breakdown with acceptance criteria + - JavaScript requirements + - Testing checklist + +#### 3. Area Tag Mapping System +- **Purpose**: HTML `` tags for precise region mapping in prototypes +- **Integration**: Works with dev-mode.js for interactive region selection +- **Benefits**: + - Enables precise click mapping on complex UI elements + - Supports image-based prototypes with interactive hotspots + - Facilitates design-to-code translation with exact coordinates + +### Workflow Integration + +#### Design to Implementation Path +1. **Design Phase**: Create specifications in WDS +2. **Implementation**: Build interactive prototypes with area tag mapping +3. **Dev Mode**: Use dev-mode.js to extract Object IDs and area coordinates +4. **Documentation**: Update specs with implementation details and region mappings +5. **Iteration**: Feed back into design process + +#### Tool Integration Points +- **MagicPatterns**: For pattern library generation +- **NanoBanana**: For automated code generation +- **html.to.design**: For reverse engineering design from implementation + +## Technical Architecture + +### Component-Based Approach +- Isolated JavaScript components for maintainability +- Event-driven architecture for user interactions +- Visual feedback systems for better UX +- **Area Tag System**: HTML `` tags for mapping interactive regions in prototypes + +### Template System +- YAML-based configuration files +- Jinja-like templating for dynamic content +- Comprehensive checklists for quality assurance + +### Browser Compatibility +- Cross-environment support with `globalThis` +- Feature detection for modern APIs +- Fallback methods for older browsers + +## Key Insights + +### 1. Bidirectional Workflow +- Traditional design-to-code flow is unidirectional +- WDS benefits from code-to-design feedback loop +- Dev mode enables continuous specification updates + +### 2. Tool Ecosystem +- No single tool solves all problems +- Combination of tools provides comprehensive solution +- Integration points are crucial for seamless workflow + +### 3. Interactive Prototypes +- Living specifications vs static documents +- Real-time feedback improves design decisions +- Object ID system bridges design and implementation + +## Future Directions + +### Tool Integration Strategy +1. **MagicPatterns**: Integrate for design system automation +2. **NanoBanana**: Explore for rapid prototyping +3. **html.to.design**: Implement for design recovery + +### Workflow Enhancement +1. **Automated Extraction**: Build tools for automatic spec generation +2. **Version Control**: Track changes between design and implementation +3. **Collaboration**: Enable real-time updates between designers and developers + +### Technical Improvements +1. **Performance**: Optimize dev-mode for large prototypes +2. **Accessibility**: Ensure tools work for all users +3. **Extensibility**: Plugin architecture for custom tools + +## Implementation Status + +### Completed +- Dev-mode.js component with full functionality +- Work-file-template.yaml with comprehensive structure +- Basic integration with WDS workflow + +### In Progress +- Tool integration testing +- Workflow documentation +- Performance optimization + +### Planned +- MagicPatterns integration +- NanoBanana exploration +- html.to.design implementation + +## Conclusion +The HTML to Design work represents a significant shift in how WDS approaches the design-implementation relationship. By focusing on bidirectional workflows and interactive tools, WDS enables more iterative and collaborative development processes. The combination of custom components (dev-mode.js) and external tools (MagicPatterns, NanoBanana, html.to.design) creates a comprehensive ecosystem for modern design and development workflows. diff --git a/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/html-to-design-work-summary.md b/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/html-to-design-work-summary.md new file mode 100644 index 00000000..d63d4a14 --- /dev/null +++ b/src/modules/wds/docs/examples/wds-v6-conversion/session-logs/html-to-design-work-summary.md @@ -0,0 +1,143 @@ +# WDS HTML to Design Work Summary + +## Overview +This document summarizes the work done on the HTML to Design side of the WDS v6 conversion, including tools tested and approaches explored. + +## Key Work Areas + +### 1. Lint Error Resolution +- **Files Fixed**: `installer.js`, `dev-mode.js`, `work-file-template.yaml`, `workflow.yaml`, `project-config.template.yaml`, `project-outline.template.yaml` +- **Main Issues Addressed**: + - JavaScript `no-undef` errors for browser globals (`document`, `window`, `navigator`) + - YAML parsing errors ("Empty mapping values are forbidden", "Unexpected scalar token") + - ESLint rule compliance (`unicorn/prefer-module`, `no-unused-vars`, etc.) + +### 2. Dev Mode JavaScript Component +- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js` +- **Purpose**: Developer/feedback mode for copying Object IDs in prototypes +- **Features Implemented**: + - Toggle dev mode with button or Ctrl+E + - Hold Shift + Click to copy Object IDs + - Visual highlights (green when Shift held) + - Tooltip display on hover + - Success feedback when copied + - Form field protection (Shift disabled when typing) + +### 3. Work File Template +- **Location**: `src/modules/wds/workflows/4-ux-design/interactive-prototypes/templates/work-file-template.yaml` +- **Purpose**: Complete planning document for section-by-section implementation +- **Structure**: + - Metadata and device compatibility + - Design tokens (Tailwind config) + - Page requirements and demo data + - Object ID mapping + - Section breakdown with acceptance criteria + - JavaScript requirements + - Testing checklist + +### 4. YAML Template Fixes +- **project-config.template.yaml**: Fixed template variable quoting +- **project-outline.template.yaml**: Fixed multi-line string formatting +- **workflow.yaml**: Resolved empty document error +- **wds-workflow-status-template.yaml**: Fixed boolean/array value quoting + +## Tools and Approaches Tested + +### 1. ESLint Configuration +- Tested browser environment detection +- Global variable declarations (`/* global document, globalThis */`) +- Environment checks (`typeof globalThis !== 'undefined'`) +- Module export patterns for browser compatibility + +### 2. YAML Linting +- Template variable quoting strategies +- Multi-line string formatting +- Empty document handling +- List syntax validation + +### 3. Interactive Prototype Architecture +- Component-based approach +- Event handling patterns +- Clipboard API integration with fallbacks +- Visual feedback systems +- Mobile-first responsive design + +## Technical Decisions + +### 1. Browser Compatibility +- Used `globalThis` for cross-environment compatibility +- Added fallback methods for clipboard operations +- Implemented feature detection for APIs + +### 2. Code Style +- Followed ESLint unicorn rules +- Used modern JavaScript patterns +- Maintained consistent formatting +- Added comprehensive comments + +### 3. Template Structure +- Used YAML for configuration files +- Implemented Jinja-like templating +- Created reusable component patterns +- Established clear naming conventions + +## Files Modified + +### JavaScript Files +1. `installer.js` - Removed unused parameter +2. `dev-mode.js` - Major refactoring for lint compliance + +### YAML Files +1. `work-file-template.yaml` - Fixed list syntax +2. `workflow.yaml` - Fixed empty document issue +3. `project-config.template.yaml` - Quoted template variables +4. `project-outline.template.yaml` - Fixed multi-line strings +5. `wds-workflow-status-template.yaml` - Quoted boolean/array values + +## Key Learnings + +### 1. Linting in Mixed Environments +- Browser JavaScript needs special handling in Node-based linters +- Template variables in YAML require careful quoting +- Empty documents in YAML can be tricky + +### 2. Interactive Prototype Development +- Component isolation is crucial for maintainability +- Event handling needs careful state management +- Visual feedback improves user experience significantly + +### 3. Template Design +- Clear structure helps with implementation +- Comprehensive checklists ensure quality +- Flexibility in configuration is important + +## Next Steps (for continuation) + +### 1. Complete Testing +- Run full lint suite to verify all fixes +- Test dev-mode functionality in browser +- Validate YAML template rendering + +### 2. Documentation +- Add inline code documentation +- Create usage examples +- Document template variables + +### 3. Integration +- Test with full WDS workflow +- Verify agent compatibility +- Check BMAD integration points + +## Technical Debt +- Some ESLint rules disabled with specific comments +- YAML templates could benefit from schema validation +- Dev-mode component could use more testing + +## Tools Mastered +- ESLint with browser globals +- YAML linting with templates +- JavaScript clipboard API +- Tailwind CSS integration +- Component-based architecture + +This summary provides a foundation for continuing the HTML to Design work in a new chat session, with clear understanding of what's been accomplished and what remains to be done. diff --git a/src/modules/wds/docs/method/phase-4-ux-design-guide.md b/src/modules/wds/docs/method/phase-4-ux-design-guide.md index b66d95de..690e66b1 100644 --- a/src/modules/wds/docs/method/phase-4-ux-design-guide.md +++ b/src/modules/wds/docs/method/phase-4-ux-design-guide.md @@ -94,6 +94,21 @@ Freya helps you: - Refine specifications - Visualize the concept before development +**Visual Refinement (Optional):** + +If the prototype looks functional but not visually appealing (design system incomplete): + +- Freya automatically identifies components needing refinement +- Injects components to Figma via MCP server for visual polish +- Designer refines in Figma (colors, spacing, typography, states) +- Freya reads refined components back automatically +- Updates design system with new tokens and components +- Re-renders prototype with enhanced design system + +This iterative refinement enables you to build the design system organically as you create prototypes, rather than requiring a complete design system upfront. + +See: [Figma Integration](../../workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md) + ### 4E: PRD Update **When:** Page design is complete, before moving to the next scenario diff --git a/src/modules/wds/docs/method/phase-5-design-system-guide.md b/src/modules/wds/docs/method/phase-5-design-system-guide.md index 5d3caf43..4958d150 100644 --- a/src/modules/wds/docs/method/phase-5-design-system-guide.md +++ b/src/modules/wds/docs/method/phase-5-design-system-guide.md @@ -17,6 +17,16 @@ Design System builds your component library following atomic design principles. Your Design System includes: +- **Visual Design (01-Visual-Design/)** - Early design exploration before scenarios + - Mood boards and style direction + - NanoBanana design concepts + - Color and typography exploration + - Visual inspiration and references +- **Assets (02-Assets/)** - Final production assets + - Logos and brand elements + - Icon sets + - Photography and illustrations + - Custom graphics - **Design Tokens** - Colors, typography, spacing, shadows - **Atomic Components** - Buttons, inputs, labels, icons - **Molecular Components** - Form groups, cards, list items @@ -97,6 +107,114 @@ Notice pattern across pages → Extract as reusable component 4. Next page references the system component 5. Repeat +### Visual Design Exploration (01-Visual-Design/) + +**Early Design Phase - Before Scenarios:** + +Before diving into scenario-specific design, establish your visual direction: + +**Mood Boards:** +- Collect visual inspiration +- Define style direction (modern, playful, professional, etc.) +- Establish visual tone and personality +- Reference examples from similar products + +**Design Concepts (NanoBanana):** +- Generate design variations using NanoBanana +- Explore different visual approaches +- Create custom graphics and illustrations +- Generate placeholder assets for prototypes + +**Color Exploration:** +- Test color palette options +- Define primary, secondary, and semantic colors +- Ensure accessibility (contrast ratios) +- Document color psychology and usage + +**Typography Tests:** +- Experiment with font pairings +- Define hierarchy (headings, body, labels) +- Test readability at different sizes +- Document font usage guidelines + +**When to Use:** +- At project start (before Phase 4 scenarios) +- When establishing brand identity +- When exploring multiple visual directions +- Before committing to design tokens + +**Output Location:** `D-Design-System/01-Visual-Design/` + +--- + +### Production Assets (02-Assets/) + +**Later in Design Process - As Design Solidifies:** + +Once your visual direction is established and scenarios are designed: + +**Logos:** +- Final logo files (SVG, PNG) +- Logo variations (light/dark, horizontal/vertical) +- Brand mark and wordmark +- Usage guidelines + +**Icons:** +- Icon sets for UI elements +- Custom icons for product features +- Consistent style and sizing +- Multiple formats (SVG, PNG) + +**Images:** +- Photography for product pages +- Illustrations for empty states +- Hero images and backgrounds +- Optimized for web + +**Graphics:** +- Custom graphics and elements +- Decorative elements +- Patterns and textures +- Exported from NanoBanana or Figma + +**When to Add:** +- After visual direction is established +- When design is near completion +- Before development handoff +- As final assets are created + +**Output Location:** `D-Design-System/02-Assets/` + +--- + +### Figma Integration (Optional) + +**Automated Visual Refinement:** + +WDS supports automated Figma integration via MCP server for visual design refinement: + +**Workflow:** +1. Create functional prototype in Phase 4D +2. Freya identifies components needing visual polish +3. Freya injects components to Figma automatically (via MCP server) +4. Designer refines visual design in Figma +5. Freya reads refined components back automatically +6. Design system updated with new tokens/components +7. Prototype re-rendered with polished design + +**Benefits:** +- Build design system organically (no upfront investment) +- Component-level precision (not full-page extraction) +- Automated Object ID traceability +- Bidirectional sync (Prototype ↔ Figma ↔ Design System) + +**Tools:** +- **Figma MCP** (recommended): Automated integration via MCP server +- **Figma**: Visual design tool for refinement +- See: [Figma Integration Guide](../../workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md) + +--- + ### Component Extraction As you specify scenarios in Phase 4, components naturally emerge: diff --git a/src/modules/wds/docs/tools/cursor-windsurf.md b/src/modules/wds/docs/tools/cursor-windsurf.md new file mode 100644 index 00000000..e19860e0 --- /dev/null +++ b/src/modules/wds/docs/tools/cursor-windsurf.md @@ -0,0 +1,190 @@ +# Cursor/Windsurf IDE + +**Category:** Development Environment +**Purpose:** AI-powered IDE for WDS agent workflows +**Website:** / + +--- + +## What It Is + +Cursor and Windsurf are AI-powered IDEs built on VS Code that enable natural language interaction with WDS agents (Freya, Saga, Idunn). They provide the environment where agents can read, write, and modify code while maintaining full context of your project. + +--- + +## Why WDS Recommends It + +**AI Agent Integration:** +- Native support for AI agents like Freya, Saga, Idunn +- Agents can read/write files, run commands, analyze code +- Context-aware suggestions and automation + +**WDS Workflow Support:** +- File structure navigation for WDS projects +- Terminal integration for workflow commands +- Multi-file editing for specifications and prototypes +- Git integration for version control + +**Developer Experience:** +- VS Code compatibility (extensions, themes, settings) +- Fast performance +- Intelligent code completion +- Built-in terminal + +--- + +## Setup Instructions + +### 1. Installation + +**Cursor:** +```bash +# Download from https://cursor.sh +# Install for your OS (Windows, macOS, Linux) +``` + +**Windsurf:** +```bash +# Download from https://codeium.com/windsurf +# Install for your OS (Windows, macOS, Linux) +``` + +### 2. Initial Configuration + +Open Settings (Ctrl+, or Cmd+,): + +```json +{ + "editor.formatOnSave": true, + "editor.defaultFormatter": "esbenp.prettier-vscode", + "files.autoSave": "onFocusChange", + "terminal.integrated.defaultProfile.windows": "PowerShell", + "terminal.integrated.defaultProfile.osx": "zsh" +} +``` + +### 3. Recommended Extensions + +Install these extensions for WDS workflows: + +- **Prettier** - Code formatting +- **ESLint** - JavaScript linting +- **Markdown All in One** - Markdown editing +- **YAML** - YAML file support +- **Live Server** - Preview HTML prototypes +- **GitLens** - Enhanced Git integration + +### 4. WDS-Specific Setup + +Create workspace settings for WDS projects: + +`.vscode/settings.json`: +```json +{ + "files.associations": { + "*.agent.yaml": "yaml", + "*.workflow.yaml": "yaml" + }, + "search.exclude": { + "**/node_modules": true, + "**/dist": true, + "**/.git": true + }, + "files.watcherExclude": { + "**/node_modules/**": true + } +} +``` + +--- + +## WDS Best Practices + +### DO ✅ + +**1. Use Agent Chat Effectively** +- Be specific with requests to Freya, Saga, or Idunn +- Reference files using @ mentions +- Provide context about what you're trying to achieve + +**2. Organize Workspace** +- Open WDS project at root level +- Use workspace folders for multi-repo projects +- Keep terminal open for workflow commands + +**3. Leverage AI Features** +- Use Ctrl+K for inline AI edits +- Use chat for complex refactoring +- Let agents handle repetitive tasks + +**4. File Navigation** +- Use Ctrl+P for quick file open +- Use breadcrumbs for navigation +- Bookmark frequently used files + +### DON'T ❌ + +**1. Don't Fight the AI** +- If agent suggests changes, review before rejecting +- Provide feedback to improve suggestions +- Trust agents for WDS-specific patterns + +**2. Don't Skip Git Integration** +- Commit frequently +- Use descriptive commit messages +- Review changes before committing + +**3. Don't Ignore Workspace Settings** +- Configure for your project structure +- Use consistent formatting +- Set up proper file associations + +--- + +## Keyboard Shortcuts + +**Essential for WDS:** + +| Action | Windows/Linux | macOS | +|--------|---------------|-------| +| Command Palette | Ctrl+Shift+P | Cmd+Shift+P | +| Quick Open | Ctrl+P | Cmd+P | +| AI Chat | Ctrl+L | Cmd+L | +| Inline AI Edit | Ctrl+K | Cmd+K | +| Terminal | Ctrl+` | Cmd+` | +| Find in Files | Ctrl+Shift+F | Cmd+Shift+F | +| Git Panel | Ctrl+Shift+G | Cmd+Shift+G | + +--- + +## Troubleshooting + +### Issue: Agent can't read files + +**Solution:** +- Ensure files are in workspace +- Check file permissions +- Reload window (Ctrl+Shift+P → "Reload Window") + +### Issue: Slow performance + +**Solution:** +- Exclude large folders from search +- Disable unused extensions +- Increase memory limit in settings + +--- + +## Resources + +**Cursor:** +- Website: +- Documentation: Check website + +**Windsurf:** +- Website: +- Documentation: Check website + +--- + +[← Back to Tools](wds-tools-guide.md) diff --git a/src/modules/wds/docs/tools/figma-mcp.md b/src/modules/wds/docs/tools/figma-mcp.md new file mode 100644 index 00000000..10e26257 --- /dev/null +++ b/src/modules/wds/docs/tools/figma-mcp.md @@ -0,0 +1,325 @@ +# Figma MCP + +**Category:** Integration Tool +**Purpose:** MCP server for automated Figma integration with WDS +**Repository:** WDS Figma MCP Server + +--- + +## What It Is + +Figma MCP (Model Context Protocol) is a server that enables automated, bidirectional communication between WDS agents (Freya) and Figma. It allows precise component-level injection from HTML prototypes into Figma and automated reading of refined components back into the design system. + +--- + +## Why WDS Recommends It + +**Automation:** +- Freya automatically injects components to Figma +- No manual upload or conversion needed +- Automated design token extraction +- Bidirectional sync (Prototype ↔ Figma ↔ Design System) + +**Precision:** +- Component-level injection (not full pages) +- Object ID preservation automatic +- Target specific Figma pages +- Batch component operations + +**Integration:** +- Seamless WDS workflow integration +- Page naming matches specification structure +- Automated design system updates +- Version control friendly + +--- + +## Setup Instructions + +### 1. Installation + +```bash +# Install Figma MCP server +npm install -g @wds/figma-mcp-server +``` + +### 2. Figma API Access + +Get your Figma personal access token: + +1. Go to Figma Settings → Account +2. Scroll to "Personal access tokens" +3. Click "Generate new token" +4. Name it "WDS MCP Server" +5. Copy the token + +### 3. Configuration + +Set up environment variables: + +```bash +# Set Figma access token +export FIGMA_ACCESS_TOKEN="your-token-here" + +# Or create .env file +echo "FIGMA_ACCESS_TOKEN=your-token-here" > .env +``` + +Create MCP configuration file: + +`.wds/figma-mcp-config.yaml`: +```yaml +figma: + access_token: ${FIGMA_ACCESS_TOKEN} + default_file_id: "your-figma-file-id" + default_page: "WDS Components" + +extraction: + preserve_object_ids: true + extract_design_tokens: true + convert_to_components: true + maintain_hierarchy: true + +injection: + auto_layout: true + responsive_constraints: true + component_naming: "object-id" + page_naming: "scenario-page" + +sync: + bidirectional: true + auto_update_design_system: false + conflict_resolution: "manual" + +naming_conventions: + page_format: "{scenario-number}-{scenario-name} / {page-number}-{page-name}" + example: "01-Customer-Onboarding / 1.2-Sign-In" + source: "docs/C-Scenarios/" +``` + +### 4. Initialize MCP Server + +```bash +# Initialize for your project +wds figma init + +# Test connection +wds figma test-connection +``` + +### 5. Get Figma File ID + +From your Figma file URL: +``` +https://figma.com/file/ABC123DEF456/Project-Name + ^^^^^^^^^^^^ + This is your file ID +``` + +--- + +## Freya's Automated Workflow + +### Phase 1: Injection (Automated by Freya) + +``` +User: "Prototype needs refinement" + ↓ +Freya analyzes prototype components + ↓ +Freya identifies components needing refinement + ↓ +Freya presents options to user + ↓ +User: "Yes, inject to Figma" + ↓ +Freya automatically: + - Determines target Figma file from config + - Creates/navigates to matching page + - Injects selected components via MCP + - Preserves Object IDs in layer names + - Provides Figma link to user +``` + +### Phase 2: Reading Back (Automated by Freya) + +``` +User: "Finished refining in Figma" + ↓ +Freya automatically: + - Connects to Figma via MCP + - Reads refined components + - Extracts design tokens + - Identifies variants and states + - Presents changes to user + ↓ +User: "Update design system" + ↓ +Freya automatically: + - Updates design system files + - Creates/updates component docs + - Updates design tokens + - Offers to re-render prototype +``` + +--- + +## WDS Best Practices + +### DO ✅ + +**1. Use Freya Automation** +- Let Freya handle injection automatically +- Freya analyzes components and determines what to inject +- Freya reads refined components back +- No manual commands needed + +**2. Maintain Object ID Traceability** +- All components have Object IDs in HTML +- MCP preserves Object IDs in Figma layer names +- Enables tracking from spec → prototype → Figma → design system + +**3. Follow Page Naming Convention** +- Pages match WDS specification structure +- Format: `[Scenario-Number]-[Scenario-Name] / [Page-Number]-[Page-Name]` +- Example: `01-Customer-Onboarding / 1.2-Sign-In` + +**4. Batch Related Components** +- Inject related components together +- Maintains context for designer +- Efficient workflow + +### DON'T ❌ + +**1. Don't Inject Entire Pages** +- Use component-level precision +- Inject only what needs refinement +- Avoid unnecessary extraction + +**2. Don't Skip Object IDs** +- Always include Object IDs in HTML +- Required for traceability +- Enables automated mapping + +**3. Don't Manually Upload** +- Use MCP server, not manual upload +- Automation is more reliable +- Maintains consistency + +--- + +## Troubleshooting + +### Issue: MCP server can't connect to Figma + +**Solution:** +```bash +# Verify access token +echo $FIGMA_ACCESS_TOKEN + +# Test connection +wds figma test-connection + +# Check Figma file permissions +# Ensure token has access to file +``` + +### Issue: Components not injecting + +**Solution:** +- Verify Object IDs exist in HTML +- Check Figma file ID in config +- Ensure page name is correct +- Check MCP server logs + +### Issue: Design tokens not extracting + +**Solution:** +- Ensure Figma uses variables (not hardcoded values) +- Check extraction settings in config +- Verify component has proper styling +- Review MCP server logs + +### Issue: Object IDs not preserved + +**Solution:** +- Check `preserve_object_ids: true` in config +- Verify Object IDs in HTML data attributes +- Ensure MCP server version is up to date + +--- + +## Security Best Practices + +### DO ✅ + +**1. Protect Access Token** +```bash +# Use environment variables +export FIGMA_ACCESS_TOKEN="token" + +# Or .env file (add to .gitignore) +echo "FIGMA_ACCESS_TOKEN=token" > .env +``` + +**2. Add to .gitignore** +```gitignore +.env +.wds/figma-mcp-config.yaml # If contains sensitive data +``` + +**3. Use Separate Tokens** +- Different tokens for dev/production +- Rotate tokens periodically +- Revoke unused tokens + +### DON'T ❌ + +**1. Don't Commit Tokens** +- Never commit access tokens to git +- Don't hardcode in configuration files +- Don't share tokens in documentation + +**2. Don't Use Personal Tokens for Team** +- Create team/project-specific tokens +- Use service accounts when available +- Track token usage + +--- + +## Advantages Over Manual Methods + +**vs. html.to.design:** +- ✅ Component-level precision (not full page) +- ✅ Automated Object ID preservation +- ✅ Bidirectional sync +- ✅ Batch operations +- ✅ Freya integration + +**vs. Manual Figma Creation:** +- ✅ Faster workflow +- ✅ Maintains code-design sync +- ✅ Automated token extraction +- ✅ Consistent structure +- ✅ Reduced manual work + +--- + +## Resources + +**Documentation:** +- MCP Server Integration Guide: `workflows/5-design-system/figma-integration/mcp-server-integration.md` +- Prototype to Figma Workflow: `workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md` + +**Configuration:** +- Example config: `.wds/figma-mcp-config.yaml` +- Environment setup: `.env.example` + +**Support:** +- Figma API Docs: +- Check MCP server logs for errors +- Contact WDS team for integration issues + +--- + +[← Back to Tools](wds-tools-guide.md) diff --git a/src/modules/wds/docs/tools/figma.md b/src/modules/wds/docs/tools/figma.md new file mode 100644 index 00000000..1280480c --- /dev/null +++ b/src/modules/wds/docs/tools/figma.md @@ -0,0 +1,212 @@ +# Figma + +**Category:** Design Tool +**Purpose:** Visual design refinement and design system documentation +**Website:** + +--- + +## What It Is + +Figma is a collaborative design tool used in WDS for visual design refinement when prototypes need polish. It's where designers refine components extracted from HTML prototypes and define design tokens. + +--- + +## Why WDS Recommends It + +**Visual Design Refinement:** +- Polish components extracted from prototypes +- Define design tokens (colors, spacing, typography) +- Create component variants and states +- Document design decisions + +**Collaboration:** +- Real-time collaboration with team +- Share designs with stakeholders +- Comment and feedback system +- Version history + +**WDS Integration:** +- MCP server integration for component injection +- Bidirectional sync with design system +- Page structure mirrors WDS specifications +- Component traceability via Object IDs + +--- + +## Setup Instructions + +### 1. Account Creation + +1. Go to +2. Sign up for free account +3. Install desktop app (recommended) or use web version + +### 2. WDS Project Setup + +Create Figma file structure: + +``` +[Project Name] Design Refinement +├── 01-Customer-Onboarding/ +│ ├── 1.1-Start-Page +│ ├── 1.2-Sign-In +│ └── 1.3-Sign-Up +├── 02-Product-Catalog/ +│ ├── 2.1-Product-List +│ └── 2.2-Product-Detail +└── Components/ + ├── Buttons + ├── Inputs + └── Cards +``` + +### 3. Design Tokens Setup + +Create Figma variables: + +**Colors:** +``` +Collection: Colors +├── primary/50 +├── primary/600 +├── primary/700 +├── neutral/50 +└── neutral/900 +``` + +**Spacing:** +``` +Collection: Spacing +├── xs = 4px +├── sm = 8px +├── md = 16px +└── lg = 24px +``` + +**Typography:** +``` +Styles: Typography +├── Heading/1 +├── Heading/2 +├── Body/Regular +└── Body/Bold +``` + +--- + +## WDS Best Practices + +### DO ✅ + +**1. Match WDS Structure** +- Page names: `[Scenario-Number]-[Scenario-Name] / [Page-Number]-[Page-Name]` +- Example: `01-Customer-Onboarding / 1.2-Sign-In` +- Mirrors `docs/C-Scenarios/` structure + +**2. Preserve Object IDs** +- Include Object IDs in layer names +- Example: Layer name "btn-login-submit" +- Maintains traceability to code + +**3. Use Design Tokens** +- Always use variables for colors +- Use variables for spacing +- Apply text styles consistently +- Don't hardcode values + +**4. Document Decisions** +- Add descriptions to components +- Document when to use each variant +- Note accessibility requirements +- Include usage examples + +### DON'T ❌ + +**1. Don't Diverge from Specs** +- If design changes, update specification +- Keep Figma and specs in sync +- Notify team of design evolution + +**2. Don't Skip Component Documentation** +- Always add WDS component ID +- Document variants and states +- Include usage guidelines + +**3. Don't Hardcode Values** +- Use variables, not hex colors +- Use spacing variables +- Apply text styles + +--- + +## WDS-Specific Workflows + +### Receiving Components from Freya + +1. Freya injects components via MCP server +2. Components appear in designated page +3. Layer names include Object IDs +4. Basic styling applied + +### Refining Components + +1. Apply design tokens (colors, spacing, typography) +2. Create component variants (primary, secondary, etc.) +3. Define states (default, hover, active, disabled) +4. Add visual polish (shadows, borders, effects) +5. Document in component description + +### Sending Back to WDS + +1. Notify Freya when refinement complete +2. Freya reads components via MCP server +3. Design tokens extracted automatically +4. Design system updated +5. Prototype re-rendered with refined design + +--- + +## Keyboard Shortcuts + +**Essential for WDS:** + +| Action | Shortcut | +|--------|----------| +| Frame | F | +| Component | Ctrl/Cmd+Alt+K | +| Text | T | +| Rectangle | R | +| Duplicate | Ctrl/Cmd+D | +| Group | Ctrl/Cmd+G | +| Auto Layout | Shift+A | +| Copy Properties | Ctrl/Cmd+Alt+C | +| Paste Properties | Ctrl/Cmd+Alt+V | + +--- + +## Troubleshooting + +### Issue: Components not syncing with WDS + +**Solution:** +- Check Object IDs in layer names +- Verify Figma file ID in project config +- Ensure MCP server configured +- Check Figma API access token + +--- + +## Resources + +- Help Center: +- Community: +- API Documentation: + +**Related WDS Documentation:** +- [Figma MCP](figma-mcp.md) - Automated integration +- Figma Designer Guide: `workflows/5-design-system/figma-integration/figma-designer-guide.md` + +--- + +[← Back to Tools](wds-tools-guide.md) diff --git a/src/modules/wds/docs/tools/git.md b/src/modules/wds/docs/tools/git.md new file mode 100644 index 00000000..b15427ac --- /dev/null +++ b/src/modules/wds/docs/tools/git.md @@ -0,0 +1,285 @@ +# Git + +**Category:** Version Control +**Purpose:** Track changes, collaborate, maintain project history +**Website:** + +--- + +## What It Is + +Git is a distributed version control system that tracks changes to your WDS project files. It enables collaboration, maintains history, and allows you to experiment safely with branches. + +--- + +## Why WDS Recommends It + +**Version Control:** +- Track all specification changes +- Maintain prototype history +- Document design system evolution +- Rollback if needed + +**Collaboration:** +- Multiple team members can work simultaneously +- Review changes before merging +- Track who changed what and when + +**WDS Workflow Integration:** +- Commit after each phase completion +- Branch for experimental designs +- Tag releases and milestones + +--- + +## Setup Instructions + +### 1. Installation + +**Windows:** +```bash +# Download from https://git-scm.com +# Or use winget +winget install Git.Git +``` + +**macOS:** +```bash +# Using Homebrew +brew install git +``` + +**Linux:** +```bash +# Ubuntu/Debian +sudo apt-get install git + +# Fedora +sudo dnf install git +``` + +### 2. Initial Configuration + +```bash +# Set your identity +git config --global user.name "Your Name" +git config --global user.email "your.email@example.com" + +# Set default branch name +git config --global init.defaultBranch main + +# Set default editor +git config --global core.editor "code --wait" + +# Enable color output +git config --global color.ui auto +``` + +### 3. WDS-Specific Configuration + +Create `.gitignore` for WDS projects: + +```gitignore +# Node modules +node_modules/ +npm-debug.log* + +# Build outputs +dist/ +build/ +*.log + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db + +# Environment +.env +.env.local + +# Temporary files +*.tmp +.cache/ +``` + +--- + +## WDS Best Practices + +### DO ✅ + +**1. Commit Frequently** +```bash +# After completing each phase +git add docs/C-Scenarios/01-Customer-Onboarding/ +git commit -m "feat: Complete customer onboarding scenario specification" + +# After design system updates +git add D-Design-System/ +git commit -m "feat: Add button component to design system" +``` + +**2. Use Descriptive Commit Messages** +```bash +# Good +git commit -m "feat: Add login page specification with multi-language support" +git commit -m "fix: Correct button hover state in design system" +git commit -m "docs: Update prototype-to-figma workflow guide" + +# Bad +git commit -m "updates" +git commit -m "fix stuff" +git commit -m "wip" +``` + +**3. Branch for Experiments** +```bash +# Create branch for design exploration +git checkout -b design/hero-section-variants + +# Experiment with different approaches +# ... + +# Merge if successful +git checkout main +git merge design/hero-section-variants + +# Or discard if not +git branch -D design/hero-section-variants +``` + +**4. Tag Milestones** +```bash +# Tag completed phases +git tag -a v1.0-phase4-complete -m "Phase 4: UX Design complete" + +# Tag releases +git tag -a v1.0-launch -m "Production launch" +``` + +### DON'T ❌ + +**1. Don't Commit Generated Files** +- Add build outputs to `.gitignore` +- Don't commit `node_modules/` +- Don't commit temporary files + +**2. Don't Force Push to Main** +```bash +# Never do this on shared branches +git push --force origin main # ❌ +``` + +**3. Don't Commit Secrets** +- Never commit API keys +- Never commit passwords +- Use environment variables +- Add `.env` to `.gitignore` + +--- + +## Common WDS Workflows + +### Starting a New WDS Project + +```bash +# Initialize repository +git init + +# Add WDS files +git add . + +# Initial commit +git commit -m "chore: Initialize WDS project structure" + +# Connect to remote +git remote add origin https://github.com/username/project.git +git push -u origin main +``` + +### Daily Workflow + +```bash +# Start of day - get latest changes +git pull + +# Work on specifications +# ... + +# Stage and commit changes +git add docs/C-Scenarios/ +git commit -m "feat: Add product detail page specification" + +# Push to remote +git push +``` + +### Collaboration Workflow + +```bash +# Create feature branch +git checkout -b feature/checkout-flow + +# Work on feature +# ... + +# Commit changes +git add . +git commit -m "feat: Add checkout flow specifications" + +# Push branch +git push -u origin feature/checkout-flow + +# Create pull request on GitHub/GitLab +# Team reviews +# Merge when approved +``` + +--- + +## Troubleshooting + +### Issue: Merge conflicts + +**Solution:** +```bash +# Pull latest changes +git pull + +# Resolve conflicts in files +# Edit files to resolve conflicts + +# Mark as resolved +git add +git commit -m "chore: Resolve merge conflicts" +``` + +### Issue: Accidentally committed wrong files + +**Solution:** +```bash +# Undo last commit, keep changes +git reset --soft HEAD~1 + +# Or remove specific file from commit +git reset HEAD +git checkout -- +``` + +--- + +## Resources + +- Documentation: +- Pro Git Book: +- GitHub Guides: + +--- + +[← Back to Tools](wds-tools-guide.md) diff --git a/src/modules/wds/docs/tools/html-to-design.md b/src/modules/wds/docs/tools/html-to-design.md new file mode 100644 index 00000000..726aea8f --- /dev/null +++ b/src/modules/wds/docs/tools/html-to-design.md @@ -0,0 +1,178 @@ +# html.to.design + +**Category:** Conversion Tool +**Purpose:** Convert HTML prototypes to Figma (fallback method) +**Website:** + +--- + +## What It Is + +html.to.design is a web-based tool that converts HTML/CSS to Figma files. In WDS, it serves as a fallback method when MCP server is unavailable for extracting prototypes to Figma. + +--- + +## Why WDS Recommends It + +**Fallback Option:** +- When MCP server not configured +- For full-page extraction +- Quick one-off conversions +- Exploring design possibilities + +**Conversion Capabilities:** +- HTML structure → Figma frames +- CSS styles → Figma styling +- Layout (Flexbox/Grid) → Auto Layout +- Text content → Text layers + +--- + +## Setup Instructions + +### 1. Access + +No installation required - web-based tool: +1. Go to +2. No account needed for basic use +3. Premium features available with account + +### 2. Prepare Prototype + +Before uploading: + +```html + + + + + + Page Title + + + + +
+

Title

+
+ + + +``` + +--- + +## WDS Best Practices + +### DO ✅ + +**1. Clean HTML Before Upload** +- Use semantic HTML elements +- Remove debug code +- Simplify complex nesting +- Use Flexbox/Grid layouts + +**2. Include Object IDs** +```html + +``` + +**3. Use Standard CSS** +- Avoid complex positioning +- Use standard properties +- Keep selectors simple + +### DON'T ❌ + +**1. Don't Use When MCP Available** +- MCP server is preferred method +- Better Object ID preservation +- Automated workflow integration + +**2. Don't Expect Perfect Conversion** +- Manual cleanup may be needed +- Complex layouts may not convert perfectly +- Review and refine in Figma + +--- + +## Usage Workflow + +### 1. Upload HTML + +``` +1. Go to https://html.to.design +2. Upload HTML file +3. Include associated CSS +4. Select target: Figma +``` + +### 2. Configure + +``` +Options: +- Preserve layout structure: Yes +- Convert to components: Yes (if available) +``` + +### 3. Download and Import + +``` +1. Download Figma file +2. Open in Figma +3. Manually add Object IDs to layers +4. Begin refinement +``` + +--- + +## Limitations + +### What Works Well + +- Standard layouts +- Flexbox and Grid +- Text content +- Basic styling + +### What May Need Manual Adjustment + +- Complex animations +- JavaScript-driven content +- Custom SVG graphics +- Advanced CSS effects + +--- + +## When to Use + +### Use html.to.design when: + +- MCP server not configured +- Need full-page extraction +- Quick one-off conversion +- Exploring design possibilities + +### Use MCP server instead when: + +- MCP server available +- Need component-level precision +- Require Object ID traceability +- Planning iterative refinement + +--- + +## Resources + +- Website: +- Documentation: Check website for latest guides + +**Related WDS Documentation:** +- [Figma MCP](figma-mcp.md) - Recommended automated method +- Prototype to Figma Workflow: `workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md` + +--- + +[← Back to Tools](wds-tools-guide.md) diff --git a/src/modules/wds/docs/tools/nanobanana.md b/src/modules/wds/docs/tools/nanobanana.md new file mode 100644 index 00000000..5ee437db --- /dev/null +++ b/src/modules/wds/docs/tools/nanobanana.md @@ -0,0 +1,238 @@ +# NanoBanana + +**Category:** AI Design Tool +**Purpose:** Agent-driven asset creation and design inspiration +**Website:** + +--- + +## What It Is + +NanoBanana is an AI-powered design tool (think "agent-driven Photoshop") that creates visual design assets and generates design inspiration. It's used in WDS for: + +1. **Early design exploration** - Creating custom graphics, mood boards, visual concepts +2. **Sketch envisioning** - Converting sketches/specifications into visual designs (images or code) +3. **Asset creation** - Generating placeholder assets and custom graphics + +**Output formats:** +- **Images** - Visual designs, graphics, illustrations +- **Code snippets** - HTML/CSS/React code for designs + +--- + +## Why WDS Recommends It + +**Asset Creation:** +- Generate custom graphics and icons +- Create design inspiration and variations +- Explore visual concepts +- Generate placeholder assets +- Brand identity exploration + +**Design Exploration:** +- Multiple design variations quickly +- Explore different visual directions +- Generate creative ideas +- Inspire design decisions + +--- + +## Setup Instructions + +### 1. Account Creation + +1. Go to +2. Sign up for account +3. Choose plan (free tier available) + +### 2. WDS Integration + +NanoBanana has two integration workflows in WDS: + +#### **Workflow A: Early Design Exploration** + +``` +Phase 5: Visual Design Exploration + ↓ +NanoBanana (create assets/inspiration) + ↓ +Save to D-Design-System/01-Visual-Design/ + ↓ +Refine concepts → Establish visual direction + ↓ +Define design tokens (colors, typography) + ↓ +Phase 4: Create scenarios with established style + ↓ +Export final assets → D-Design-System/02-Assets/ +``` + +#### **Workflow B: Sketch Envisioning (Alternative to Figma)** + +``` +Phase 4: Create specification + ↓ +NanoBanana (sketch/spec → design as image or code) + ↓ +Freya interprets output (no Object IDs - manual process) + ↓ +Extract design tokens and components + ↓ +Update design system manually + ↓ +Create/update prototype with refined design +``` + +**Key Difference from Figma MCP:** +- ❌ No Object ID preservation (manual interpretation required) +- ❌ No automated bidirectional sync +- ✅ Can generate code snippets directly +- ✅ Can produce visual designs from text descriptions +- ✅ Faster for exploration (no Figma setup needed) + +**Folder Structure:** +- **01-Visual-Design/** - Early exploration, mood boards, NanoBanana outputs +- **02-Assets/** - Final logos, icons, images (added later) + +--- + +## WDS Best Practices + +### DO + +**1. Use for Creative Exploration** +- Generate multiple variations +- Explore different styles +- Create mood boards +- Inspire design direction + +**2. Refine AI Output** +- Don't use raw AI output +- Refine in Figma +- Align with brand guidelines +- Ensure consistency + +**3. Document Asset Sources** +- Track AI-generated assets +- Note generation prompts +- Maintain asset library +- Document usage rights + +**4. Integrate into Design System** +- Export refined assets +- Add to design system +- Create reusable components +- Document usage guidelines + +### DON'T ❌ + +**1. Don't Replace Human Design** +- Use as inspiration, not replacement +- Apply design thinking +- Ensure brand alignment +- Review quality + +**2. Don't Skip Refinement** +- Always refine AI output +- Ensure consistency +- Match brand guidelines +- Test usability + +**3. Don't Use Without Customization** +- Customize for your brand +- Adapt to design system +- Ensure uniqueness +- Avoid generic output + +--- + +## Usage Workflow + +### 1. Generate Assets + +``` +1. Describe desired asset +2. Generate multiple variations +3. Select best options +4. Download assets +``` + +### 2. Refine in Figma + +``` +1. Import to Figma +2. Apply brand colors +3. Adjust to design system +4. Create variants if needed +``` + +### 3. Integrate into WDS + +``` +1. Add to design system +2. Document usage +3. Use in prototypes +4. Share with team +``` + +### 4. Sketch Envisioning (Alternative Workflow) + +**For converting sketches/specs to designs:** + +``` +1. Provide sketch or specification to NanoBanana +2. Receive output (image or code) +3. Freya interprets output: + - Extract design tokens (colors, spacing, typography) + - Identify components and patterns + - Map to design system (manually - no Object IDs) +4. Update design system files +5. Create/update prototype +6. Test and refine +``` + +**Important Notes:** +- **No Object IDs** - Manual interpretation required +- **No automation** - Freya must manually extract and map components +- **Code snippets** - Need integration into WDS structure +- **Images** - Need manual component extraction + +--- + +## When to Use + +### Use NanoBanana for: + +**Early Design Exploration:** +- Custom graphics and icons +- Design inspiration +- Exploring visual concepts +- Creating placeholder assets +- Brand identity exploration + +**Sketch Envisioning (Alternative to Figma):** +- Converting sketches to visual designs quickly +- Generating code snippets from design concepts +- When Figma/MCP server not available +- Rapid prototyping without design system +- Exploring multiple design variations + +### Don't use for: + +- **Automated workflows** - No MCP integration (manual interpretation needed) +- **Object ID traceability** - Outputs lack Object IDs (use Figma MCP for this) +- **Final production code** - Code snippets need refinement and integration +- **Replacing design process** - Use as tool, not replacement +- **Bypassing brand guidelines** - Always align with brand standards + +--- + +## Resources + +- Website: +- Documentation: Check website for latest guides +- Support: Contact via website + +--- + +[← Back to Tools](wds-tools-guide.md) diff --git a/src/modules/wds/docs/tools/wds-tools-guide.md b/src/modules/wds/docs/tools/wds-tools-guide.md new file mode 100644 index 00000000..0885dffa --- /dev/null +++ b/src/modules/wds/docs/tools/wds-tools-guide.md @@ -0,0 +1,115 @@ +# WDS Tools + +**Purpose:** Recommended tools for WDS workflows with setup instructions and best practices. + +**Last Updated:** January 8, 2026 + +--- + +## Overview + +WDS works best with a curated set of tools that support the concept-first, iterative design workflow. Each tool has a dedicated page with comprehensive setup instructions, best practices, and WDS-specific workflows. + +--- + +## Tool Categories + +### Required Tools + +**[Cursor/Windsurf IDE](cursor-windsurf.md)** +- AI-powered IDE for WDS agent workflows +- Development environment for Freya, Saga, Idunn +- **Status:** Required for all WDS phases + +**[Git](git.md)** +- Version control for tracking changes +- Collaboration and project history +- **Status:** Required for all WDS phases + +--- + +### Recommended Tools + +**[Figma MCP](figma-mcp.md)** +- MCP server for automated Figma integration +- Component-level injection and bidirectional sync +- **Status:** Recommended for Phase 4-5 + +--- + +### Optional Tools + +**[Figma](figma.md)** +- Visual design refinement tool +- Design system documentation +- **Status:** Optional for Phase 4-5 + +**[html.to.design](html-to-design.md)** +- HTML to Figma conversion (fallback method) +- When MCP server unavailable +- **Status:** Optional for Phase 4-5 + +**[NanoBanana](nanobanana.md)** +- AI-powered asset creation tool +- Design inspiration and exploration +- **Status:** Optional for pre-Phase 4 + +--- + +## Quick Reference + +| Tool | Category | Primary Use | WDS Phase | Status | +|------|----------|-------------|-----------|--------| +| **[Cursor/Windsurf](cursor-windsurf.md)** | IDE | Development, agent interaction | All | Required | +| **[Git](git.md)** | Version Control | Track changes, collaborate | All | Required | +| **[Figma](figma.md)** | Design | Visual refinement, design system | 4-5 | Optional | +| **[Figma MCP](figma-mcp.md)** | Integration | Automated Figma ↔ WDS sync | 4-5 | Recommended | +| **[html.to.design](html-to-design.md)** | Conversion | HTML → Figma (fallback) | 4-5 | Optional | +| **[NanoBanana](nanobanana.md)** | AI Design | Asset creation, inspiration | Pre-4 | Optional | + +--- + +## Getting Started + +### Minimum Setup (Required) + +1. Install [Cursor or Windsurf IDE](cursor-windsurf.md) +2. Install [Git](git.md) +3. Configure both for your project + +### Recommended Setup (For Full WDS Workflow) + +1. Install [Cursor or Windsurf IDE](cursor-windsurf.md) +2. Install [Git](git.md) +3. Create [Figma](figma.md) account +4. Install and configure [Figma MCP](figma-mcp.md) server +5. Set up Figma API access token + +### Full Setup (All Features) + +1. Install [Cursor or Windsurf IDE](cursor-windsurf.md) +2. Install [Git](git.md) +3. Create [Figma](figma.md) account +4. Install and configure [Figma MCP](figma-mcp.md) server +5. Set up Figma API access token +6. Explore [NanoBanana](nanobanana.md) for asset creation + +### Optional Tools + +- [html.to.design](html-to-design.md) - Fallback when MCP not available +- [NanoBanana](nanobanana.md) - Asset creation and inspiration + +--- + +## Support and Resources + +Each tool page includes: +- Detailed setup instructions +- WDS-specific best practices +- Troubleshooting guides +- Integration with WDS workflows +- Links to official documentation + +--- + +**Browse individual tool pages for comprehensive guides on setup, configuration, and WDS-specific workflows.** diff --git a/src/modules/wds/workflows/1-project-brief/alignment-signoff/substeps/README.md b/src/modules/wds/workflows/1-project-brief/alignment-signoff/substeps/substeps-guide.md similarity index 100% rename from src/modules/wds/workflows/1-project-brief/alignment-signoff/substeps/README.md rename to src/modules/wds/workflows/1-project-brief/alignment-signoff/substeps/substeps-guide.md diff --git a/src/modules/wds/workflows/4-ux-design/page-specification-quality/README.md b/src/modules/wds/workflows/4-ux-design/page-specification-quality/quality-guide.md similarity index 100% rename from src/modules/wds/workflows/4-ux-design/page-specification-quality/README.md rename to src/modules/wds/workflows/4-ux-design/page-specification-quality/quality-guide.md diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-02-substeps/README.md b/src/modules/wds/workflows/4-ux-design/steps/step-02-substeps/substeps-guide.md similarity index 100% rename from src/modules/wds/workflows/4-ux-design/steps/step-02-substeps/README.md rename to src/modules/wds/workflows/4-ux-design/steps/step-02-substeps/substeps-guide.md diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md b/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md index ce42e118..44c3997b 100644 --- a/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md +++ b/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md @@ -166,9 +166,105 @@ Choice [1/2/3]: Perfect! Your prototype validates the design. ✨ -**Prototype testing complete!** +**Prototype testing complete!** -Your design is validated and ready for development. Time to extract the functional requirements we discovered. 📋 +**Visual quality assessment:** + +How does the prototype look visually? + +1. **Polished** - Design system covers everything, looks great +2. **Needs refinement** - Works but looks basic, design system incomplete +3. **Minor tweaks** - Small CSS adjustments needed + +Choice [1/2/3]: + + + **Design Refinement Available** + +Since your design system is incomplete, I can help refine the visual design using: + +1. **Figma MCP** (Recommended) - Automated component extraction with Object ID preservation +2. **NanoBanana** (Alternative) - AI-powered sketch envisioning (outputs images or code, requires manual interpretation) + +Which would you prefer? + + Analyze prototype components and identify gaps in design system + + I've analyzed the prototype and found: + +**Components needing refinement:** +- {list components missing from design system} +- {list components with incomplete states/variants} + +**Estimated refinement time:** {X} components × 15-30 min each = {Y} hours + +This will extend your design system and improve all future prototypes. + + Would you like me to: + 1. **Extract to Figma** - I'll inject these components for refinement + 2. **Continue as-is** - Functional prototype is sufficient for now + + Choice [1/2]: + + + Load and execute `workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md` Phase 2 + + **Injecting components to Figma...** + +I'm using the MCP server to inject components directly into your Figma file. + +Target page: {scenario-number}-{scenario-name} / {page-number}-{page-name} + +{Show injection progress and results} + +✓ All components injected successfully! + +**Figma link:** {provide link} + +**Next steps:** +1. Open Figma and refine the components +2. When finished, let me know and I'll read them back +3. I'll update the design system automatically +4. We can re-render the prototype with improvements + +Take your time with the refinement. I'll be here when you're ready! + + For now, would you like to: + [C] Continue to PRD update (refine Figma later) + [W] Wait here until Figma refinement is complete + + Choice [C/W]: + + + I'll wait here. Let me know when you've finished refining in Figma. + Pause workflow, wait for user notification + + Have you finished refining the components in Figma? [Y/N] + + + Execute Phase 4 of prototype-to-figma-workflow (read refined components) + {Show design token extraction and design system updates} + + Would you like me to re-render the prototype with the enhanced design system now? [Y/N] + + + Re-render prototype with updated design system + ✓ Prototype re-rendered with enhanced design system! + +The prototype now looks polished and professional. All components use the refined design tokens. + + + + + + + + What CSS adjustments are needed? + Apply quick CSS fixes to prototype + Updated! Test again in your browser. 🔄 + + +Your design is validated and ready for development. Time to extract the functional requirements we discovered. 📋 Ready to proceed to **Step 4E: PRD Update**? [Y/N] diff --git a/src/modules/wds/workflows/4-ux-design/README.md b/src/modules/wds/workflows/4-ux-design/ux-design-guide.md similarity index 96% rename from src/modules/wds/workflows/4-ux-design/README.md rename to src/modules/wds/workflows/4-ux-design/ux-design-guide.md index 00f7af8a..791812a4 100644 --- a/src/modules/wds/workflows/4-ux-design/README.md +++ b/src/modules/wds/workflows/4-ux-design/ux-design-guide.md @@ -59,6 +59,9 @@ Phase 4 transforms sketches and ideas into detailed, developer-ready page specif - Generate interactive HTML prototype - Uses Design System if enabled +- **Visual refinement option:** Extract to Figma via MCP server if design system incomplete +- Iterative refinement: Prototype → Figma → Design System → Re-render +- See: `workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md` ### 4E: PRD Update diff --git a/src/modules/wds/workflows/5-design-system/README.md b/src/modules/wds/workflows/5-design-system/design-system-guide.md similarity index 85% rename from src/modules/wds/workflows/5-design-system/README.md rename to src/modules/wds/workflows/5-design-system/design-system-guide.md index 706eddfd..4148cecc 100644 --- a/src/modules/wds/workflows/5-design-system/README.md +++ b/src/modules/wds/workflows/5-design-system/design-system-guide.md @@ -236,15 +236,26 @@ For each component: - `figma-designer-guide.md` - Step-by-step guide for designers - `figma-mcp-integration.md` - Technical MCP integration guide - `figma-component-structure.md` - Component organization in Figma (in data/design-system/) +- `prototype-to-figma-workflow.md` - **NEW:** Extract HTML prototypes to Figma for visual refinement +- `when-to-extract-decision-guide.md` - **NEW:** Decision framework for prototype extraction -**Workflow:** +**Workflows:** +**A. Figma → WDS (Existing):** 1. Designer creates/updates component in Figma 2. Designer adds WDS component ID to description 3. MCP reads component via Figma API 4. Agent generates/updates WDS specification 5. Designer reviews and confirms +**B. Prototype → Figma → WDS (NEW):** +1. HTML prototype created (Phase 4D) +2. Extract to Figma using html.to.design +3. Designer refines visual design in Figma +4. Extract design system updates (tokens, components) +5. Re-render prototype with enhanced design system +6. Iterate until polished + **Key Features:** - Component structure guidelines @@ -252,6 +263,7 @@ For each component: - Variant and state organization - Node ID tracking - Bidirectional sync workflow +- **Iterative visual refinement** (prototype → Figma → design system → re-render) --- @@ -273,6 +285,16 @@ For each component: ``` D-Design-System/ +├── 01-Visual-Design/ [Early design exploration - pre-scenario] +│ ├── mood-boards/ [Visual inspiration, style exploration] +│ ├── design-concepts/ [NanoBanana outputs, design explorations] +│ ├── color-exploration/ [Color palette experiments] +│ └── typography-tests/ [Font pairing and hierarchy tests] +├── 02-Assets/ [Final production assets] +│ ├── logos/ [Brand logos and variations] +│ ├── icons/ [Icon sets] +│ ├── images/ [Photography, illustrations] +│ └── graphics/ [Custom graphics and elements] ├── components/ │ ├── button.md [Component ID: btn-001] │ ├── input-field.md [Component ID: inp-001] diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/INTEGRATION-SUMMARY.md b/src/modules/wds/workflows/5-design-system/figma-integration/INTEGRATION-SUMMARY.md new file mode 100644 index 00000000..e8e2c60f --- /dev/null +++ b/src/modules/wds/workflows/5-design-system/figma-integration/INTEGRATION-SUMMARY.md @@ -0,0 +1,475 @@ +# WDS Prototype-to-Figma Integration - Summary + +**Date Added:** January 8, 2026 +**Version:** WDS v6 +**Status:** Ready for Public Release + +--- + +## What Was Added + +This integration completes the WDS design workflow by adding the missing dimension: **visual design creation and refinement**. + +### New Workflow: Iterative Design Refinement + +``` +Sketch → Spec → Prototype → Figma (if needed) → Design System → Re-render → Iterate +``` + +**Key Innovation:** Code prototypes serve as functional starting points. When design system is incomplete, extract to Figma for visual refinement, then feed improvements back to design system and re-render. + +--- + +## New Documentation Files + +### 1. Prototype-to-Figma Workflow +**File:** `prototype-to-figma-workflow.md` + +**Purpose:** Complete workflow for extracting HTML prototypes to Figma for visual refinement + +**Covers:** +- When and why to extract prototypes +- Step-by-step extraction process using html.to.design +- Figma refinement techniques +- Design system update process +- Re-rendering with enhanced design system +- Iteration strategies + +**Key Sections:** +- Phase 1: Identify need for refinement +- Phase 2: Extract to Figma +- Phase 3: Refine design +- Phase 4: Extract design system updates +- Phase 5: Re-render prototype +- Phase 6: Iterate or complete + +--- + +### 2. When to Extract Decision Guide +**File:** `when-to-extract-decision-guide.md` + +**Purpose:** Help designers make informed decisions about when to extract prototypes to Figma + +**Covers:** +- Decision tree and framework +- Quick assessment checklist +- Scenarios and examples +- Design system maturity levels +- Cost-benefit analysis +- Quality thresholds +- Practical examples + +**Key Features:** +- Clear decision criteria +- Red flags to avoid +- Decision matrix +- Time investment analysis +- Priority guidance + +--- + +### 3. Tools Reference +**File:** `tools-reference.md` + +**Purpose:** Quick reference for design tools used in WDS workflows + +**Covers:** +- **html.to.design:** HTML → Figma conversion +- **NanoBanana:** Spec → Code generation (optional) +- **Area Tag System:** Region mapping for image prototypes +- **Dev Mode Component:** Object ID extraction + +**Key Sections:** +- Tool features and capabilities +- How to use each tool +- Best practices +- Limitations +- Integration workflows +- Troubleshooting + +--- + +## Updated Files + +### 1. Phase 4D Prototype Workflow +**File:** `workflows/4-ux-design/substeps/4d-prototype.md` + +**Changes:** +- Added visual quality assessment after prototype testing +- Integrated Figma extraction option +- References to new workflow documentation +- Decision points for refinement vs completion + +**New Flow:** +``` +Prototype Complete → Visual Assessment → + Option 1: Polished (continue) + Option 2: Needs refinement (extract to Figma) + Option 3: Minor tweaks (quick CSS fixes) +``` + +--- + +### 2. Phase 5 Design System README +**File:** `workflows/5-design-system/README.md` + +**Changes:** +- Added Prototype → Figma → WDS workflow (Workflow B) +- Updated Figma Integration section +- Referenced new documentation files +- Documented iterative refinement capability + +**New Workflows:** +- Workflow A: Figma → WDS (existing) +- Workflow B: Prototype → Figma → WDS (new) + +--- + +## Core Concepts + +### The Missing Dimension + +**Before:** WDS created specifications and functional prototypes, but visual design creation was manual + +**After:** WDS now supports iterative visual refinement through Figma extraction + +### Design System Evolution + +**Key Principle:** Design system grows organically as prototypes are built + +**Process:** +1. Create prototype with existing design system (may look basic) +2. Extract to Figma when gaps identified +3. Refine visuals and create missing components +4. Update design system with new tokens/components +5. Re-render prototype with enhanced design system +6. Iterate until polished + +### When to Extract + +**Extract when:** +- Design system is incomplete +- Prototype needs visual polish +- New components required +- Stakeholder presentation needed + +**Don't extract when:** +- Design system covers all needs +- Prototype looks sufficient +- Rapid iteration more important +- Early exploration phase + +--- + +## Tool Integration + +### html.to.design + +**Role:** Convert HTML prototypes to Figma for visual refinement + +**Process:** +1. Upload HTML prototype +2. Configure conversion options +3. Import to Figma +4. Refine design +5. Extract design system updates + +**Benefits:** +- Preserves layout structure +- Converts CSS to Figma styles +- Maintains element hierarchy +- Enables visual refinement + +### Area Tag System + +**Role:** Precise region mapping for image-based prototypes + +**Usage:** +- Map clickable regions on images +- Include Object IDs for traceability +- Extract coordinates via dev mode +- Document region mappings + +**Integration:** +- Works with dev-mode.js component +- Supports image-based prototypes +- Enables precise click mapping + +### Dev Mode Component + +**Role:** Extract Object IDs and area coordinates from prototypes + +**Features:** +- Shift + Click to copy Object IDs +- Visual highlights +- Area tag detection +- Coordinate extraction + +**Benefit:** Maintains traceability through Figma extraction + +--- + +## Workflow Integration + +### Phase 4: UX Design + +**Updated Step 4D (Prototype):** +- Create functional prototype +- Test functionality +- **NEW:** Assess visual quality +- **NEW:** Option to extract to Figma +- Continue to PRD update + +### Phase 5: Design System + +**New Workflow Branch:** +- Existing: Component specification → Design system +- Existing: Figma manual creation → Design system +- **NEW:** Prototype extraction → Figma → Design system + +### Iteration Loop + +**Complete Cycle:** +``` +1. Sketch (concept) +2. Specification (detailed) +3. Prototype (functional) +4. Figma extraction (if needed) +5. Visual refinement +6. Design system update +7. Re-render prototype +8. Assess → Iterate or Complete +``` + +--- + +## Benefits + +### For Designers + +**Flexibility:** +- Start with functional prototypes +- Refine visuals when needed +- Iterate incrementally +- Build design system organically + +**Efficiency:** +- Don't need complete design system upfront +- Extract only when necessary +- Reuse refined components +- Reduce rework + +### For Teams + +**Collaboration:** +- Shared design language +- Clear handoff process +- Bidirectional sync +- Maintained traceability + +**Quality:** +- Polished final products +- Consistent design system +- Professional visuals +- Stakeholder-ready + +### For Projects + +**Speed:** +- Faster initial prototypes +- Iterative refinement +- Parallel work streams +- Reduced bottlenecks + +**Flexibility:** +- Adapt to changing requirements +- Grow design system as needed +- Balance speed and polish +- Ship working products + +--- + +## Public Release Readiness + +### Documentation Status + +✅ **Complete:** +- Prototype-to-Figma workflow +- Decision guide +- Tools reference +- Phase 4D integration +- Phase 5 README update + +✅ **Tested:** +- Workflow logic validated +- Integration points confirmed +- Decision framework practical +- Tool capabilities verified + +✅ **Ready for:** +- Public documentation +- User testing +- Team adoption +- Production use + +### What's Not Included + +**Out of Scope:** +- MagicPatterns integration (not needed with html.to.design) +- Automated extraction (manual process documented) +- Real-time sync (manual iteration cycle) + +**Future Enhancements:** +- Automated design token extraction +- Figma plugin for WDS +- Real-time bidirectional sync +- AI-powered component matching + +--- + +## Migration Notes + +### For Existing WDS Users + +**No Breaking Changes:** +- Existing workflows continue to work +- New workflow is optional +- Backward compatible +- Incremental adoption + +**How to Adopt:** +1. Read prototype-to-Figma workflow +2. Try with one prototype +3. Refine in Figma +4. Update design system +5. Re-render and compare +6. Expand to more pages + +### For New WDS Users + +**Recommended Approach:** +1. Start with first page +2. Create basic prototype +3. Extract to Figma +4. Build design system foundation +5. Use for subsequent pages +6. Extract only when gaps found + +--- + +## Success Metrics + +### Quality Indicators + +✅ Prototypes look polished +✅ Design system is comprehensive +✅ Figma and code are in sync +✅ Object IDs maintained throughout +✅ Iterations are productive +✅ Team aligned on visual direction + +### Efficiency Indicators + +✅ Fewer refinement cycles needed +✅ Design system grows organically +✅ Reusable components identified +✅ Faster subsequent prototypes +✅ Reduced rework + +--- + +## Next Steps + +### For Documentation + +1. ✅ Core workflow documentation complete +2. ✅ Decision guides created +3. ✅ Tools reference documented +4. ✅ Integration points updated +5. 🔄 Session logs cleanup (in progress) +6. ⏳ User testing and feedback +7. ⏳ Video tutorials (future) +8. ⏳ Example projects (future) + +### For Implementation + +1. ✅ Workflow files created +2. ✅ Phase 4D updated +3. ✅ Phase 5 updated +4. ⏳ Test with real projects +5. ⏳ Gather user feedback +6. ⏳ Refine based on usage +7. ⏳ Create example case studies + +--- + +## Key Takeaways + +### The Complete WDS Flow + +**Concept-First Approach:** +1. Sketch and specification are source of truth +2. Generate functional prototypes from specs +3. Apply design system (may be incomplete initially) +4. Extract to Figma when visual refinement needed +5. Refine design and extend design system +6. Re-render with enhanced design system +7. Iterate until polished + +### Design System Philosophy + +**Just-In-Time Design Definitions:** +- Don't need complete design system upfront +- Build definitions as needed +- Extract from working prototypes +- Grow organically with product +- Reduce upfront investment + +### Iterative Refinement + +**Balanced Approach:** +- Functional first, polish later +- Extract strategically, not automatically +- Iterate incrementally +- Ship working products +- Balance speed and quality + +--- + +## Contact and Support + +**Documentation Location:** +- `workflows/5-design-system/figma-integration/` + +**Related Documentation:** +- Phase 4: UX Design workflows +- Phase 5: Design System workflows +- Interactive Prototypes guides +- Figma Integration guides + +**Questions or Issues:** +- Review decision guide for common scenarios +- Check tools reference for troubleshooting +- Follow workflow documentation step-by-step +- Test with simple prototype first + +--- + +**This integration completes the WDS design workflow, enabling teams to create polished, production-ready designs through iterative refinement of functional prototypes.** + +--- + +## Version History + +**v1.0 - January 8, 2026** +- Initial release +- Prototype-to-Figma workflow +- Decision guide +- Tools reference +- Phase 4D and Phase 5 integration + +**Future Versions:** +- User feedback integration +- Enhanced automation +- Additional tool integrations +- Example case studies diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/mcp-server-integration.md b/src/modules/wds/workflows/5-design-system/figma-integration/mcp-server-integration.md new file mode 100644 index 00000000..9bdb53de --- /dev/null +++ b/src/modules/wds/workflows/5-design-system/figma-integration/mcp-server-integration.md @@ -0,0 +1,922 @@ +# MCP Server Integration for Prototype-to-Figma Workflow + +**Purpose:** Enable precise component injection from HTML prototypes into Figma using MCP server. + +**Key Advantage:** Component-level precision - inject exactly what needs refinement, not entire pages. + +--- + +## Overview + +The MCP (Model Context Protocol) server integration enables WDS to communicate directly with Figma, allowing: + +- **Selective component extraction** from HTML prototypes +- **Direct injection** into specific Figma files/pages +- **Object ID preservation** for traceability +- **Automated mapping** between code and design +- **Batch operations** for multiple components + +--- + +## Architecture + +### Component Flow + +``` +HTML Prototype (with Object IDs) + ↓ +WDS Agent identifies components to extract + ↓ +MCP Server reads HTML/CSS for selected components + ↓ +Converts to Figma-compatible format + ↓ +Injects into target Figma file/page + ↓ +Designer refines in Figma + ↓ +MCP Server reads refined design + ↓ +Updates WDS Design System + ↓ +Re-render prototype with enhanced design system +``` + +### MCP Server Role + +**Bidirectional Bridge:** +- **WDS → Figma:** Inject components for refinement +- **Figma → WDS:** Read refined components back + +**Capabilities:** +- Read HTML/CSS structure +- Convert to Figma nodes +- Create frames, auto-layout, text layers +- Apply styling (colors, spacing, typography) +- Preserve Object IDs in layer names +- Read Figma component definitions +- Extract design tokens +- Map component variants + +--- + +## Commands + +### Extract Component to Figma + +**Command:** +```bash +wds figma inject [options] +``` + +**Parameters:** +- `component-id`: Object ID of component to extract (e.g., "btn-login-submit") +- `--file `: Target Figma file ID +- `--page `: Target page within Figma file +- `--position `: Position to inject component (optional) +- `--batch `: Extract multiple components from list + +**Example:** +```bash +# Inject single component (page name matches specification) +wds figma inject btn-login-submit --file abc123 --page "01-Customer-Onboarding / 1.2-Sign-In" + +# Inject multiple components to same scenario/page +wds figma inject --batch components-to-refine.txt --file abc123 --page "01-Customer-Onboarding / 1.2-Sign-In" +``` + +**Page Naming Convention:** +- Format: `[Scenario-Number]-[Scenario-Name] / [Page-Number]-[Page-Name]` +- Example: `01-Customer-Onboarding / 1.2-Sign-In` +- Matches WDS specification structure in `docs/C-Scenarios/` +- Maintains traceability from spec → prototype → Figma + +**Output:** +``` +✓ Component btn-login-submit extracted from prototype +✓ Converted to Figma format +✓ Injected into Figma file abc123, page "Login Components" +✓ Object ID preserved in layer name +✓ Position: (100, 200) +``` + +--- + +### Extract Section to Figma + +**Command:** +```bash +wds figma inject-section [options] +``` + +**Parameters:** +- `section-name`: Section identifier from specification +- `--file `: Target Figma file ID +- `--page `: Target page within Figma file +- `--include-children`: Include all child components + +**Example:** +```bash +# Inject entire login form section +wds figma inject-section login-form --file abc123 --include-children +``` + +--- + +### Read Refined Component from Figma + +**Command:** +```bash +wds figma read [options] +``` + +**Parameters:** +- `component-id`: Object ID of component in Figma +- `--file `: Source Figma file ID +- `--extract-tokens`: Extract design tokens +- `--update-design-system`: Automatically update design system + +**Example:** +```bash +# Read refined component and update design system +wds figma read btn-login-submit --file abc123 --extract-tokens --update-design-system +``` + +**Output:** +``` +✓ Component btn-login-submit read from Figma +✓ Design tokens extracted: + - Background: primary.600 + - Text: neutral.50 + - Padding: spacing.md spacing.lg + - Border-radius: radius.md +✓ Design system updated: D-Design-System/components/button.md +``` + +--- + +### Batch Operations + +**Command:** +```bash +wds figma batch --list +``` + +**Operations:** +- `inject`: Inject multiple components +- `read`: Read multiple refined components +- `sync`: Bidirectional sync + +**Example batch file (components-to-refine.txt):** +``` +btn-login-submit +btn-signup-cta +input-email +input-password +link-forgot-password +``` + +**Command:** +```bash +wds figma batch inject --list components-to-refine.txt --file abc123 +``` + +--- + +## Workflow Integration + +### Phase 4D: After Prototype Creation + +**Agent workflow:** + +```markdown +1. Prototype created and tested +2. Visual quality assessment +3. If needs refinement: + a. Identify components that need polish + b. Generate component list + c. Offer to inject to Figma + d. Execute MCP injection + e. Provide Figma link to designer +``` + +**Agent dialogue:** + +``` +I've identified 5 components that could benefit from visual refinement: +- Login button (btn-login-submit) +- Email input (input-email) +- Password input (input-password) +- Forgot password link (link-forgot-password) +- Sign up CTA (btn-signup-cta) + +Would you like me to inject these into Figma for refinement? + +[Y] Yes, inject all +[S] Select specific components +[N] No, continue as-is + +Choice: +``` + +--- + +### Phase 5: Reading Refined Components + +**Agent workflow:** + +```markdown +1. Designer completes refinement in Figma +2. Designer notifies agent +3. Agent reads refined components via MCP +4. Extracts design tokens +5. Updates design system +6. Offers to re-render prototype +``` + +**Agent dialogue:** + +``` +I see you've refined the components in Figma. Let me read them back: + +Reading btn-login-submit... ✓ +Reading input-email... ✓ +Reading input-password... ✓ +Reading link-forgot-password... ✓ +Reading btn-signup-cta... ✓ + +Design tokens extracted: +- 3 new colors added to palette +- 2 new spacing values defined +- 1 new typography style created + +Design system updated: +- Button component enhanced +- Input component refined +- Link component created + +Would you like me to re-render the prototype with these improvements? + +[Y] Yes, re-render now +[R] Review changes first +[L] Re-render later + +Choice: +``` + +--- + +## MCP Server Configuration + +### Setup + +**1. Install MCP Server** +```bash +npm install -g @wds/figma-mcp-server +``` + +**2. Configure Figma API Access** +```bash +# Set Figma personal access token +export FIGMA_ACCESS_TOKEN="your-token-here" + +# Or in .env file +FIGMA_ACCESS_TOKEN=your-token-here +``` + +**3. Initialize MCP Server** +```bash +wds figma init +``` + +**4. Test Connection** +```bash +wds figma test-connection +``` + +--- + +### Configuration File + +**Location:** `.wds/figma-mcp-config.yaml` + +```yaml +figma: + access_token: ${FIGMA_ACCESS_TOKEN} + default_file_id: "abc123def456" + default_page: "WDS Components" + +extraction: + preserve_object_ids: true + extract_design_tokens: true + convert_to_components: true + maintain_hierarchy: true + +injection: + auto_layout: true + responsive_constraints: true + component_naming: "object-id" + page_naming: "scenario-page" # Matches WDS spec structure + +sync: + bidirectional: true + auto_update_design_system: false + conflict_resolution: "manual" + +naming_conventions: + page_format: "{scenario-number}-{scenario-name} / {page-number}-{page-name}" + example: "01-Customer-Onboarding / 1.2-Sign-In" + source: "docs/C-Scenarios/" +``` + +--- + +## Figma File Organization + +### Recommended Structure + +**Figma file should mirror WDS specification structure:** + +``` +[Project Name] Design Refinement +├── 01-Customer-Onboarding/ +│ ├── 1.1-Start-Page +│ ├── 1.2-Sign-In +│ ├── 1.3-Sign-Up +│ └── ... +├── 02-Family-Management/ +│ ├── 2.1-Family-Dashboard +│ ├── 2.2-Add-Member +│ └── ... +└── Components/ + ├── Buttons + ├── Inputs + └── Cards +``` + +**Benefits:** +- Direct mapping to WDS specifications +- Easy to locate components by scenario/page +- Maintains project structure consistency +- Clear handoff to developers + +**Page Naming:** +- Use exact scenario and page numbers from specs +- Format: `[Number]-[Name]` (e.g., `1.2-Sign-In`) +- Matches folder structure in `docs/C-Scenarios/` + +--- + +## Component Selection Strategies + +### Strategy 1: Individual Components + +**When to use:** Specific components need refinement + +**Process:** +```bash +# Inject one component at a time +wds figma inject btn-login-submit --file abc123 +wds figma inject input-email --file abc123 +``` + +**Advantages:** +- Precise control +- Focused refinement +- Easy to track changes + +--- + +### Strategy 2: Component Groups + +**When to use:** Related components need consistent refinement + +**Process:** +```bash +# Create component group file +echo "btn-login-submit +btn-signup-cta +btn-cancel" > login-buttons.txt + +# Inject group +wds figma batch inject --list login-buttons.txt --file abc123 +``` + +**Advantages:** +- Consistent design decisions +- Efficient batch processing +- Related components together + +--- + +### Strategy 3: Section-Based + +**When to use:** Entire section needs refinement + +**Process:** +```bash +# Inject entire section with all components +wds figma inject-section login-form --file abc123 --include-children +``` + +**Advantages:** +- Complete context +- Layout refinement +- Holistic design decisions + +--- + +### Strategy 4: Iterative Refinement + +**When to use:** Multiple refinement cycles needed + +**Process:** +```bash +# Iteration 1: Inject basic components +wds figma inject btn-login-submit --file abc123 + +# Designer refines in Figma + +# Read back refined version +wds figma read btn-login-submit --file abc123 --update-design-system + +# Iteration 2: Re-inject with design system updates +wds figma inject btn-login-submit --file abc123 --version 2 + +# Continue until satisfied +``` + +**Advantages:** +- Incremental improvement +- Design system grows with each iteration +- Reduced rework + +--- + +## Object ID Mapping + +### Preservation Strategy + +**In HTML Prototype:** +```html + +``` + +**In Figma (after injection):** +``` +Layer name: "btn-login-submit" +Description: "Object ID: btn-login-submit" +``` + +**In Design System:** +```yaml +# D-Design-System/components/button.md +Button Component [btn-001] + +Object ID Mapping: +- btn-login-submit → Login page submit button +- btn-signup-cta → Signup page CTA button +``` + +--- + +### Traceability + +**Benefits:** +- Track component from spec → prototype → Figma → design system +- Identify which Figma components map to which code elements +- Update specific components without affecting others +- Maintain consistency across iterations + +**Workflow:** +``` +Specification: "Login button" (conceptual) + ↓ +Prototype: data-object-id="btn-login-submit" (code) + ↓ +Figma: Layer "btn-login-submit" (design) + ↓ +Design System: Button.primary [btn-001] (documentation) + ↓ +Re-rendered Prototype: class="btn-primary" (enhanced code) +``` + +--- + +## Design Token Extraction + +### Automatic Token Detection + +**MCP Server analyzes:** +- Colors used in component +- Spacing/padding values +- Typography styles +- Border radius +- Shadows/effects + +**Example extraction:** + +**From Figma component:** +``` +Background: #2563eb +Text: #ffffff +Padding: 12px 16px +Border-radius: 8px +Font: Inter, 16px, 600 +``` + +**To Design Tokens:** +```yaml +colors: + primary: + 600: "#2563eb" + neutral: + 50: "#ffffff" + +spacing: + md: 12px + lg: 16px + +radius: + md: 8px + +typography: + button: + font-family: "Inter" + font-size: 16px + font-weight: 600 +``` + +--- + +### Token Mapping + +**MCP Server can:** +- Detect similar colors and suggest token names +- Identify spacing patterns +- Recognize typography scales +- Propose token structure + +**Agent dialogue:** + +``` +I've analyzed the refined button component and detected these values: + +Colors: +- Background: #2563eb → Suggest: primary.600 +- Text: #ffffff → Suggest: neutral.50 + +Spacing: +- Padding horizontal: 16px → Suggest: spacing.lg +- Padding vertical: 12px → Suggest: spacing.md + +Would you like to: +[A] Accept all suggestions +[C] Customize token names +[R] Review each token + +Choice: +``` + +--- + +## Error Handling + +### Common Issues + +**Issue: Component not found in prototype** +``` +Error: Component with Object ID "btn-login-submit" not found in prototype + +Solution: +- Verify Object ID exists in HTML +- Check data-object-id attribute +- Ensure prototype file is current +``` + +**Issue: Figma file access denied** +``` +Error: Cannot access Figma file abc123 + +Solution: +- Verify Figma access token +- Check file permissions +- Ensure file ID is correct +``` + +**Issue: Component structure too complex** +``` +Warning: Component has deeply nested structure (8 levels) +This may not convert cleanly to Figma + +Suggestion: +- Simplify HTML structure +- Extract sub-components separately +- Use flatter hierarchy +``` + +--- + +### Conflict Resolution + +**Scenario: Component exists in both prototype and Figma** + +**Options:** +``` +Component btn-login-submit already exists in Figma. + +[O] Overwrite with new version +[M] Merge changes +[V] Create new version +[S] Skip this component + +Choice: +``` + +**Merge strategy:** +- Preserve Figma refinements +- Apply new structural changes +- Prompt for conflicts + +--- + +## Best Practices + +### DO ✅ + +**1. Use Object IDs consistently** +```html + + +``` + +**2. Regenerate or update prototype** + + +**Re-render approach:** + +1. **Regenerate** - Create fresh prototype with new design system +2. **Update** - Apply design system to existing prototype +3. **Hybrid** - Update critical sections, regenerate others + +Choice [1/2/3]: + + +**3. Test updated prototype** + +Verify: +- Visual quality improved ✅ +- Functionality preserved ✅ +- Design system applied correctly ✅ +- All Object IDs maintained ✅ + +--- + +### Phase 6: Iterate or Complete + +**Assessment:** + + +**Prototype quality check:** + +1. **Complete** - Looks polished, ready for development +2. **Iterate** - Needs another refinement cycle +3. **Minor tweaks** - Small adjustments needed + +Choice [1/2/3]: + + + + Return to Phase 2 (Extract to Figma again) + Starting iteration 2 with enhanced design system as baseline + + + + ✅ Prototype complete and polished! + Mark prototype as final + Update scenario tracking + + +--- + +## Tools Integration + +### html.to.design + +**Purpose:** Convert HTML prototypes to Figma + +**Features:** +- Preserves layout structure +- Converts CSS to Figma styles +- Maintains element hierarchy +- Extracts design tokens +- Creates Figma components + +**Usage:** +``` +1. Upload HTML file +2. Configure conversion options +3. Download Figma file +4. Import to Figma workspace +``` + +**Best Practices:** +- Clean HTML structure before extraction +- Use semantic HTML elements +- Include Object IDs in data attributes +- Document area tags for image sections +### NanoBanana (Optional) + +**Purpose:** Agent-driven asset creation and design inspiration tool + +**Website:** + +**Use Case in WDS:** Create visual assets, design inspiration, and possibly export design elements + +**Description:** Think of it as "agent-driven Photoshop" - an AI-powered tool for creating visual design assets and exploring design possibilities. + +### Features + +**Asset Creation:** +- Visual design generation +- Design inspiration and variations +- Asset creation (images, graphics, icons) +- Design exploration +- Possibly code export for certain elements + +### Integration with WDS + +**Workflow:** +``` +Design Concept + → NanoBanana (create assets/inspiration) + → Visual Assets + → Use in Figma or Prototypes + → Refine and integrate +``` + +**When to use:** +- Need visual design inspiration +- Creating custom graphics/assets +- Exploring design variations +- Generating design ideas +- Creating placeholder assets + +**When to Skip:** +- Have existing design assets +- Working with established brand guidelines +- Simple text/layout-only designs +- Using stock assets + +### Best Practices + +**DO ✅** +- Use for design exploration and inspiration +- Generate multiple variations +- Refine AI-generated assets in Figma +- Use as creative starting point +- Export and integrate into design system + +**DON'T ❌** +- Use as replacement for design thinking +- Skip refinement of generated assets +- Ignore brand guidelines +- Use without customization +- Rely solely on AI-generated designs +### Design System Updates + +``` +D-Design-System/ + design-tokens.md ← Updated from Figma + components/ + button.md ← Updated from Figma + input.md ← New from Figma + figma-mappings.md ← Figma node references + refinement-history.md ← Track iterations +``` + +--- + +## Decision Framework + +### When to Extract to Figma? + +**Extract if ANY of these are true:** + +1. **Visual Quality Gap** + - Prototype looks unpolished + - Design system incomplete + - Missing visual hierarchy + +2. **Design System Gaps** + - Need new components + - Missing variants/states + - Token palette incomplete + +3. **Stakeholder Needs** + - Client presentation required + - High-fidelity mockups needed + - Marketing materials + +**Don't extract if ALL of these are true:** + +1. Prototype looks good enough +2. Design system covers all needs +3. Focus is on functionality +4. Rapid iteration more important + +--- + +## Best Practices + +### DO ✅ + +1. **Maintain Object IDs** + - Keep Object IDs through extraction + - Use as Figma layer names + - Enables traceability + +2. **Document Iterations** + - Track version history + - Note design decisions + - Record token changes + - **Update specifications when design evolves** + - Document why design changed from original spec + +3. **Sync Bidirectionally** + - Figma → Design System + - Design System → Prototype + - Keep everything aligned + +4. **Iterate Incrementally** + - Small refinement cycles + - Test after each iteration + - Don't over-polish early + +### DON'T ❌ + +1. **Don't Extract Too Early** + - Wait until concept is validated + - Ensure functionality works first + - Don't polish throwaway work + +2. **Don't Lose Traceability** + - Maintain Object ID connections + - Document Figma references + - Track design system changes + +3. **Don't Diverge Without Updating Specs** + - New design ideas during Figma refinement are welcome + - **BUT:** Update specifications to match new design decisions + - Keep Figma, specs, and code in sync + - Update design system consistently + - Specifications remain the source of truth + +4. **Don't Over-Iterate** + - Know when "good enough" is sufficient + - Balance polish with progress + - Ship working products + +--- + +## Troubleshooting + +### Extraction Issues + +**Problem:** html.to.design doesn't preserve layout + +**Solution:** +- Use semantic HTML structure +- Avoid complex CSS positioning +- Simplify before extraction +- Use Flexbox/Grid layouts + +--- + +**Problem:** Object IDs lost in extraction + +**Solution:** +- Add Object IDs to data attributes +- Use as CSS classes +- Include in element IDs +- Document mapping separately + +--- + +### Figma Refinement Issues + +**Problem:** Can't match design system tokens + +**Solution:** +- Create Figma variables first +- Map extracted values to variables +- Document token mappings +- Use consistent naming + +--- + +**Problem:** Components don't match code structure + +**Solution:** +- Align Figma component hierarchy with HTML +- Use same naming conventions +- Document component boundaries +- Keep structures parallel + +--- + +### Re-rendering Issues + +**Problem:** Design system changes break prototype + +**Solution:** +- Test incrementally +- Update one token at a time +- Verify after each change +- Keep rollback version + +--- + +**Problem:** Prototype loses functionality after re-render + +**Solution:** +- Preserve JavaScript logic +- Don't change HTML structure +- Only update styling +- Test all interactions + +--- + +## Success Metrics + +**Quality Indicators:** + +✅ Prototype looks polished +✅ Design system is comprehensive +✅ Figma and code are in sync +✅ Object IDs maintained throughout +✅ Iterations are productive +✅ Team alignment on visual direction + +**Efficiency Indicators:** + +✅ Fewer refinement cycles needed +✅ Design system grows organically +✅ Reusable components identified +✅ Faster subsequent prototypes +✅ Reduced rework + +--- + +## Example: Complete Iteration Cycle + +### Iteration 1: Basic Prototype + +**Input:** Login page specification + +**Output:** Functional HTML prototype +- Form works +- Validation functions +- But looks basic (incomplete design system) + +**Assessment:** Needs visual refinement + +--- + +### Iteration 2: Figma Refinement + +**Extract to Figma:** +- Upload to html.to.design +- Import to Figma +- Structure preserved + +**Refine in Figma:** +- Apply proper typography (Inter font) +- Refine color palette (brand colors) +- Add button variants (primary, secondary) +- Define input states (default, focus, error) +- Add visual polish (shadows, borders) + +**Extract to Design System:** +- New tokens: colors, spacing, typography +- New components: Button [btn-001], Input [inp-001] +- Updated: design-tokens.md, components/ + +--- + +### Iteration 3: Re-render + +**Update Prototype:** +- Apply new design tokens +- Use new component classes +- Regenerate with design system + +**Result:** +- Same functionality ✅ +- Polished visuals ✅ +- Design system extended ✅ + +**Assessment:** Complete! Ready for development + +--- + +## Integration with Existing Workflows + +### Phase 4D: Prototype + +**Updated decision point:** + +```markdown +After prototype creation: + +1. Test functionality +2. Assess visual quality +3. If needs refinement → Extract to Figma +4. If sufficient → Complete +``` + +### Phase 5: Design System + +**New workflow branch:** + +```markdown +Design System can be populated via: + +A. Component specification (existing) +B. Figma manual creation (existing) +C. Prototype extraction (NEW - this workflow) +``` + +--- + +## Next Steps + +**To implement this workflow:** + +1. ✅ Read this guide +2. ✅ Set up html.to.design account +3. ✅ Create test prototype +4. ✅ Practice extraction process +5. ✅ Refine in Figma +6. ✅ Update design system +7. ✅ Re-render and compare +8. ✅ Iterate until comfortable + +--- + +**This workflow completes the WDS design refinement loop, enabling iterative improvement from functional prototypes to polished, production-ready designs.** diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/tools-reference.md b/src/modules/wds/workflows/5-design-system/figma-integration/tools-reference.md new file mode 100644 index 00000000..23504124 --- /dev/null +++ b/src/modules/wds/workflows/5-design-system/figma-integration/tools-reference.md @@ -0,0 +1,665 @@ +# Design Tools Reference for WDS + +**Purpose:** Quick reference for design tools used in WDS workflows, particularly for prototype-to-Figma extraction. + +--- + +## MCP Server (Primary Method) + +**Purpose:** Precise component injection from HTML prototypes to Figma + +**Use Case in WDS:** Extract specific components for visual refinement with full traceability + +**See:** `mcp-server-integration.md` for complete documentation + +### Features + +**Component-Level Precision:** +- Select specific components by Object ID +- Inject individual components or sections +- Batch component extraction +- Granular control over what gets refined + +**Conversion Capabilities:** +- HTML structure → Figma frames +- CSS styles → Figma styling +- Layout (Flexbox/Grid) → Auto Layout +- Text content → Text layers +- Colors → Color fills +- Spacing → Padding/gaps + +**Preservation:** +- Object IDs maintained in layer names +- Element hierarchy preserved +- Component boundaries respected +- Traceability throughout workflow + +### How to Use + +**1. Prepare Prototype** +``` +Ensure your HTML prototype: +- Uses semantic HTML elements +- Has Object IDs on all components (data-object-id) +- Uses Flexbox or Grid for layouts +- Has clean CSS structure +``` + +**2. Inject via MCP Server** +```bash +# Single component +wds figma inject btn-login-submit --file abc123 + +# Multiple components +wds figma batch inject --list components.txt --file abc123 + +# Entire section +wds figma inject-section login-form --file abc123 +``` + +**3. Verify in Figma** +``` +- Open target Figma file +- Navigate to injection page +- Verify components injected correctly +- Check Object IDs preserved +``` + +**4. Read Refined Components Back** +```bash +# After designer refines in Figma +wds figma read btn-login-submit --file abc123 --update-design-system +``` + +### Advantages over Manual Upload + +✅ **Component-level precision** - Inject only what needs refinement +✅ **Object ID preservation** - Automatic mapping maintained +✅ **Bidirectional sync** - Read refined components back +✅ **Batch operations** - Efficient multi-component extraction +✅ **Direct integration** - Seamless WDS workflow +✅ **Automated token extraction** - Design system updates automatic + +--- + +## html.to.design (Alternative Method) + +**Purpose:** Manual HTML to Figma conversion (fallback option) + +**Website:** + +**Use Case in WDS:** When MCP server unavailable or for full-page extraction + +**Note:** MCP server approach is preferred for component-level precision and traceability. + +### When to Use html.to.design + +**Use when:** +- MCP server not configured +- Need to extract entire page at once +- Quick one-off conversion needed +- Exploring design possibilities + +**Don't use when:** +- MCP server available (use MCP instead) +- Need component-level precision +- Require Object ID traceability +- Planning iterative refinement + +### How to Use + +**1. Prepare Prototype** +``` +Ensure your HTML prototype: +- Uses semantic HTML elements +- Has clean CSS structure +- Uses Flexbox or Grid for layouts +``` + +**2. Upload to html.to.design** +``` +1. Go to https://html.to.design +2. Upload HTML file +3. Include associated CSS files +4. Select target: Figma +``` + +**3. Import to Figma** +``` +1. Download converted Figma file +2. Open in Figma +3. Manually add Object IDs to layers +4. Begin refinement +``` + +**Limitations:** +- No automatic Object ID preservation +- Entire page extraction (less precise) +- Manual token extraction required +- No automated design system sync + +### Best Practices + +**DO ✅** +- Use semantic HTML (header, nav, main, section, article) +- Apply consistent class naming +- Use Flexbox/Grid for layouts +- Include Object IDs for traceability +- Clean up HTML before extraction +- Test prototype before extracting + +**DON'T ❌** +- Use complex CSS positioning (absolute, fixed) +- Rely on JavaScript-generated content +- Use inline styles excessively +- Have deeply nested structures +- Include debug/test code +- Extract incomplete prototypes + +### Limitations + +**What Works Well:** +- Standard layouts (header, content, footer) +- Flexbox and Grid layouts +- Text content and typography +- Basic styling (colors, spacing, borders) +- Image placeholders +- Component-based structures + +**What May Need Manual Adjustment:** +- Complex animations +- JavaScript-driven interactions +- Dynamic content +- Custom SVG graphics +- Advanced CSS effects +- Responsive breakpoints + +### Tips for Better Extraction + +**1. Simplify Structure** +```html + +
+
+
+
Text
+
+
+
+ + +
+

Text

+
+``` + +**2. Use Flexbox/Grid** +```css +/* Preferred: Flexbox */ +.container { + display: flex; + gap: 16px; + padding: 24px; +} + +/* Avoid: Absolute positioning */ +.item { + position: absolute; + top: 50px; + left: 100px; +} +``` + +**3. Include Object IDs** +```html + + +``` + +**4. Clean CSS** +```css +/* Preferred: Token-based */ +.button { + background: var(--color-primary-600); + padding: var(--spacing-md) var(--spacing-lg); + border-radius: var(--radius-md); +} + +/* Avoid: Hardcoded values scattered --> +.button { + background: #2563eb; + padding: 12px 16px; + border-radius: 8px; +} +``` + +--- + +## NanoBanana + +**Purpose:** Agent-driven asset creation, design inspiration, and sketch envisioning tool + +**Website:** + +**Use Cases in WDS:** +1. Create visual design assets and explore design concepts +2. Convert sketches/specifications to visual designs (images or code) +3. Generate design inspiration and placeholder assets + +**Output Formats:** +- Images (visual designs, graphics) +- Code snippets (HTML/CSS/React) + +**Description:** Agent-driven Photoshop - AI-powered tool for visual asset creation and design exploration + +### Features + +**Asset Creation Capabilities:** +- Visual design generation +- Design inspiration and variations +- Custom graphics and icons +- Image assets +- Design concept exploration +- Possibly code export for certain elements + +### Integration with WDS + +**Workflow:** +``` +Design Concept + → NanoBanana (create assets/inspiration) + → Visual Assets/Design Ideas + → Import to Figma for refinement + → Integrate into Design System + → Use in Prototypes +``` + +**When to Use:** +- Need visual design inspiration +- Creating custom graphics/assets +- Exploring design variations +- Generating design concepts +- Creating placeholder visuals +- Brand identity exploration + +**When to Skip:** +- Have existing design assets +- Working with established brand +- Simple text/layout designs +- Using stock assets +- Strict brand guidelines + +### Best Practices + +**DO ✅** +- Use for creative exploration +- Generate multiple variations +- Refine AI-generated assets +- Use as inspiration starting point +- Integrate refined assets into design system +- Document asset sources + +**DON'T ❌** +- Replace human design thinking +- Skip refinement process +- Ignore brand guidelines +- Use without customization +- Rely solely on AI output +- Skip quality review + +--- + +## Area Tag System + +**Purpose:** Precise region mapping in HTML prototypes for interactive hotspots + +**Use Case in WDS:** Map clickable regions on image-based prototypes or complex UI elements + +### What Are Area Tags? + +HTML `` elements within `` tags that define clickable regions on images: + +```html +Prototype + + + Login Button + Sign Up Link + +``` + +### When to Use Area Tags + +**Use When:** +- Working with image-based prototypes +- Need precise click mapping +- Complex UI with overlapping elements +- Screenshot-based specifications +- Testing click regions + +**Don't Use When:** +- HTML elements are clickable directly +- Simple button/link interactions +- Fully interactive prototype exists +- Accessibility is primary concern + +### Integration with Dev Mode + +The dev-mode.js component can extract area tag coordinates: + +```javascript +// Dev mode detects area tags +document.querySelectorAll('area').forEach(area => { + const coords = area.coords; + const objectId = area.dataset.objectId; + console.log(`${objectId}: ${coords}`); +}); +``` + +### Creating Area Tags + +**1. Get Coordinates** +``` +Use image editor or browser dev tools: +- Top-left corner: (x1, y1) +- Bottom-right corner: (x2, y2) +- Format: "x1,y1,x2,y2" +``` + +**2. Define Area** +```html +Description +``` + +**3. Link to Map** +```html + + + + +``` + +### Best Practices + +**DO ✅** +- Include Object IDs in data attributes +- Provide descriptive alt text +- Test all clickable regions +- Document area mappings +- Use for image-based prototypes + +**DON'T ❌** +- Use for fully interactive HTML prototypes +- Forget accessibility considerations +- Overlap areas without purpose +- Skip testing on different screen sizes +- Use as replacement for proper HTML + +### Accessibility Considerations + +Area tags have limitations: +- Not keyboard accessible by default +- Screen readers may not announce properly +- Better to use actual HTML elements when possible + +**Workaround:** +```html + +Login Button +``` + +--- + +## Dev Mode Component + +**Purpose:** Interactive tool for extracting Object IDs and area coordinates from prototypes + +**Location:** `workflows/4-ux-design/interactive-prototypes/templates/components/dev-mode.js` + +### Features + +**Object ID Extraction:** +- Hold Shift + Click to copy Object IDs +- Visual highlights when Shift held +- Tooltip display on hover +- Success feedback when copied +- Form field protection + +**Area Tag Extraction:** +- Detect area tags in prototype +- Extract coordinates +- Map to Object IDs +- Export for documentation + +### Usage + +**1. Include in Prototype** +```html + +``` + +**2. Activate Dev Mode** +``` +- Click "Dev Mode" button, or +- Press Ctrl+E (Cmd+E on Mac) +``` + +**3. Extract Object IDs** +``` +- Hold Shift +- Click on element +- Object ID copied to clipboard +``` + +**4. Extract Area Coordinates** +``` +- Dev mode detects area tags +- Displays coordinates +- Exports mapping data +``` + +### Integration with html.to.design + +**Workflow:** +``` +1. Create prototype with Object IDs +2. Use dev mode to verify Object IDs +3. Extract to Figma via html.to.design +4. Object IDs preserved in layer names +5. Maintain traceability +``` + +--- + +## Tool Comparison + +| Tool | Category | Primary Use | Input | Output | WDS Use Case | +|------|----------|-------------|-------|--------|--------------| +| **MCP Server** | Figma Integration | Automated sync | HTML + Object ID | Figma components | Precise refinement (PRIMARY) | +| **html.to.design** | HTML → Figma | Full-page conversion | HTML/CSS | Figma file | Fallback method (OPTIONAL) | +| **NanoBanana** | AI Design | Asset creation + Sketch envisioning | Text/Sketch/Spec | Images or Code | Early exploration OR sketch-to-design (OPTIONAL) | +| **Area Tags** | Region mapping | Clickable regions | Image + coords | Clickable map | Image prototypes | +| **Dev Mode** | ID extraction | Object ID tracking | Prototype | Object IDs | Traceability | + +--- + +## Recommended Workflow + +### Standard Flow (MCP Server - Recommended) + +``` +1. Create specification (Phase 4C) +2. Build HTML prototype manually (Phase 4D) +3. Add Object IDs to all components +4. Test functionality +5. Inject specific components to Figma via MCP server (if needed) +6. Refine in Figma +7. Read refined components via MCP server +8. Design system auto-updated +9. Re-render prototype +``` + +**Advantages:** +- Component-level precision +- Object ID traceability maintained +- Automated design system updates +- Bidirectional sync + +### Alternative Flow (Manual Upload - Fallback) + +``` +1. Create specification (Phase 4C) +2. Build HTML prototype manually (Phase 4D) +3. Add Object IDs to all elements +4. Test functionality +5. Upload to html.to.design (if MCP unavailable) +6. Manually add Object IDs to Figma layers +7. Refine in Figma +8. Manually extract design tokens +9. Update design system manually +10. Re-render prototype +``` + +**Use when:** MCP server not available + +### With Asset Creation (NanoBanana - Optional) + +``` +1. Create specification (Phase 4C) +2. Use NanoBanana for design inspiration/assets (optional) +3. Import assets to Figma +4. Build HTML prototype manually (Phase 4D) +5. Add Object IDs to all components +6. Test functionality +7. Inject to Figma via MCP server (if needed) +8. Refine in Figma (with NanoBanana assets) +9. Read back via MCP server +10. Design system auto-updated +11. Re-render prototype +``` + +**Use NanoBanana for:** +- Creating custom graphics/icons +- Generating design inspiration +- Exploring visual concepts +- Creating placeholder assets + +### Image-Based Flow (With Area Tags) + +``` +1. Create specification (Phase 4C) +2. Create image-based prototype +3. Add area tags for clickable regions +4. Include Object IDs in area tags +5. Test click regions +6. Extract to Figma via html.to.design +7. Refine in Figma +8. Convert to HTML prototype +9. Update design system +``` + +--- + +## Cost Considerations + +### html.to.design +- Free tier available +- Paid plans for advanced features +- Check current pricing at website + +### NanoBanana +- Pricing varies by usage +- Check current pricing at website +- Consider cost vs time savings + +### Area Tags +- Free (standard HTML) +- No additional cost + +### Dev Mode +- Free (included in WDS) +- No additional cost + +--- + +## Troubleshooting + +### html.to.design Issues + +**Problem:** Layout not preserved +**Solution:** Use Flexbox/Grid, simplify structure + +**Problem:** Styles not converted +**Solution:** Use standard CSS properties, avoid complex selectors + +**Problem:** Text content missing +**Solution:** Ensure text is in HTML, not JavaScript-generated + +### NanoBanana Issues + +**Problem:** Generated code doesn't match design system +**Solution:** Customize output, apply design system manually + +**Problem:** Complex interactions not generated correctly +**Solution:** Review and rewrite interaction logic + +### Area Tag Issues + +**Problem:** Clicks not registering +**Solution:** Verify coordinates, check map name matches + +**Problem:** Accessibility concerns +**Solution:** Add keyboard support, use actual HTML when possible + +### Dev Mode Issues + +**Problem:** Object IDs not copying +**Solution:** Check Shift key, verify Object IDs exist + +**Problem:** Dev mode not activating +**Solution:** Check script loaded, try Ctrl+E + +--- + +## Resources + +**html.to.design:** +- Website: +- Documentation: Check website for latest docs + +**NanoBanana:** +- Website: +- Documentation: Check website for latest docs + +**HTML Area Tags:** +- MDN Reference: +- W3C Spec: + +**WDS Documentation:** +- Prototype Workflow: `workflows/4-ux-design/interactive-prototypes/` +- Figma Integration: `workflows/5-design-system/figma-integration/` +- Dev Mode: `workflows/4-ux-design/interactive-prototypes/templates/components/` + +--- + +**This reference provides quick access to tool information for WDS design workflows. For detailed workflows, see the specific workflow documentation files.** diff --git a/src/modules/wds/workflows/5-design-system/figma-integration/when-to-extract-decision-guide.md b/src/modules/wds/workflows/5-design-system/figma-integration/when-to-extract-decision-guide.md new file mode 100644 index 00000000..d1901074 --- /dev/null +++ b/src/modules/wds/workflows/5-design-system/figma-integration/when-to-extract-decision-guide.md @@ -0,0 +1,663 @@ +# When to Extract Prototypes to Figma - Decision Guide + +**Purpose:** Help designers decide when to extract HTML prototypes to Figma for visual refinement. + +**Quick Answer:** Extract when the design system is incomplete and the prototype needs visual polish. + +--- + +## Decision Tree + +``` +Prototype Created + ↓ +Does it look polished? + ↓ + ┌─────┴─────┐ + YES NO + ↓ ↓ +Complete Is design system incomplete? + ↓ + ┌─────┴─────┐ + YES NO + ↓ ↓ + Extract to Quick CSS fixes + Figma sufficient + ↓ + Refine design + ↓ + Update design system + ↓ + Re-render prototype + ↓ + Iterate or Complete +``` + +--- + +## Quick Assessment Checklist + +### ✅ Extract to Figma if: + +- [ ] Prototype not visually appealing or unpolished +- [ ] Design system missing components for this view +- [ ] Need to define new design tokens (colors, spacing, typography) +- [ ] Stakeholder presentation requires high-fidelity +- [ ] Multiple similar components need standardization +- [ ] Visual hierarchy unclear +- [ ] Spacing/alignment inconsistent + +### ❌ Don't Extract if: + +- [ ] Prototype already looks good +- [ ] Design system covers all needs +- [ ] Still validating functionality +- [ ] Rapid iteration more important than polish +- [ ] Early exploration phase +- [ ] Internal testing only + +--- + +## Scenarios + +### Scenario 1: First Page in Project + +**Situation:** Creating first prototype, design system is empty + +**Decision:** ✅ **Extract to Figma** + +**Reason:** Need to establish design foundation +- Define color palette +- Set typography scale +- Create spacing system +- Build first components + +**Workflow:** +1. Create basic prototype (functional) +2. Extract to Figma +3. Define complete design system +4. Re-render with design system +5. Use for all subsequent pages + +--- + +### Scenario 2: Similar to Existing Pages + +**Situation:** Design system already has most components needed + +**Decision:** ❌ **Don't Extract** + +**Reason:** Design system sufficient +- Reuse existing components +- Apply existing tokens +- Minor variations can be CSS tweaks + +**Workflow:** +1. Create prototype with design system +2. Test functionality +3. Make minor CSS adjustments if needed +4. Complete + +--- + +### Scenario 3: New Component Type Needed + +**Situation:** Page needs component type not in design system (e.g., data table) + +**Decision:** ✅ **Extract to Figma** + +**Reason:** Need to design new component properly +- Define component structure +- Create variants and states +- Document design tokens +- Add to design system + +**Workflow:** +1. Create basic prototype +2. Extract to Figma +3. Design new component thoroughly +4. Add to design system +5. Re-render prototype +6. Component now available for future use + +--- + +### Scenario 4: Stakeholder Presentation + +**Situation:** Working prototype exists but looks basic, client review tomorrow + +**Decision:** ✅ **Extract to Figma** + +**Reason:** Need polished visuals for presentation +- Apply professional styling +- Refine visual hierarchy +- Add polish (shadows, effects) +- Create presentation-ready mockups + +**Workflow:** +1. Extract current prototype +2. Polish in Figma quickly +3. Present Figma mockups +4. After approval, update design system +5. Re-render for development + +--- + +### Scenario 5: Rapid Prototyping Phase + +**Situation:** Testing multiple concepts quickly, designs will change + +**Decision:** ❌ **Don't Extract** + +**Reason:** Too early for polish +- Focus on functionality +- Validate concepts first +- Avoid polishing throwaway work + +**Workflow:** +1. Create basic prototypes +2. Test with users +3. Iterate on functionality +4. Once concept validated, then extract for polish + +--- + +## Design System Maturity Levels + +### Level 1: Empty (0-5 components) + +**Typical Decision:** Extract to Figma +**Reason:** Need to build foundation +**Focus:** Establish design tokens and core components + +### Level 2: Growing (6-15 components) + +**Typical Decision:** Extract when gaps found +**Reason:** Fill missing pieces +**Focus:** Expand component library strategically + +### Level 3: Mature (16+ components) + +**Typical Decision:** Rarely extract +**Reason:** Most needs covered +**Focus:** Reuse existing, minor variations only + +--- + +## Cost-Benefit Analysis + +### Benefits of Extracting + +**Design Quality:** +- Professional visual polish +- Consistent design system +- Reusable components +- Better stakeholder buy-in + +**Long-term Efficiency:** +- Design system grows +- Future prototypes faster +- Reduced design debt +- Team alignment + +### Costs of Extracting + +**Time Investment:** +- Extraction process: 15-30 min +- Figma refinement: 1-3 hours +- Design system update: 30-60 min +- Re-rendering: 15-30 min +- **Total: 2-5 hours per page** + +**Workflow Overhead:** +- Context switching +- Tool learning curve +- Sync maintenance +- Version tracking + +--- + +## When Time is Limited + +### High Priority: Extract + +**These pages justify the time investment:** +- Landing pages (first impression) +- Onboarding flows (user retention) +- Checkout/payment (conversion critical) +- Dashboard (frequent use) +- Marketing pages (brand representation) + +### Lower Priority: Skip + +**These pages can stay basic:** +- Admin panels (internal use) +- Error pages (rare views) +- Settings pages (utility focus) +- Debug/test pages (temporary) + +--- + +## Team Collaboration Factors + +### Extract When: + +**Designer-Developer Collaboration:** +- Designer needs to define visual direction +- Developer needs clear component specs +- Team needs shared design language + +**Stakeholder Communication:** +- Client needs to approve visuals +- Marketing needs branded materials +- Sales needs demo materials + +### Skip When: + +**Solo Development:** +- One person doing design + dev +- Direct implementation faster +- No handoff needed + +**Internal Tools:** +- Team understands context +- Functionality over aesthetics +- Rapid iteration valued + +--- + +## Quality Thresholds + +### Extract if Prototype Has: + +**Visual Issues:** +- Inconsistent spacing +- Poor typography hierarchy +- Clashing colors +- Misaligned elements +- Unclear visual hierarchy + +**Missing Design Elements:** +- No hover states +- Missing loading states +- Incomplete error states +- No disabled states +- Basic placeholder styling + +**Component Gaps:** +- Custom components needed +- Existing components insufficient +- New patterns required +- Variant expansion needed + +### Don't Extract if Prototype Has: + +**Sufficient Quality:** +- Consistent spacing +- Clear hierarchy +- Appropriate colors +- Aligned elements +- Professional appearance + +**Complete Design System Coverage:** +- All components available +- States defined +- Variants sufficient +- Tokens applied + +--- + +## Iteration Strategy + +### First Iteration + +**Always extract if:** +- Establishing design foundation +- First page in project +- Setting visual direction + +### Subsequent Iterations + +**Extract only if:** +- Significant design system gaps +- New component types needed +- Visual quality insufficient + +### Final Iteration + +**Extract if:** +- Stakeholder presentation +- Production launch +- Marketing materials needed + +--- + +## Practical Examples + +### Example 1: E-commerce Product Page + +**Phase 1: Sketch (Concept)** +- Designer creates hand-drawn sketch of product page +- Shows product gallery, reviews section, rating display +- Rough layout and component placement + +**Phase 2: Specification (Phase 4C)** +- Freya analyzes sketch +- Creates detailed specification: + - Product gallery: Image carousel with thumbnails + - Reviews component: User avatar, rating, text, date + - Rating stars: 5-star display with half-star support +- All Object IDs defined +- Content and interactions specified + +**Phase 3: Prototype (Phase 4D)** +- Freya builds functional HTML prototype +- Uses existing design system (buttons, inputs, cards) +- Product gallery, reviews, ratings are basic/functional but unpolished + +**Initial Assessment:** +- Prototype works functionally ✅ +- Design system has: buttons, inputs, cards +- Missing: product gallery, reviews component, rating stars (visual refinement needed) + +**Decision:** ✅ Extract to Figma + +**Phase 4: Figma Refinement** + +Freya automatically: +1. Analyzes prototype components +2. Identifies missing components (gallery, reviews, ratings) +3. Injects to Figma via MCP server +4. Page: `02-Product-Catalog / 2.3-Product-Detail` + +Designer in Figma: +5. Designs product gallery component (image zoom, transitions) +6. Designs reviews component (typography, spacing, layout) +7. Designs rating component (star icons, colors, states) +8. Applies design tokens (colors, spacing, typography) + +**Phase 5: Design System Update** + +Freya automatically: +9. Reads refined components from Figma +10. Extracts design tokens +11. Updates design system: + - `D-Design-System/components/product-gallery.md` + - `D-Design-System/components/review-card.md` + - `D-Design-System/components/rating-stars.md` + +**Phase 6: Re-render** +12. Freya re-renders prototype with enhanced design system +13. Prototype now polished and professional + +**Result:** +- ✅ Polished product page +- ✅ 3 new reusable components in design system +- ✅ Specification updated (if design evolved) +- ✅ All future product pages can use these components + +--- + +### Example 2: Settings Page + +**Phase 1: Sketch (Concept)** +- Designer creates simple sketch of settings page +- Shows form fields, toggles, save button +- Standard layout, no custom components + +**Phase 2: Specification (Phase 4C)** +- Freya analyzes sketch +- Creates specification: + - Form fields: Email, password, notifications + - Toggle switches: Email notifications, push notifications + - Save button: Standard primary button +- All components exist in design system + +**Phase 3: Prototype (Phase 4D)** +- Freya builds HTML prototype +- Uses existing design system components: + - Form inputs (already designed) + - Toggle switches (already designed) + - Buttons (already designed) +- Prototype looks polished immediately + +**Initial Assessment:** +- Prototype works functionally ✅ +- Prototype looks polished ✅ +- Design system has: forms, toggles, buttons +- All components available +- Internal use only + +**Decision:** ❌ Don't Extract + +**Actions:** +1. Apply existing design system ✅ (already done) +2. Minor CSS tweaks for spacing (if needed) +3. Test functionality ✅ +4. Complete ✅ + +**Result:** +- ✅ Functional, polished page in 30 minutes +- ✅ No Figma extraction needed +- ✅ Design system reuse successful + +--- + +### Example 3: Landing Page + +**Phase 1: Sketch (Concept)** +- Designer creates detailed sketch of landing page +- Hero section with headline, subtext, CTA +- Feature cards with icons and descriptions +- Testimonials with photos and quotes +- Multiple CTA sections throughout + +**Phase 2: Specification (Phase 4C)** +- Freya analyzes sketch +- Creates comprehensive specification: + - Hero section: Large headline, supporting text, primary CTA + - Feature cards: Icon, title, description, learn more link + - Testimonials: User photo, quote, name, company + - CTA sections: Headline, button, background treatment +- All Object IDs defined +- Multi-language content specified + +**Phase 3: Prototype (Phase 4D)** +- Freya builds functional HTML prototype +- Uses basic design system components +- Hero, features, testimonials are functional but basic +- Client presentation in one week (high priority!) + +**Initial Assessment:** +- Prototype works functionally ✅ +- Design system has basic components +- Needs visual refinement: hero section, feature cards, testimonials, CTA sections +- Client presentation next week (high stakes!) + +**Decision:** ✅ Extract to Figma + +**Phase 4: Figma Refinement** + +Freya automatically: +1. Analyzes prototype components +2. Identifies components needing refinement (hero, features, testimonials, CTAs) +3. Injects to Figma via MCP server +4. Page: `01-Marketing / 1.1-Landing-Page` + +Designer in Figma: +5. Designs hero component (brand-critical, high impact) +6. Designs feature cards (icons, layout, spacing) +7. Designs testimonial component (photos, typography) +8. Polishes CTA sections (visual hierarchy, contrast) +9. Applies brand colors, typography, spacing tokens + +**Phase 5: Design System Update** + +Freya automatically: +10. Reads refined components from Figma +11. Extracts design tokens and components +12. Updates design system: + - `D-Design-System/components/hero-section.md` + - `D-Design-System/components/feature-card.md` + - `D-Design-System/components/testimonial.md` + - `D-Design-System/components/cta-section.md` + +**Phase 6: Re-render for Presentation** +13. Freya re-renders prototype with enhanced design system +14. Prototype now presentation-ready + +**Result:** +- ✅ Polished, professional landing page +- ✅ 4 new reusable components for future marketing pages +- ✅ Client presentation ready +- ✅ Design system significantly expanded + +--- + +## Red Flags: When NOT to Extract + +### 🚩 Premature Optimization + +**Sign:** Polishing before validating concept +**Problem:** Wasting time on designs that may change +**Solution:** Validate functionality first, polish later + +### 🚩 Over-Engineering + +**Sign:** Creating design system for one-off pages +**Problem:** Overhead exceeds benefit +**Solution:** Keep it simple for unique pages + +### 🚩 Analysis Paralysis + +**Sign:** Endless refinement cycles +**Problem:** Never shipping +**Solution:** Set "good enough" threshold + +### 🚩 Tool Obsession + +**Sign:** Using Figma because you can, not because you should +**Problem:** Process over progress +**Solution:** Focus on outcomes, not tools + +--- + +## Decision Matrix + +| Factor | Extract | Don't Extract | +|--------|---------|---------------| +| **Design System Maturity** | Empty/Growing | Mature | +| **Visual Quality** | Needs polish | Sufficient | +| **Component Coverage** | Gaps exist | Complete | +| **Stakeholder Needs** | Presentation | Internal | +| **Time Available** | 2-5 hours | < 1 hour | +| **Page Importance** | High priority | Low priority | +| **Iteration Phase** | First/Final | Middle | +| **Team Size** | Collaborative | Solo | + +**Score:** 5+ "Extract" factors → Extract to Figma +**Score:** 5+ "Don't Extract" factors → Skip extraction + +--- + +## Questions to Ask + +Before deciding, ask yourself: + +1. **Does the design system have what I need?** + - Yes → Don't extract + - No → Consider extracting + +2. **Is this page important enough to polish?** + - Yes → Extract + - No → Skip + +3. **Do I have 2-5 hours for refinement?** + - Yes → Can extract + - No → Skip + +4. **Will this create reusable components?** + - Yes → Extract (investment pays off) + - No → Skip (one-off work) + +5. **Is the concept validated?** + - Yes → Safe to polish + - No → Too early + +6. **Do stakeholders need polished visuals?** + - Yes → Extract + - No → Skip + +--- + +## Best Practices + +### DO ✅ + +1. **Extract strategically** + - First page in project + - High-priority pages + - When design system gaps identified + +2. **Batch extractions** + - Extract multiple pages together + - Efficient use of time + - Consistent design decisions + +3. **Document decisions** + - Why extracted + - What was refined + - Design system updates + +4. **Set time limits** + - Don't over-polish + - Good enough is sufficient + - Ship working products + +### DON'T ❌ + +1. **Don't extract everything** + - Selective extraction + - Focus on high-value pages + - Skip low-priority pages + +2. **Don't extract too early** + - Validate concepts first + - Ensure functionality works + - Don't polish throwaway work + +3. **Don't extract too late** + - Don't accumulate design debt + - Address gaps early + - Build design system progressively + +4. **Don't extract without plan** + - Know what needs refinement + - Have clear goals + - Update design system after + +--- + +## Summary + +**Extract to Figma when:** +- Design system is incomplete +- Prototype needs visual polish +- New components required +- Stakeholder presentation needed +- High-priority page +- Time available for refinement + +**Skip extraction when:** +- Design system covers all needs +- Prototype looks sufficient +- Rapid iteration more important +- Low-priority page +- Time constrained +- Early exploration phase + +**Remember:** The goal is shipping polished, functional products. Extract strategically, not automatically. + +--- + +**Use this guide to make informed decisions about when to invest time in Figma refinement versus moving forward with code-based prototypes.** diff --git a/src/modules/wds/workflows/project-analysis/conversation-persistence/README.md b/src/modules/wds/workflows/project-analysis/conversation-persistence/persistence-guide.md similarity index 100% rename from src/modules/wds/workflows/project-analysis/conversation-persistence/README.md rename to src/modules/wds/workflows/project-analysis/conversation-persistence/persistence-guide.md diff --git a/src/modules/wds/workflows/workflow-init/methodology-instructions/README.md b/src/modules/wds/workflows/workflow-init/methodology-instructions/methodology-guide.md similarity index 100% rename from src/modules/wds/workflows/workflow-init/methodology-instructions/README.md rename to src/modules/wds/workflows/workflow-init/methodology-instructions/methodology-guide.md