whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/excalidraw-integration/guides/excalidraw-guide.md

@@ -0,0 +1,320 @@
+# Excalidraw Guide
+
+**Optional sketching tool integration for visual design thinking**
+
+---
+
+## Overview
+
+Excalidraw is a free, open-source whiteboard tool that creates hand-drawn style diagrams. This integration provides:
+
+- ✅ Setup and configuration guides
+- ✅ WDS-specific workflows
+- ✅ AI collaboration patterns
+- ✅ Export automation (optional)
+- ✅ Component library (optional)
+
+**Status:** Optional - Enable in project configuration
+
+---
+
+## When to Use Excalidraw
+
+### **Perfect For:**
+
+- Digital sketching (alternative to paper)
+- Collaborative design sessions
+- AI-generated layout variations
+- Version-controlled wireframes
+- Iterative design exploration
+
+### **Not Required If:**
+
+- You prefer paper and pen
+- You use other tools (Figma, iPad, etc.)
+- You're comfortable with your current workflow
+
+---
+
+## Quick Start
+
+### **1. Enable in Project**
+
+**Edit:** `project-config.yaml` (or during project initialization)
+
+```yaml
+sketching:
+  tool: excalidraw # or "paper" or "figma" or "other"
+  excalidraw:
+    enabled: true
+    auto_export: false # Auto-generate PNG/SVG on save
+    use_library: true # Load WDS component library
+    grid_size: 20 # Snap to grid (px)
+```
+
+### **2. Install Tools**
+
+**VS Code Extension (Recommended):**
+
+```
+1. Open Extensions (Ctrl+Shift+X)
+2. Search "Excalidraw"
+3. Install "Excalidraw Editor"
+```
+
+**Or use web version:**
+
+- <https://excalidraw.com> (no installation needed)
+
+### **3. Load WDS Library (Optional)**
+
+**If `use_library: true` in config:**
+
+```
+1. Open Excalidraw
+2. Click library icon
+3. Load: workflows/4-ux-design/excalidraw-integration/wds-library.excalidrawlib
+4. Components now available for drag-and-drop
+```
+
+---
+
+## Documentation
+
+### **Setup & Configuration**
+
+→ [excalidraw-setup.md](excalidraw-setup.md)
+
+- Installation options
+- VS Code configuration
+- Project settings
+- Grid and theme setup
+
+### **Sketching Workflow**
+
+→ [sketching-guide.md](sketching-guide.md)
+
+- When to sketch
+- What to sketch
+- How to sketch
+- File organization
+
+### **Export Workflow**
+
+→ [export-workflow.md](export-workflow.md)
+
+- Manual export (PNG/SVG)
+- Automated export (GitHub Actions)
+- File naming conventions
+- GitHub display
+
+### **AI Collaboration**
+
+→ [ai-collaboration.md](ai-collaboration.md)
+
+- AI-generated layouts
+- AI analysis of sketches
+- Iteration workflow
+- Best practices
+
+---
+
+## File Organization
+
+**When Excalidraw is enabled:**
+
+```
+C-Scenarios/[scenario-name]/
+├── sketches/
+│   ├── page-name.excalidraw     ← Source (editable)
+│   ├── page-name.png            ← Export (GitHub display)
+│   └── page-name.svg            ← Export (scalable, optional)
+└── specifications.md
+```
+
+**In specifications.md:**
+
+```markdown
+## Design
+
+![Page Wireframe](./sketches/page-name.png)
+
+[Edit in Excalidraw](./sketches/page-name.excalidraw)
+```
+
+---
+
+## Integration with WDS Workflow
+
+### **Phase 4: UX Design**
+
+**Step 4B-02: Sketch Interface**
+
+**If Excalidraw enabled:**
+
+```
+Agent: "I see you've enabled Excalidraw. Would you like to:
+        1. Sketch manually in Excalidraw
+        2. Have me generate layout variations
+        3. Use paper/pen instead"
+```
+
+**AI can:**
+
+- Generate `.excalidraw` files with layout options
+- Analyze your sketches (upload PNG)
+- Suggest improvements
+- Create variations
+
+---
+
+## Optional Features
+
+### **Component Library**
+
+**File:** `wds-library.excalidrawlib`
+
+Pre-built components:
+
+- Mobile/tablet/desktop frames
+- Buttons, inputs, cards
+- Navigation patterns
+- Common layouts
+
+**Enable:** Set `use_library: true` in config
+
+### **Auto-Export**
+
+**GitHub Actions or pre-commit hooks**
+
+Automatically generates PNG/SVG when you save `.excalidraw` files.
+
+**Enable:** Set `auto_export: true` in config
+
+See: [automation/README.md](automation/README.md)
+
+---
+
+## Comparison with Other Tools
+
+### **Excalidraw vs Paper**
+
+**Excalidraw:**
+
+- ✅ Digital, shareable
+- ✅ AI can generate
+- ✅ Version controlled
+- ✅ Easy to iterate
+- ❌ Requires tool setup
+
+**Paper:**
+
+- ✅ Zero setup
+- ✅ Fast and natural
+- ✅ No distractions
+- ❌ Must photograph/scan
+- ❌ Harder to iterate
+
+### **Excalidraw vs Figma**
+
+**Excalidraw:**
+
+- ✅ Free and open-source
+- ✅ Hand-drawn aesthetic
+- ✅ AI can generate
+- ✅ Simpler, faster
+- ❌ Less precise
+
+**Figma:**
+
+- ✅ Professional tool
+- ✅ Pixel-perfect
+- ✅ Component systems
+- ✅ Team libraries
+- ❌ Steeper learning curve
+- ❌ Requires account
+
+---
+
+## Disabling Excalidraw
+
+**To disable after enabling:**
+
+**Edit:** `project-config.yaml`
+
+```yaml
+sketching:
+  tool: paper # or "figma" or "other"
+  excalidraw:
+    enabled: false
+```
+
+**Agent will:**
+
+- Skip Excalidraw-specific prompts
+- Use generic sketching workflow
+- Not generate `.excalidraw` files
+
+**Your existing files:**
+
+- Remain in project
+- Can still be opened
+- Not automatically deleted
+
+---
+
+## Support
+
+### **Issues with Excalidraw?**
+
+**VS Code extension not working:**
+
+- Restart VS Code
+- Check extension is enabled
+- Try web version as fallback
+
+**Files won't open:**
+
+- Verify JSON is valid
+- Check file extension is `.excalidraw`
+- Try opening in web version
+
+**AI can't generate files:**
+
+- Check core helpers are loaded
+- Verify project config
+- Report issue to WDS
+
+### **Community**
+
+**Excalidraw:**
+
+- Website: <https://excalidraw.com>
+- GitHub: <https://github.com/excalidraw/excalidraw>
+- Discord: <https://discord.gg/UexuTaE>
+
+**WDS:**
+
+- Discord: [WDS community]
+- GitHub: [WDS issues]
+
+---
+
+## Next Steps
+
+**If Excalidraw is enabled:**
+
+1. Install VS Code extension (or use web)
+2. Load WDS library (optional)
+3. Configure grid and theme
+4. Start sketching!
+
+**Learn more:**
+
+- [Setup Guide](excalidraw-setup.md)
+- [Sketching Guide](sketching-guide.md)
+- [AI Collaboration](ai-collaboration.md)
+
+---
+
+**Excalidraw integration is optional but powerful - enable it if digital sketching fits your workflow!** 🎨✨