Introducing a new way to review your PRs.

Read the announcement

cathrynlavery / diagram-design

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

View on GitHub

23 documents · Updated Nov 20, 2026

docs / diagram-taxonomy-and-semantics

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 understandPatternNearest typeEssential signal
Arrivals compete for finite service capacityFan-in queue / bottleneckData flowQueue depth, capacity, constrained service, and admitted or deferred work
The same questions repeat across stagesStage framework with semantic slotsProcessOrdered stages with stable Question, Input, Governance, and Output slots
Loose input becomes a durable recordUnstructured input → structured artifactData flowSource statements, extracted fields, provenance, and unknown values
Similar decisions diverge under different rulesPaired policy-evaluation tracesFlowchartMatching rule order, explicit statuses, and first divergence
A supported route crosses a trust boundarySecure paved roadArchitectureActors, allowed and blocked paths, a privileged gate, isolated runtime, and audit output
Controls must be read by enforcement pointGovernance / control catalogLayer stackNamed surfaces, controls, actors, timing, exceptions, and gaps
Each defense reduces but does not erase riskCompensating security layersLayer stackThreat input, mitigation, limitation, residual risk, and response
Blocks need stable identity and traceable structureTraceable block decompositionTreeBlock IDs, parent-child structure, optional I/O labels, and registry traceability
One subject moves through phases and outcomesLifecycle phase mapState machinePrimary 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 problemVisual typeDistinguishing question
One logical system snapshotArchitectureWhat talks to what?
Two synchronized topology snapshotsArchitecture deltaWhat survives, appears, disappears, changes, moves, or reconnects?
A legacy landscape before modernizationIT current-stateWhere are the silos, file hand-offs, and pain points?
An end-to-end stack on a container platformHigh-LevelHow do the main data phases fit inside the platform boundary?
Role-scoped data work across pipeline stagesData flowWho does what, and what payload changes at each stage?
Data-platform integration surfacesDP integrationWhich sources and consumers connect, and over what wire?
Per-role access permissionsDP security matrixWho can do what to each platform component?
Software placed on hosts or managed servicesDeploymentWhat runs where, in which environment, at what version and replica count?
Rooms, buildings, and paths on one siteAxonometric planWhat stands where, and how is the space used?
Parts of one physical objectExploded axonometricWhat are the parts, and how do they fit together?
Shared dependencies or cyclesDependency graphWhat cannot be expressed by a single-parent tree?
Scope or trust through containmentNestedWhich smaller scopes sit inside broader scopes?
Stacked abstraction or control levelsLayer stackWhich 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 problemVisual typeDistinguishing question
Branching decisions or algorithmsFlowchartWhich decision leads to which outcome?
Messages between actors over timeSequenceWhich actor sends each request or reply, and in what order?
A finite set of states and triggersState machineWhich event moves the subject to another state?
Sequential work with owners, payloads, and toolsProcessWho performs each stage, and what enters or leaves it?
Cross-functional handoffsSwimlaneWhere does work move between teams or vendors?
Customer-visible and hidden service work across stagesService blueprintWhat happens above and below the line of visibility?
A repeated cycle that writes to shared stateLoopHow does the last station return to the first?
Events on an honest time scaleTimelineWhen did milestones or incidents occur?
Tasks with start and end datesGanttWhich work overlaps in a project plan?
A person's actions and feelingsUser journeyHow does one persona experience each stage?
Work counted by current stateKanbanWhat is queued, active, blocked, or done now?
Narrative work sliced into releasesStory mapWhat 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 problemVisual typeDistinguishing question
Domain entities and cardinalityER / data modelWhich entities relate, and how many can participate?
Physical tables and SQL rulesDatabase schemaWhich columns, constraints, indexes, and delete actions exist?
Classes with operations and typed relationshipsUML classWhat does each class own, inherit, or use?
Parent-to-child structureTreeWhich items belong below each parent?
Human, agent, or team ownershipOrg chartWho owns, routes, reports, or escalates to whom?
Overlap between setsVennWhich 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 problemVisual type or variantDistinguishing question
Compare categories by one quantityBar chartWhich category is larger or smaller?
Follow a continuous trendLine chartHow does a value change across time or sequence?
Compare two states across seriesSlopegraph / dumbbellWho changed, and how large is the gap?
Show distributionsRidgeline / beeswarmWhere is the mass, crowd, or outlier?
Show rank movementBump chartWhich item changed position?
Compare two continuous variablesScatter plotAre the variables correlated, clustered, or marked by outliers?
Add magnitude to a two-variable comparisonBubble chartWhich item combines position with a large footprint?
Compare entities across normalized criteriaRadar / SpiderWhat shape does each option have across the same criteria?
Compare one series around a meaningful cyclePolar chartHow does magnitude vary around the cycle?
Show a part-to-whole breakdownTreemapWhich parts dominate the total?
Show a two-way part-to-whole breakdownMarimekkoWhich category and series combination dominates?
Scan row and column combinationsHeatmapWhich cell or cluster stands out?
Show quantity splitting or mergingSankeyHow much moves along each branch?
Show ranked narrowing or conversion drop-offPyramid / funnelWhere does priority or volume narrow?
Show signed changes to one running totalWaterfallHow 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 problemVisual typeDistinguishing question
Two-axis positioning or prioritizationQuadrantWhere does each item sit against two named dimensions?
Value chain against evolutionWardley mapWhat should be built, bought, or watched as it changes?
Causes grouped around one observed effectFishboneWhat causes were investigated for this outcome?
Storage tiers with quality and access changesMedallionHow 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…PreferAvoid
Logical components and connectionsArchitectureDeployment details that do not affect the logical claim
Two related topologies and their changesArchitecture deltaA timeline or a second independently arranged architecture
Hosts, zones, artifacts, versions, or replicasDeploymentA logical architecture with hostnames added as decoration
One floor or site with physical rooms or buildingsAxonometric planExploded axonometric
One physical object with separated partsExploded axonometricLayer stack when no physical part exists
Role-owned data with typed payloadsData flowSwimlane when payload shape and access scope are central
A cross-team business handoffSwimlaneData flow when no typed data-pipeline story exists
A sequential process with tools and input/outputProcessSwimlane when each payload and tool must remain visible
Customer and service work split by visibility across stagesService blueprintUser journey when no sentiment curve is needed, or Swimlane when arrows are the claim
Entities and relationship cardinalityERDatabase schema when SQL behavior is not the issue
SQL columns and referential actionsDatabase schemaER when the foreign key must anchor to a column
A single-parent hierarchyTreeDependency graph without shared parents or cycles
Current work by stateKanbanArrows between cards
A real experience with sentimentUser journeyProcess when no person or sentiment is present
One subject's phases and outcomesState machine with Lifecycle phase mapSequence when actor messages carry the story
A signed sequence changing one totalWaterfallBar for independent categories or Sankey for branching quantities
A one-way whole whose relative parts matterTreemapBar when the reader needs exact ranked values more than proportion
A row-by-column quantity matrixHeatmapA multi-hue chart when one monotone magnitude ramp is the claim
Quantity that splits or merges across stagesSankeyProcess 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

TriggerConsequenceGuard
Choosing a type before identifying load-bearing behaviorThe layout looks plausible but hides the queue, boundary, divergence, lifecycle, or risk storySelect one primary semantic pattern first when behavior matters
Using a tree for shared dependencies or cyclesFan-in or the cycle disappearsUse Dependency graph when a node has multiple parents or a cycle
Using Architecture delta for unrelated snapshotsThe reader infers continuity or migration order that the figure does not proveUse two synchronized states with stable IDs and a change ledger
Using Exploded axonometric for a floor or site planSpatial relation is mistaken for assembly orderUse Axonometric plan for rooms, buildings, paths, and one site plate
Using a Kanban board to show movementArrows turn a state census into an unclear process mapKeep Kanban connector-free; use Swimlane or Process for flow
Using a Service blueprint for a handoff flowThe stage grid shows visibility but not ownership transfer or message orderUse Swimlane for arrows and cross-team handoffs
Using a User journey without a sentiment curveThe figure becomes a process map with extra rowsUse a named sentiment level for each stage or choose Process or Timeline
Mixing conceptual entities with physical tablesReaders cannot tell whether names, types, or delete rules are authoritativeUse ER for domain relationships and Database schema for SQL details
Treating traceable block decomposition as a new diagram typeThe taxonomy grows without a new layout grammar and Tree limits become unclearRoute the pattern to Tree and keep extended block facts in the registry
Modeling actor messages as lifecycle phasesThe reader cannot tell whether the figure shows progress or exchangeUse Lifecycle phase map for one subject and Sequence for message timing
Collapsing cancellation and failure into one terminal stateA key lifecycle outcome disappearsUse distinct labeled terminal states
Using Waterfall for independent comparisons or branching quantitiesThe chart suggests a running total that does not existUse Bar for categories and Sankey for splitting or merging flow
Using Sankey without balanced quantitiesRibbon thickness appears to prove a transfer that the totals do not supportReconcile every node's incoming and outgoing amounts before drawing
Omitting small parts from a TreemapThe displayed whole no longer represents the stated totalKeep every part, or merge the tail into a named Other bucket
Using a multi-hue Heatmap for one unsigned measureHue suggests extra categories or a false signed scaleUse one monotone magnitude ramp and one focal accent at most
Exceeding the pattern or type budgetLabels and paths compete, so the central claim is lostApply the stricter budget and split into overview plus detail
Relying on color or animation for states and outcomesA still, print, or reduced-motion reader cannot recover the decisionKeep status, outcome, scale, and risk words in the static frame

Key files

FileWhy to read it
skills/…/SKILL.mdCentral routing table for semantic patterns and supported visual types
skills/…/semantic-patterns.mdPattern triggers, required signals, budgets, anti-patterns, and static fallbacks
skills/…/type-architecture.mdLogical system structure, trust-boundary grouping, and nested containment
skills/…/type-architecture-delta.mdSynchronized topology comparison and change semantics
skills/…/type-data-flow.mdRole-scoped data-pipeline grammar and payload distinction
skills/…/type-process.mdMulti-actor process grammar with owners and payloads
skills/…/type-service-blueprint.mdCustomer, frontstage, backstage, and support work on a shared visibility grid
skills/…/type-sequence.mdTime-ordered actor messages and branch grammar
skills/…/type-state.mdState and transition grammar used by lifecycle maps
skills/…/type-swimlane.mdCross-functional ownership and handoff grammar
skills/…/type-journey.mdPersona experience grammar and sentiment requirement
skills/…/type-bar.mdCategory comparison and two-value dumbbell distinction
skills/…/type-heatmap.mdComplete row-by-column comparison and focal-cell semantics
skills/…/type-sankey.mdQuantity flow grammar for splitting and merging amounts
skills/…/type-treemap.mdOne-way part-to-whole area encoding and Marimekko variant
skills/…/type-deployment.mdPhysical placement, environment zones, versions, and replicas
skills/…/type-db-schema.mdPhysical SQL schema boundary against conceptual ER modeling
skills/…/type-tree.mdParent-child hierarchy used by traceable block decomposition
skills/…/type-kanban.mdCurrent-state work board and its no-connector contract
skills/…/type-waterfall.mdRunning-total grammar, signed bridges, and reconciliation
docs/…/0002-semantic-patterns-do-not-expand-the-taxonomy.mdDecision that semantic patterns reuse visual types and record taxonomy counts