Diagram Design

Editorial diagrams your designer won't hate.

New in 2.0 — the Loop: flywheels with a shared-memory hub. The dashed lines are the write-backs.

New in 2.3: semantic system patterns and optional accessible motion, while static output stays the default.

27 visual types. One agent skill for Claude Code, Codex, and Pi. Semantic patterns describe behavior separately from layout, so a queue, policy trace, or trust boundary can use the nearest existing type without expanding the type count. Static HTML remains the default; optional motion is available for ordered explanations. The skill also redraws draw.io or Mermaid sources at a chosen format, size, and detail level.

No Figma. No generic rounded boxes. No 30-minute color-picking sessions.

---

Why I built it

I write at littlemight.com (and run BestSelf.co on the side). Every time I needed a diagram — an architecture sketch, a flowchart, a pyramid of what matters most — I'd ask Claude and get back a generic rounded-box thing that looked nothing like the rest of the site. I'd either fight with Figma for 30 minutes or just skip the diagram.

So I built a Claude Code skill for it. Twenty-seven visual types, editorial quality, matches your brand in 60 seconds by reading your website.

The highest-quality move is usually deletion. Every node earns its place. The accent color is reserved for the 1–2 things the reader should look at first. Target density: 4/10.

---

What it makes

All 27 visual types ship in three static variants: minimal light, minimal dark, and full-editorial. Open any of them directly in a browser. There is no build step, JavaScript, or external image dependency.

Architecture Components + connections	Flowchart Decision logic	Sequence Messages over time
State machine States + transitions	ER / data model Entities + fields	Timeline Events on an axis
Swimlane Cross-functional flow	Quadrant Two-axis positioning	Nested Hierarchy by containment
Tree Parent → children	Org chart Ownership + routing	Venn Set overlap
Layer stack Stacked abstractions	Pyramid / funnel Ranked hierarchy or drop-off	Consultant 2×2 Scenario matrix · named cells
Radar / Spider Multi-axis comparison	Loop Flywheel · stations around a hub	IT current-state Legacy landscape · modernization
High-Level End-to-end stack on a cluster	Bar chart Categorical comparison	Line chart Trends over time
Gantt Tasks and phases on a timeline	Scatter plot Distribution and correlation	Process Multi-actor sequential workflow
Medallion Multi-tier data storage	Data flow Role-scoped pipeline steps	DP integration Sources → core → consumers
DP security matrix Per-role access permissions

Browse the live gallery: cathrynlavery.github.io/diagram-design — or open skills/diagram-design/assets/index.html locally to flip through all 27 diagrams with light / dark / full-editorial tabs.

---

Install

Pi:

pi install https://github.com/cathrynlavery/diagram-design

Run /reload in an open Pi session. Pi makes the skill available for matching diagram requests; use /skill:diagram-design to invoke it explicitly. Pi also loads the /export-diagram prompt template.

Claude Code:

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

Claude Cowork: Customize → Directory → Plugins → + → paste cathrynlavery/diagram-design → Sync, then install from the Personal list.

Codex:

npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design

Editable install

Managed installs are convenient, but changes to references/style-guide.md may be replaced by package updates. Clone the repo and install the local path if you plan to customize the style guide:

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design

# Pi: register the checkout as a local package
pi install ~/code/diagram-design

# Claude Code: symlink the inner skill
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

The shared skill lives at skills/diagram-design/. Pi discovers it through the repo's standard skills/ package directory; Claude Code, Codex, and other Agent Skills-compatible tools use the same files.

---

Onboarding — make it look like your brand

The whole point: ship editorial-quality diagrams in your colors and typography, not a generic template.

Out of the box, diagrams render in a clean jet-black + atomic-tangerine palette (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines). Good enough to screenshot straight away. But 60 seconds of onboarding is better — the skill will pull your brand from your website and apply it across every diagram.

The flow

You:     "onboard diagram-design to https://yoursite.com"
Agent:   → fetches the homepage
         → extracts the dominant palette + font stack
         → maps detected values to semantic roles:
             paper, ink, muted, accent, link
         → shows a proposed diff
         → writes your tokens to references/style-guide.md
You:     "yes, apply it"

Every new diagram now uses your colors. Your website's paper color becomes the diagram background. Your CTA color becomes the focal accent. Your body font stack becomes the node label family.

Brand matching also emits a fidelity receipt: sampled URLs, exact color roles, font families and weights, font source URLs, and any fallback. Public site fonts are used directly and verified after rendering rather than silently replaced with generic system fonts.

What gets extracted

Detected from your site	Becomes
<body> background	paper token
Primary text color	ink token
Secondary / caption text	muted token
Cards or containers	paper-2 token
Most-used brand color (CTA, link, heading)	accent token
<h1> font family	title font
<body> font family	node-name font
<code> / <pre> font	sublabel font

Contrast checks happen automatically

Before writing tokens, the skill verifies WCAG AA contrast on ink over paper. If your site has a color that fails contrast at diagram sizes (9–12px), it proposes an adjusted value and explains why.

Accessible by default

Every diagram template gives the inline SVG an accessible name and description: role="img", a resolving aria-labelledby, and first-child <title> / <desc> slots. IDs are prefixed per diagram and variant, so multiple SVG exports can be safely inlined on one page without duplicate accessible-name IDs. Decorative specimen icons are hidden from assistive technology instead.

Manual override

Prefer to set tokens by hand? Open skills/diagram-design/references/style-guide.md and edit the table. Everything downstream reads from there — all 27 diagrams, the annotation primitive, and the gallery all inherit semantic role names (accent, not #eb6c36).

First-run gate

The skill won't silently ship default-skinned diagrams into a branded project. On first use in a new project, it checks if style-guide.md has been customized. If not, it pauses and asks:

"This is your first diagram in this project. The style guide is still at the default. Want to run onboarding, paste tokens manually, or proceed with default?"

See skills/diagram-design/references/onboarding.md for the full spec.

---

Quickstart

# From a cloned checkout, open the gallery to see all 27 diagrams
open skills/diagram-design/assets/index.html       # macOS
xdg-open skills/diagram-design/assets/index.html  # Linux

# In Claude Code, Codex, or Pi, ask:
# "Make me an architecture diagram of my app: frontend, backend, database, Redis cache."
# "I need a quadrant showing Q2 projects by impact vs effort."
# "Give me a sequence of a bearer call with token refresh on 401."
# (branching refresh uses the ALT combined-fragment grammar in type-sequence.md;
#  see skills/diagram-design/assets/example-sequence-oauth.html — not a full authorize-code handshake)

Your agent will pick the right type, build the HTML, and save it. You can also start from a template directly:

cp skills/diagram-design/assets/template.html my-diagram.html        # minimal light
cp skills/diagram-design/assets/template-full.html my-diagram.html   # editorial with summary cards
cp skills/diagram-design/assets/template-motion.html my-diagram.html # optional accessible motion

Semantic patterns and optional motion

When behavior matters, the skill chooses a semantic pattern first and a visual type second. The seven routed patterns cover fan-in queues and bottlenecks, repeated stage slots, unstructured-input transformation, paired policy traces, secure paved roads, governance catalogs, and compensating security layers. Each pattern defines its triggers, primitives, budget, anti-patterns, static fallback, and nearest visual type in semantic-patterns.md.

Motion is optional and does not create another visual type. animation.md defines none, reveal, step, and loop modes with a complete static first frame, deterministic timing, and controls when interaction is available. Reduced-motion output shows the complete static frame and hides/disables playback controls. Motion HTML uses the exact reviewed controller from template-motion.html; arbitrary or modified inline scripts, remote assets, CSS imports, and executable HTML attributes are rejected. The default is none: ordinary output remains static and script-free. example-policy-trace-animated.html is the self-contained interactive example.

---

Import from draw.io or Mermaid

Already have diagrams in draw.io / diagrams.net or Mermaid? Point the skill at the source and it redraws them — same content, this design system, at whatever the destination needs.

*A 12-node draw.io file redrawn at balanced detail for a blog post. The source's six pastel fills became one accent; its hand-dragged coordinates becam