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-example-gallery

The diagram example gallery is a set of standalone HTML artifacts and screenshot references that show what the diagram-design skill can produce. It gives an engineer a visual reference for supported diagram types and for the main ways an artifact can be presented. The gallery belongs to the broader diagram asset library, alongside the reusable diagram templates.

The collection turns the skill's type guide into concrete, viewable examples. Each example shows a complete diagram in a browser-ready page, so an engineer can compare the visual grammar and choose a suitable starting point before creating a new artifact.

The gallery page lets a reader select a diagram type and then select a standard visual variant. It opens the matching standalone example for inspection rather than treating the gallery as the diagram itself.

The selection path is shown below.

flowchart LR
    A[Diagram question] --> B[Gallery type]
    B --> C{Presentation mode}
    C -->|standard| D[Minimal light]
    C -->|standard| E[Minimal dark]
    C -->|standard| F[Full editorial]
    C -->|special| G[Single-purpose example]
    D --> H[Standalone HTML artifact]
    E --> H
    F --> H
    G --> H

References: skills/…/index.html• L210-386 skills/…/index.html• L398-429

Thumbnail manifest

The thumbnail manifest records the link between each compact WEBP preview and its source PNG. It also records the source and thumbnail hashes, dimensions, and rendering settings so screenshot references can be traced back to the artifact that produced them. The collection now includes a waterfall preview with the same trace data.

References: docs/…/manifest.json• L1-16 docs/…/manifest.json• L370-376

Example families

The examples are grouped by the kind of question the diagram answers. This grouping helps an engineer choose a visual form without treating the file names as the product model. The collection now also includes a traceable tree example for showing a root capability and its child blocks, plus a waterfall example for showing how changes bridge one total to another.

Question being explainedExample familiesRepresentative artifact
How parts connect or work togetherArchitecture, high-level, flowchart, process, data flow, sequence, state, swimlane, deployment, dependencyskills/…/example-architecture.html
How data, ownership, or scope is shapedER, database schema, UML class, layers, nested, tree, tree block decomposition, org chart, data lake, medallionskills/…/example-db-schema.html
How work, time, or experience changesTimeline, Gantt, user journey, story map, Kanban, loop, IT current-stateskills/…/example-journey.html
How values, groups, or categories compareQuadrant, radar, polar, Venn, pyramid, bar, line, treemap, scatter, bubble, beeswarm, Sankey, waterfall, heatmap, Marimekko, streamgraph, fishbone, Wardley mapskills/…/example-heatmap.html
How a platform handles data and controlsDP integration, DP security matrix, medallion, data flow, high-levelskills/…/example-dp-integration.html

The collection also includes focused examples for imported Mermaid, draw.io, and Excalidraw sources. These show the result of preserving source meaning while applying the diagram system's own visual treatment. The diagram taxonomy and semantic patterns page explains how to select among these families.

References: skills/…/SKILL.md• L65-123 skills/…/index.html• L210-375 skills/…/example-import-mermaid.html• L19-24 skills/…/example-import-drawio.html• L57-63 skills/…/example-import-excalidraw.html• L21-26 skills/…/example-waterfall.html• L29-35

Variant conventions

Standard variants

Most diagram types use one subject with three presentation variants. The file stem names the type. A suffix names the presentation mode. The new axonometric plan and exploded axonometric families also provide an optional animated counterpart for showing the same subject in stages.

ModeNaming patternPurpose
Minimal lightexample-<type>.htmlDefault screenshot-ready view with the diagram and a short title.
Minimal darkexample-<type>-dark.htmlDark page or slide context where the diagram must keep its meaning against a dark surface.
Full editorialexample-<type>-full.htmlLong-form content where the diagram is paired with a subtitle, supporting cards, and a footer.
Optional motionexample-<type>-animated.htmlProgressive reveal or assembly while keeping a complete static frame available.

The variants are alternate presentations of the same diagram subject. They do not define new diagram types and should not change the core meaning. For example, the architecture example keeps the same content site model across light, dark, and full editorial files. The tree block decomposition example follows the same light, dark, and full editorial family. The waterfall family uses the same convention for its budget bridge across example-waterfall.html, example-waterfall-dark.html, and example-waterfall-full.html. The state lifecycle family applies the same convention to a newsletter publication flow across example-state-lifecycle.html, example-state-lifecycle-dark.html, and example-state-lifecycle-full.html. The heatmap, Marimekko, and streamgraph families extend the same convention to matrix intensity, part-to-whole comparison, and layered change over time.

The new axonometric plan families keep their subject stable across light, dark, and full editorial files. The coffee shop plan follows a customer path from the entrance to the espresso bar and seating. The warehouse plan follows goods from receiving through storage, picking, packing, and shipping. Their animated files reveal those spatial stages without replacing the complete plan.

The new exploded axonometric families keep their layers stable across light, dark, and full editorial files. The AI agent stack separates the interface, harness, skills, tools, and secrets vault. The mechanical keyboard separates the keycaps, switches, plate, PCB, and case. Their animated files assemble those layers into the final view while preserving the static exploded artifact.

The state lifecycle family demonstrates how one state-machine subject stays stable across presentation modes. Its primary rail moves from Draft to Sent, while approval, retry, cancellation, and failure remain visible as supporting or terminal outcomes. The light and dark files provide compact views. The full file adds a subtitle, explanatory cards, and a footer without changing that state model.

References: skills/…/SKILL.md• L504-519 skills/…/example-architecture.html• L57-63 skills/…/example-architecture-dark.html• L57-63 skills/…/example-architecture-full.html• L43-53 skills/…/example-tree-block-decomposition.html• L57-66 skills/…/example-tree-block-decomposition-dark.html• L57-66 skills/…/example-tree-block-decomposition-full.html• L35-47 skills/…/example-waterfall.html• L29-35 skills/…/example-waterfall-dark.html• L29-35 skills/…/example-waterfall-full.html• L34-41 skills/…/example-state-lifecycle.html• L21-27 skills/…/example-state-lifecycle-dark.html• L30-34 skills/…/example-state-lifecycle-full.html• L45-53 skills/…/example-heatmap.html• L27-48 skills/…/example-heatmap-dark.html• L27-48 skills/…/example-heatmap-full.html• L34-56 skills/…/example-marimekko.html• L28-54 skills/…/example-marimekko-dark.html• L28-54 skills/…/example-marimekko-full.html• L32-60 skills/…/example-streamgraph.html• L27-49 skills/…/example-streamgraph-dark.html• L27-49 skills/…/example-streamgraph-full.html• L34-58 skills/…/example-axonometric-plan-coffee-shop.html• L63-69 skills/…/example-axonometric-plan-coffee-shop-dark.html• L63-69 skills/…/example-axonometric-plan-coffee-shop-full.html• L37-45 skills/…/example-axonometric-plan-coffee-shop-animated.html• L193-200 skills/…/example-axonometric-plan-warehouse.html• L63-69 skills/…/example-axonometric-plan-warehouse-dark.html• L63-69 skills/…/example-axonometric-plan-warehouse-full.html• L37-45 skills/…/example-axonometric-plan-warehouse-animated.html• L193-200 skills/…/example-exploded-ai-stack.html• L63-69 skills/…/example-exploded-ai-stack-dark.html• L63-69 skills/…/example-exploded-ai-stack-full.html• L37-45 skills/…/example-exploded-ai-stack-animated.html• L206-213 skills/…/example-exploded-keyboard.html• L63-69 skills/…/example-exploded-keyboard-dark.html• L63-69 skills/…/example-exploded-keyboard-full.html• L37-45 skills/…/example-exploded-keyboard-animated.html• L206-213

Special presentation modes

Some examples demonstrate a presentation layer that is not part of the three-file standard. The gallery marks these as single-purpose entries and does not offer the normal variant switch for them.

Special modeExamplesRole in the collection
Imported sourceexample-import-mermaid.html, example-import-drawio.html, example-import-excalidraw.htmlShows a finished redraw of an external diagram source.
Consultant quadrantexample-quadrant-consultant.htmlShows a named 2×2 scenario matrix with a distinct consulting-style treatment.
Terminalexample-loop-terminal.htmlShows a loop inside a command-line window treatment for developer-focused content.
Animated semantic patternexample-policy-trace-animated.html, example-queue-animated.html, example-paved-road-animated.htmlShows ordered change, divergence, bottleneck behavior, or protected paths through motion.
Animated spatial or layered viewexample-axonometric-plan-coffee-shop-animated.html, example-axonometric-plan-warehouse-animated.html, example-exploded-ai-stack-animated.html, example-exploded-keyboard-animated.htmlShows spatial stages or separated layers through optional motion while retaining a static view.

These files are examples of presentation choices, not replacements for the static default. The diagram animation page covers the motion rules and the static fallback that animated examples must retain.

References: skills/…/index.html• L349-371 skills/…/SKILL.md• L513-519 skills/…/example-loop-terminal.html• L31-47 skills/…/example-queue-animated.html• L190-205 skills/…/example-import-excalidraw.html• L21-26 skills/…/example-axonometric-plan-coffee-shop-animated.html• L184-200 skills/…/example-axonometric-plan-warehouse-animated.html• L184-200 skills/…/example-exploded-ai-stack-animated.html• L184-213 skills/…/example-exploded-keyboard-animated.html• L184-213

Diagram type coverage

Structural diagrams

Structural examples explain parts, boundaries, relationships, and ownership. Their value is the match between the question and the visual grammar: architecture shows connected components, sequence shows ordered messages, and state shows transitions between conditions.

Type groupSupported examples
System structureArchitecture, high-level, high-level vertical, deployment, dependency
Process structureFlowchart, process, data flow, swimlane, sequence, sequence OAuth
Relationship structureER, database schema, UML class, nested, tree, tree block decomposition, org chart, layers
State and cycle structureState, state lifecycle, IT current-state, loop

The examples make these distinctions visible without requiring an engineer to infer them from a template. The state lifecycle family gives the state category a complete subject with a main progression, recovery path, and terminal outcomes. The type guide remains the source for the semantic choice; the gallery supplies the visual reference.

References: skills/…/SKILL.md• L81-123 skills/…/example-architecture.html• L61-63 skills/…/example-sequence-oauth.html• L1-17 skills/…/example-state.html• L1-20 skills/…/example-state-lifecycle.html• L21-27 skills/…/example-state-lifecycle-full.html• L45-53 skills/…/example-tree-block-decomposition.html• L61-66

Spatial and layered diagrams

Spatial and layered examples explain how a subject is arranged in space or built from parts. An axonometric plan shows zones and movement through a physical layout. An exploded axonometric view separates related layers so their order and role can be read before they are assembled.

Type groupSupported examplesMain question
Axonometric planCoffee shop, warehouseHow are rooms, zones, and movement arranged?
Exploded axonometricAI agent stack, mechanical keyboardWhat parts or layers make up the subject?

The coffee shop example highlights the espresso bar as the focal room. The warehouse example highlights packing as the focal zone. The AI agent stack highlights skills as the focal layer. The mechanical keyboard highlights switches as the focal part. These examples show how a spatial or layered diagram can carry a main path and one clear point of attention.

References: skills/…/example-axonometric-plan-coffee-shop.html• L63-69 skills/…/example-axonometric-plan-coffee-shop-full.html• L37-45 skills/…/example-axonometric-plan-warehouse.html• L63-69 skills/…/example-axonometric-plan-warehouse-full.html• L37-45 skills/…/example-exploded-ai-stack.html• L63-69 skills/…/example-exploded-ai-stack-full.html• L37-45 skills/…/example-exploded-keyboard.html• L63-69 skills/…/example-exploded-keyboard-full.html• L37-45

Quantitative and planning diagrams

Quantitative examples show values, rank, distribution, movement, or comparison. Planning examples show time, work state, experience, or strategic position. The collection includes related forms as separate examples because the axes and reading order change the question each diagram can answer.

PurposeSupported examples
Comparison and positionBar, line, slopegraph, radar, polar, quadrant, Venn, pyramid
Distribution and flowScatter, bubble, beeswarm, ridgeline, Sankey, treemap
Movement and causeBump, waterfall, fishbone, Wardley map
Planning and workTimeline, Gantt, Kanban, story map, user journey
Matrix intensityHeatmap
Part-to-whole comparisonMarimekko
Layered change over timeStreamgraph

The examples are not a catalog of chart decoration. They demonstrate when a change in axis, ordering, containment, or flow carries the meaning of the artifact. The waterfall example makes a running total and its contributing changes visible as one bridge from a starting value to an ending total. The heatmap makes a value pattern readable across two dimensions and calls out one focal cell. The Marimekko example uses column width for each pipeline's share and segment height for the runner mix within that pipeline. The streamgraph uses layer thickness and the full envelope to show how weekly build minutes change over time.

References: skills/…/SKILL.md• L91-107 skills/…/SKILL.md• L114-123 skills/…/example-sankey.html• L1-18 skills/…/example-gantt.html• L1-18 skills/…/example-waterfall.html• L29-35 skills/…/example-waterfall-full.html• L34-41 skills/…/example-heatmap.html• L31-48 skills/…/example-heatmap-full.html• L41-56 skills/…/example-marimekko.html• L33-54 skills/…/example-marimekko-full.html• L39-60 skills/…/example-streamgraph.html• L31-49 skills/…/example-streamgraph-full.html• L41-58

Data and platform diagrams

Data and platform examples focus on the movement, storage, quality, and control of data across a system. They extend the structural set with views for platform integration, data tiers, and role-based access.

ConcernSupported examples
Platform pathHigh-level, data flow, DP integration
Data shape and qualityER, database schema, data lake, medallion
Control and accessDP security matrix, layers

These examples help an engineer separate a topology question from a data-model question. The diagram taxonomy and semantic patterns page provides the related selection rules.

References: skills/…/SKILL.md• L108-114 skills/…/example-dp-integration.html• L1-18 skills/…/example-dp-security-matrix.html• L1-18 skills/…/example-medallion.html• L1-18

Import and semantic examples

Import examples and semantic-pattern examples show cases where the main concern is not only the visual type. An imported artifact must retain the source relationships, while a semantic example must make behavior such as queue pressure or policy divergence clear.

Example kindDemonstrated concern
Mermaid, draw.io, and Excalidraw importsSource content becomes a clean standalone artifact without copying the source renderer's layout.
Traceable tree decompositionA root capability and child blocks remain linked through stable block identity and readable hierarchy.
Policy traceTwo rule paths can be compared until their first meaningful divergence.
Fan-in queueMultiple inputs converge on bounded capacity and produce backpressure.
Secure paved roadTrust boundaries and permitted paths remain legible as a system changes.

The diagram verification suite is the companion page for checking these artifacts after they are created.

References: skills/…/SKILL.md• L531-542 skills/…/example-import-drawio.html• L57-63 skills/…/example-import-excalidraw.html• L21-26 skills/…/example-tree-block-decomposition-full.html• L35-47 skills/…/example-policy-trace-animated.html• L190-204 skills/…/example-queue-animated.html• L190-205 skills/…/example-paved-road-animated.html• L190-205

Change checklist

When these files or sections are changed, remember to consider these:

  • A new gallery type needs a matching data-type entry and a matching base example before the selector can open it.
  • A standard type needs light, dark, and full files when it is presented as a normal variant family; a single-purpose entry must stay marked as single-purpose so unsupported variant links are not offered.
  • A renamed type must keep the selector value, file stem, and any related data-parent-type relationship aligned.
  • A standard tree decomposition family must keep its light, dark, and full artifacts aligned with the tree-block-decomposition selector value.
  • The waterfall family must keep its light, dark, and full artifacts aligned with the waterfall selector value and with the same bridge subject.
  • The state lifecycle family must keep its light, dark, and full artifacts aligned with the state-lifecycle selector value and with the same state subject and transitions.
  • The heatmap family must keep its light, dark, and full artifacts aligned with the heatmap selector value and with the same rows, columns, values, and focal cell.
  • The Marimekko family must keep its light, dark, and full artifacts aligned with the marimekko selector value and with the same pipeline totals, runner segments, and focal segment.
  • The streamgraph family must keep its light, dark, and full artifacts aligned with the streamgraph selector value and with the same time periods, layers, and focal trend.
  • The coffee shop and warehouse axonometric plan families must keep their light, dark, full, and optional animated artifacts aligned with the same rooms, zones, path, and focal area.
  • The AI agent stack and mechanical keyboard exploded families must keep their light, dark, full, and optional animated artifacts aligned with the same ordered layers and focal part.
  • A new or changed screenshot preview must keep its manifest source path, source hash, dimensions, and thumbnail hash aligned with the rendered files.
  • A motion example must retain a complete static frame and remain linked to the motion guidance and verification checks.
  • An imported example must keep its source kind and fidelity expectations clear instead of appearing to be a native type example.

Important failure modes

TriggerConsequenceGuard
A gallery tab points to a missing or differently named example fileThe preview fails to load or opens the wrong artifactKeep the selector's type value and the example-<type><variant>.html naming pattern in sync.
A single-purpose example is given normal variant controlsReaders can request files that do not exist or do not represent the special modeKeep data-single on imported, consultant, terminal, and animated entries.
A dark or full example changes the diagram's semantic contentReaders compare different claims instead of different presentationsTreat variants as alternate shells for one subject.
An axonometric plan variant changes a room, zone, movement path, or focal areaReaders compare different spatial claims across presentation modesPreserve the same plan subject and focal area in light, dark, full, and animated views.
An exploded view variant changes a layer, order, or focal partReaders compare different assemblies while the artifacts still look relatedPreserve the same layer set, order, and focal part across the family.
An animated spatial or layered view hides the complete static frameA print view, reduced-motion user, or no-script browser loses the explanationKeep the complete plan or exploded frame in the artifact and use motion only as an enhancement.
A state lifecycle variant drops a recovery or terminal transitionThe example no longer demonstrates the state model promised by the familyKeep the primary rail, recovery states, and terminal outcomes consistent across all three files.
A heatmap loses a row, column, value, or focal cell in one variantReaders cannot compare the same matrix across presentation modesPreserve the same two-dimensional data and focal story in light, dark, and full files.
A Marimekko variant changes a column width or segment height without changing the data meaningPipeline or runner shares become false while the chart still looks plausibleKeep widths, heights, and the stated part-to-whole reading consistent across variants.
A streamgraph variant changes a layer or time valueThe envelope tells a different trend from the other presentationsKeep periods, layer values, zero intervals, and the focal trend consistent across variants.
A screenshot manifest points to a stale source or hashA thumbnail can look valid while no longer representing the named source artifactUpdate the manifest entry from the rendered source and preserve its hash and dimensions.
Motion is the only usable view of an exampleA print view, reduced-motion user, or no-script browser loses the explanationKeep the complete static frame available in the artifact.

Key files

FileWhy to read it
skills/…/index.htmlProvides the gallery's type list, variant controls, special-entry markers, and preview selection behavior.
docs/…/manifest.jsonRecords the source-to-thumbnail links and render metadata for screenshot references.
skills/…/SKILL.mdDefines the supported visual types, the standard variant convention, semantic patterns, and output expectations.
skills/…/example-architecture.htmlShows the minimal light form for a standard structural example.
skills/…/example-architecture-full.htmlShows how a full editorial presentation adds context around the same diagram subject.
skills/…/example-architecture-dark.htmlShows the dark presentation of the same standard example family.
skills/…/example-line-dark.htmlShows how a quantitative line example preserves chart meaning on a dark surface.
skills/…/example-tree-block-decomposition.htmlShows the minimal light form for the traceable tree decomposition family.
skills/…/example-tree-block-decomposition-dark.htmlShows the dark presentation of the traceable tree decomposition family.
skills/…/example-tree-block-decomposition-full.htmlShows the full editorial presentation of the traceable tree decomposition family.
skills/…/example-waterfall.htmlShows the minimal light form for a bridge from a starting total through changes to an ending total.
skills/…/example-waterfall-dark.htmlShows the same waterfall subject in a dark presentation.
skills/…/example-waterfall-full.htmlShows the waterfall subject with editorial context and supporting explanation.
skills/…/example-state-lifecycle.htmlShows the minimal light form for the newsletter publication state lifecycle.
skills/…/example-state-lifecycle-dark.htmlShows the state lifecycle subject in a dark presentation.
skills/…/example-state-lifecycle-full.htmlShows the state lifecycle subject with editorial context and supporting explanation.
skills/…/example-heatmap.html, skills/…/example-heatmap-dark.html, skills/…/example-heatmap-full.htmlShow the same service-by-sprint intensity pattern in minimal light, minimal dark, and full editorial presentations.
skills/…/example-marimekko.html, skills/…/example-marimekko-dark.html, skills/…/example-marimekko-full.htmlShow the same pipeline-by-runner part-to-whole comparison across the three standard presentation modes.
skills/…/example-streamgraph.html, skills/…/example-streamgraph-dark.html, skills/…/example-streamgraph-full.htmlShow the same weekly build-minute layers and trend in the three standard presentation modes.
skills/…/example-axonometric-plan-coffee-shop.html, skills/…/example-axonometric-plan-coffee-shop-dark.html, skills/…/example-axonometric-plan-coffee-shop-full.htmlShow the same coffee shop plan in light, dark, and full editorial presentations.
skills/…/example-axonometric-plan-coffee-shop-animated.htmlShows the coffee shop plan as an optional staged reveal with a complete static fallback.
skills/…/example-axonometric-plan-warehouse.html, skills/…/example-axonometric-plan-warehouse-dark.html, skills/…/example-axonometric-plan-warehouse-full.htmlShow the same warehouse flow in light, dark, and full editorial presentations.
skills/…/example-axonometric-plan-warehouse-animated.htmlShows the warehouse flow as an optional staged reveal with a complete static fallback.
skills/…/example-exploded-ai-stack.html, skills/…/example-exploded-ai-stack-dark.html, skills/…/example-exploded-ai-stack-full.htmlShow the same AI agent layers in light, dark, and full editorial presentations.
skills/…/example-exploded-ai-stack-animated.htmlShows the AI agent layers as an optional assembly sequence with a complete static fallback.
skills/…/example-exploded-keyboard.html, skills/…/example-exploded-keyboard-dark.html, skills/…/example-exploded-keyboard-full.htmlShow the same keyboard layers in light, dark, and full editorial presentations.
skills/…/example-exploded-keyboard-animated.htmlShows the keyboard layers as an optional assembly sequence with a complete static fallback.
skills/…/example-queue-animated.htmlShows a semantic-pattern example with ordered motion and a complete static state.
skills/…/example-import-mermaid.htmlShows the standalone result for a Mermaid import example.
skills/…/example-import-drawio.htmlShows the standalone result for a draw.io import example.
skills/…/example-import-excalidraw.htmlShows the standalone result for an Excalidraw import example.
skills/…/example-quadrant-consultant.htmlShows a special presentation mode that is not part of the standard variant family.