Diagram Design: Editorial Diagrams for Claude Code
/diagram-design
Diagram Design is a Claude Code skill that generates 27 types of self-contained HTML/SVG diagrams styled to look hand-designed, not AI-generated. Its design system enforces real constraints — one accent color, 4px spacing, no shadows — instead of letting Claude freelance a layout. Reach for it if you ask Claude for architecture or flow diagrams and hate the generic rounded-box look; skip it if a quick unicode sketch says it faster.
What Diagram Design Offers
Diagram Design is a Claude Code skill — installable as a plugin or a symlinked repo — that produces 27 editorial-style diagram types as self-contained HTML files with inline SVG, no build step and no external images. Each diagram ships in three variants (minimal light, minimal dark, full-editorial), and the skill can read a target website to pull its color palette and fonts into every diagram it generates afterward.
The Problem with Generic Diagrams
Diagram Design's creator, Cathryn Lavery, built it after hitting the same wall repeatedly while writing at littlemight.com and running BestSelf.co: asking Claude for a diagram — an architecture sketch, a flowchart, a priority pyramid — produced a generic rounded-box graphic that clashed with the rest of the site, leaving her to either fight Figma for 30 minutes or skip the diagram entirely. The skill exists to close that gap by giving Claude a fixed design system (one accent color, a 4px grid, no shadows) instead of letting it improvise a look each time.
Key Capabilities
- ✓27 diagram types across three variants (minimal light, minimal dark, full-editorial), each a self-contained HTML file with inline SVG which is browser-openable, requiring no build step or JavaScript, no external images.
- ✓A branding onboarding step that fetches a target website and proposes a token diff for palette and fonts before writing anything, so brand colors don't get applied silently.
- ✓Built-in WCAG AA contrast checking on the ink-over-paper color pair before tokens are written, with an adjusted value proposed if a site's color fails at diagram text sizes.
- ✓A first-run gate: on a new project, if the style guide is still at its defaults, the skill pauses and asks whether to run onboarding, paste tokens manually, or proceed with defaults.
- ✓Export to standalone SVG (with injected Google Fonts) or PNG (rasterized via Playwright at 2x) through a /diagram-design:export slash command.
- ✓A progressive-disclosure architecture: SKILL.md is a lean index, and only the reference file for the requested diagram type loads, out of 34 reference files total covering types, primitives, and utilities.
- ✓Three optional primitives — italic-serif annotation callouts, a hand-drawn SVG sketchy filter, and a terminal/CLI-window skin — plus a 55-icon monochrome set (Tabler Icons and Simple Icons) for architecture and sequence diagrams.
- ✓A skin-lint script (scripts/lint-skin.py) that contributors run against new examples, with a repo-wide --all --baseline check that has to stay green.
Diagram Types and Applications
- •Generating an architecture, flowchart, sequence, or state-machine diagram — the kind of technical diagram that usually ends up in docs or a README — straight from a Claude Code conversation, without opening Figma.
- •Producing chart-style diagrams — bar, line, Gantt, scatter plot, radar/spider — for anything from a roadmap review to a data-pipeline design doc.
- •Building a quadrant or consultant 2x2 to score options, like ranking a backlog by impact vs. effort, with named cells instead of a generic four-box grid.
- •Making onboarding or system diagrams that follow a company's existing brand guidelines instead of a generic AI look, for teams publishing into brand-sensitive docs or blog posts.
- •Exporting a diagram as SVG or PNG to drop into Figma, a slide deck, or a social card, via the /diagram-design:export command.
Getting Started with Diagram Design
Clone the repo and symlink the inner skill into Claude Code's skills directory: `git clone [email protected]:cathrynlavery/diagram-design.git ~/code/diagram-design` then `ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design`, and restart Claude Code — the skill registers as `diagram-design` and activates whenever you ask for a diagram. The real skill lives at `skills/diagram-design/` inside the repo, which is why the same tree also works as a Codex skill or a Claude Cowork plugin. Prefer a faster path? Install it as a plugin instead: `/plugin marketplace add cathrynlavery/diagram-design` then `/plugin install diagram-design@diagram-design` in Claude Code, or `npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design` for Codex — the README notes the trade-off is that edits to references/style-guide.md don't survive plugin updates, so the clone-and-symlink route is better if you plan to hand-edit the style guide.
Branding and Customization
Ask Claude to `onboard diagram-design to https://yoursite.com` and the skill fetches the homepage, extracts the dominant palette and font stack, and maps them to five semantic tokens — paper, ink, muted, accent, and link — then shows a proposed diff before writing anything. Say 'yes, apply it' and every diagram generated afterward inherits your site's background as the paper color, your CTA color as the accent, and your body font as the node-label family; a table in the README maps specific source elements (body background, primary text, secondary text, card containers, dominant brand color, heading/body/code fonts) to each token. Prefer to skip the fetch step? Edit `skills/diagram-design/references/style-guide.md` by hand — every diagram, the annotation primitive, and the gallery all read from that one file. Before any onboarding, diagrams render in a default jet-black and atomic-tangerine palette the README calls 'good enough to screenshot straight away.'
Strengths
- ✓Diagrams are self-contained HTML with inline SVG — no build step, no JS dependency, no external images — so they open directly in a browser and can be checked into a repo alongside the docs they illustrate.
- ✓The onboarding flow shows a proposed token diff before writing anything, and the first-run gate stops the skill from silently shipping default-skinned diagrams into a branded project.
- ✓A progressive-disclosure structure — SKILL.md is a lean index, and only the reference file for the requested type loads — keeps 34 reference files from bloating Claude's context on a routine request.
- ✓27 diagram types across three variants each cover a wide range of technical diagrams, from architecture sketches to Gantt charts, without switching tools.
- ✓MIT license with no proprietary lock-in, and a documented contribution path (a skin-lint script plus a repo-wide baseline check) for anyone adding new examples.
When Not to Use This Skill
- △The diagram-type count is inconsistent in the source itself: the GitHub description says '29 editorial diagram types' while the README body repeats '27 types' — check the live gallery yourself rather than trust one number.
- △PNG export needs a separate one-time Python/Playwright setup (`pip install playwright && playwright install chromium`) that isn't bundled with the skill.
- △SVG/PNG exports are diagram-only — the README says editorial cards and headers from the '-full' variants aren't included in either export format.
- △Hand-editing the style guide only sticks if you installed via clone-and-symlink; the README says plugin-cache installs lose references/style-guide.md edits on plugin updates.
- △No version number or roadmap is documented beyond a 'New in 2.0' note for the Loop diagram and the MIT license — nothing in the README describes release cadence or long-term maintenance plans.
Alternatives to Diagram Design
Frequently Asked Questions
Diagram Design works as a Claude Code skill, a Claude Code or Claude Cowork plugin, and a Codex skill installed via `npx skills add`, according to the README's install instructions for each.
Diagram Design's onboarding step fetches your website, extracts its dominant color palette and font stack, maps them to tokens like paper, ink, and accent, and writes them to references/style-guide.md after you approve a proposed diff.
Diagram Design supports exporting diagrams to SVG or PNG through its `/diagram-design:export` command — SVG injects Google Fonts so it renders standalone, and PNG is rasterized via Playwright at 2x scale by default, which needs a one-time `pip install playwright && playwright install chromium` setup.
Diagram Design is released under the MIT license, per its GitHub repository listing.
Diagram Design lets you edit `skills/diagram-design/references/style-guide.md` directly instead of running the website-onboarding flow — every diagram, the annotation primitive, and the gallery all read their colors and fonts from that single file.
Diagram Design's design system uses one accent color reserved for the 1-2 focal elements per diagram, three font families (Instrument Serif, Geist sans, Geist Mono), 1px hairline borders, no shadows, a maximum 10px border-radius, and every coordinate and gap divisible by 4.
Who should try it — and who should skip
Try Diagram Design if visual communication matters in your technical docs and you already use Claude Code for documentation or planning work — especially if you want diagrams that follow your own brand guidelines instead of a generic AI look, and you're comfortable editing a Markdown-based style guide by hand. Skip it if you just need a one-off diagram inside a single unicode block, a simple list, or a table — the README itself says a well-written paragraph often beats a diagram, and this skill's whole design system is overkill for a single box with a label.
Related repositories
Want a second opinion on diagram-design?
Ask an AI that can read this page — one click and you get its take on diagram-design.