An editorial diagram design system for AI coding agents

Diagram Design is a skill/plugin that gives AI coding agents—Claude Code, Codex, Factory Droid, and Pi—the ability to produce editorial-quality diagrams. It ships 38 visual types, each rendered as self-contained HTML + SVG files with no build step, no JavaScript runtime, and no external image dependencies. The output is meant to look like a polished publication, not a generic flowchart tool.

The author kept needing diagrams for her blog and products, but AI assistants returned generic rounded-box diagrams that clashed with her site's design. Fixing them in Figma took 30 minutes; skipping them lost the communication value. This project encodes an editorial standard—one accent color, 1–2 focal elements, 1px hairlines, no shadows, 4px grid—so agents can produce diagrams that match a brand and are actually pleasant to publish.

The skill covers 38 diagram types, from architecture, flowchart, sequence, and state machine to Sankey, fishbone, Wardley map, kanban, user journey, deployment, dependency graph, UML class, story map, and database schema. Each type ships in three static variants: minimal light, minimal dark, and full-editorial. A key design decision is that behavior is described by semantic patterns independently of layout—queue, policy trace, trust boundary, and other recurring situations reuse the nearest visual type instead of multiplying the type count. Static HTML is the default; optional accessible motion (reveal, step, loop) is available for ordered explanations.

After installation, you can run onboarding with a URL: the agent fetches the homepage, extracts the dominant palette and font stack, maps them to semantic tokens (paper, ink, muted, accent, link), and writes the result into references/style-guide.md after showing a diff. It also checks WCAG AA contrast for text on background and proposes adjusted values when needed. The SVG output is accessible by default: role="img", aria-labelledby, title/desc slots, and prefixed IDs to avoid collisions. Saved brand profiles can be reused across projects via ~/.diagram-design/profiles/ and a .diagram-design marker.

The repo is structured as a skill package with a small SKILL.md that loads references only when needed. At startup an agent sees just the skill name and description; a flowchart request loads only SKILL.md plus type-flowchart.md, while importing a draw.io file pulls in import-drawio.md, output-spec.md, and the chosen type reference. Plugin manifests for Claude Code, Codex, Factory Droid, and prompt templates for Pi live in their own directories; Python scripts in scripts/ verify geometry, treemap area accuracy, Mermaid/draw.io imports, and documentation sync in CI.

Install via each client's plugin mechanism. Claude Code:

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

Codex:

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add 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

Pi:

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

Once installed, open the gallery at skills/diagram-design/assets/index.html or just ask in natural language: "Make me an architecture diagram of my app: frontend, backend, database, Redis cache." You can also start from a template: cp skills/diagram-design/assets/template.html my-diagram.html.

If you already have diagrams in draw.io/diagrams.net or Mermaid, the skill can redraw them in this design system. It parses .drawio, .drawio.xml, .drawio.png/.svg and Mermaid .mmd/.mermaid or fenced blocks in Markdown. Four dials control the output: format (html/svg/png/html+png), size (doc-inline, slide-16x9, social-og, etc.), detail (faithful/balanced/simplified), and audience (engineer/mixed/executive). Every import ends with a fidelity ledger summarizing what was merged, collapsed, or dropped. Exporting the generated HTML to SVG or PNG is supported via /export-diagram.

Use this skill when you need a polished, brandable diagram for a blog post, deck, documentation, or social card, and you're already working in an agent like Claude Code or Codex. It is not for quick unicode diagrams for tweets or terminal output, lists (use a table), before/after comparisons (use a table), or single-box "diagrams" that are better written as a sentence. The rule of thumb: if a reader would learn more from a well-written paragraph, don't draw. Output files carry a Google Fonts reference, so fully offline use is limited to the system fonts fallback. Static output is guaranteed; motion is an opt-in extra with a strict review.