---

name: illustrate description: "Draws diagrams, charts, and technical illustrations (44 types) as self-contained HTML with inline SVG, plus optional SVG/PNG/PDF export, in the project's tracked color and font theme. Use this skill whenever the user asks to draw, diagram, visualize, chart, map, sketch, or illustrate something, even without saying 'illustrate': architecture or system design, infrastructure, cloud or deployment topology, data flow, flowcharts, sequence, state machines, ER or database schema, UML class, dependency graphs, org charts, timelines, Gantt, swimlanes, process or workflow maps, user journeys, kanban, story maps, quadrants, Venn, pyramids, fishbone root-cause, Sankey, Wardley maps, bar, line, scatter, heatmap, waterfall, treemap, radar, or polar charts, and exploded or axonometric views. Also use to redraw .drawio, Mermaid (.mmd), or .excalidraw files, add a diagram to docs, a PR, or a spec, set up the illustration theme, or export a diagram. Not for photos or AI-generated raster images."

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.

Forty-four diagram types. Semantic patterns describe behavior; type references describe layout. 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:

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:

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 44 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.
• Attribute-only before/after → table; topology changes → Architecture delta.
• 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: semantic pattern, then visual type

When behavior, state, enforcement, or risk carries the meaning, first load references/semantic-patterns.md and choose one primary pattern. Then choose the nearest visual type below for layout. If no pattern matches, choose the type directly.

| Behavioral trigger | Semantic 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 pattern owns semantic primitives and its tighter budget; the type owns layout grammar; the active project theme owns every colour. Use references/animation.md only when motion is requested or materially clarifies ordered change; static remains the default.

Selection guide

| If you're showing… | Use | Reference | |---|---|---| | Components + connections in one system snapshot | Architecture | type-architecture.md | | Structural change between synchronized Before / After topologies, with a Changes ledger | Architecture delta | type-architecture-delta.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 | | One quantitative series across cyclic categories; angle=category, radius=magnitude | Polar chart | type-polar.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 | | Parts of one object pulled apart along one axis: a teardown, an unboxing, assembly order | Exploded axonometric | type-exploded.md | | One floor or site seen from above at an angle: rooms with furniture, buildings by phase | Axonometric plan | type-axonometric-plan.md | | Overlap between sets | Venn | type-venn.md | | Ranked hierarchy or conversion drop-off | Pyramid / funnel | type-pyramid.md | | Quantitative comparison across categories; dumbbell for two values per category | Bar chart | type-bar.md | | A start total bridged to an end total by signed contributions (budget bridge, headcount deltas) | Waterfall | type-waterfall.md | | Part-of-whole where the relative sizes are the story (marimekko for two dimensions) | Treemap | type-treemap.md | | Cross-tabulated data; fill encodes value per cell | Heatmap | type-heatmap.md | | Continuous trends over time, change between exactly two states (slopegraph), one distribution per series (ridgeline), composition over time (streamgraph), or rank movement across snapshots (bump) | Line chart | type-line.md | | Tasks and phases on a timeline | Gantt | type-gantt.md | | Correlation or distribution of two variables; bubble (three variables) and beeswarm (one variable, dot per item) variants | 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 | | A quantity splitting and merging across stages, band width = amount | Sankey | type-sankey.md | | Causes of one observed effect, grouped by category (root-cause analysis) | Fishbone | type-fishbone.md | | Value chain against evolution — what to build, buy, and what is moving | Wardley map | type-wardley.md | | Work-in-progress by state, with WIP limits and blocked items | Kanban | type-kanban.md | | What a person does across stages of an experience, and how it feels | User journey | type-journey.md | | Where software runs — zones, hosts, artifacts, replicas, ports | Deployment | type-deployment.md | | What depends on what, with fan-in and cycles a tree cannot express | Dependency graph | [type-de