Create technical and product diagrams — architecture, IT current-state, flowchart, sequence, state machine, ER / data model, timeline, swimlane, quadrant, radar / spider, loop / flywheel, nested, tree, org chart, layer stack, venn, pyramid / funnel, bar chart, line chart, Gantt, scatter plot, high-level, process, medallion, data flow, DP integration, DP security matrix — as standalone HTML files with inline SVG. Ships with a neutral editorial skin and a first-run gate that prompts users to customize the style guide (colors, fonts) from their own website before generating. Includes annotation-callout primitive and optional sketchy variant.
Create technical and product diagrams — architecture, IT current-state, flowchart, sequence, state machine, ER / data model, timeline, swimlane, quadrant, radar / spider, loop / flywheel, nested, tree, org chart, layer stack, venn, pyramid / funnel, bar chart, line chart, Gantt, scatter plot, high-level, process, medallion, data flow, DP integration, DP security matrix — as standalone HTML files with inline SVG. Ships with a neutral editorial skin and a first-run gate that prompts users to customize the style guide (colors, fonts) from their own website before generating. Includes annotation-callout primitive and optional sketchy variant.
license
MIT
metadata
{"version":"2.0"}
Diagram Design
Create visual diagrams as self-contained HTML files with inline SVG and CSS, following an opinionated editorial design system.
Twenty-seven 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.
0. First-time setup — style guide gate
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) pull from your website URL, (b) extract from an installed skill, (c) extract from a local folder / design-system directory, (d) paste tokens manually, (e) proceed with the default for now."
Then branch:
(a) → follow references/onboarding.md § URL to fetch the site, extract palette + fonts, propose a diff, and write style-guide.md.
(b) → follow references/onboarding.md § Skill — ask which skill, read its SKILL.md / CSS / token files, map to semantic roles, propose diff.
(c) → follow references/onboarding.md § Folder — ask for the path, glob for CSS/JSON/MD token files, map to semantic roles, propose diff.
(d) → accept the user's tokens and write them into style-guide.md under a new "Custom tokens" section.
(e) → proceed; optionally remind the user they can run onboarding later.
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.
1. Philosophy
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:
Every node represents a distinct idea. Two nodes that always travel together are one node.
Every connection carries information. If the relationship is obvious from layout, remove the line.
Coral is editorial, not a flag. 1–2 focal nodes per diagram. Using it on 5 nodes erases the signal.
The schematic isn't done when everything is added. It's done when nothing can be removed.
Target density: 4/10. Enough to be technically complete. Not so dense it needs a guide. Above 9 nodes, it's probably two diagrams.
2. When to Use
Use for any of the 27 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:
Quick unicode diagrams → use wiretext.
Lists of things → table or bullets.
Simple before/after → table.
One-shape "diagrams" → just write the sentence.
Before drawing, ask: Would the reader learn more from this than from a well-written paragraph? If no, don't draw.
If a 3-column table communicates the same thing, pick the table.
If you're combining two types, pick the dominant axis — don't hybridize grammars.
If you're past the complexity budget (§7), split into an overview + detail.
Always load the relevant references/type-*.md before drawing — it contains layout conventions, anti-patterns, and example files for that type.
4. Universal Anti-patterns
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
Diagonal / slanted connectors between off-axis nodes
Rounded right-angle (orthogonal) elbows are mandatory — see §6 Mandatory connector rules
Arrow label sitting on or touching its connector
Label must have a 6–10px gap above the line so the connector stays visible
Two connectors overlapping or running on the same path
Each connection must be independently traceable — bridge crossings, offset parallels
Two connectors sharing a single attach point on a box
Fan attach points along the edge (≥12px apart) so every arrow is clearly distinct — see §6 rule 4
Connector routed behind a non-endpoint box without need
Reroute around intervening boxes; the dashed-transit exception (§6 rule 5) only applies when an unavoidable intervening box sits on the direct path
Type-specific anti-patterns live in each references/type-*.md.
5. Design System
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.
Semantic roles (at a glance)
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.
Node type → treatment
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
Typography (summary — full spec in style-guide.md)
Title — Instrument Serif, 1.75rem, 400 — H1 only
Node name — Geist (sans), 12px, 600 — human-readable labels
Sublabel — Geist Mono, 9px — ports, URLs, field types
Eyebrow / tag — Geist Mono, 7–8px, uppercase, tracked — type tags, axis labels
Arrow label — Geist Mono, 8px — annotation on arrows
Editorial aside — Instrument Serif italic, 14px — callouts only
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.
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.
<rectwidth="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:
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.
Draw arrows before boxes so z-order puts lines behind nodes.
Mandatory connector rules
These five rules are non-negotiable. Run the pre-output checklist (§9) to verify before producing any diagram.
Rounded right-angle (orthogonal) connectors are mandatory. Never use diagonal <line> or straight slanted paths between nodes that don't share an x or y axis. Every bend must be a quarter-arc with r=8 (or r=6 minimum for tight layouts). See references/type-architecture.md for the elbow-path formula. Reserve plain straight <line> only for connections whose endpoints share the same x or y coordinate. Diagonal connectors are an automatic fail.
Label-to-connector margin: 6–10px gap, always. A label must never sit on its arrow — the connector must remain visible. Place the label centered above (or beside, for vertical segments) the line with a minimum 6px gap between the bottom of the label's mask rect and the connector stroke. The opaque mask rect prevents the arrow from bleeding through, but the visible gap between mask edge and line preserves the reader's ability to trace the connection. If the label is large enough that 6px feels cramped, push it to 8–10px. Never let the mask rect touch or overlap the stroke.
No overlapping connectors. Two connectors must never share the same stroke path, run parallel on top of each other, or be drawn on top of each other for any segment. When two orthogonal arrows must cross at a single point, apply the bridge / hop primitive (see references/type-architecture.md § Crossing arrows). When two arrows naturally want to overlap, offset their routing by ≥12px so each line is independently traceable. If you find yourself stacking connectors, redesign the layout — it means two nodes are too close, or the diagram is over budget (split into overview + detail).
Shared edge → fan the attach points. When two or more connectors enter or exit the same edge of a box, each must have its own distinct attach point along that edge — no two connectors may share a single point on a box. Spread the attach points evenly along the edge with ≥12px between adjacent points (8px minimum for very small boxes). Routing rules:
For N connectors on an edge of length L, attach point k (1..N) sits at offset L * k / (N + 1) from the edge's leading corner.
When the connectors fan out to destinations on different sides, route each one orthogonally from its own attach point — no merging strokes near the box.
When two parallel connectors run in the same direction, keep them ≥12px apart along their entire length, not just at the attach point. Each arrow must remain independently traceable end-to-end.
No connector may hide another. If you can't tell two arrows apart at a glance, the layout has failed.
A connector must not pass behind a box that isn't its source or destination — except when the box is geometrically unavoidable on a direct orthogonal path. Reroute around intervening boxes by default. The only legitimate exception is when a cross-cutting node (e.g., a footer service, a horizontal layer bar) physically sits between the connector's source and destination on the only straight path between them — for example, a METRICS arrow exiting an Observability footer bar and rising into a zone above must cross the Active Directory footer bar that sits between them. In that exception:
The stroke must be dashed (e.g., stroke-dasharray="4,3") to signal "transit, not interaction" — it tells the reader the intervening box is not an endpoint.
The label sits at the visible end of the connector (typically near the source) so it doesn't fall behind the intervening box.
No marker (arrowhead) may land on the intervening box's edge — the marker resolves at the true destination only.
When in doubt, reroute. The exception exists for the narrow case where rerouting is geometrically impossible, not as a shortcut to avoid layout work.
Node box — full pattern
<!-- 1. Opaque paper mask — prevents arrows bleeding through transparent fills --><rectx="X"y="Y"width="W"height="H"rx="6"fill="#f5f5f5"/><!-- 2. Styled box --><rectx="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) --><rectx="X+8"y="Y+6"width="28"height="12"rx="2"fill="transparent"stroke="STROKE@0.40"stroke-width="0.8"/><textx="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) --><textx="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) --><textx="CX"y="CY+18"fill="#4f5d75"font-size="9"font-family="'Geist Mono', monospace"text-anchor="middle">tech:port</text>
Arrow labels — always mask, always with margin
Every arrow label needs an opaque rect behind it. Without one it bleeds through the line. And the label must sit with a visible gap above the connector — never on top of it.
<!-- Mask sits 14px above the arrow (8px text height + 6px gap). Stroke is at ARROW_Y. --><rectx="MID_X-18"y="ARROW_Y-20"width="36"height="12"rx="2"fill="#f5f5f5"/><textx="MID_X"y="ARROW_Y-11"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.
Mandatory 6–10px gap between the bottom of the mask rect and the arrow stroke. The connector must remain visible — a label that hides its own arrow is a hard fail.
Never writing-mode vertical.
For vertical segments, place the label to the side (not on the line) with the same 6–10px horizontal gap.
Legend — horizontal strip at the bottom
Never put the legend inside the diagram area. Place as a horizontal strip after all nodes, with a hairline separator:
Right type for what I'm showing? (§3 selection guide)
Would a table / paragraph do the same job? (If yes — don't draw.)
Loaded the matching references/type-*.md?
Remove test:
Can I remove any node? (Would a reader still understand?)
Can I merge any two nodes? (Do they always travel together?)
Can I remove any arrow? (Is the relationship obvious from layout?)
Can I remove any label? (Does color or shape already signal it?)
Signal:
Coral used on ≤2 elements? If more, which actually deserve focal status?
Legend covers every type used — and nothing extra?
Within the type's complexity budget (§7)?
Technical:
Arrows drawn before boxes?
Every connector between off-axis nodes uses a rounded right-angle elbow (r=8)? No diagonal <line> slants?
Every arrow label has a visible 6–10px gap above its connector? (Mask rect not touching the stroke.)
No two connectors overlap, share a stroke path, or run on top of each other? Crossings use the bridge/hop primitive?
When several connectors enter or exit the same edge of a box, each has its own attach point (≥12px apart)? No connector hides another?
No connector passes behind a non-endpoint box, except the unavoidable-intervening-box case (§6 rule 5) — and in that case, the stroke is dashed and the label sits at the visible end?
Every arrow label has an opaque fill="#f5f5f5" rect behind it?
Legend is a horizontal bottom strip, not floating?
No vertical writing-mode text?
viewBox expanded for the legend strip (~60px)?
Every font size, coord, width, height, gap divisible by 4?
Typography:
Human-readable names in Geist sans, not Geist Mono?
Technical sublabels (ports, commands, URLs) in Geist Mono?
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.
Terminal variant (optional, replaces any of the above) — see primitive-terminal.md. template-terminal.html, example-<type>-terminal.html. Charcoal-black CLI-window chrome, monospace type, one red-orange accent. Good for dev-tool / CLI-product posts and technical social cards; not brand-tokenized, so skip it for onboarded/brand-matched output.
To create a new diagram
Copy the variant closest to what you want (template.html for minimal, template-full.html for cards).
Load the matching references/type-<name>.md for layout conventions.
Replace the eyebrow, h1, and SVG body.
Run the §9 taste gate.
11. Output
Always produce a single self-contained .html file:
Embedded CSS (no external except Google Fonts)
Inline SVG (no external images)
No JavaScript required
Renders correctly in any modern browser.
Exporting to PNG / SVG
When the user asks to export, save, rasterize, or convert a generated diagram to .png or .svg, load references/export.md and follow the procedure there. Both formats deliver the diagram only (the <svg> node) — editorial wrappers like cards and headers are dropped by design. Export is manual — never produce export files unprompted.
