Illustrate

Create visual illustrations as self-contained HTML files with inline SVG and CSS. Use the editorial system by default, or the technical-color family when the user wants its colored component/step grammar or built-in browser export toolbar.

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. Project theme gate

Before generating a diagram, resolve the project theme from

.github/illustration-theme.yml

bash

python scripts/illustration_theme.py --project-root . resolve --format yaml

If the file is missing, initialize it before drawing. In an interactive conversation, ask the user to choose Cobalt Porcelain (recommended and default), Emerald Mist, Sanduq Classic, or a custom theme, then choose light/dark mode and font loading. In non-interactive automation, create

cobalt/light

deterministically:

bash

python scripts/illustration_theme.py --project-root . init --non-interactive

The initializer writes the tracked project policy to

.github/illustration-theme.yml

. Never modify the skill's bundled style guide to customize one consumer project. On every generation, apply the resolved

colors

and

typography

values to the selected template, including SVG text elements and arrow markers. Literal colors and fonts in examples are structural samples only; project tokens win.

For preset selection, custom light/dark themes, local/remote/system font policies, or design-system extraction, load

references/theme-initialization.md

. For URL, installed-skill, and folder extraction, also load

references/onboarding.md

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.
The active accent is editorial, not a flag. Use it on 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.

Choose the visual family before drawing:

Editorial for restrained documentation, product, data, and quantitative visuals across all types.
Technical-color architecture for cloud, infrastructure, network, security, and topology maps; this is the merged former
```
architecture-diagram
```
skill.
Technical-color process flow for numbered workflows, approvals, automation, onboarding, and runbooks; this is the merged former
```
process-flow-diagram
```
skill.

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.

3. Diagram Types

Selection guide

If you're showing…	Use	Reference
Components + connections in a system	Architecture	type-architecture.md
Legacy IT landscape grouped by phase/department; documents the before state in modernization proposals	IT current-state	type-it-state.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
Multiple entities scored across 3–5 quantitative criteria	Radar / Spider	type-radar.md
Reinforcing cycle / flywheel where the last step feeds the first and a shared hub accumulates state	Loop	type-loop.md
Hierarchy through containment / scope	Nested	type-nested.md
Parent → children relationships	Tree	type-tree.md
Human/agent/team ownership, reporting, routing, escalation	Org chart	type-org-chart.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
Quantitative comparison across categories	Bar chart	type-bar.md
Continuous trends over time	Line chart	type-line.md
Tasks and phases on a timeline	Gantt	type-gantt.md
Distribution and correlation between two variables	Scatter plot	type-scatter.md
End-to-end data stack on a container cluster	High-Level	type-high-level.md
Multi-actor sequential process with data handoffs	Process	type-process.md
Multi-tier data storage with quality levels and access policies	Medallion	type-medallion.md
Role-scoped data flow: who does what at each pipeline step	Data flow	type-data-flow.md
Integration topology of a data platform — sources → core → consumers	DP integration	type-dp-integration.md
Per-role / per-component access permissions matrix	DP security matrix	type-dp-security-matrix.md

Rules of thumb:

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 in editorial output	Mono is for technical content in the editorial family. The technical-color family intentionally uses JetBrains Mono throughout.
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 per project. Built-in theme definitions live in

assets/illustration-themes.yml

, and the active project selection lives in

.github/illustration-theme.yml

references/style-guide.md

defines the semantic roles (

paper

ink

muted

accent

link

, typography, and spacing). The default is Cobalt Porcelain light. Emerald Mist and the former Sanduq Classic palette remain selectable, and project files may define custom light and dark palettes plus font families.

When specs or type references mention a semantic role, use the current resolver output. Resolved project tokens override every literal color or font shown in a historical example.

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 — resolved
```
serif
```
, 1.75rem, 400 — H1 only
Node name — resolved
```
sans
```
, 12px, 600 — human-readable labels
Sublabel — resolved
```
mono
```
, 9px — ports, URLs, field types
Eyebrow / tag — resolved
```
mono
```
, 7–8px, uppercase, tracked — type tags, axis labels
Arrow label — resolved
```
mono
```
, 8px — annotation on arrows
Editorial aside — resolved
```
serif
```
italic, 14px — callouts only

Mono is for technical content. Names use the active sans family. Titles and callouts use the active serif family. Load

remote_css_url

only when

font_loading

resolves to

remote

; otherwise use the tracked stacks with locally installed or system fallbacks. Built-in stacks include Arabic fallbacks so mixed English/Arabic labels remain readable.

6. Core SVG Primitives

Universal building blocks. Type-specialized primitives (lifeline, activation bar, region) live in the relevant

references/type-*.md

. Optional primitives:

Editorial callouts → primitive-annotation.md
Hand-drawn variant → primitive-sketchy.md
Icon set (laptop, server, DB, K8s, Docker, AWS, …) → primitive-icons.md. Browse the gallery at
```
assets/icons.html
```
.
Terminal / CLI-window variant → primitive-terminal.md
Merged Architecture Diagram family, templates, and examples → technical-color-architecture.md
Merged Process Flow Diagram family, templates, and examples → technical-color-process-flow.md

Background

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.

svg

<rect width="100%" height="100%" fill="#f6f8fc"/>

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:

svg

<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="#f6f8fc"/>
<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.

Arrow markers (define all three, always)

svg

<marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
  <polygon points="0 0, 8 3, 0 6" fill="#4f6078"/>
</marker>
<marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
  <polygon points="0 0, 8 3, 0 6" fill="#2563eb"/>
</marker>
<marker id="arrow-link" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
  <polygon points="0 0, 8 3, 0 6" fill="#1d4ed8"/>
</marker>

Arrow	Stroke	When
Default	muted `#4f6078`	Internal, generic
Accent	cobalt `#2563eb`	Primary / highlighted / headline
Link-blue	`#1d4ed8`	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.

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

svg

<!-- 1. Opaque paper mask — prevents arrows bleeding through transparent fills -->
<rect x="X" y="Y" width="W" height="H" rx="6" fill="#f6f8fc"/>
<!-- 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="'IBM Plex Mono', 'Noto Sans Arabic', monospace"
      text-anchor="middle" letter-spacing="0.08em">API</text>
<!-- 4. Node name (resolved sans — human-readable) -->
<text x="CX" y="CY+2" fill="#15233c" font-size="12" font-weight="600"
      font-family="'IBM Plex Sans', 'Noto Sans Arabic', sans-serif" text-anchor="middle">Node Name</text>
<!-- 5. Technical sublabel (resolved mono) -->
<text x="CX" y="CY+18" fill="#4f6078" font-size="9"
      font-family="'IBM Plex Mono', 'Noto Sans Arabic', 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.

svg

<!-- Mask sits 14px above the arrow (8px text height + 6px gap). Stroke is at ARROW_Y. -->
<rect x="MID_X-18" y="ARROW_Y-20" width="36" height="12" rx="2" fill="#f6f8fc"/>
<text x="MID_X" y="ARROW_Y-11" fill="#6b7a90" font-size="8"
      font-family="'IBM Plex Mono', 'Noto Sans Arabic', 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:

svg

<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="#4f6078" font-size="8" font-family="'IBM Plex Mono', 'Noto Sans Arabic', monospace"
      letter-spacing="0.14em">LEGEND</text>
<!-- Items — horizontal row, ~160px apart -->

Expand SVG

viewBox

height by ~60px.

7. Layout & Spacing

4px grid

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.

Complexity budget (per diagram)

Limit	Rule
Max nodes	9
Max arrows / transitions	12
Max accent 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 org chart depth	4
Max org chart nodes	12
Max layers (layer stack)	6
Max circles (venn)	3
Max layers (pyramid)	6
Max radar axes	5
Max radar series	5
Max focal radar series	1
Max bars (bar chart)	8
Max series (line chart)	5
Max tasks (Gantt)	12
Max points (scatter plot)	30
Max annotation callouts	2

If you exceed, split into two diagrams (overview + detail).

Page layout

Header — eyebrow (resolved mono), title (resolved serif), optional subtitle (resolved sans + muted).
Diagram container — default: clean, borderless, no background — the SVG sits directly on the page paper. Optional framed variant (for card-heavy layouts or hero placements):
```
paper-2
```
bg + 1px
```
rule
```
border + 8px radius +
```
1.5rem
```
padding +
```
overflow-x: auto
```
.
Summary cards — 2–3 col grid with varied widths (e.g.,
```
1.1fr 1fr 0.9fr
```
).
Footer — colophon in resolved mono, muted, hairline top border.

8. Summary Card Pattern

Don't use 3 identical generic cards. Vary the treatment:

html

<div class="card">
  <p class="eyebrow">SECTION LABEL</p>
  <div class="card-header">
    <span class="card-dot accent"></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.25rem
```
No
box-shadow
Card dots: 7px,
```
border-radius: 50%
```
— ink / muted / accent / link / soft variants

9. Pre-Output Checklist (Taste Gate)

Run before producing any diagram.

Type fit:

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:

Active accent 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 rect filled with the resolved
```
paper
```
token 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 use the resolved sans family, not the mono family?
Technical sublabels (ports, commands, URLs) use the resolved mono family?
Page title uses the resolved serif family?
Annotation callouts use the resolved serif family in italic? (see primitive-annotation.md)
No blanket JetBrains Mono unless the technical-color family was explicitly selected?

10. Templates & Variants

Every first-class diagram ships in four core variants (see

assets/

Variant	File pattern	When to use
Minimal light (default)	`template.html` , `example-<type>.html`	Screenshot-ready. Diagram + title. Uses the active project's light palette.
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.
Hand-drawn	`template-hand.html` , `example-<type>-hand.html`	Deterministic Rough.js rendering for essays, workshops, and working-sketch presentation.
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.
Technical-color architecture	`assets/technical-color/architecture/`	Cloud, infrastructure, security, and topology illustrations with semantic component colors and built-in Copy/PNG/PDF.
Technical-color process flow	`assets/technical-color/process-flow/`	Approval, automation, runbook, and decision workflows with numbered steps and built-in Copy/PNG/PDF.

Hand-drawn generation — see primitive-sketchy.md. The committed

-hand

files are generated from every minimal example with Rough.js; do not edit them manually.

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

Resolve
```
.github/illustration-theme.yml
```
; initialize Cobalt when the project has no selection.
Choose editorial, merged technical-color architecture, or merged technical-color process flow.
Load
```
references/type-<name>.md
```
for editorial output; load the matching
```
technical-color-*.md
```
reference for either merged family.
Copy the closest template/example, replace its content, and apply every resolved color and font token while preserving the selected family's visual and export grammar.
Run
```
illustration_theme.py validate
```
, audit the output for stale default literals, then 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)
Editorial variants require no JavaScript; technical-color variants preserve their pinned export scripts

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

.svg

, load

references/export.md

and follow the procedure there. The portable command source is

commands/export-diagram.md

. 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.

illustrate

NPX Install

Tags

SKILL.md Content