---

name: diagram-design description: Create branded architecture, architecture delta, IT current-state, flowchart, sequence, state machine, ER/data model, timeline, swimlane, quadrant, radar/spider, polar chart (polar/radial lollipop), loop/flywheel, nested, tree, org chart, layer stack, exploded axonometric, axonometric plan, Venn, pyramid/funnel, treemap and marimekko, heatmap, bar and dumbbell, waterfall, line (slopegraph, ridgeline, streamgraph, bump), Gantt and scatter charts (bubble, beeswarm), high-level, process, medallion, data flow, DP integration, DP security matrix, Sankey, fishbone, Wardley map, kanban, user journey, deployment, dependency graph, UML class, story map, or database schema diagrams as HTML/SVG/PNG, with .drawio, Mermaid, and .excalidraw import, plus lifecycle phase maps, block decomposition trees, and onboarding guidance. license: MIT metadata: version: "2.6"

Diagram Design

Create diagrams as self-contained HTML files with inline SVG and an editorial design system.

Forty-four visual types. Semantic patterns describe behavior; type references describe layout.

---

0. First-time setup — style guide gate

Before generating your first diagram in a new project, verify the style guide has been customized.

Do not silently ship default-skinned diagrams into a branded project.

First resolve any project .diagram-design marker per references/profiles.md; a successfully resolved marker selects its profile and bypasses this gate. That reference owns failures, the protected default, and save behavior.

Open references/style-guide.md and check the default tokens. If they are still the shipped defaults (paper #f5f5f5, ink #2d3142, accent #eb6c36), pause and ask the user:

"This is your first diagram in this project and the style guide is still default. Customize now? Options: (a) website URL, (b) installed skill, (c) local folder/design-system, (d) paste tokens, (e) keep default, (f) load saved profile."

Then branch per the matching section of references/onboarding.md; for (f) follow references/profiles.md.

Once the style guide has been customized (or the user explicitly chose default), skip this gate on later runs. A leading profile header names the copied-in active profile. Without a header, any semantic-role value or typography family differing from shipped defaults means custom-unsaved: skip the gate and offer to save it as a profile. All-default tokens with no marker/header trigger the gate. After onboarding, offer to save as a named client profile per references/profiles.md.

---

1. Philosophy

The highest-quality move is usually deletion.

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 44 visual 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.
• 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. 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 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. Use references/animation.md only when motion is requested or materially clarifies ordered change; static remains the default.

Visual-type guide (44)

| 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 by phase or department; shows the before state | 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; the last step feeds the first and a 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 | 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 | 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), or rank movement across several 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-dependency.md | | Classes with operations, inheritance, composition (other UML routes elsewhere) | UML class | type-uml-class.md | | Narrative backbone sliced into releases, with the cut line | Story map | type-story-map.md | | Physical tables: SQL types, constraints, indexes, column-level FKs | Database schema | type-db-schema.md |

Rules of thumb:

• If a 3-column table communicates the same thing, pick the table.
• If two types seem useful, pick the dominant axis; a semantic pattern may add behavior-specific primitives, not a second layout grammar.
• If you're past the complexity budget (§7), split into an overview + detail.

Always load the chosen type reference linked in the guide before drawing. When routed above, also load semantic-patterns.md; when animation is chosen, load animation.md.

Confirm before drawing

Before rendering, state the plan in one short message: the chosen visual type (a