Diagram Design

Name: Diagram Design
Author: cathrynlavery

Editorial diagrams your designer won't hate.

New in 2.0 — the Loop: flywheels with a shared-memory hub. The dashed lines are the write-backs.

New in 2.3: semantic system patterns and optional accessible motion, while static output stays the default.

New in 2.5.10: ten more layout grammars — Sankey, fishbone, Wardley map, kanban, user journey, deployment, dependency graph, UML class, story map, and database schema.

39 editorial diagram types for Claude Code, Codex, Factory Droid, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop. Semantic patterns describe behavior separately from layout, so a queue, policy trace, or trust boundary can use the nearest existing type without expanding the type count. Static HTML remains the default; optional motion is available for ordered explanations. The skill also redraws draw.io or Mermaid sources at a chosen format, size, and detail level.

No Figma. No generic rounded boxes. No 30-minute color-picking sessions.

Why I built it

I write at littlemight.com (and run BestSelf.co on the side). Every time I needed a diagram — an architecture sketch, a flowchart, a pyramid of what matters most — I'd ask Claude and get back a generic rounded-box thing that looked nothing like the rest of the site. I'd either fight with Figma for 30 minutes or just skip the diagram.

So I built a Claude Code skill for it. Thirty-nine visual types, editorial quality, matches your brand in 60 seconds by reading your website.

The highest-quality move is usually deletion. Every node earns its place. The accent color is reserved for the 1–2 things the reader should look at first. Target density: 4/10.

What it makes

All 39 visual types ship in three static variants: minimal light, minimal dark, and full-editorial. Open any of them directly in a browser. There is no build step, JavaScript, or external image dependency.

<table> <tr> <td align="center" width="33%"><img src="docs/screenshots/architecture.png" alt="Architecture"> Architecture Components + connections</td> <td align="center" width="33%"><img src="docs/screenshots/it-state.png" alt="IT current-state"> IT current-state Legacy landscape + modernization</td> <td align="center" width="33%"><img src="docs/screenshots/flowchart.png" alt="Flowchart"> Flowchart Decision logic</td> </tr> <tr> <td align="center"><img src="docs/screenshots/sequence.png" alt="Sequence"> Sequence Messages over time</td> <td align="center"><img src="docs/screenshots/state.png" alt="State machine"> State machine States + transitions</td> <td align="center"><img src="docs/screenshots/er.png" alt="ER"> ER / data model Entities + fields</td> </tr> <tr> <td align="center"><img src="docs/screenshots/timeline.png" alt="Timeline"> Timeline Events on an axis</td> <td align="center"><img src="docs/screenshots/swimlane.png" alt="Swimlane"> Swimlane Cross-functional flow</td> <td align="center"><img src="docs/screenshots/quadrant.png" alt="Quadrant"> Quadrant Two-axis positioning</td> </tr> <tr> <td align="center"><img src="docs/screenshots/radar.png" alt="Radar chart"> Radar / spider Multi-axis comparison</td> <td align="center"><img src="docs/screenshots/loop.png" alt="Loop"> Loop / flywheel Reinforcing cycle + shared hub</td> <td align="center"><img src="docs/screenshots/nested.png" alt="Nested"> Nested Hierarchy by containment</td> </tr> <tr> <td align="center"><img src="docs/screenshots/tree.png" alt="Tree"> Tree Parent → children</td> <td align="center"><img src="docs/screenshots/org-chart.png" alt="Org chart"> Org chart Ownership + routing</td> <td align="center"><img src="docs/screenshots/layers.png" alt="Layer stack"> Layer stack Stacked abstractions</td> </tr> <tr> <td align="center"><img src="docs/screenshots/venn.png" alt="Venn"> Venn Set overlap</td> <td align="center"><img src="docs/screenshots/pyramid.png" alt="Pyramid"> Pyramid / funnel Ranked hierarchy or drop-off</td> <td align="center"><img src="docs/screenshots/bar.png" alt="Bar chart"> Bar chart Categorical comparison</td> </tr> <tr> <td align="center"><img src="docs/screenshots/treemap.png" alt="Treemap"> Treemap Part-of-whole by area</td> <td align="center"><img src="docs/screenshots/line.png" alt="Line chart"> Line chart Trends over time</td> <td align="center"><img src="docs/screenshots/gantt.png" alt="Gantt"> Gantt Tasks + phases on a timeline</td> </tr> <tr> <td align="center"><img src="docs/screenshots/scatter.png" alt="Scatter plot"> Scatter plot Distribution + correlation</td> <td align="center"><img src="docs/screenshots/high-level.png" alt="High-Level"> High-Level End-to-end stack on a cluster</td> <td align="center"><img src="docs/screenshots/process.png" alt="Process"> Process Multi-actor sequential workflow</td> </tr> <tr> <td align="center"><img src="docs/screenshots/medallion.png" alt="Medallion"> Medallion Multi-tier data storage</td> <td align="center"><img src="docs/screenshots/data-flow.png" alt="Data flow"> Data flow Role-scoped pipeline steps</td> <td align="center"><img src="docs/screenshots/dp-integration.png" alt="DP integration"> DP integration Sources → core → consumers</td> </tr> <tr> <td align="center"><img src="docs/screenshots/dp-security-matrix.png" alt="DP security matrix"> DP security matrix Per-role access permissions</td> <td align="center"><img src="docs/screenshots/sankey.png" alt="Sankey"> Sankey Quantities that split + merge</td> <td align="center"><img src="docs/screenshots/fishbone.png" alt="Fishbone"> Fishbone Grouped causes → one effect</td> </tr> <tr> <td align="center"><img src="docs/screenshots/wardley.png" alt="Wardley map"> Wardley map Value chain × evolution</td> <td align="center"><img src="docs/screenshots/kanban.png" alt="Kanban"> Kanban Work in progress by state</td> <td align="center"><img src="docs/screenshots/journey.png" alt="User journey"> User journey Stages, actions + sentiment</td> </tr> <tr> <td align="center"><img src="docs/screenshots/deployment.png" alt="Deployment"> Deployment Zones, hosts + artifacts</td> <td align="center"><img src="docs/screenshots/dependency.png" alt="Dependency graph"> Dependency graph Fan-in, ranks + cycles</td> <td align="center"><img src="docs/screenshots/uml-class.png" alt="UML class"> UML class Classes, operations + typed relations</td> </tr> <tr> <td align="center"><img src="docs/screenshots/story-map.png" alt="Story map"> Story map Backbone × release slices</td> <td align="center"><img src="docs/screenshots/db-schema.png" alt="Database schema"> Database schema Physical tables + column FKs</td> <td align="center"><img src="docs/screenshots/polar.png" alt="Polar chart"> Polar chart Cyclic magnitude · linear radius</td> </tr> </table>

The v2.5.10 release added the final ten types above. Compare their light, dark, and full-editorial variants in the 30-variant contact sheet.

Browse the live gallery: cathrynlavery.github.io/diagram-design — or open skills/diagram-design/assets/index.html locally to flip through all 39 diagrams with light / dark / full-editorial tabs.

Install

Claude Code:

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

Then enable updates once: run /plugin, open Marketplaces, select diagram-design, and choose Enable auto-update. Claude Code disables auto-update by default for third-party marketplaces; after this toggle, it refreshes the marketplace and installed plugin in the background after startup. Run /reload-plugins when prompted, or let the next session load the update.

Codex:

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

Codex refreshes configured Git marketplaces at startup. To fetch immediately, run codex plugin marketplace upgrade diagram-design and start a new session.

Factory Droid:

droid plugin marketplace add https://github.com/cathrynlavery/diagram-design
droid plugin install diagram-design@diagram-design --scope user

Droid tracks Git plugins by commit rather than the manifest's display version. To fetch a merged update, run droid plugin marketplace update diagram-design, then droid plugin update diagram-design@diagram-design --scope user, and start a new session.

Claude Cowork (organization marketplace): Organization GitHub marketplaces currently require a private or internal repository, so first mirror this public repository into one owned by your organization. In Organization settings → Plugins, choose Add plugin → GitHub, connect that mirror, and enable Sync automatically from the marketplace menu. Automatic sync runs when a pull request containing a plugin version bump is merged to the mirror's default branch; direct pushes do not trigger the webhook. Install Diagram Design from the resulting organization marketplace.

Pi:

pi install https://github.com/cathrynlavery/diagram-design

Run /reload in an open Pi session. Pi makes the skill available for matching diagram requests; use /skill:diagram-design to invoke it explicitly. Pi also loads the /export-diagram, /import-mermaid, /profile, and /doctor prompt templates. The unpinned Git install is intentional: Pi has no automatic package refresh, so run pi update --extensions to pull merged updates.

One-time migration: an existing standalone npx skills add copy will not start following the Codex marketplace automatically. Remove that standalone copy, then use the Codex marketplace commands above. Likewise, uninstall a personal Cowork copy and reinstall Diagram Design from your organization's marketplace. Future marketplace version bumps then flow through each client's native update path.

Editable install

Managed installs are convenient, but changes to references/style-guide.md may be replaced by package updates. Saved profiles in ~/.diagram-design/profiles/ survive updates, and projects with a .diagram-design marker are unaffected. Clone the repo and install the local path if you plan to customize the working style guide directly:

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design

# Pi: register the checkout as a local package
pi install ~/code/diagram-design

# Claude Code: symlink the inner skill
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

The shared skill lives at skills/diagram-design/. Pi discovers it through the repo's standard skills/ package directory; Claude Code, Codex, Factory Droid, and other Agent Skills-compatible tools use the same files.

Onboarding — make it look like your brand

The whole point: ship editorial-quality diagrams in your colors and typography, not a generic template.

Out of the box, diagrams render in a clean jet-black + atomic-tangerine palette (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines). Good enough to screenshot straight away. But 60 seconds of onboarding is better — the skill will pull your brand from your website and apply it across every diagram.

The flow

You:     "onboard diagram-design to https://yoursite.com"
Agent:   → fetches the homepage
         → extracts the dominant palette + font stack
         → maps detected values to semantic roles:
             paper, ink, muted, accent, link
         → shows a proposed diff
         → writes your tokens to references/style-guide.md
You:     "yes, apply it"

Every new diagram now uses your colors. Your website's paper color becomes the diagram background. Your CTA color becomes the focal accent. Your body font stack becomes the node label family.

Brand matching also emits a fidelity receipt: sampled URLs, exact color roles, font families and weights, font source URLs, and any fallback. Public site fonts are used directly and verified after rendering rather than silently replaced with generic system fonts.

What gets extracted

Detected from your site	Becomes
`<body>` background	`paper` token
Primary text color	`ink` token
Secondary / caption text	`muted` token
Cards or containers	`paper-2` token
Most-used brand color (CTA, link, heading)	`accent` token
`<h1>` font family	`title` font
`<body>` font family	`node-name` font
`<code>` / `<pre>` font	`sublabel` font

Contrast checks happen automatically

Before writing tokens, the skill verifies WCAG AA contrast on ink over paper. If your site has a color that fails contrast at diagram sizes (9–12px), it proposes an adjusted value and explains why.

Accessible by default

Every diagram template gives the inline SVG an accessible name and description: role="img", a resolving aria-labelledby, and first-child <title> / <desc> slots. IDs are prefixed per diagram and variant, so multiple SVG exports can be safely inlined on one page without duplicate accessible-name IDs. Decorative specimen icons are hidden from assistive technology instead.

Manual override

Prefer to set tokens by hand? Open skills/diagram-design/references/style-guide.md and edit the table. Everything downstream reads from there — all 39 diagrams, the annotation primitive, and the gallery all inherit semantic role names (accent, not #eb6c36).

First-run gate

The skill won't silently ship default-skinned diagrams into a branded project. On first use in a new project, it checks if style-guide.md has been customized. If not, it pauses and asks:

"This is your first diagram in this project. The style guide is still at the default. Want to run onboarding, paste tokens manually, or proceed with default?"

See skills/diagram-design/references/onboarding.md for the full spec.

Working with multiple clients

Onboard a brand once, save the result as a named profile, then add a .diagram-design marker containing profile: <slug> to each client project. Marker projects read ~/.diagram-design/profiles/<slug>.md directly, so parallel workspaces can use different brands without overwriting a shared installed style-guide.md.

The profile library is shared across Claude Code, Codex, Factory Droid, and Pi. Use /diagram-design:profile in Claude Code, /profile in Factory Droid or Pi, or ask in natural language in any host. See profiles.md for the storage, marker, and recovery contract.

Quickstart

# From a cloned checkout, open the gallery to see all 39 diagrams
open skills/diagram-design/assets/index.html       # macOS
xdg-open skills/diagram-design/assets/index.html  # Linux

# In Claude Code, Codex, Factory Droid, or Pi, ask:
# "Make me an architecture diagram of my app: frontend, backend, database, Redis cache."
# "I need a quadrant showing Q2 projects by impact vs effort."
# "Give me a sequence of a bearer call with token refresh on 401."
# (branching refresh uses the ALT combined-fragment grammar in type-sequence.md;
#  see skills/diagram-design/assets/example-sequence-oauth.html — not a full authorize-code handshake)

Your agent will pick the right type, build the HTML, and save it. You can also start from a template directly:

cp skills/diagram-design/assets/template.html my-diagram.html        # minimal light
cp skills/diagram-design/assets/template-full.html my-diagram.html   # editorial with summary cards
cp skills/diagram-design/assets/template-motion.html my-diagram.html # optional accessible motion

Semantic patterns and optional motion

When behavior matters, the skill chooses a semantic pattern first and a visual type second. The seven routed patterns cover fan-in queues and bottlenecks, repeated stage slots, unstructured-input transformation, paired policy traces, secure paved roads, governance catalogs, and compensating security layers. Each pattern defines its triggers, primitives, budget, anti-patterns, static fallback, and nearest visual type in semantic-patterns.md.

Motion is optional and does not create another visual type. animation.md defines none, reveal, step, and loop modes with a complete static first frame, deterministic timing, and controls when interaction is available. Reduced-motion output shows the complete static frame and hides/disables playback controls. Motion HTML uses the exact reviewed controller from template-motion.html; arbitrary or modified inline scripts, remote assets, CSS imports, and executable HTML attributes are rejected. The default is none: ordinary output remains static and script-free. example-policy-trace-animated.html is the self-contained interactive example.

Import from draw.io or Mermaid

Already have diagrams in draw.io / diagrams.net or Mermaid? Point the skill at the source and it redraws them — same content, this design system, at whatever the destination needs.

A 12-node draw.io file redrawn at balanced detail for a blog post. The source's six pastel fills became one accent; its hand-dragged coordinates became a 4px grid.

/diagram-design:import-drawio platform.drawio
/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-drawio platform.drawio --detail=faithful --format=png --page=all
/diagram-design:import-mermaid README.md --diagram=all
/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified

Or just ask: "redraw this drawio file for my deck", "make this Mermaid block editorial", or "この Mermaid をスライド用にきれいにして".

Reads the common containers draw.io writes — .drawio, .drawio.xml, .drawio.png (embedded diagram), and .drawio.svg — including compressed payloads that look like base64 garbage in an editor. For Mermaid, it accepts .mmd, .mermaid, and one or more fenced mermaid blocks in Markdown. It parses text only: no rendering, JavaScript, browser, network, or followed click targets.

The four dials

The point isn't conversion, it's fitting the output to where it's going. Same source file, three different diagrams:

Dial	Options	What it changes
Format	`html` · `svg` · `png` · `html+png`	The deliverable. SVG for Figma, PNG for slides, HTML for the web.
Size	`doc-inline` · `doc-wide` · `slide-16x9` · `slide-4x3` · `social-og` · `social-square` · `print-a4-landscape` · `print-letter-landscape` · `fit`	The `viewBox` and the type ramp — a projected slide gets 16px node names, not 12px.
Detail	`faithful` (≤24 nodes, zoned) · `balanced` (≤12) · `simplified` (≤7)	How much of the source survives, via a fixed degrade ladder — decorations, then duplicates, then leaf clusters, then infrastructure.
Audience	`engineer` · `mixed` · `executive`	The wording, not the count. `Auth Service / JWT · RS256 · :8443` → `Auth Service / token check` → `Sign-in`.

Every import ends with a fidelity ledger — what got merged, collapsed, or dropped. You know the source; you'd notice anyway.

Detail: balanced · 12 source nodes → 8 drawn
Collapsed: "Token valid?" decision → edge label on Gateway → Auth
Dropped:   1 sticky note ("legacy path, to be retired") — unconnected in source
Kept in full: the request path (Web/Mobile → Gateway → Orders → Postgres)

What never carries over: source or renderer coordinates, source palette, source fonts, draw.io's diagonal connector spaghetti, or Mermaid's automatic layout. What always does: components, relationships, grouping, and direction. See references/import-drawio.md, references/import-mermaid.md, and references/output-spec.md.

Export to PNG / SVG

Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. Use the slash command for your agent:

Pi:

/export-diagram path/to/diagram.html
/export-diagram path/to/diagram.html --svg-only
/export-diagram path/to/diagram.html --png-only --scale=3

Claude Code:

/diagram-design:export-diagram path/to/diagram.html
/diagram-design:export-diagram path/to/diagram.html --svg-only
/diagram-design:export-diagram path/to/diagram.html --png-only --scale=3

Or just ask in natural language:

"Export this diagram as SVG and PNG."
"Save my-diagram.html as PNG."

SVG — extracts the <svg> node and injects Google Fonts so it renders standalone in browsers, Figma, and Illustrator.
PNG — rasterizes the diagram via Playwright at 2× by default. One-time setup: pip install playwright && playwright install chromium.

Both formats are diagram-only — editorial cards and headers from -full variants aren't included. For a screenshot of the full editorial layout, use your browser's print-to-PDF or full-page screenshot. See skills/diagram-design/references/export.md for the full procedure.

For motion-enabled HTML, export the explicit final state: open ?motion=static, wait for document.fonts.ready, and confirm the motion root has data-frame="static" before capture. Use ?motion=step&step=N only when a named intermediate frame was requested.

Architecture

Progressive disclosure. SKILL.md routes behavior first when needed, then layout. Semantic, type, and animation references load only when relevant.

diagram-design/
├── .agents/plugins/marketplace.json — Codex marketplace catalog
├── .claude-plugin/                  — Claude marketplace + plugin manifest
├── .codex-plugin/                   — Codex plugin manifest
├── .factory-plugin/                 — Factory Droid marketplace + p

…

---

## diagram-design

---
name: diagram-design
description: Create branded architecture, 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, Venn, pyramid/funnel, treemap, bar, line, Gantt and scatter charts, 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 standalone HTML/SVG/PNG. Redraw .drawio/.drawio.png/.drawio.svg or Mermaid .mmd sources at a chosen size/detail; onboard brand tokens from a website; add semantic patterns, callouts, accessible motion, or sketchy/hand-drawn styling.
license: MIT
metadata:
  version: "2.6"
---

# Diagram Design

Create visual diagrams as self-contained HTML files with inline SVG and CSS, following an opinionated editorial design system.

Thirty-nine visual types. Semantic patterns describe behavior independently; type references describe layout. Details load from `references/` only when selected.

---

## 0. First-time setup — style guide gate

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

Don't silently ship default-skinned diagrams into a branded project.

First check the project root for a `.diagram-design` marker and resolve it per [`references/profiles.md`](references/profiles.md). A valid marker whose profile exists selects that file directly and skips this gate; `profile: default` also skips it. A malformed or missing-profile marker follows the visible failure handling in that reference. Never copy a marker-selected profile over the installed working copy.

Open [`references/style-guide.md`](references/style-guide.md) and check the default tokens. If they're still the shipped defaults (paper `#f5f5f5`, ink `#2d3142`, accent `#eb6c36` atomic-tangerine), **pause and ask the user**:

> *"This is your first diagram in this project. The style guide is still at the default (neutral white-smoke + atomic-tangerine). 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, (f) load a saved client profile."*

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

**Once the style guide has been customized** (or the user explicitly opted for default), skip this gate on subsequent 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. At the end of every onboarding method, offer to save the result 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 39 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.
- 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. Selection: semantic pattern, then visual type

When behavior, state, enforcement, or risk carries the meaning, first load [`references/semantic-patterns.md`](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 |

The pattern owns semantic primitives and its tighter budget; the type owns layout grammar. Use [`references/animation.md`](references/animation.md) only when motion is requested or materially clarifies ordered change; static remains the default.

### Visual-type guide (39)

| If you're showing… | Use | Reference |
|---|---|---|
| Components + connections in a system | **Architecture** | [type-architecture.md](references/type-architecture.md) |
| Legacy IT landscape grouped by phase/department; documents the *before* state in modernization proposals | **IT current-state** | [type-it-state.md](references/type-it-state.md) |
| Decision logic with branches | **Flowchart** | [type-flowchart.md](references/type-flowchart.md) |
| Time-ordered messages between actors | **Sequence** | [type-sequence.md](references/type-sequence.md) |
| States + transitions + guards | **State machine** | [type-state.md](references/type-state.md) |
| Entities + fields + relationships | **ER / data model** | [type-er.md](references/type-er.md) |
| Events positioned in time | **Timeline** | [type-timeline.md](references/type-timeline.md) |
| Cross-functional process with handoffs | **Swimlane** | [type-swimlane.md](references/type-swimlane.md) |
| Two-axis positioning / prioritization | **Quadrant** | [type-quadrant.md](references/type-quadrant.md) |
| Multiple entities scored across 3–5 quantitative criteria | **Radar / Spider** | [type-radar.md](references/type-radar.md) |
| One quantitative series across cyclic categories; angle=category, radius=magnitude | **Polar chart** | [type-polar.md](references/type-polar.md) |
| Reinforcing cycle / flywheel where the last step feeds the first and a shared hub accumulates state | **Loop** | [type-loop.md](references/type-loop.md) |
| Hierarchy through containment / scope | **Nested** | [type-nested.md](references/type-nested.md) |
| Parent → children relationships | **Tree** | [type-tree.md](references/type-tree.md) |
| Human/agent/team ownership, reporting, routing, escalation | **Org chart** | [type-org-chart.md](references/type-org-chart.md) |
| Stacked abstraction levels | **Layer stack** | [type-layers.md](references/type-layers.md) |
| Overlap between sets | **Venn** | [type-venn.md](references/type-venn.md) |
| Ranked hierarchy or conversion drop-off | **Pyramid / funnel** | [type-pyramid.md](references/type-pyramid.md) |
| Quantitative comparison across categories | **Bar chart** | [type-bar.md](references/type-bar.md) |
| Part-of-whole where the relative sizes are the story | **Treemap** | [type-treemap.md](references/type-treemap.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](references/type-line.md) |
| Tasks and phases on a timeline | **Gantt** | [type-gantt.md](references/type-gantt.md) |
| Distribution and correlation between two variables, three with area-sized marks (bubble), or one variable with a dot per item (beeswarm) | **Scatter plot** | [type-scatter.md](references/type-scatter.md) |
| End-to-end data stack on a container cluster | **High-Level** | [type-high-level.md](references/type-high-level.md) |
| Multi-actor sequential process with data handoffs | **Process** | [type-process.md](references/type-process.md) |
| Multi-tier data storage with quality levels and access policies | **Medallion** | [type-medallion.md](references/type-medallion.md) |
| Role-scoped data flow: who does what at each pipeline step | **Data flow** | [type-data-flow.md](references/type-data-flow.md) |
| Integration topology of a data platform — sources → core → consumers | **DP integration** | [type-dp-integration.md](references/type-dp-integration.md) |
| Per-role / per-component access permissions matrix | **DP security matrix** | [type-dp-security-matrix.md](references/type-dp-security-matrix.md) |
| A quantity splitting and merging across stages, band width = amount | **Sankey** | [type-sankey.md](references/type-sankey.md) |
| Causes of one observed effect, grouped by category (root-cause analysis) | **Fishbone** | [type-fishbone.md](references/type-fishbone.md) |
| Value chain against evolution — what to build, buy, and what is moving | **Wardley map** | [type-wardley.md](references/type-wardley.md) |
| Work-in-progress by state, with WIP limits and blocked items | **Kanban** | [type-kanban.md](references/type-kanban.md) |
| What a person does across stages of an experience, and how it feels | **User journey** | [type-journey.md](references/type-journey.md) |
| Where software runs — zones, hosts, artifacts, replicas, ports | **Deployment** | [type-deployment.md](references/type-deployment.md) |
| What depends on what, with fan-in and cycles a tree cannot express | **Dependency graph** | [type-dependency.md](references/type-dependency.md) |
| Classes with operations, inheritance, composition (other UML routes elsewhere) | **UML class** | [type-uml-class.md](references/type-uml-class.md) |
| Narrative backbone sliced into releases, with the cut line | **Story map** | [type-story-map.md](references/type-story-map.md) |
| Physical tables: SQL types, constraints, indexes, column-level FKs | **Database schema** | [type-db-schema.md](references/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 (and semantic pattern, if routed), the size preset, and anything the complexity budget (§7) will force out. If the user is reachable, let them redirect before you draw; if not, proceed and note the assumptions beside the deliverable. Skip the pause only when the request already pins type, size, and content exactly.

---

## 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 |
| Reproducing Mermaid's renderer layout | Imports automatic spacing and routing instead of making an editorial layout |
| Any breach of the six §6 connector rules | Diagonal slants, labels touching their stroke, masks clipped by a later node, overlapping paths, shared attach points, transit behind a non-endpoint box — each is an automatic fail; §6 states them in full |

Type-specific anti-patterns live in each type reference linked in the guide.

---

## 5. Design System

**The design system is skinnable.** All colors, typography, and tokens live in a single source of truth — [`references/style-guide.md`](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`](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

**Korean labels** — Geist and Instrument Serif carry no Hangul. Extend the family on that `<text>`, budget 1em per Unicode wide or full-width character and the Latin advance for every other, and never set Hangul below 12px. Full rules in [`style-guide.md`](references/style-guide.md#korean-labels).

**Mono is for technical content only** — never as a blanket "dev" font, and never JetBrains Mono.

```html
<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&family=Noto+Sans+KR:wght@400;500;600&family=Noto+Serif+KR:wght@400&display=swap" rel="stylesheet">

6. Core SVG Primitives

Universal building blocks. Type-specialized primitives (lifeline, activation bar, region) live in the relevant type reference linked in the guide. 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
Optional explanatory motion → animation.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.

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

Arrow markers (define all three, always)

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

Mandatory connector rules

These six 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.
A label mask must not overlap a node drawn after it. Rule 2 keeps the label off its own connector; this one keeps it off the boxes. Because nodes are painted after labels, a mask that lands partly inside a node is covered by the node fill and the text renders as a fragment sitting on the node border. Place the label on a segment of the connector that runs through open canvas — for a connector leaving a node's right edge, that means clearing the node's x + width before the mask starts. A mask fully inside a node is a badge chip and is fine; a mask overlapping a zone container is fine too, since zones are painted first. From a repository checkout, verify with python3 <repo-root>/scripts/verify-geometry.py <file>.

Node box — full pattern

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

Arrow labels — always mask, always with ma

…

Diagram Design

Skill Details

Diagram Design

Why I built it

What it makes

Install

Editable install

Onboarding — make it look like your brand

The flow

What gets extracted

Contrast checks happen automatically

Accessible by default

Manual override

First-run gate

Working with multiple clients

Quickstart

Semantic patterns and optional motion

Import from draw.io or Mermaid

The four dials

Export to PNG / SVG

Architecture

6. Core SVG Primitives

Background

Arrow markers (define all three, always)

Mandatory connector rules

Node box — full pattern

Arrow labels — always mask, always with ma

Related Skills