Skill · excalidraw-diagram

The Excalidraw Diagram Creator

Generate .excalidraw JSON files where the shape itself carries the meaning — diagrams that make a visual argument instead of merely labeling boxes.

DISPLAY → ARGUE

Core Philosophy

The structure should be the meaning

Before drawing anything, every diagram must survive two tests. If it can't, the shape isn't doing its job.

🧩

Isomorphism Test

Remove all the text — does the structure alone communicate the concept? If meaning collapses without labels, the layout isn't carrying its weight.

🎓

Education Test

Could someone learn something concrete from this — or does it just label boxes? A good diagram teaches a relationship, not a vocabulary list.

Design Process

Seven steps, from intent to delivery

A repeatable pipeline: assess depth, understand, map to patterns, sketch, generate, render-and-fix, then verify.

Assess Depth Fork

Decide which kind of diagram you're making — this branches the whole process.

Simple

Abstract shapes, mental models, labels and relationships.

Comprehensive

Real systems & architecture → read the research mandate, evidence artifacts & multi-zoom guidance.

references/evidence-and-research.md

Understand Deeply

For each concept ask: What does it do? What relationships exist? What's the core flow? What would someone need to see?

Map Concepts to Patterns

Pull from the pattern library — fan-out, convergence, tree, timeline, spiral, cloud, assembly line, side-by-side, gap/break. Each major concept gets a different visual pattern. No uniform cards or grids.

references/visual-patterns.md

Sketch the Flow

Mentally trace how the eye moves through the diagram. There should be a clear visual story from entry to exit.

Generate JSON

Apply container discipline, color rules, aesthetics, layout & text rules. For large diagrams, build one section at a time — never generate the whole thing in one pass.

design-rules.md element-templates.md color-palette.md json-schema.md large-diagram-strategy.md

Render & Validate Mandatory

Render → read the PNG → audit against your vision → fix → repeat. Typically 2–4 iterations.

uv run python render_excalidraw.py <file.excalidraw>

references/render-validate.md

Final Quality Check

Verify all 27 items on the quality checklist before delivering.

references/quality-checklist.md

Reference Library

Progressive disclosure, on demand

The SKILL.md stays lean — detail lives in reference files loaded only when a step needs them.

color-palette.md

Single source of truth for colors & brand styles. Read before generating any diagram.

visual-patterns.md

Concept-to-pattern mapping table & full pattern library.

design-rules.md

Container discipline, color rules, aesthetics, layout & text rules.

element-templates.md

Copy-paste JSON templates per element type.

json-schema.md

Full JSON schema reference.

evidence-and-research.md

Research mandate, evidence artifacts & multi-zoom architecture.

large-diagram-strategy.md

Build comprehensive diagrams section by section.

render-validate.md

The full render → view → fix loop.

quality-checklist.md

The 27-item pre-delivery gate.