Diagram Design

Summary

Diagram Design is an open-source agent-skills library that generates editorial diagrams for coding agents, outputting self-contained HTML and SVG. It requires no external dependencies to run and is intended for application developers. The README calls it an alternative to Mermaid, and its documentation positions it alongside other diagramming tools. The project has had multiple releases since its inception.

38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop.

Command line

Values are placeholders taken from each option’s declared default. Nothing is executed here — the output shown is a recording of a run that already happened.

Release history

1. changes since 2026-08-11 Aug 30, 2026 · issue 011

   Diagram Design gains Draw.io import, ten new diagram types, named client profiles, Pi support, and automatic plugin updates.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch commits-2026-08-11 https://github.com/cathrynlavery/diagram-design.git
   # already have the repo? check out this version:
   $ git checkout commits-2026-08-11

   └──▷ TRY IT
   Verify that a Draw.io import was extracted and redrawn correctly before merging a diagram update.
   copy

   $ python3 scripts/verify-drawio-import.py

   Run adversarial Sankey geometric contract tests to confirm the checker fires on ribbon narrowing, node volume loss, and label/bar mismatches.
   copy

   $ python3 scripts/test-verify-sankey.py

   • ›Adds the /diagram-design:import workflow to redraw Draw.io files (raw, compressed, PNG-embedded, and SVG-embedded) at a chosen format, size, and detail level into the project design system.
   • ›Adds verify-drawio-import.py to verify Draw.io import correctness; invoke with python3 scripts/verify-drawio-import.py.
   • ›Adds verify-beeswarm.py to enforce nine geometric invariants on beeswarm diagrams (shared value scale, no overprint, and seven additional contracts).
   • ›Adds lint-render.py to lint diagram examples as rendered in headless Chromium, catching clipped SVG viewports, collapsed SVGs, page overflow, and runtime errors that source-level linting cannot detect.
   • ›Adds test-verify-sankey.py with adversarial fixtures covering both polarities of the Sankey geometric contract (ribbons, node volume, stage monotonicity, label/bar agreement, and dark/light variant parity).
   +7 moreshow less

   • ›Adds named client profiles (PR #61).
   • ›Adds automatic plugin updates via native marketplaces with a version gate.
   • ›Ships ten editorial diagram types in one release, including a treemap (part-of-whole by area), a dumbbell Bar variant, and a slopegraph line variant for change between two states.
   • ›Adds native Pi package support for compatibility with the Pi platform.
   • ›Adds native Droid plugin packaging via the factory.
   • ›Adds a pre-draw checkpoint, docs-sync gate, packaged self-check, and ADRs to the skill module.
   • ›Adds a GitHub Actions CI workflow (.github/workflows/ci.yml) with a multi-OS matrix (Linux, Windows, macOS), automated visual artifact packaging and upload on linter failures, and a GitHub Step Summary table for matrix run results.
2. changes since 2026-08-11 Aug 27, 2026 · issue 009

   Diagram Design gains draw.io import with format/size/fidelity control, native Pi support, new chart types, and client profiles.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch commits-2026-08-11 https://github.com/cathrynlavery/diagram-design.git
   # already have the repo? check out this version:
   $ git checkout commits-2026-08-11

   └──▷ TRY IT
   Redraw an existing draw.io architecture diagram into the project design system at high fidelity without copying draw.io geometry or styling.
   copy

   $ /diagram-design:import path/to/architecture.drawio

   • ›Adds the /diagram-design:import workflow to redraw draw.io files at a chosen output format, size, and detail level, with support for raw, compressed, PNG-embedded, and SVG-embedded .drawio files.
   • ›Adds a verify-ridgeline.py script that enforces eight geometric invariants on ridgeline charts (amplitude, pitch, shared bins, closure, and more).
   • ›Adds lint-render.py, a headless-Chromium linter that catches rendered diagram breakage invisible to source inspection — clipped SVG content, collapsed SVGs, page overflow, and runtime errors.
   • ›Adds test-verify-sankey.py, an adversarial test suite for verify-sankey.py covering both true-positive and true-negative polarities.
   • ›Adds animated HTML examples for Semantic Pattern #1 (Fan-in Queue / Bottleneck) as example-queue-animated.html and Semantic Pattern #5 (Secure Paved Road) as example-paved-road-animated.html.
   +1 moreshow less

   • ›Adds a multi-OS CI testing matrix covering Linux, Windows, and macOS, with GitHub Step Summary table generation and visual artifact packaging on linter failures.
3. changes since 2026-08-11 Aug 25, 2026 · issue 007

   Diagram Design adds draw.io import, native Pi support, named client profiles, new chart types, and automatic plugin updates.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch commits-2026-08-11 https://github.com/cathrynlavery/diagram-design.git
   # already have the repo? check out this version:
   $ git checkout commits-2026-08-11

   • ›Adds the /diagram-design:import workflow to redraw draw.io files (raw, compressed, PNG-embedded, and SVG-embedded) at a chosen format, size, and detail level into the project design system.
   • ›Adds native Pi package support for compatibility with the Pi platform.
   • ›Adds named client profiles (PR #61).
   • ›Adds automatic plugin updates via native marketplaces with a version gate.
   • ›Adds treemap diagram type for part-of-whole visualization by area.
   +11 moreshow less

   • ›Adds dumbbell as a variant of the Bar diagram type.
   • ›Adds slopegraph as a variant of the Line diagram type for showing change between two states.
   • ›Ships ten additional editorial diagram types in a single release (commit 4691a2f).
   • ›Adds verify-ridgeline.py script to verify that a ridgeline chart's drawn ridges match their declared bin values, enforcing eight geometric invariants including single amplitude, even pitch, shared bins, and zero closure.
   • ›Adds lint-render.py script to lint diagram examples as rendered in headless Chromium, catching clipped SVG content, collapsed SVGs, page overflow, and runtime errors that source-level linting cannot detect.
   • ›Adds adversarial test suite scripts/test-verify-sankey.py for the Sankey verifier, covering both polarities (fires when it should, stays quiet when it shouldn't).
   • ›Adds a pre-draw checkpoint, docs-sync gate, packaged self-check, and ADRs for the skill workflow.
   • ›Adds animated example example-queue-animated.html for Semantic Pattern #1 (Fan-in Queue / Bottleneck).
   • ›Adds animated example example-paved-road-animated.html for Semantic Pattern #5 (Secure Paved Road).
   • ›Deploys a live diagram gallery to GitHub Pages.
   • ›Adds a multi-OS CI testing matrix covering Linux, Windows, and macOS with automated visual artifact packaging and upload on linter failures, plus a GitHub Step Summary table for matrix run results.
4. changes since 2026-08-11 Aug 21, 2026 · issue 004

   Adds draw.io import with format/size/fidelity control, native Pi support, new chart types, named client profiles, and automatic plugin updates.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch commits-2026-08-11 https://github.com/cathrynlavery/diagram-design.git
   # already have the repo? check out this version:
   $ git checkout commits-2026-08-11

   └──▷ TRY IT
   Redraw an existing draw.io file into the project design system at a chosen fidelity level — useful for migrating legacy architecture diagrams without copying draw.io geometry or styling.
   copy

   $ /diagram-design:import

   Verify sankey flow conservation, column totals, ribbon width constancy, and label accuracy before merging a budget or pipeline diagram.
   copy

   $ python3 scripts/verify-sankey.py

   Validate that all ridgeline chart ridges share a single amplitude and common bin positions so silhouettes remain comparable across rows.
   copy

   $ python3 scripts/verify-ridgeline.py

   • ›Adds /diagram-design:import workflow to redraw draw.io files (raw, compressed, PNG-embedded, and SVG-embedded) at a chosen format, size, and detail level in the project design system.
   • ›Adds native Pi package support for compatibility with the Pi platform.
   • ›Adds verify-sankey.py script enforcing five sankey invariants: flow conservation per node, equal column totals, constant ribbon width, printed-label accuracy, and light/dark variant consistency.
   • ›Adds verify-ridgeline.py script enforcing eight ridgeline invariants including shared amplitude, even pitch, shared bins, and zero-closed outlines.
   • ›Adds treemap diagram type for part-of-whole visualization by area.
   +9 moreshow less

   • ›Ships ten additional editorial diagram types in a single release.
   • ›Adds dumbbell as a variant of the Bar diagram type.
   • ›Adds slopegraph as a variant of the Line diagram type for visualizing change between two states.
   • ›Adds animated example example-queue-animated.html for Semantic Pattern #1 (Fan-in Queue / Bottleneck).
   • ›Adds animated example example-paved-road-animated.html for Semantic Pattern #5 (Secure Paved Road).
   • ›Adds named client profiles support.
   • ›Adds automatic plugin updates via native marketplaces with a version gate.
   • ›Adds pre-draw checkpoint, docs-sync gate, packaged self-check, and ADRs to the skill package.
   • ›Deploys a live gallery to GitHub Pages.