Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, or concepts.

Excalidraw Diagram Creator Generate .excalidraw JSON files that argue visually , not just display information. Setup: If the user asks you to set up this skill (renderer, dependencies, etc.), see README.md for instructions. Customization All colors and brand specific styles live in one file: references/color palette.md . Read it before generating any diagram and use it as the single source of truth for all color choices — shape fills, strokes, text colors, evidence artifact backgrounds, everything. To make this skill produce diagrams in your own brand style, edit color palette.md . Everything else in this file is universal design methodology and Excalidraw best practices. Core Philosophy Diagrams should ARGUE, not DISPLAY. A diagram isn't formatted text. It's a visual argument that shows relationships, causality, and flow that words alone can't express. The shape should BE the meaning. The Isomorphism Test : If you removed all text, would the structure alone communicate the concept? If not, redesign. The Education Test : Could someone learn something concrete from this diagram, or does it just label boxes? A good diagram teaches—it shows actual formats, real event names, concrete examples. Depth Assessment (Do This First) Before designing, determine what level of detail this diagram needs: Simple/Conceptual Diagrams Use abstract shapes when: Explaining a mental model or philosophy The audience doesn't need technical specifics The concept IS the abstraction (e.g., "separation of concerns") Comprehensive/Technical Diagrams Use concrete examples when: Diagramming a real system, protocol, or architecture The diagram will be used to teach or explain (e.g., YouTube video) The audience needs to understand what things actually look like You're showing how multiple technologies integrate For technical diagrams, you MUST include evidence artifacts (see below). Research Mandate (For Technical Diagrams) Before drawing anything technical, research the actual specifications. If you're diagramming a protocol, API, or framework: 1. Look up the actual JSON/data formats 2. Find the real event names, method names, or API endpoints 3. Understand how the pieces actually connect 4. Use real terminology, not generic placeholders Bad: "Protocol" → "Frontend" Good: "AG UI streams events (RUN STARTED, STATE DELTA, A2UI UPDATE)" → "CopilotKit renders via createA2UIMessageRenderer()" Research makes diagrams accurate AND educational. Evidence Artifacts Evidence artifacts are concrete examples that prove your diagram is accurate and help viewers learn. Include them in technical diagrams. Types of evidence artifacts (choose what's relevant to your diagram): Artifact Type When to Use How to Render Code snippets APIs, integrations, implementation details Dark rectangle + syntax colored text (see color palette for evidence artifact colors) Data/JSON examples Data formats, schemas, payloads Dark rectangle + colored text (see color palette) Event/step sequences Protocols, workflows, lifecycles Timeline pattern (line + dots + labels) UI mockups Showing actual output/results Nested rectangles mimicking real UI Real input content Showing what goes IN to a system Rectangle with sample content visible API/method names Real function calls, endpoints Use actual names from docs, not placeholders Example : For a diagram about a streaming protocol, you might show: The actual event names from the spec (not just "Event 1", "Event 2") A code snippet showing how to connect What the streamed data actually looks like Example : For a diagram about a data transformation pipeline: Show sample input data (actual format, not "Input") Show sample output data (actual format, not "Output") Show intermediate states if relevant The key principle: show what things actually look like , not just what they're called. Multi Zoom Architecture Comprehensive diagrams operate at multiple zoom levels simultaneously. Think of it like a map that shows both the country borders AND the street names. Level 1: Summary Flow A simplified overview showing the full pipeline or process at a glance. Often placed at the top or bottom of the diagram. Example : Input → Processing → Output or Client → Server → Database Level 2: Section Boundaries Labeled regions that group related components. These create visual "rooms" that help viewers understand what belongs together. Example : Grouping by responsibility (Backend / Frontend), by phase (Setup / Execution / Cleanup), or by team (User / System / External) Level 3: Detail Inside Sections Evidence artifacts, code snippets, and concrete examples within each section. This is where the educational value lives. Example : Inside a "Backend" section, you might show the actual API response format, not just a box labeled "API Response" For comprehensive diagrams, aim to include all three levels. The summary gives context, the sections organize, and the details teach. Bad vs Good Bad (Displaying) Good (Arguing) 5 equal boxes with labels Each concept has a shape that mirrors its behavior Card grid layout Visual structure matches conceptual structure Icons decorating text Shapes that ARE the meaning Same container for everything Distinct visual vocabulary per concept Everything in a box Free floating text with selective containers Simple vs Comprehensive (Know Which You Need) Simple Diagram Comprehensive Diagram Generic labels: "Input" → "Process" → "Output" Specific: shows what the input/output actually looks like Named boxes: "API", "Database", "Client" Named boxes + examples of actual requests/responses "Events" or "Messages" label Timeline with real event/message names from the spec "UI" or "Dashboard" rectangle Mockup showing actual UI elements and content ~30 seconds to explain ~2 3 minutes of teaching content Viewer learns the structure Viewer learns the structure AND the details Simple diagrams are fine for abstract concepts, quick overviews, or when the audience already knows the details. Comprehensive diagrams are needed for technical architectures, tutorials, educational content, or when you want the diagram itself to teach. Container vs. Free Floating Text Not every piece of text needs a shape around it. Default to free floating text. Add containers only when they serve a purpose. Use a Container When... Use Free Floating Text When... It's the focal point of a section It's a label or description It needs visual grouping with other elements It's supporting detail or metadata Arrows need to connect to it It describes something nearby The shape itself carries meaning (decision diamond, etc.) Typography alone creates sufficient hierarchy It represents a distinct "thing" in the system It's a section title, subtitle, or annotation Typography as hierarchy : Use font size, weight, and color to create visual hierarchy without boxes. A 28px title doesn't need a rectangle around it. The container test : For each boxed element, ask "Would this work as free floating text?" If yes, remove the container. Design Process (Do This BEFORE Generating JSON) Step 0: Assess Depth Required Before anything else, determine if this needs to be: Simple/Conceptual : Abstract shapes, labels, relationships (mental models, philosophies) Comprehensive/Technical : Concrete examples, code snippets, real data (systems, architectures, tutorials) If comprehensive : Do research first. Look up actual specs, formats, event names, APIs. Step 1: Understand Deeply Read the content. For each concept, ask: What does this concept DO ? (not what IS it) What relationships exist between concepts? What's the core transformation or flow? What would someone need to SEE to understand this? (not just read about) Step 2: Map Concepts to Patterns For each concept, find the visual pattern that mirrors its behavior: If the concept... Use this pattern Spawns multiple outputs Fan out (radial arrows from center) Combines inputs into one Convergence (funnel, arrows merging) Has hierarchy/nesting Tree (lines + free floating text) Is a sequence of steps Timeline (line + dots + free floating labels) Loops or improves continuously Spiral/Cycle (arrow returning to start) Is an abstract state or context Cloud (overlapping ellipses) Transforms input to output Assembly line (before → process → after) Compares two things Side by side (parallel with contrast) Separates into phases Gap/Break (visual separation between sections) Step 3: Ensure Variety For multi concept diagrams: each major concept must use a different visual pattern . No uniform cards or grids. Step 4: Sketch the Flow Before JSON, mentally trace how the eye moves through the diagram. There should be a clear visual story. Step 5: Generate JSON Only now create the Excalidraw elements. See below for how to handle large diagrams. Step 6: Render & Validate (MANDATORY) After generating the JSON, you MUST run the render view fix loop until the diagram looks right. This is not optional — see the Render & Validate section below for the full process. Large / Comprehensive Diagram Strategy For comprehensive or technical diagrams, you MUST build the JSON one section at a time. Do NOT attempt to generate the entire file in a single pass. This is a hard constraint — Claude Code has a ~32,000 token output limit per response, and a comprehensive diagram easily exceeds that in one shot. Even if it didn't, generating everything at once leads to worse quality. Section by section is better in every way. The Section by Section Workflow Phase 1: Build each section 1. Create the base file with the JSON wrapper ( type , version , appState , files ) and the first section of elements. 2. Add one section per edit. Each section gets its own dedicated pass — take your time with it. Think carefully about the layout, spacing, and how this section connects to what's already there. 3. Use descriptive string IDs (e.g., "trigger rect" , "arrow fan left" ) so cross section references are readable. 4. Namespace seeds by section (e.g., section 1 uses 100xxx, section 2 uses 200xxx) to avoid collisions. 5. Update cross section bindings as you go. When a new section's element needs to bind to an element from a previous section (e.g., an arrow connecting sections), edit the earlier element's boundElements array at the same time. Phase 2: Review the whole After all sections are in place, read through the complete JSON and check: Are cross section arrows bound correctly on both ends? Is the overall spacing balanced, or are some sections cramped while others have too much whitespace? Do IDs and bindings all reference elements that actually exist? Fix any alignment or binding issues before rendering. Phase 3: Render & validate Now run the render view fix loop from the Render & Validate section. This is where you'll catch visual issues that aren't obvious from JSON — overlaps, clipping, imbalanced composition. Section Boundaries Plan your sections around natural visual groupings from the diagram plan. A typical large diagram might split into: Section 1 : Entry point / trigger Section 2 : First decision or routing Section 3 : Main content (hero section — may be the largest single section) Section 4 N : Remaining phases, outputs, etc. Each section should be independently understandable: its elements, internal arrows, and any cross references to adjacent sections. What NOT to Do Don't generate the entire diagram in one response. You will hit the output token limit and produce truncated, broken JSON. Even if the di

excalidraw-diagram