ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md

5.7 KiB
Raw Blame History

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)

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:

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

  • Installation options
  • VS Code configuration
  • Project settings
  • Grid and theme setup

Sketching Workflow

→ sketching-guide.md

  • When to sketch
  • What to sketch
  • How to sketch
  • File organization

Export Workflow

→ export-workflow.md

  • Manual export (PNG/SVG)
  • Automated export (GitHub Actions)
  • File naming conventions
  • GitHub display

AI Collaboration

→ 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:

## 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

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

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:

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:

Excalidraw integration is optional but powerful - enable it if digital sketching fits your workflow! 🎨✨