cathrynlavery/diagram-design
ProductivityAn Agent Skill that turns plain-language requests into self-contained HTML/SVG diagrams in your brand.
What it is
Diagram Design is an Agent Skill that lets coding agents produce publication-ready diagrams as a single self-contained HTML file with inline SVG. It supports 51 diagram types, including architecture, flowcharts, sequence diagrams, ER models, timelines, quadrants, Gantt charts, and swimlanes. Each type has light, dark, and full-editorial variants, and the output opens in a browser without a build step, JavaScript, or external images.
The visual system is deliberately constrained: one accent color, hairline borders, no shadows, a maximum 10px border radius, and coordinates on a 4px grid. Rather than replacing a canvas editor, it is aimed at people who can describe a diagram in words and want a consistent editorial look without spending time in Figma. The project states that it fits published diagrams better than diagrams that change every sprint in Git, where Mermaid remains the better choice.
Install and first diagram
Install through the cross-agent skills CLI, which detects skills/diagram-design/SKILL.md and copies the skill into the host roots you select:
npx skills add cathrynlavery/diagram-design
Claude Code has a plugin marketplace path with slash commands and updates:
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
Codex, Copilot, Factory Droid, Pi, Qoder, Kiro, and OpenCode each have their own install route; the README covers them separately. To inspect the supplied examples from a cloned checkout:
# macOS
open skills/diagram-design/assets/index.html
# Linux
xdg-open skills/diagram-design/assets/index.html
Then ask the agent for a diagram in natural language, such as an architecture diagram with a frontend, backend, database, and cache. The agent selects the diagram type, states its plan, and writes an .html file you can open by double-clicking. A standalone npx skills add install does not follow marketplace updates; refresh it with npx skills update diagram-design.
Brand onboarding and profiles
To match an existing site, ask the agent to onboard the skill to a URL. It fetches the homepage, extracts the dominant palette and font stack, maps them to semantic roles (paper, ink, muted, accent, link), shows a proposed diff, and writes the tokens into the style guide after confirmation. WCAG AA contrast is checked on ink over paper before tokens are written. Saved named profiles in ~/.diagram-design/profiles/ let parallel projects use different brands without overwriting a shared style guide.
Import, export, and output constraints
The skill can redraw existing .drawio, Mermaid, Excalidraw, and PlantUML sources rather than just converting them. A four-dial model controls format (html, svg, png, html+png), size, detail level, and audience wording, and every import ends with a fidelity ledger listing what was merged, collapsed, or dropped. SVG export works for Figma and slides; PNG export rasterizes through Playwright at 2× by default, so it requires pip install playwright && playwright install chromium. Both export formats contain the diagram only, not the editorial cards and headers from the full variants.
By default a diagram loads Instrument Serif, Geist, and Geist Mono from Google Fonts, which is the only network request. Setting the font source to system removes all network requests. Optional motion is off by default; when enabled, it includes a complete static first frame, and reduced-motion output hides playback controls. The repository is MIT-licensed and the agent reads only the type reference it needs for a given request.
HotRepo's take
Diagram Design entered the all-language daily GitHub ranking at position 8 on 2026-11-19 and accumulated 68,341 stars by that snapshot. Daily gains from 2026-09-08 through 2026-10-14 mostly ranged from roughly 800 to 2,300 stars, with over 1,000 added on several days, showing that its appeal was not a single-day spike. The repository positions itself explicitly against Mermaid for Git-hosted diagrams that change frequently, while arguing that an Agent Skill can produce a more consistent published result. Its skill is static rather than a runtime: output quality depends on the model and can vary between runs, so the value lies in the encoded design rules and template/reference set more than in deterministic generation.
Written by AI from the project's README, updated . The project's own docs are the source of truth.
Hacker News
You might also like
- tt-a1i/archifyTurns an idea, plan, or codebase into a shareable interactive HTML diagram through your coding agent.
- zarazhangrui/frontend-slidesAn agent skill that turns a brief or PowerPoint into a self-contained HTML slide deck.
- wevm/ondinePrecompiles Mermaid diagrams to SVG at build time so sites ship a tiny runtime instead of a full parser.
- jgraph/drawio-desktopA desktop wrapper of the draw.io diagram editor for Windows, macOS and Linux that works offline.
- mermaid-js/mermaidGenerates flowcharts, sequence diagrams, Gantt charts and other diagrams from Markdown-like text, aimed at developers and technical writers.