Diagram taxonomy and semantic patterns
Diagram design starts with the reader's question. The skill maps that question to one of nine semantic patterns and one of 45 visual types. A pattern states the behavior or risk that matters. A visual type supplies the page grammar that makes that meaning easy to read. Use this page with the diagram design skill, then see diagram onboarding and output, diagram style and primitives, and diagram example gallery.
Grammar selection
Pattern-first selection
Choose a primary semantic pattern when behavior, state, enforcement, or risk carries the claim. Then choose the closest visual type for the layout. If no pattern fits, choose the type from the reader's main question.
The pattern supplies the special meaning. The type supplies the dominant axis, placement, and connector grammar. Do not combine two layout grammars to preserve every detail.
The selection path is:
flowchart TD
Q[Reader question] --> B{Behavior, state, risk, or enforcement matters?}
B -->|Yes| P[Choose one primary semantic pattern]
B -->|No| T[Choose the visual type directly]
P --> G[Choose the closest visual type]
T --> R[Read the type reference]
G --> R
R --> C{Within the stricter complexity budget?}
C -->|Yes| D[Design the static meaning]
C -->|No| S[Split into overview and detail]
When two types seem valid, name the dominant axis: time, ownership, messages, state, containment, quantity, relationship, or physical placement. If neither axis can carry the claim without crowding, split the subject.
References: skills/…/SKILL.md• L65-81 skills/…/SKILL.md• L132-142 skills/…/semantic-patterns.md• L1-5
Semantic patterns
Reusable behavior patterns
Semantic patterns are reusable story shapes. They tell the reader what to inspect in the figure. The visual type decides where that story appears.
| Reader must understand | Pattern | Nearest type | Essential signal |
|---|---|---|---|
| Arrivals compete for finite service capacity | Fan-in queue / bottleneck | Data flow | Queue depth, capacity, constrained service, and admitted or deferred work |
| The same questions repeat across stages | Stage framework with semantic slots | Process | Ordered stages with stable Question, Input, Governance, and Output slots |
| Loose input becomes a durable record | Unstructured input → structured artifact | Data flow | Source statements, extracted fields, provenance, and unknown values |
| Similar decisions diverge under different rules | Paired policy-evaluation traces | Flowchart | Matching rule order, explicit statuses, and first divergence |
| A supported route crosses a trust boundary | Secure paved road | Architecture | Actors, allowed and blocked paths, a privileged gate, isolated runtime, and audit output |
| Controls must be read by enforcement point | Governance / control catalog | Layer stack | Named surfaces, controls, actors, timing, exceptions, and gaps |
| Each defense reduces but does not erase risk | Compensating security layers | Layer stack | Threat input, mitigation, limitation, residual risk, and response |
| Blocks need stable identity and traceable structure | Traceable block decomposition | Tree | Block IDs, parent-child structure, optional I/O labels, and registry traceability |
| One subject moves through phases and outcomes | Lifecycle phase map | State machine | Primary phases, interruption or recovery states, labeled transitions, and distinct terminal outcomes |
The pattern budget is part of the meaning. A queue shows representative arrivals and capacity. A paired trace shows two paths. A lifecycle map keeps a short phase rail and separate terminal outcomes. Traceable block decomposition stays a Tree and keeps extended detail in its registry rather than adding a new layout axis.
Keep states, outcomes, blocked paths, unknown values, and residual risk in text. Color, position, and motion can reinforce meaning, but a still image must communicate the claim without them.
References: skills/…/SKILL.md• L65-81 skills/…/semantic-patterns.md• L7-19 skills/…/semantic-patterns.md• L21-47 skills/…/semantic-patterns.md• L119-147
Visual type families
System structure and placement
These types explain what a system contains, where its boundaries are, or where its parts run. Choose them by the physical or logical question the reader must answer.
| Communication problem | Visual type | Distinguishing question |
|---|---|---|
| One logical system snapshot | Architecture | What talks to what? |
| Two synchronized topology snapshots | Architecture delta | What survives, appears, disappears, changes, moves, or reconnects? |
| A legacy landscape before modernization | IT current-state | Where are the silos, file hand-offs, and pain points? |
| An end-to-end stack on a container platform | High-Level | How do the main data phases fit inside the platform boundary? |
| Role-scoped data work across pipeline stages | Data flow | Who does what, and what payload changes at each stage? |
| Data-platform integration surfaces | DP integration | Which sources and consumers connect, and over what wire? |
| Per-role access permissions | DP security matrix | Who can do what to each platform component? |
| Software placed on hosts or managed services | Deployment | What runs where, in which environment, at what version and replica count? |
| Rooms, buildings, and paths on one site | Axonometric plan | What stands where, and how is the space used? |
| Parts of one physical object | Exploded axonometric | What are the parts, and how do they fit together? |
| Shared dependencies or cycles | Dependency graph | What cannot be expressed by a single-parent tree? |
| Scope or trust through containment | Nested | Which smaller scopes sit inside broader scopes? |
| Stacked abstraction or control levels | Layer stack | Which concepts belong at each level? |
Architecture describes logical relationships. Its containment variant makes administrative and traffic scopes visible when the hierarchy itself is the claim. Architecture delta compares exactly two related topologies and explains the differences in a change ledger. Deployment adds placement, versions, and replicas. Axonometric plan uses one physical plate. Exploded axonometric separates parts of one object. High-Level shows phases inside a platform boundary, while DP integration shows source and consumer surfaces around a platform with no phase axis.
References: skills/…/SKILL.md• L83-106 skills/…/SKILL.md• L115-120 skills/…/type-architecture.md• L1-10 skills/…/type-architecture.md• L73-101 skills/…/type-architecture-delta.md• L1-22 skills/…/type-deployment.md• L1-17 skills/…/type-axonometric-plan.md• L1-12 skills/…/type-exploded.md• L1-10 skills/…/type-dp-integration.md• L1-7 skills/…/type-dp-security-matrix.md• L1-7
Flow, interaction, and lifecycle
These types make order, ownership, exchange, or change visible. The key choice is whether the reader follows decisions, messages, work ownership, state changes, a person's experience, or visible and hidden service work.
| Communication problem | Visual type | Distinguishing question |
|---|---|---|
| Branching decisions or algorithms | Flowchart | Which decision leads to which outcome? |
| Messages between actors over time | Sequence | Which actor sends each request or reply, and in what order? |
| A finite set of states and triggers | State machine | Which event moves the subject to another state? |
| Sequential work with owners, payloads, and tools | Process | Who performs each stage, and what enters or leaves it? |
| Cross-functional handoffs | Swimlane | Where does work move between teams or vendors? |
| Customer-visible and hidden service work across stages | Service blueprint | What happens above and below the line of visibility? |
| A repeated cycle that writes to shared state | Loop | How does the last station return to the first? |
| Events on an honest time scale | Timeline | When did milestones or incidents occur? |
| Tasks with start and end dates | Gantt | Which work overlaps in a project plan? |
| A person's actions and feelings | User journey | How does one persona experience each stage? |
| Work counted by current state | Kanban | What is queued, active, blocked, or done now? |
| Narrative work sliced into releases | Story map | What is the whole story, and where is the release cut? |
These grammars are not interchangeable. Sequence uses messages and lifelines. Swimlane uses ownership lanes and handoffs. Process adds payloads and tools. Service blueprint uses a shared stage grid and a line of visibility, without arrows. User journey adds a sentiment curve for one persona. Kanban is a state census with no connectors. A Loop requires a real return to its first station and a shared state hub. A lifecycle phase map is a State Machine pattern for one subject, not a message exchange.
References: skills/…/SKILL.md• L87-99 skills/…/SKILL.md• L111-113 skills/…/SKILL.md• L124-129 skills/…/type-sequence.md• L1-14 skills/…/type-state.md• L1-17 skills/…/type-process.md• L1-7 skills/…/type-service-blueprint.md• L1-18 skills/…/type-swimlane.md• L1-17 skills/…/type-journey.md• L1-5 skills/…/type-kanban.md• L1-4 skills/…/type-story-map.md• L1-9
Data models and hierarchies
These types describe relationships among entities, records, classes, owners, sets, or members. Select the grammar by the level of truth the reader needs.
| Communication problem | Visual type | Distinguishing question |
|---|---|---|
| Domain entities and cardinality | ER / data model | Which entities relate, and how many can participate? |
| Physical tables and SQL rules | Database schema | Which columns, constraints, indexes, and delete actions exist? |
| Classes with operations and typed relationships | UML class | What does each class own, inherit, or use? |
| Parent-to-child structure | Tree | Which items belong below each parent? |
| Human, agent, or team ownership | Org chart | Who owns, routes, reports, or escalates to whom? |
| Overlap between sets | Venn | Which members are unique or shared? |
ER is conceptual or logical. Database schema is physical and anchors foreign keys to columns. UML class is for operations and inheritance. Tree is for one-parent hierarchy. Use Dependency graph when shared parents or cycles are part of the claim. Use Org chart when responsibility matters more than generic hierarchy.
References: skills/…/SKILL.md• L89-103 skills/…/type-er.md• L1-15 skills/…/type-db-schema.md• L1-18 skills/…/type-uml-class.md• L1-24 skills/…/type-tree.md• L1-12 skills/…/type-org-chart.md• L1-17 skills/…/type-venn.md• L1-13
Quantitative comparison and composition
These types encode measured values through position, length, area, angle, rank, or band width. Match the encoding to the comparison task.
| Communication problem | Visual type or variant | Distinguishing question |
|---|---|---|
| Compare categories by one quantity | Bar chart | Which category is larger or smaller? |
| Follow a continuous trend | Line chart | How does a value change across time or sequence? |
| Compare two states across series | Slopegraph / dumbbell | Who changed, and how large is the gap? |
| Show distributions | Ridgeline / beeswarm | Where is the mass, crowd, or outlier? |
| Show rank movement | Bump chart | Which item changed position? |
| Compare two continuous variables | Scatter plot | Are the variables correlated, clustered, or marked by outliers? |
| Add magnitude to a two-variable comparison | Bubble chart | Which item combines position with a large footprint? |
| Compare entities across normalized criteria | Radar / Spider | What shape does each option have across the same criteria? |
| Compare one series around a meaningful cycle | Polar chart | How does magnitude vary around the cycle? |
| Show a part-to-whole breakdown | Treemap | Which parts dominate the total? |
| Show a two-way part-to-whole breakdown | Marimekko | Which category and series combination dominates? |
| Scan row and column combinations | Heatmap | Which cell or cluster stands out? |
| Show quantity splitting or merging | Sankey | How much moves along each branch? |
| Show ranked narrowing or conversion drop-off | Pyramid / funnel | Where does priority or volume narrow? |
| Show signed changes to one running total | Waterfall | How does one total become the next? |
The variants keep their parent grammar while changing the question. A Waterfall is a sequential running-total bridge. A Sankey is a branching quantity flow whose band thickness carries magnitude. A Funnel is ordered narrowing. A Treemap uses area for a one-way whole; Marimekko uses width, height, and area for a two-way whole. A Heatmap uses a complete row-by-column grid for scanning combinations. Use a table when a small set of exact values is more useful than visual comparison.
References: skills/…/SKILL.md• L93-114 skills/…/type-bar.md• L1-16 skills/…/type-heatmap.md• L1-4 skills/…/type-heatmap.md• L36-59 skills/…/type-sankey.md• L1-3 skills/…/type-sankey.md• L8-29 skills/…/type-treemap.md• L1-22 skills/…/type-treemap.md• L70-97 skills/…/type-line.md• L1-15 skills/…/type-scatter.md• L1-13 skills/…/type-polar.md• L1-12 skills/…/type-waterfall.md• L1-27
Strategy and diagnosis
These types organize choices, causes, scope, evolution, or storage quality rather than runtime structure. Their axes and cuts carry the main argument.
| Communication problem | Visual type | Distinguishing question |
|---|---|---|
| Two-axis positioning or prioritization | Quadrant | Where does each item sit against two named dimensions? |
| Value chain against evolution | Wardley map | What should be built, bought, or watched as it changes? |
| Causes grouped around one observed effect | Fishbone | What causes were investigated for this outcome? |
| Storage tiers with quality and access changes | Medallion | How is the same data promoted or retained? |
A story map is not a Kanban board: its columns are narrative order and its rows are release slices. A User journey is not a story map: it follows one person's sentiment. Medallion is not a general data-stack view: its tiers are quality or access levels of the same dataset. Wardley maps are strategy views, not runtime topology.
References: skills/…/SKILL.md• L96-123 skills/…/type-quadrant.md• L1-11 skills/…/type-wardley.md• L1-14 skills/…/type-fishbone.md• L1-12 skills/…/type-medallion.md• L1-7
Semantic boundaries
Type distinctions
Several types can describe the same subject from different angles. Keep the distinction that makes the reader's question answerable instead of combining grammars in one figure.
| If the subject is… | Prefer | Avoid |
|---|---|---|
| Logical components and connections | Architecture | Deployment details that do not affect the logical claim |
| Two related topologies and their changes | Architecture delta | A timeline or a second independently arranged architecture |
| Hosts, zones, artifacts, versions, or replicas | Deployment | A logical architecture with hostnames added as decoration |
| One floor or site with physical rooms or buildings | Axonometric plan | Exploded axonometric |
| One physical object with separated parts | Exploded axonometric | Layer stack when no physical part exists |
| Role-owned data with typed payloads | Data flow | Swimlane when payload shape and access scope are central |
| A cross-team business handoff | Swimlane | Data flow when no typed data-pipeline story exists |
| A sequential process with tools and input/output | Process | Swimlane when each payload and tool must remain visible |
| Customer and service work split by visibility across stages | Service blueprint | User journey when no sentiment curve is needed, or Swimlane when arrows are the claim |
| Entities and relationship cardinality | ER | Database schema when SQL behavior is not the issue |
| SQL columns and referential actions | Database schema | ER when the foreign key must anchor to a column |
| A single-parent hierarchy | Tree | Dependency graph without shared parents or cycles |
| Current work by state | Kanban | Arrows between cards |
| A real experience with sentiment | User journey | Process when no person or sentiment is present |
| One subject's phases and outcomes | State machine with Lifecycle phase map | Sequence when actor messages carry the story |
| A signed sequence changing one total | Waterfall | Bar for independent categories or Sankey for branching quantities |
| A one-way whole whose relative parts matter | Treemap | Bar when the reader needs exact ranked values more than proportion |
| A row-by-column quantity matrix | Heatmap | A multi-hue chart when one monotone magnitude ramp is the claim |
| Quantity that splits or merges across stages | Sankey | Process when no magnitude or branching is present |
When two types still seem valid, choose the dominant axis. Do not treat traceability metadata as a new layout axis; keep it with the Tree-based pattern and its registry.
References: skills/…/SKILL.md• L132-138 skills/…/type-architecture.md• L73-101 skills/…/type-architecture-delta.md• L1-10 skills/…/type-data-flow.md• L1-7 skills/…/type-process.md• L1-7 skills/…/type-service-blueprint.md• L1-13 skills/…/type-db-schema.md• L1-5 skills/…/type-dependency.md• L1-5 skills/…/type-sankey.md• L57-69 skills/…/type-treemap.md• L55-68 skills/…/type-waterfall.md• L1-17
Complexity budgets
Every pattern and type has a capacity for nodes, edges, lanes, stages, or marks. Apply the stricter limit. Crossing that limit usually means the figure contains more than one argument.
Use these actions when the subject is too large:
- Group repeated items into a named cohort when the group is not the point.
- Keep the overview to the main actors, paths, states, or measures.
- Move rules and field detail into notes or a companion page.
- Split into an overview and detail figures when the structure must remain visible.
The broad target is nine nodes and twelve arrows. Type limits refine it. For example, Sequence uses up to five lifelines, User journey uses up to six stages, Service blueprint uses four to six stages, and Lifecycle phase map uses four to five primary phases plus a small set of recovery and terminal states. Sankey uses three stage columns, up to eight nodes, and up to twelve flows. A type may exceed the broad target only when its own grammar makes the extra detail the claim.
References: skills/…/SKILL.md• L45-46 skills/…/SKILL.md• L132-138 skills/…/semantic-patterns.md• L27-29 skills/…/semantic-patterns.md• L41-47 skills/…/type-sequence.md• L89-97 skills/…/type-journey.md• L32-47 skills/…/type-service-blueprint.md• L15-34 skills/…/type-sankey.md• L46-55 skills/…/type-treemap.md• L7-12
Static semantics
The complete meaning must remain visible in a static frame. This matters most for queues, policy traces, security paths, state changes, and quantitative encodings that may be read without motion or color.
Use stable labels for states and outcomes. Show blocked paths as blocked. Distinguish SKIPPED from NOT REACHED. Show unknown values and residual risk. For quantitative types, keep the relevant scale, units, totals, or signed values honest. Heatmaps must state the included row and column set. Sankeys must balance incoming and outgoing quantities. Treemaps must account for small parts instead of hiding them. Animation can reveal order, but it is a presentation layer and does not create a new semantic pattern.
References: skills/…/semantic-patterns.md• L29-31 skills/…/semantic-patterns.md• L65-73 skills/…/semantic-patterns.md• L79-87 skills/…/type-heatmap.md• L53-74 skills/…/type-sankey.md• L23-44 skills/…/type-treemap.md• L55-59 skills/…/type-polar.md• L55-57 skills/…/type-waterfall.md• L59-69
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to the supported type list in skills/…/SKILL.md must stay aligned with this taxonomy, the type-reference links, and the example gallery.
- Changes to a semantic pattern must update its routing row, required signal, budget, static fallback, anti-patterns, nearest type, and recorded pattern count together.
- Changes to a type boundary must be checked against adjacent grammars, especially Architecture versus Architecture delta or Deployment, Axonometric plan versus Exploded axonometric, ER versus Database schema, Process versus Swimlane or Service blueprint, User journey versus Service blueprint, Kanban versus Story map, and Waterfall versus Bar, Dumbbell, Sankey, or Funnel.
- Changes to Architecture delta must preserve synchronized Before and After topology, stable identity, explicit change status, and the visible change ledger.
- Changes to traceable block decomposition must keep Tree's hierarchy limits, block identity, and registry traceability aligned; the pattern must not add a layout grammar.
- Changes to Service blueprint must preserve the shared stage grid, complete required layers, and line-of-visibility role without introducing flow arrows or a sentiment curve.
- Changes to complexity budgets must preserve both the global budget and the stricter pattern or type budget.
- Changes to state, risk, boundary, or quantity semantics must keep text labels complete so static and reduced-motion views retain the same meaning.
- Changes to the visual-type or semantic-pattern count must update the taxonomy, verification count, and ADR 0002 together.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Choosing a type before identifying load-bearing behavior | The layout looks plausible but hides the queue, boundary, divergence, lifecycle, or risk story | Select one primary semantic pattern first when behavior matters |
| Using a tree for shared dependencies or cycles | Fan-in or the cycle disappears | Use Dependency graph when a node has multiple parents or a cycle |
| Using Architecture delta for unrelated snapshots | The reader infers continuity or migration order that the figure does not prove | Use two synchronized states with stable IDs and a change ledger |
| Using Exploded axonometric for a floor or site plan | Spatial relation is mistaken for assembly order | Use Axonometric plan for rooms, buildings, paths, and one site plate |
| Using a Kanban board to show movement | Arrows turn a state census into an unclear process map | Keep Kanban connector-free; use Swimlane or Process for flow |
| Using a Service blueprint for a handoff flow | The stage grid shows visibility but not ownership transfer or message order | Use Swimlane for arrows and cross-team handoffs |
| Using a User journey without a sentiment curve | The figure becomes a process map with extra rows | Use a named sentiment level for each stage or choose Process or Timeline |
| Mixing conceptual entities with physical tables | Readers cannot tell whether names, types, or delete rules are authoritative | Use ER for domain relationships and Database schema for SQL details |
| Treating traceable block decomposition as a new diagram type | The taxonomy grows without a new layout grammar and Tree limits become unclear | Route the pattern to Tree and keep extended block facts in the registry |
| Modeling actor messages as lifecycle phases | The reader cannot tell whether the figure shows progress or exchange | Use Lifecycle phase map for one subject and Sequence for message timing |
| Collapsing cancellation and failure into one terminal state | A key lifecycle outcome disappears | Use distinct labeled terminal states |
| Using Waterfall for independent comparisons or branching quantities | The chart suggests a running total that does not exist | Use Bar for categories and Sankey for splitting or merging flow |
| Using Sankey without balanced quantities | Ribbon thickness appears to prove a transfer that the totals do not support | Reconcile every node's incoming and outgoing amounts before drawing |
| Omitting small parts from a Treemap | The displayed whole no longer represents the stated total | Keep every part, or merge the tail into a named Other bucket |
| Using a multi-hue Heatmap for one unsigned measure | Hue suggests extra categories or a false signed scale | Use one monotone magnitude ramp and one focal accent at most |
| Exceeding the pattern or type budget | Labels and paths compete, so the central claim is lost | Apply the stricter budget and split into overview plus detail |
| Relying on color or animation for states and outcomes | A still, print, or reduced-motion reader cannot recover the decision | Keep status, outcome, scale, and risk words in the static frame |
Key files
| File | Why to read it |
|---|---|
| skills/…/SKILL.md | Central routing table for semantic patterns and supported visual types |
| skills/…/semantic-patterns.md | Pattern triggers, required signals, budgets, anti-patterns, and static fallbacks |
| skills/…/type-architecture.md | Logical system structure, trust-boundary grouping, and nested containment |
| skills/…/type-architecture-delta.md | Synchronized topology comparison and change semantics |
| skills/…/type-data-flow.md | Role-scoped data-pipeline grammar and payload distinction |
| skills/…/type-process.md | Multi-actor process grammar with owners and payloads |
| skills/…/type-service-blueprint.md | Customer, frontstage, backstage, and support work on a shared visibility grid |
| skills/…/type-sequence.md | Time-ordered actor messages and branch grammar |
| skills/…/type-state.md | State and transition grammar used by lifecycle maps |
| skills/…/type-swimlane.md | Cross-functional ownership and handoff grammar |
| skills/…/type-journey.md | Persona experience grammar and sentiment requirement |
| skills/…/type-bar.md | Category comparison and two-value dumbbell distinction |
| skills/…/type-heatmap.md | Complete row-by-column comparison and focal-cell semantics |
| skills/…/type-sankey.md | Quantity flow grammar for splitting and merging amounts |
| skills/…/type-treemap.md | One-way part-to-whole area encoding and Marimekko variant |
| skills/…/type-deployment.md | Physical placement, environment zones, versions, and replicas |
| skills/…/type-db-schema.md | Physical SQL schema boundary against conceptual ER modeling |
| skills/…/type-tree.md | Parent-child hierarchy used by traceable block decomposition |
| skills/…/type-kanban.md | Current-state work board and its no-connector contract |
| skills/…/type-waterfall.md | Running-total grammar, signed bridges, and reconciliation |
| docs/…/0002-semantic-patterns-do-not-expand-the-taxonomy.md | Decision that semantic patterns reuse visual types and record taxonomy counts |