<a href="https://trendshift.io/repositories/26141?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-26141"
target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/26141" alt="cathrynlavery%2Fdiagram-design |
Trendshift" width="250" height="55"/>
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.
New in 2.5.10: ten more layout grammars — Sankey, fishbone, Wardley map, kanban, user journey, deployment, dependency graph, UML class, story map, and database schema.
Editorial diagram types for Claude Code, Codex, Factory Droid, Pi, and Agent Skills-compatible hosts. Self-contained HTML + SVG. No shadows. No
Mermaid slop. 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, Mermaid, or Excalidraw sources at a chosen format, size, and detail level.
No Figma. No generic rounded boxes. No 30-minute color-picking sessions.
Project site: diagramdesign.dev
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. Editorial-quality visual types, matched to 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
Every visual type ships 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 |  IT current-state Legacy landscape + modernization |  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 |
 Radar / spider Multi-axis comparison | Loop / flywheel Reinforcing cycle + shared hub |  Nested Hierarchy by containment |
 Tree Parent → children |  Org chart Ownership + routing |  Layer stack Stacked abstractions |
 Venn Set overlap |  Pyramid / funnel Ranked hierarchy or drop-off |  Bar chart Categorical comparison |
 Treemap Part-of-whole by area |  Line chart Trends over time |  Gantt Tasks + phases on a timeline |
 Scatter plot Distribution + correlation |  High-Level End-to-end stack on a cluster |  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 |  Sankey Quantities that split + merge |  Fishbone Grouped causes → one effect |
 Wardley map Value chain × evolution |  Kanban Work in progress by state |  User journey Stages, actions + sentiment |
 Deployment Zones, hosts + artifacts |  Dependency graph Fan-in, ranks + cycles |  UML class Classes, operations + typed relations |
 Story map Backbone × release slices |  Database schema Physical tables + column FKs |  Polar chart Cyclic magnitude · linear radius |
 Waterfall Running total + signed bridges |  Architecture delta Before · Changes · After topology |  Exploded axonometric Parts pulled apart on one axis |
 Axonometric plan Rooms and buildings on one plate |  Heatmap Value per row × column cell |
Architecture delta compares synchronized topologies through a Before · Changes · After ledger of added, removed, changed, moved, and rewired objects.
See its reference and [order-fulfilment
example](skills/diagram-design/assets/example-architecture-delta.html). Attribute-only comparisons remain tables; a single snapshot uses Architecture.
Exploded axonometric draws one object in 2:1 dimetric projection with its parts lifted apart at equal gaps: a [phone
teardown](skills/diagram-design/assets/example-exploded-phone.html), an unboxing, an
app stack, an AI agent stack, or
a mechanical keyboard. Every coordinate comes from one projection function, and the
animated phone opens assembled and explodes once. See its
Axonometric plan uses the same projection for one floor or one site: walls cut at desk height so every room reads from a single view, or buildings on
a campus tagged by build phase. See the office floor, the
campus, the [coffee
shop](skills/diagram-design/assets/example-axonometric-plan-coffee-shop.html), the [fulfillment
floor](skills/diagram-design/assets/example-axonometric-plan-warehouse.html), the [phased campus
animation](skills/diagram-design/assets/example-axonometric-plan-campus-animated.html), and the
The v2.5.10 release added ten layout grammars. Compare their light, dark, and full-editorial variants in the 30-variant contact sheet.
Browse the live gallery: cathrynlavery.github.io/diagram-design — or open
skills/diagram-design/assets/index.html locally to flip through every diagram with light / dark /
full-editorial tabs.
Install
Official builds come only from this repository. LittleMight, Cathryn Lavery's company, publishes the plugin directory listings; a listing under any
other name is an unofficial copy. PRIVACY.md lists what the skill sends over the network.
Claude Code:
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
Then enable updates once: run /plugin, open Marketplaces, select diagram-design, and choose Enable auto-update. Claude Code disables
auto-update by default for third-party marketplaces; after this toggle, it refreshes the marketplace and installed plugin in the background after
startup. Run /reload-plugins when prompted, or let the next session load the update.
Codex:
codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design
Codex refreshes configured Git marketplaces at startup. To fetch immediately, run codex plugin marketplace upgrade diagram-design and start a new session.
GitHub Copilot:
copilot plugin marketplace add cathrynlavery/diagram-design
copilot plugin install diagram-design@diagram-design
Copilot installs the shared Diagram Design skill plus its doctor, export, import, and profile capabilities from the existing repository marketplace.
Confirm discovery with copilot skill list (or /skills in an interactive session), then ask for a diagram in natural language. To fetch a merged
update, run copilot plugin marketplace update diagram-design, then copilot plugin update diagram-design@diagram-design.
Factory Droid:
droid plugin marketplace add https://github.com/cathrynlavery/diagram-design
droid plugin install diagram-design@diagram-design --scope user
Droid tracks Git plugins by commit rather than the manifest's display version. To fetch a merged update, run `droid plugin marketplace update
diagram-design, thendroid plugin update diagram-design@diagram-design --scope user`, and start a new session.
Claude Cowork (organization marketplace): Organization GitHub marketplaces currently require a private or internal repository, so first mirror
this public repository into one owned by your organization. In Organization settings → Plugins, choose Add plugin → GitHub, connect that
mirror, and enable Sync automatically from the marketplace menu. Automatic sync runs when a pull request containing a plugin version bump is
merged to the mirror's default branch; direct pushes do not trigger the webhook. Install Diagram Design from the resulting organization marketplace.
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, /import-mermaid, /import-excalidraw, /profile, and /doctor prompt templates. The unpinned Git install is
intentional: Pi has no automatic package refresh, so run pi update --extensions to pull merged updates.
Kiro: Import the Agent Skill from the repository subdirectory URL:
https://github.com/cathrynlavery/diagram-design/tree/main/skills/diagram-design
Kiro copies imported skills into .kiro/skills/ for a workspace or ~/.kiro/skills/ globally, so re-import the URL to pick up updates. Custom agents
that declare resources should include skill://diagram-design/**/SKILL.md.
OpenCode: Copy or symlink skills/diagram-design/ to .opencode/skills/diagram-design in a project or ~/.config/opencode/skills/diagram-design
globally. OpenCode has no Diagram Design marketplace package; copied installs update only when you replace the directory from a newer checkout.
Any other Agent Skills host (Cursor, Cline, Amp, Gemini CLI, Windsurf, Zed, Warp, Roo, Kilo, and the rest) - the cross-agent [skills
CLI](https://skills.sh) resolves this repository, detects skills/diagram-design/SKILL.md, and installs the whole skill (references/, assets/,
scripts/) into every host root you select:
npx skills add cathrynlavery/diagram-design
When the selected roots resolve to more than one skills directory, the CLI asks for an installation method and recommends Symlink: one canonical
copy, linked into each root, so a later update reaches all of them at once. Pass --copy for independent copies per host instead. A selection that
resolves to a single directory is copied, because the distinction is immaterial there. Where symlinks are unavailable (Windows without Developer Mode)
the CLI falls back to copies and reports which roots it copied.
This is a standalone install, separate from every marketplace above: it does not follow marketplace updates automatically. Pull merged updates with
npx skills update diagram-design. It also installs the Agent Skill only, so the /export-diagram, /import-mermaid, /profile, and /doctor
command surfaces stay with the native packages. On a host that has one of the marketplaces above, prefer the marketplace.
One-time migration: an existing standalone
npx skills addcopy will not start following the Codex marketplace automatically. Remove that
standalone copy, then use the Codex marketplace commands above. Likewise, uninstall a personal Cowork copy and reinstall Diagram Design from your
organization's marketplace. Future marketplace version bumps then flow through each client's native update path.
Editable install
Managed installs are convenient, but changes to references/style-guide.md may be replaced by package updates. Saved profiles in
~/.diagram-design/profiles/ survive updates, and projects with a .diagram-design marker are unaffected. Clone the repo and install the local path
if you plan to customize the working style guide directly:
```bash git clone [email protected]: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
Other Agent Skills hosts: create only the roots you use mkdir -p ~/.agents/skills ~/.cursor/skills ~/.cline/skills ~/.kiro/skills
~/.config/opencode/skills ~/.copilot/skills ln -s ~/code/diagram-design/skills/diagram-design ~/.agents/skills/diagram-design ln -s
~/code/diagram-design/skills/diagram-design ~/.cursor/skills/diagram-design ln -s ~/code/diagram-design/skills/diagram-design
~/.cline/skills/diagram-design ln -s ~/code/diagram-design/skills/diagram-design ~/.kiro/skills/diagram-design ln -s
~/code/diagram-design/skills/diagram-design ~/.config/opencode/skills/diagram-design ln -s ~/code/diagram-design/skills/diagram-design
~/.copilot/skills/diagram-design ```
The shared skill lives at skills/diagram-design/. Pi discovers it through the repo's standard skills/ package directory; Claude Code, GitHub
Copilot, Codex, Factory Droid, 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 — every diagram, 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.
Working with multiple clients
Onboard a brand once, save the result as a named profile, then add a .diagram-design marker containing profile: <slug> to each client project.
Marker projects read ~/.diagram-design/profiles/<slug>.md directly, so parallel workspaces can use different brands without overwriting a shared
installed style-guide.md.
The profile library is shared across Claude Code, Codex, Factory Droid, and Pi. Use /diagram-design:profile in Claude Code, /profile in Factory
Droid or Pi, or ask in natural language in any host. See profiles.md for the storage, marker, and
recovery contract.
Quickstart
```bash
From a cloned checkout, open the gallery to see every diagram
open skills/diagram-design/assets/index.html # macOS xdg-open skills/diagram-design/assets/index.html # Linux
In Claude Code, Codex, Factory Droid, 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) ```
Operator recipes for editable installs, first diagrams, brand setup, import, export, validation, Windows junctions, and reusable prompts live in docs/cookbook.md.
Your agent will pick the right type, build the HTML, and save it. You can also start from a template directly:
```bash 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 nine routed patterns cover fan-in queues and
bottlenecks, repeated stage slots, unstructured-input transformation, paired policy traces, secure paved roads, governance catalogs, compensating
security layers, traceable block decomposition, and lifecycle phase maps. 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, Mermaid, or Excalidraw
Already have diagrams in draw.io / diagrams.net, Mermaid, or Excalidraw? 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 became a 4px grid.
``` /diagram-design:import-drawio platform.drawio /diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified
--audience=executive /diagram-design:import-drawio platform.drawio --detail=faithful --format=png --page=all /diagram-design:import-mermaid README.md
--diagram=all /diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified /diagram-design:import-excalidraw
whiteboard.excalidraw --size=slide-16x9 --detail=simplified ```
Or just ask: "redraw this drawio file for my deck", "make this Mermaid block editorial", "make this whiteboard sketch presentable", or "この Mermaid をスライド用にきれいにして".
Reads the common containers draw.io writes — .drawio, .drawio.xml, .drawio.png (embedded diagram), and .drawio.svg — including compressed
payloads that look like base64 garbage in an editor. For Mermaid, it accepts .mmd, .mermaid, and one or more fenced mermaid blocks in Markdown.
For Excalidraw, it accepts .excalidraw and .excalidraw.json scene files (not .excalidraw.png/.excalidraw.svg exports). It parses text only: no
rendering, JavaScript, browser, network, or followed click targets.
The four dials
The point isn't conversion, it's fitting the output to where it's going. Same source file, three different diagrams:
| Dial | Options | What it changes |
|---|---|---|
| **F |