/diagram-design

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, box plot), high-level, process, medallion, data flow, DP integration, DP security matrix, Sankey, fishbone, Wardley map, kanban, user journey, service blueprint, deployment, dependency graph (arc diagram), UML class, story map, or database schema diagrams as HTML/SVG/PNG, with .drawio, Mermaid, .excalidraw, and PlantUML 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-five 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`](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`](references/style-guide.md) and check the default tokens. If they are still the shipped defaults (paper `#f5f5f5`, ink `#2d3142`, accent `#bf4520`), **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`](references/onboarding.md); for **(f)** follow [`references/profiles.md`](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 45 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 → a separate plain-text tool such as wiretext. This skill doesn't ship one.
• 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`](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`](references/animation.md) only when motion is requested or materially clarifies ordered change; static remains the default.

Visual-type guide (45)

| If you're showing… | Use | Reference | |---|---|---| | Components + connections in one snapshot; nested admin vs traffic scopes | **Architecture** | [type-architecture.md](references/type-architecture.md) | | Structural change between synchronized Before / After topologies, with a Changes ledger