DOCSEARCHbyAlgolia
Submit Docs

Excalidraw Diagram Skill

repository·main·Indexed 26 days ago

https://github.com/coleam00/excalidraw-diagram-skill

A tool for coding agents to generate high-quality Excalidraw diagrams from natural language. It features a Playwright-based render pipeline for visual validation, brand customization via a color palette, and a set of JSON templates for elements like rectangles, arrows, and text. The skill is designed for agents supporting the .claude/skills/ directory, such as Claude Code or OpenCode.

Tokens
7.3K
Snippets
18
Records
37
Agent score
88%

What's inside excalidraw-diagram-skill

  1. Select appropriate shapes and colors based on semantic meaning

    main

    Avoid using shapes for decoration; use them only to encode meaning. Aim for <30% of text elements to be inside containers.

    Shape Mapping

    Concept TypeShapeUsage
    Labels/DetailsnoneFree-floating text for hierarchy
    Section TitlesnoneUse font size/weight
    Timeline Markerssmall ellipse (10-20px)Visual anchors
    Start/Trigger/InputellipseSoft origin
    End/Output/ResultellipseDestination
    Decision/ConditiondiamondClassic decision symbol
    Process/Action/SteprectangleContained action
    Abstract Stateoverlapping ellipseFuzzy/cloud-like
    Hierarchy Nodelines + textStructure through lines

    Color Principles

    • Semantic Purpose: Every color must correspond to a purpose (start, end, decision, AI, error, etc.) defined in references/color-palette.md.
    • Hierarchy: Use color for text hierarchy (titles vs. details).
    • Contrast: Always pair a darker stroke with a lighter fill.
    • Constraint: Do not invent new colors; use Primary/Neutral or Secondary if a concept doesn't fit existing categories.

  2. Use the Excalidraw Diagram Skill

    main

    Once installed and set up, you can use the skill by providing a natural language description of the diagram you want to create to your coding agent.

    Example Prompt:

    "Create an Excalidraw diagram showing how the AG-UI protocol streams events from an AI agent to a frontend UI"

  3. Set up the Excalidraw render script

    main

    If you are using the render script for the first time, you must synchronize the environment and install the required Chromium browser via Playwright. Run these commands from the project root:

    cd .claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium

  4. Apply modern aesthetic settings to Excalidraw elements

    main

    For professional, clean diagrams, use the following property settings:

    • Roughness: Set roughness: 0 for clean, crisp, technical edges. Use roughness: 1 only for informal brainstorming.
    • Stroke Width:
      • strokeWidth: 1: Thin/elegant for lines, dividers, and subtle connections.
      • strokeWidth: 2: Standard for shapes and primary arrows.
      • strokeWidth: 3: Bold for emphasis (main flow lines).
    • Opacity: Always use opacity: 100. Use color, size, and stroke width to create hierarchy instead of transparency.
    • Markers: Use small dots (10-20px ellipse) instead of full shapes for timeline markers, bullet points, or connection nodes.

  5. Build large or comprehensive diagrams using a section-by-section workflow

    main

    When creating large or technical diagrams, do not attempt to generate the entire JSON file in a single pass due to token limits and quality degradation. Instead, follow a three-phase workflow:

    Phase 1: Build each section

    1. Create the base file: Initialize with the JSON wrapper (type, version, appState, files) and the first section's elements.
    2. Add one section per edit: Dedicate a separate pass to each section. Plan layout, spacing, and connections carefully.
    3. Use descriptive string IDs: Use readable IDs like "trigger_rect" or "arrow_fan_left".
    4. Namespace seeds by section: Prevent ID collisions by using numeric prefixes (e.g., Section 1 uses 100xxx, Section 2 uses 200xxx).
    5. Update cross-section bindings: When a new section connects to a previous one, update the earlier element's boundElements array in the same edit.

    Phase 2: Review the whole

    Check the complete JSON for:

    • Correct cross-section arrow bindings on both ends.
    • Balanced spacing (avoid cramped sections or excessive whitespace).
    • Valid ID and binding references.

    Phase 3: Render & validate

    Run the render-view-fix loop to catch visual issues like overlaps, clipping, or imbalanced composition.

    Section Planning

    Plan boundaries around natural visual groupings. A typical structure includes:

    • Section 1: Entry point / trigger
    • Section 2: First decision or routing
    • Section 3: Main content (hero section)
    • Section 4-N: Remaining phases or outputs.
    {
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}

  6. Determine diagram depth: Simple vs. Comprehensive

    main

    Before generating a diagram, assess the required level of detail to choose between two primary modes:

    Simple/Conceptual Diagrams

    Use abstract shapes and generic labels (e.g., "Input", "Process") when:

    • Explaining mental models or philosophies.
    • The audience does not require technical specifics.
    • The concept is an abstraction (e.g., "separation of concerns").

    Comprehensive/Technical Diagrams

    Use concrete examples, real data, and evidence artifacts when:

    • Diagramming real systems, protocols, or architectures.
    • The diagram is intended for teaching or tutorials (e.g., YouTube videos).
    • The audience needs to see actual formats, event names, or API endpoints.
    • You are showing how multiple technologies integrate.

  7. Render Excalidraw JSON to PNG

    main

    To view your diagram, you must render the .excalidraw JSON file to a PNG image. This is a mandatory step in the workflow to validate visual layout, text clipping, and element positioning.

    Run the following command to generate a PNG in the same directory as your source file:

    cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py <path-to-file.excalidraw>

    After rendering, use a Read tool to inspect the resulting PNG image.

  9. Iterative Render & Validate Workflow

    main

    Do not rely on JSON alone to judge a diagram. Follow this iterative loop to ensure quality:

    1. Render & View: Run the render script and inspect the PNG.
    2. Audit Vision: Compare the rendered result against your original conceptual design (visual hierarchy, eye flow, and pattern usage).
    3. Check for Defects: Look for text clipping, overlapping elements, poorly routed arrows, ambiguous labels, uneven spacing, or unbalanced composition.
    4. Fix: Edit the JSON. Common fixes include:
      • Widening containers for clipped text.
      • Adjusting x/y coordinates for alignment.
      • Adding waypoints to arrow points arrays to route around elements.
      • Repositioning labels or resizing elements.
    5. Repeat: Re-render and re-view until the diagram passes both the vision and defect checks (typically 2-4 iterations).

  10. Implement Multi-Zoom Architecture for comprehensive diagrams

    main

    Comprehensive diagrams should operate at three simultaneous zoom levels to provide context and detail:

    1. Level 1: Summary Flow: A simplified overview of the full pipeline (e.g., Input → Processing → Output) placed at the top or bottom.
    2. Level 2: Section Boundaries: Labeled regions (e.g., "Backend", "Frontend", or "Phase 1") that group related components into visual "rooms".
    3. Level 3: Detail Inside Sections: The inclusion of evidence artifacts, code snippets, and concrete examples within the sections to provide educational value.

  11. Include evidence artifacts in technical diagrams

    main

    For comprehensive/technical diagrams, you must include evidence artifacts to prove accuracy and aid learning. Choose relevant types from the following:

    Artifact TypeWhen to UseHow to Render
    Code snippetsAPIs, integrations, implementation detailsDark rectangle + syntax-colored text
    Data/JSON examplesData formats, schemas, payloadsDark rectangle + colored text
    Event/step sequencesProtocols, workflows, lifecyclesTimeline pattern (line + dots + labels)
    UI mockupsShowing actual output/resultsNested rectangles mimicking real UI
    Real input contentShowing what goes IN to a systemRectangle with sample content visible
    API/method namesReal function calls, endpointsUse actual names from docs, not placeholders

    Key Principle: Show what things actually look like (e.g., real event names like RUN_STARTED) rather than using generic placeholders (e.g., Event 1).

  12. Set up the Excalidraw diagram skill renderer

    main

    The skill uses a Playwright-based render pipeline for visual validation. You can set this up in two ways:

    Option A: Agent-assisted (Recommended) Instruct your coding agent to: "Set up the Excalidraw diagram skill renderer by following the instructions in SKILL.md."

    Option B: Manual Setup Navigate to the references directory and use uv to install dependencies and Playwright Chromium binaries.

    cd .claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium