Architecture
Structure
Skill explainer · cathrynlavery/diagram-design
Diagram Design
Forty-five editorial diagram types, one rule above all: delete until nothing can be removed.
A Claude/Cursor skill that writes self-contained HTML with inline SVG in a skinnable editorial system. It routes a request through 9 semantic patterns to 45 type references, ships importers for draw.io, Excalidraw and Mermaid, and backs its charts with geometry verifiers. I read the skill, ran all 74 repository checks and the 6 shipped scripts. The highest-quality move is usually deletion.
v2.6.119plugin version
7a12007commit, 21 Oct 2026
45visual types
6commands
6skill scripts
74/74repo checks pass
Who it is for
Anyone who wants a diagram that looks designed rather than generated: architecture, charts, journeys, maps.
What you get
One HTML file per diagram, optional SVG/PNG export, and a brand profile you can save and reload.
How It Works
It Picks A Pattern, Then A Type, Then Asks
The skill is a router. Behavior picks the pattern, the pattern picks the nearest layout, and the plan is confirmed before anything is drawn.
1
Style gate. If they are still the shipped defaults (paper #f5f5f5, ink #2d3142, accent #bf4520), pause and ask the user.
2
Semantic pattern. When behavior, state, enforcement, or risk carries the meaning, first load semantic-patterns.md.
3
Visual type. Always load the chosen type reference linked in the guide before drawing.
4
Confirm. Before rendering, state the plan in one short message: the chosen visual type (and semantic pattern, if routed), the size preset, and anything the complexity budget (§7) will force out.
5
Density. Target density: 4/10. Enough to be technically complete. Not so dense it needs a guide. Above 9 nodes, it's probably two diagrams.
The 9 Semantic Patterns
| Behavioral trigger | Pattern | Nearest type |
|---|---|---|
| Fan-in, queue depth, finite capacity, bottleneck | Fan-in queue / bottleneck | Data flow |
| Repeated Question / Input / Governance / Output slots across stages | Stage framework with semantic slots | Process |
| Conversation or loose input becomes a structured durable artifact | Unstructured input → structured artifact | Data flow |
| Two rule traces need pass/fail/skipped/not-reached and first divergence | Paired policy-evaluation traces | Flowchart |
| Trust boundaries plus permitted/forbidden ingress or deploy paths | Secure paved road | Architecture |
| Controls grouped by where they are enforced | Governance / control catalog | Layer stack |
| Defenses compensate for prior gaps and residual risk propagates | Compensating security layers | Layer stack |
| Hierarchical, ID-addressable decomposition needing per-block I/O, constraints, and a code link | Traceable block decomposition | Tree |
| One subject progresses through phases, waits, retries, cancellation, and terminal outcomes | Lifecycle phase map | State Machine |
The Types
Every Type Is A Reference File With Rules And Anti-Patterns
Pick a type. The tag is the row from the SKILL.md §3 guide; How it works lists the reference file’s layout conventions; the quotes are its own anti-patterns, all checked at build time.
Gallery
The Repo’s Own Renders For 45 Types
Screenshots shipped in docs/screenshots, one per type. Click to enlarge.
Architecture delta
Structure
IT current-state
Structure
Flowchart
Flow & behavior
Sequence
Flow & behavior
State machine
Flow & behavior
ER / data model
Structure
Timeline
Time & planning
Swimlane
Flow & behavior
Quadrant
Charts
Radar / Spider
Charts
Polar chart
Charts
Loop
Flow & behavior
Nested
Structure
Tree
Structure
Org chart
Structure
Layer stack
Structure
Exploded axonometric
Spatial
Axonometric plan
Spatial
Venn
Charts
Pyramid / funnel
Charts
Bar chart
Charts
Waterfall
Charts
Treemap
Charts
Heatmap
Charts
Line chart
Charts
Gantt
Time & planning
Scatter plot
Charts
High-Level
Structure
Process
Flow & behavior
Medallion
Structure
Data flow
Flow & behavior
DP integration
Structure
DP security matrix
Structure
Sankey
Flow & behavior
Fishbone
Time & planning
Wardley map
Time & planning
Kanban
Time & planning
User journey
Flow & behavior
Service blueprint
Flow & behavior
Deployment
Structure
Dependency graph
Structure
UML class
Structure
Story map
Time & planning
Database schema
Structure
Commands And Scripts
Importers Parse; The Skill Redraws
Six slash commands drive the workflow. Six stdlib-first scripts do the deterministic work, and I ran each one.
Taste
It Names The Slop It Refuses To Make
The universal anti-patterns from SKILL.md §4, verbatim.
| Anti-pattern | Why it fails |
|---|---|
| Dark mode + cyan/purple glow | Looks "technical" without design decisions |
| JetBrains Mono as blanket "dev" font | Mono is for technical content — ports, commands, URLs. Names go in Geist sans. |
| Identical boxes for every node | Erases hierarchy |
| Legend floating inside the diagram area | Collides with nodes |
| Arrow labels with no masking rect | Bleeds through the line |
Vertical writing-mode text on arrows | Unreadable |
| 3 equal-width summary cards as default | Generic grid — vary widths |
| Shadow on any element | Shadows are out. Borders are in. |
rounded-2xl on boxes | Max radius 6–10px or none |
| Coral on every "important" node | Coral is 1–2 editorial accents, not a signaling system |
| Reproducing Mermaid's renderer layout | Imports automatic spacing and routing instead of making an editorial layout |
| Any breach of the six §6 connector rules | Automatic fail: diagonal slants, labels touching their stroke, masks clipped by a later node, overlapping paths, shared attach points, transit behind a non-endpoint box |
What I Found Running It
The Code Is Solid; The Runner Is Inconsistent
I ran 74 repository checks (every scripts/test-*.py and verify-*.py) plus the 6 skill scripts on the box, with nice and timeout, at commit 7a12007.
| Run | Result | Note |
|---|---|---|
| 74 repo checks, first pass | 59 pass, 15 fail | 12 verifiers exit 2 when given no paths; 3 Playwright tests fail before Chromium is installed. |
| Same 15, rerun correctly | 15/15 pass | After playwright install chromium and adding --all (or --shipped for verify-motion). |
| self_check.py over 217 assets | 215 OK, 2 FAIL | icons.html and index.html are galleries, not diagrams; exit code 1 for the batch. |
| 3 extractors on fixtures | pass | draw.io: 12 nodes / 8 edges, node budget flagged OVER (max 9). |
| export_svg / export_png | pass | 9 KB SVG and 38 KB PNG from example-waterfall.html. |
| git status after all runs | clean | No files written into the repo. |
Gap Verifier flags disagree
Most verifiers take --all; verify-motion takes --shipped and rejects --all. Without a flag they print usage and exit 2, which reads like a failure in CI.
Gap Playwright is a silent prerequisite
Three tests and PNG export need a downloaded Chromium. The export command documents this; the test scripts just crash with a stack trace.
Gap Version drift
plugin.json says 2.6.119; SKILL.md metadata says 2.6.
Bug Escaped IR headers
drawio_extract and excalidraw_extract print the file name markdown-escaped (sample\-architecture\.drawio); mermaid_extract does not.
Copy Untrusted-input stance in parsers
The Excalidraw and Mermaid extractors treat labels as data and discard links and payloads. That is the right default for anything an agent reads.
Copy Verifiers for the chart math
Waterfall, Sankey, beeswarm and others check the rendered geometry against declared values, so a plausible-but-wrong chart fails.
Build Your Own
What To Steal
One reference file per output type. Each has Best for, layout rules and anti-patterns. The agent loads only the one it needs.
Route by meaning before layout. A semantic pattern picks the behavior; the type picks geometry.
Gate on brand tokens. Refuse to ship defaults into a branded project without asking.
Confirm the plan in one message. Type, size and what the budget cuts, before drawing.
Ship the checker. self_check.py lets the agent verify its own file.
Sources
Everything Here Is Checked
Each quote on this page is compared with its source file at build time; the build fails on any mismatch.