Hs:excalidraw

Excalidraw Diagram Skill

Generate diagrams that argue visually — shapes mirror meaning, not just labeled boxes.

Mode Detection (Do This First)

This skill supports two rendering backends. Detect which is available:

Mode A — MCP Canvas (preferred): Test with mcp__excalidraw__read_diagram_guide(). If it works, use MCP tools for live canvas editing. See references/mcp-workflow.md.

Mode B — File-based (fallback): Generate .excalidraw JSON files, render to PNG via Playwright. No server needed. See references/file-workflow.md.

If neither is set up, guide the user through setup (see respective workflow files).

Core Philosophy

Diagrams should ARGUE, not DISPLAY.

• Isomorphism Test: Remove all text — does the structure alone communicate the concept?
• Education Test: Could someone learn something concrete, or does it just label boxes?
• Container Test: Could any boxed element work as free-floating text? If yes, remove the box.

Default to free-floating text. Add containers only when shapes carry meaning. Aim for <30% of text elements inside containers.

Design Process (Before Generating Anything)

Step 0: Assess Depth

For technical diagrams: Research actual specs, event names, APIs before drawing. Include evidence artifacts. See references/design-methodology.md.

Step 1: Map Concepts to Visual Patterns

Each major concept should use a different visual pattern — no uniform card grids.

Step 2: Plan Layout

Guide the eye: typically left→right or top→bottom. Important elements get more whitespace.

Step 3: Generate & Validate

Follow the workflow for your active mode (MCP or file-based).

Auto-Diagram (Zero-Config Codebase Analysis)

When user says "diagram this repo", "visualize the architecture", or "auto diagram":

Follow the full pipeline in references/auto-diagram-guide.md:

1. Detect project type and framework
2. Discover components (max 15 tool calls)
3. Map connections (max 10 tool calls)
4. Verify with user before drawing
5. Select layout pattern
6. Generate diagram using active mode

Limits: Max 12 components, 20 arrows per diagram. Group if more found.

Color Quick Reference

Pull colors from references/color-palette.md (single source of truth).

Rule: Same-role shapes get same colors. Max 3-4 fill colors per diagram.

Shape Reference

Sizing Rules

Err on the side of too much space. Tight spacing is the #1 mistake.

Modern Aesthetics

• roughness: 0 for clean/modern (default), 1 for hand-drawn
• strokeWidth: 2 standard, 1 subtle, 3 emphasis
• opacity: 100 always — use color/size for hierarchy, not transparency
• fontFamily: 3 (monospace)
• Arrow labels: strokeStyle: "dashed" for async, "dotted" for weak deps

Self-Critique Loop (Both Modes)

After generating, validate before presenting:

1. Render/screenshot — view the actual output
2. Audit vs. vision — does structure match the planned design?
3. Check defects — overlaps, clipped text, misrouted arrows, uneven spacing
4. Fix — adjust coordinates, widen containers, reroute arrows
5. Re-render — repeat until clean (typically 2-4 iterations, max 2 for MCP)

Stop when: no clipped text, arrows connect correctly, spacing consistent, balanced composition.

Quality Checklist

• Research done (for technical diagrams)
• Evidence artifacts included (code snippets, real data)
• Multi-zoom: summary + sections + detail
• Each concept uses different visual pattern
• Minimal containers (<30% text in boxes)
• Lines as structure for trees/timelines
• All relationships have arrows
• Clear visual flow path
• roughness: 0, opacity: 100, fontFamily: 3
• Rendered and visually validated
• No overlapping/clipped elements
• Balanced composition

References (Load As Needed)

For universal SVG layout rules that apply across any rendered SVG output, load /hs:tech-graph and apply its spacing, arrow routing, label placement, and z-index ordering guidance. Useful when reviewing exported Excalidraw SVGs for collisions or unreadable labels.