From diagram-design
Generates standalone HTML files with inline SVG for 13 diagram types: architecture, flowcharts, sequences, state machines, ERDs, timelines, swimlanes, quadrants, trees, and more. Customizable style guide with first-run onboarding.
npx claudepluginhub cathrynlavery/diagram-design --plugin diagram-designThis skill uses the workspace's default tool permissions.
Create visual diagrams as self-contained HTML files with inline SVG and CSS, following an opinionated editorial design system.
assets/example-architecture-dark.htmlassets/example-architecture-full.htmlassets/example-architecture.htmlassets/example-er-dark.htmlassets/example-er-full.htmlassets/example-er.htmlassets/example-flowchart-dark.htmlassets/example-flowchart-full.htmlassets/example-flowchart.htmlassets/example-layers-dark.htmlassets/example-layers-full.htmlassets/example-layers.htmlassets/example-nested-dark.htmlassets/example-nested-full.htmlassets/example-nested.htmlassets/example-pyramid-dark.htmlassets/example-pyramid-full.htmlassets/example-pyramid.htmlassets/example-quadrant-consultant.htmlassets/example-quadrant-dark.htmlGenerates 13 types of editorial-quality HTML+SVG diagrams (architecture, flowcharts, sequences, ER models, timelines) for blog posts and documentation with brand-matched styling and no external dependencies.
Generates dark-themed SVG diagrams for architecture, flowcharts, sequences, structures, mind maps, timelines, state machines, and data flows to visualize systems, processes, and concepts.
Generates Excalidraw JSON diagram files (.excalidraw) for visualizing workflows, architectures, and concepts as visual arguments with evidence artifacts for technical diagrams.
Share bugs, ideas, or general feedback.
Create visual diagrams as self-contained HTML files with inline SVG and CSS, following an opinionated editorial design system.
Thirteen diagram types. One shared design system, complexity budget, and taste gate. Type-specific conventions live in references/ and are loaded only when you pick a type.
Before generating your first diagram in a new project, verify the style guide has been customized.
Open references/style-guide.md and check the default tokens. If they're still the shipped defaults (paper #faf7f2, ink #1c1917, accent #b5523a rust), pause and ask the user:
"This is your first Schematic in this project. The style guide is still at the default (neutral stone + rust). Do you want to customize it to match your brand first? Options: (a) run onboarding — I'll pull colors and fonts from your website, (b) paste your tokens manually, (c) proceed with the default for now."
Then branch:
references/onboarding.md to fetch the site, extract palette + fonts, propose a diff, and write style-guide.md.style-guide.md under a new "Custom tokens" section.Once the style guide has been customized (or the user explicitly opted for default), skip this gate on subsequent runs. A simple way to detect customization: if the accent value in style-guide.md differs from #b5523a, assume custom.
Don't silently ship default-skinned diagrams into a branded project — that's the failure mode this gate exists to prevent.
The highest-quality move is usually deletion.
From .impeccable.md: "Confident restraint. Earn every element. One color accent, two families, a small spacing vocabulary. If removing it wouldn't hurt the page, remove it."
Applied to schematics:
Target density: 4/10. Enough to be technically complete. Not so dense it needs a guide. Above 9 nodes, it's probably two diagrams.
Use for any of the 13 diagram types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list.
Don't use for:
Before drawing, ask: Would the reader learn more from this than from a well-written paragraph? If no, don't draw.
| If you're showing… | Use | Reference |
|---|---|---|
| Components + connections in a system | Architecture | type-architecture.md |
| Decision logic with branches | Flowchart | type-flowchart.md |
| Time-ordered messages between actors | Sequence | type-sequence.md |
| States + transitions + guards | State machine | type-state.md |
| Entities + fields + relationships | ER / data model | type-er.md |
| Events positioned in time | Timeline | type-timeline.md |
| Cross-functional process with handoffs | Swimlane | type-swimlane.md |
| Two-axis positioning / prioritization | Quadrant | type-quadrant.md |
| Hierarchy through containment / scope | Nested | type-nested.md |
| Parent → children relationships | Tree | type-tree.md |
| Stacked abstraction levels | Layer stack | type-layers.md |
| Overlap between sets | Venn | type-venn.md |
| Ranked hierarchy or conversion drop-off | Pyramid / funnel | type-pyramid.md |
Rules of thumb:
Always load the relevant references/type-*.md before drawing — it contains layout conventions, anti-patterns, and example files for that type.
These mark "AI slop" schematics of any type:
| 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 |
Type-specific anti-patterns live in each references/type-*.md.
The design system is skinnable. All colors, typography, and tokens live in a single source of truth — references/style-guide.md. This file describes semantic roles (paper, ink, muted, accent, link, …). The default skin is a cool editorial palette (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines); to apply your own brand, either edit style-guide.md directly or run the URL-based flow described in references/onboarding.md.
When specs below or in type references mention "ink", "accent", "muted", etc., look up the current hex value in
style-guide.md.
| Role | Purpose |
|---|---|
paper, paper-2 | Page bg and container bg |
ink | Primary text / stroke |
muted, soft | Secondary text, default arrows, sublabels |
rule, rule-solid | Hairline borders |
accent, accent-tint | 1–2 focal elements per diagram |
link | HTTP/API calls, external arrows |
Focal rule: accent goes on 1–2 elements max. Everything else is ink / muted / soft. If you're tempted to accent 4 things, you haven't decided what's focal yet.
| Type | Fill | Stroke |
|---|---|---|
| Focal (1–2 max) | accent-tint | accent |
| Backend / API / Step | white | ink |
| Store / State | ink @ 0.05 | muted |
| External / Cloud | ink @ 0.03 | ink @ 0.30 |
| Input / User | muted @ 0.10 | soft |
| Optional / Async | ink @ 0.02 | ink @ 0.20 dashed 4,3 |
| Security / Boundary | accent @ 0.05 | accent @ 0.50 dashed 4,4 |
Mono is for technical content. Names are Geist sans. Page title is Instrument Serif. Italic Instrument Serif is reserved for annotation callouts. Never JetBrains Mono as a blanket "dev" font.
<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&display=swap" rel="stylesheet">
Universal building blocks. Type-specialized primitives (lifeline, activation bar, region) live in the relevant references/type-*.md. Optional primitives:
Default: clean paper, no dot pattern. Single <rect> filled with paper. Don't wrap the diagram in a secondary container background — the diagram sits directly on the page.
<rect width="100%" height="100%" fill="#f5f5f5"/>
Optional: dotted paper variant. When a long-form editorial diagram benefits from textured ground (essays, hero diagrams on a dedicated page), opt in by adding the dots pattern and a second rect:
<defs>
<pattern id="dots" width="22" height="22" patternUnits="userSpaceOnUse">
<circle cx="1" cy="1" r="0.9" fill="rgba(45,49,66,0.10)"/>
</pattern>
</defs>
<rect width="100%" height="100%" fill="#f5f5f5"/>
<rect width="100%" height="100%" fill="url(#dots)" opacity="0.6"/>
Don't use the dot pattern when the diagram sits inside a product page, slide, or card — the texture compounds with surrounding chrome and reads as noise.
<marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
<polygon points="0 0, 8 3, 0 6" fill="#4f5d75"/>
</marker>
<marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
<polygon points="0 0, 8 3, 0 6" fill="#eb6c36"/>
</marker>
<marker id="arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
<polygon points="0 0, 8 3, 0 6" fill="#2e5aa8"/>
</marker>
| Arrow | Stroke | When |
|---|---|---|
| Default | muted #4f5d75 | Internal, generic |
| Accent | coral #eb6c36 | Primary / highlighted / headline |
| Link-blue | #2e5aa8 | HTTP/API calls, external systems |
| Dashed | stroke-dasharray="5,4" + any color | Optional, passive, return, async |
Draw arrows before boxes so z-order puts lines behind nodes.
<!-- 1. Opaque paper mask — prevents arrows bleeding through transparent fills -->
<rect x="X" y="Y" width="W" height="H" rx="6" fill="#f5f5f5"/>
<!-- 2. Styled box -->
<rect x="X" y="Y" width="W" height="H" rx="6" fill="FILL" stroke="STROKE" stroke-width="1"/>
<!-- 3. Rectangular type tag (rx=2, NOT a pill) -->
<rect x="X+8" y="Y+6" width="28" height="12" rx="2" fill="transparent" stroke="STROKE@0.40" stroke-width="0.8"/>
<text x="X+22" y="Y+15" fill="STROKE@0.8" font-size="7" font-family="'Geist Mono', monospace"
text-anchor="middle" letter-spacing="0.08em">API</text>
<!-- 4. Node name (Geist sans — human-readable) -->
<text x="CX" y="CY+2" fill="#2d3142" font-size="12" font-weight="600"
font-family="'Geist', sans-serif" text-anchor="middle">Node Name</text>
<!-- 5. Technical sublabel (Geist Mono) -->
<text x="CX" y="CY+18" fill="#4f5d75" font-size="9"
font-family="'Geist Mono', monospace" text-anchor="middle">tech:port</text>
Every arrow label needs an opaque rect behind it. Without one it bleeds through the line.
<rect x="MID_X-18" y="ARROW_Y-12" width="36" height="12" rx="2" fill="#f5f5f5"/>
<text x="MID_X" y="ARROW_Y-3" fill="#7a8399" font-size="8"
font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.06em">WRITE</text>
Rules: ≤14 characters, all-caps, centered on segment midpoint, 8–10px above line. Never writing-mode vertical.
Never put the legend inside the diagram area. Place as a horizontal strip after all nodes, with a hairline separator:
<line x1="30" y1="LEGEND_Y-8" x2="VIEWBOX_W-30" y2="LEGEND_Y-8"
stroke="rgba(45,49,66,0.10)" stroke-width="0.8"/>
<text x="30" y="LEGEND_Y+8" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace"
letter-spacing="0.14em">LEGEND</text>
<!-- Items — horizontal row, ~160px apart -->
Expand SVG viewBox height by ~60px.
All values — font sizes, padding, node dimensions, gaps, x/y coords — divisible by 4. Non-negotiable.
| Category | Allowed values |
|---|---|
| Font sizes | 8, 12, 16, 20, 24, 28, 32, 40 |
| Node width / height | 80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320 |
| x / y coordinates | multiples of 4 |
| Gap between nodes | 20, 24, 32, 40, 48 |
| Padding inside boxes | 8, 12, 16 |
| Border radius | 4, 6, 8 |
Exempt: stroke widths (0.8, 1, 1.2), opacity values, and the 22×22 dot-pattern.
Quick check: if a coordinate ends in 1, 2, 3, 5, 6, 7, 9 — fix it.
| Limit | Rule |
|---|---|
| Max nodes | 9 |
| Max arrows / transitions | 12 |
| Max coral elements | 2 |
| Max lifelines (sequence) | 5 |
| Max lanes (swimlane) | 5 |
| Max items (quadrant) | 12 |
| Max entities (ER) | 8 |
| Max nesting levels (nested) | 6 |
| Max tree depth | 4 |
| Max layers (layer stack) | 6 |
| Max circles (venn) | 3 |
| Max layers (pyramid) | 6 |
| Max annotation callouts | 2 |
If you exceed, split into two diagrams (overview + detail).
paper-2 bg + 1px rule border + 8px radius + 1.5rem padding + overflow-x: auto.1.1fr 1fr 0.9fr).Don't use 3 identical generic cards. Vary the treatment:
<div class="card">
<p class="eyebrow">SECTION LABEL</p>
<div class="card-header">
<span class="card-dot coral"></span>
<h3>Card Title</h3>
</div>
<ul><li>Item</li></ul>
</div>
Rules:
background: #ffffff (not paper — slight lift without shadow)border: 1px solid rgba(45,49,66,0.12)border-radius: 6px, padding: 1.25rembox-shadowborder-radius: 50% — ink / muted / coral / link / soft variantsRun before producing any diagram.
Type fit:
references/type-*.md?Remove test:
Signal:
Technical:
fill="#f5f5f5" rect behind it?writing-mode text?viewBox expanded for the legend strip (~60px)?Typography:
Every diagram ships in three variants (see assets/):
| Variant | File pattern | When to use |
|---|---|---|
| Minimal light (default) | template.html, example-<type>.html | Screenshot-ready. Diagram + title. Warm paper. |
| Minimal dark | template-dark.html, example-<type>-dark.html | Dark mode sites, slides, high-contrast posts. |
| Full editorial | template-full.html, example-<type>-full.html | Long-form posts where the diagram is the hero. |
| Consultant special (quadrant only) | example-quadrant-consultant.html | BCG/McKinsey-style 2×2 scenario matrix. Clinical sans-serif, white bg, bold blue double-ended axes, named scenario cells. See type-quadrant.md. |
Sketchy variant (optional, applied to any of the above) — see primitive-sketchy.md. SVG turbulence filter wobbles strokes for a hand-drawn feel. Good for essays, not for technical docs.
template.html for minimal, template-full.html for cards).references/type-<name>.md for layout conventions.Always produce a single self-contained .html file:
Renders correctly in any modern browser.