excalidraw-generation_skill

Overview

This skill generates hand-drawn, Excalidraw-style diagrams optimized for developer-facing presentations and informal visual explanation. It combines semantic analysis of the user's request with evidence-based design guardrails to produce accessible, minimal, and aesthetically consistent Excalidraw JSON. I output ready-to-render .excalidraw files and require automated SVG rendering via the provided script.

How this skill works

I analyze the user's prompt or slide content to extract core concepts (entities, relationships, flows) and classify the semantic type (containment, flow, comparison, hierarchy, grouping, annotation). I select an appropriate layout, build the diagram using element factories (rectangles, ellipses, arrows, frames, callouts) while enforcing cognitive and accessibility constraints, then save the JSON to diagrams/<slug>.excalidraw. Finally, I mandate running the supplied render-excalidraw.sh script to produce the SVG; I never embed raw JSON in markdown or attempt manual conversion.

When to use it

• When the user asks to “create excalidraw diagram”, “generate excalidraw”, “hand-drawn diagram”, “sketch diagram”, or “whiteboard style diagram”.
• When spatial or conceptual relationships (architecture, containment, hierarchy) are primary.
• During brainstorming, ideation, or early-stage design reviews where informal visuals help.
• When annotations or callouts will clarify intent without creating visual clutter.
• When a single clear idea can be shown within strict cognitive limits.

Best practices

• Strictly enforce the cognitive-load limit: max 9 visual elements (7±2 recommended).
• Use the colorblind-safe palette only: Primary blue #3b82f6 and accent orange #f97316; never rely on color alone.
• Keep total diagram text under 50 words and present one idea per diagram; split complex concepts into multiple diagrams.
• Ensure text contrast meets WCAG AA (>=4.5:1) and use hand-drawn roughness=1 for informal aesthetic.
• Always save JSON to diagrams/<slug>.excalidraw and run ${CLAUDE_PLUGIN_ROOT}/scripts/render-excalidraw.sh to produce the SVG — no manual SVG conversion.

Example use cases

• High-level architecture diagram showing service boundaries and data flow between 3–7 components.
• Mind map or brainstorming sketch with a central idea and 3–6 branches (radial layout).
• Vertical containment diagram for platform vs. tenant boundaries using nested frames.
• Annotated flowchart for an onboarding process with arrows and 3–6 labeled steps.
• Side-by-side comparison diagram (pros vs cons) with minimal labels and color + shape cues.