Module 4.2 — ✏️ excalidraw | Skill Design

🧩 What it is / what it does

The skill excalidraw-diagram-generator converts natural language descriptions into files .excalidraw (JSON) that open directly in Excalidraw — with no additional setup.

💡 Main concept

Excalidraw is a freehand-style diagramming tool (hand-drawn look). The skill turns text into Structured JSON compatible with the Excalidraw schema — elements such as rectangles, ellipses, diamonds, arrows, and text, each with position, size, color, and style properties.

Supported diagram types

🔀 Flowcharts

Process flows with decision nodes (diamonds), start/end nodes (ellipses), and steps (rectangles).

🕸️ Relationship Diagrams

Entities and their connections; useful for data modeling and dependency mapping.

🧠 Mind Maps

Radial layout with a central node and branches expanding in a circle, generated automatically.

🏗️ System Architecture

System components (services, databases, APIs) with arrows showing data flow.

Key Concepts

📄

.excalidraw

JSON format

✋

Hand-drawn

Visual style

🗣️

Natural language

Input

🖱️

No setup

Opens directly

🎣 When it triggers

Claude invokes the excalidraw-diagram-generator when it recognizes one of the trigger phrases listed in the description from the skill.

🎯 Exact triggers (from the skill description)

→ "create a diagram"

→ "make a flowchart"

→ "visualize a process"

→ "draw a system architecture"

→ "create a mind map"

→ "generate an Excalidraw file"

Timeline: from request to file

The user requests the diagram in natural language

E.g.: "Create a flowchart of the deploy process"

Skill activated — Claude chooses the diagram type

Flowchart, relationship, mind map, or system architecture

Generate JSON with elements and coordinates

Each element gets x, y, width, height, strokeColor, backgroundColor, type

Saved .excalidraw file and instructions delivered

The user opens it in excalidraw.com or the local app—no conversion needed

💡 Tip: The skill accepts requests in Portuguese. Just describe the process—Claude infers the steps, connections, and hierarchy without you listing every element.

Key Concepts

🔍

Auto-detection

Diagram type

🗂️

Extraction

From entities

📐

Layout

Positioning

💾

Final file

.excalidraw

🚀 How it improves your pages

Diagrams delivered already editable eliminate the cycle of “create in Figma, export PNG, repeat for every change.”

✓ DO with the skill

✓ Generate a system architecture diagram in the very first conversation
✓ Create an onboarding flow to include in docs or presentations
✓ Map dependencies between code modules in a mind map
✓ Use the delivered file as an editable draft in Excalidraw

✗ AVOID

✗ Expecting pixel-perfect rendering — the style is intentionally "sketch"
✗ Request formal UML diagrams with strict notation (use Mermaid for this)
✗ Generate more than ~40 nodes in a single call — quality degrades
✗ Use as a substitute for precise vector tools (Illustrator, Figma)

📊 Concrete value in the final result

Editable

Delivered as JSON, any element can be moved, recolored, or deleted in Excalidraw without recreating everything.

Iterative

Adjustment requests ("add a cache node between the server and the database") generate a new file in seconds.

Exportable

Excalidraw exports to PNG/SVG with a transparent background — fits into any doc or slide.

Key Concepts

🔄

Rapid iteration

Seconds/adjustment

🖊️

Editable

Open JSON

📤

Export PNG/SVG

For docs

⏱️

No tools

extra

⚙️ How it works under the hood

6-step pipeline defined in SKILL.md: understand → choose type → extract structure → generate JSON → format output → save and instruct.

📦 Skill tech stack

excalidraw-schema.md

Complete Excalidraw JSON schema: element types, required properties, valid values.

element-types.md

Detailed specifications for rectangle, ellipse, diamond, arrow, line, and text — with JSON examples.

split-excalidraw-library.py

Python script that explodes a .excalidrawlib into individual icons for use in diagrams with external libraries (AWS, Material, etc.).

Starter templates

flowchart-template.json

Basic structure for flowcharts — nodes connected in a linear sequence with branching support.

relationship-template.json

Grid layout for relationship diagrams — entities arranged in a matrix with bidirectional arrows.

mindmap-template.json

Radial layout — central node with branches expanding in an arc, generated using trigonometric angle calculations.

⚙️ Technical detail: Element IDs are generated automatically (random 20-character strings) to ensure uniqueness within the JSON. Arrows reference the IDs of the source and destination nodes in the fields startBinding e endBinding.

✓ Simple diagrams (recommended)

• Flowchart: 5–15 nodes
• Mind map: 1 center + up to 8 branches
• Relationships: up to 10 entities
• Architecture: 6–12 components

✗ Avoid — degrades quality

• More than 40 elements in one call
• Diagrams with dense overlap
• Labels longer than 3–4 words
• Hierarchies with more than 4 levels

Key Concepts

🗺️

JSON schema

Excalidraw

🔗

Bindings

Start/End IDs

🐍

split-library.py

External icons

📐

Radial layout

Trigonometry

💬 Practical example + Ready-to-use PROMPT

Three real-world scenarios: a process flowchart, system architecture with icons, and a strategy mind map.

📋 Scenario 1 — Deployment process flowchart

You want to visually document your team's CI/CD pipeline in the README.

Create a flowchart of our deployment process: 1. Developer pushes to the branch 2. CI runs tests (if they fail → notify Slack and stop) 3. Build the Docker image 4. Deploy to staging 5. Smoke tests (if they fail → automatic rollback) 6. Manual approval by the tech lead 7. Deploy to production 8. Monitor for 10 minutes Save as deploy-flow.excalidraw

🏗️ Scenario 2 — Microservices Architecture

Architecture diagram for a technical presentation to the team.

Draw a system architecture diagram with these components: - React frontend (browser) - API Gateway - Auth Service (JWT) - Product Service - Order Service - PostgreSQL (shared) - Redis cache (between API Gateway and services) - Notification Service (async via message queue) Show data flow arrows. Output: microservices-arch.excalidraw

🧠 Scenario 3 — Product mind map

Create a mind map for "Product Launch": Center: Q3 Launch Main branches: Marketing, Product, Eng, Data, Support - Marketing → email campaign, social ads, landing page - Product → feature flags, onboarding, changelog - Eng → gradual deployment, monitoring, rollback plan - Data → activation metrics, funnel, cohorts - Support → FAQ, training, escalation Save: lancamento-q3.excalidraw

🎯 Expected result: A file .excalidraw with all elements positioned. Open in excalidraw.com or in the desktop app—no additional installation needed. Adjust colors and positions freely after generation.

Key Concepts

🔀

Flowchart

Linear process

🏗️

System arch

Components

🧠

Mind map

Radial

📎

Name the file

In the prompt

🧬 Works well with / limitations — and the contrast with beautiful-mermaid

Excalidraw and beautiful-mermaid complement each other: one for visual sketches, the other for precise technical diagrams.

🔬 Excalidraw vs beautiful-mermaid — when to use each?

✏️ Excalidraw

• Style hands-free — relaxed look, ideal for presentations and wireframes
• File editable — you open and adjust each element on the canvas
• No formal notation — complete layout freedom
• Best for: onboarding, casual technical docs, visual brainstorming

📊 beautiful-mermaid

• Style clean technical — precise rendering based on Mermaid text
• Code as the source — versionable diagrams in Git
• Formal notation: Sequence, Class, Gantt, ER, C4, Git graph
• Best for: PRs, technical READMEs, API documentation, reports

Rule of thumb: if the diagram is going into a deck or presentation → Excalidraw. If it goes to README or PR → beautiful-mermaid.

Works with these course skills

📊 beautiful-mermaid(T4 • 4.1)

Use Excalidraw for the initial draft, then convert it to Mermaid when you need a versionable, precise diagram in the repo.

🔭 website-intelligence(T4 • 4.4)

Extract a site's structure with website-intelligence, then visualize its information architecture in an Excalidraw diagram.

🧱 web-artifacts-builder(T1 • 1.3)

Map the component architecture with Excalidraw before building with web-artifacts-builder — the diagram becomes the visual specification.

🕹️ agent-browser(T4 • 4.3)

Automate opening and screenshotting the .excalidraw file in the browser with agent-browser to integrate the diagram into documentation pipelines.

⚠️ Skill limitations

• Doesn't support formal UML diagrams (use Mermaid classDiagram or sequenceDiagram)
• Icons from external libraries (AWS, Material) require manual setup with split-excalidraw-library.py
• Node positioning is approximate — very complex layouts may need manual adjustment
• Doesn't replace vector tools for precise UI design

Key Concepts

✏️

Hands-free

vs. technical

🔗

Complementary

with Mermaid

🚫

No formal UML

Limitation

🏆

Presentations

Ideal use case

✅ Module 4.2 Summary

✓ The skill excalidraw-diagram-generator generates files .excalidraw from natural-language descriptions

✓ Supports flowcharts, relationship diagrams, mind maps, and system architecture

✓ The output is pure JSON compatible with Excalidraw—no conversion needed; it opens directly

✓ Internally uses a JSON schema + templates (flowchart, relationship, mindmap)

✓ External icons (AWS, Material) via split-excalidraw-library.py with manual setup

✓ Complements beautiful-mermaid: freehand style for presentations vs. technical style for repos

✓ Ideal complexity: 5–15 nodes; avoid more than 40 elements per call

✓ Works with website-intelligence, web-artifacts-builder, and agent-browser

Next module

🕹️

4.3 — agent-browser

Playwright browser automation: navigation, screenshots, data extraction, and web testing directly through Claude Code.

← Back to Track 4 Next Module: 4.3 agent-browser →