cathrynlavery/diagram-design: Editorial Diagrams Without Figma

cathrynlavery/diagram-design: Editorial Diagrams Without Figma

Developers who write documentation, blog posts, or technical proposals share a recurring frustration: diagrams that look like afterthoughts. Either you spend thirty minutes in Figma aligning boxes, or you accept the generic rounded-rectangle output from AI tools that matches nothing else on your site. cathrynlavery/diagram-design addresses this directly — it's a Claude Code skill that generates fourteen types of editorial-quality diagrams as self-contained HTML and SVG, with automatic brand extraction from your live website.

What is cathrynlavery/diagram-design?

cathrynlavery/diagram-design is an open-source Claude Code skill maintained by Cathryn Lavery, founder of BestSelf.co and writer at littlemight.com. The repository has accumulated 2,763 stars and 207 forks as of its last commit on May 11, 2026, with HTML as its primary language and an MIT License.

The tool sits at the intersection of AI-assisted development and design systems. Rather than generating diagrams as opaque images or relying on Mermaid's limited aesthetic, it produces standalone HTML files with embedded SVG — no JavaScript^{↗ Bright Coding Blog}, no external dependencies, no build step required. Open any output directly in a browser.

Lavery built this after repeated friction: asking Claude for diagrams yielded "generic rounded-box thing[s] that looked nothing like the rest of the site." The skill's core premise is that diagrams should match your established brand automatically, not require manual color-picking sessions.

The fourteen supported diagram types cover most technical communication needs: architecture diagrams, flowcharts, sequence diagrams, state machines, ER/data models, timelines, swimlanes, quadrants, nested hierarchies, trees, org charts, Venn diagrams, layer stacks, pyramids/funnels, and a consultant-style 2×2 scenario matrix. Each ships in three visual variants: minimal light, minimal dark, and full-editorial.

Key Features

Brand extraction in 60 seconds. The skill's standout capability reads your website's CSS and maps detected colors and fonts to semantic roles: paper (background), ink (primary text), muted (secondary text), accent (CTA/brand color), and link. Your body background becomes the diagram background; your heading font becomes the title family. WCAG AA contrast checks run automatically before tokens are written.

Zero-dependency outputs. Every diagram is a single HTML file with inline SVG. No CDN calls, no npm installs, no runtime JavaScript. This matters for documentation that needs to survive years, embedded contexts with strict CSP policies, or environments where external assets are blocked.

Progressive disclosure architecture. The skill's SKILL.md serves as a lean index; individual type references load only when needed. Ask for a flowchart, and Claude loads only type-flowchart.md. This keeps context windows tight and response times fast regardless of how many diagram types exist.

Semantic design system. One accent color, 1–2 focal elements per diagram. Three font families: Instrument Serif for titles and italic callouts, Geist Sans for node names, Geist Mono for technical sublabels. 1px hairlines, no shadows, maximum 10px border radius. A strict 4px grid system — "non-negotiable, it's what keeps the diagrams from feeling AI-generated."

Editorial primitives. Annotation callouts use italic serif with dashed Bézier leaders for margin asides. An optional sketchy SVG filter (turbulence + displacement map) produces hand-drawn variants suited for essays rather than technical documentation.

First-run guardrails. The skill detects uncustomized style-guide.md and pauses to offer onboarding, manual token entry, or deliberate default usage. This prevents accidentally shipping generic-skinned diagrams into branded projects.

Use Cases

Technical documentation and README files. Architecture diagrams showing component relationships, sequence diagrams for API authentication flows, or ER diagrams for data models — all matching your project's documentation site colors without leaving your editor.

Blog posts and newsletters. The full-editorial variant with summary cards and annotation callouts suits long-form content where diagrams need to feel intentional, not pasted-in. The sketchy filter variant works for less formal essays where hand-drawn warmth is appropriate.

Internal proposals and strategy documents. Quadrant charts for prioritization (impact vs. effort), consultant 2×2 matrices for scenario planning, pyramid diagrams for ranked hierarchies — generated directly from conversation without context-switching to design tools.

Presentation scaffolding. Because outputs are pure HTML/SVG, they can be screenshotted at any resolution, opened directly in a browser tab for presenting, or embedded in slide decks without rasterization artifacts.

Design system documentation. The automatic brand extraction makes this particularly valuable for design system maintainers who need to produce consistent diagram examples across documentation sites.

Installation & Setup

The recommended installation preserves your ability to customize the style guide:

# Clone the repository to a persistent location
git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design

# Symlink the inner skill directory into Claude Code's skills folder
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

The symlink points to skills/diagram-design/ inside the repository — this nested structure allows the same codebase to function as a Claude Code skill, a Codex plugin, and a standalone tool. Restart Claude Code after creating the symlink; the skill registers as diagram-design and activates on diagram-related requests.

For quicker evaluation without customization intent, install as a plugin:

Claude Code:

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

Claude Cowork: Navigate to 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

Note that plugin installation places the skill in cache; edits to references/style-guide.md will not survive updates. Use the clone-and-symlink method if you plan to customize tokens manually.

Real Code Examples

The README provides direct template usage for starting diagrams from scratch:

# Minimal light variant — clean, no editorial chrome
cp assets/template.html my-diagram.html

# Full editorial variant with summary cards and styled containers
cp assets/template-full.html my-diagram.html

These templates provide the structural foundation that the skill populates based on your conversation. The light template suits inline documentation; the full template suits standalone explanatory diagrams with richer visual hierarchy.

For brand onboarding, the interaction pattern is:

You:     "onboard diagram-design to https://yoursite.com"
Claude:  → 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"

This is not a command to paste but the documented conversational flow. The skill handles the HTTP request, CSS parsing, color extraction, and token mapping automatically.

To browse all fourteen diagram types with live variant switching:

# Open the gallery in your default browser
open ~/.claude/skills/diagram-design/assets/index.html

The gallery file is a self-contained HTML page with tabbed navigation between light, dark, and full-editorial variants for each diagram type. No server required — file:// protocol works fine.

Advanced Usage & Best Practices

Manual token override. For precise control, edit skills/diagram-design/references/style-guide.md directly. The semantic role system (accent, not #eb6c36) means changes propagate through all diagram types, primitives, and the gallery automatically.

Density discipline. The documentation emphasizes restraint: "Target density: 4/10." Every node must earn its place. The accent color is reserved for the 1–2 elements the reader should notice first. This editorial discipline prevents the cluttered outputs common in automated diagram tools.

Type selection. The SKILL.md selection guide helps match intent to diagram type. Before defaulting to a flowchart, consider whether a timeline (events on axis), swimlane (cross-functional flow), or state machine (transitions between states) communicates the structure more directly.

When not to use it. The documentation is explicit about anti-patterns: unicode diagrams for tweets (use wiretext), simple lists (use tables or bullets), before/after comparisons (use tables), and single-shape "diagrams" (just write the sentence). This self-awareness is rare and valuable.

Comparison with Alternatives

Mermaid remains the default for GitHub-embedded diagrams due to native rendering, but its aesthetic is deliberately generic. Figma offers unlimited control at the cost of manual effort and subscription pricing. cathrynlavery/diagram-design occupies a distinct niche: brand-matched, zero-dependency outputs generated through conversation rather than manipulation of design tools.

The trade-off is ecosystem maturity. Mermaid has years of community contributions; this skill has 2,763 stars and active maintenance but a narrower scope. For teams already using Claude Code, the integration friction is near zero.

FAQ

Does this require a paid Claude subscription? The skill works with Claude Code; check Anthropic's current pricing for Code access.

Can I use these diagrams commercially? Yes — MIT License permits commercial use, modification, and distribution.

What if my website uses CSS-in-JS or complex build pipelines? The onboarding fetches the rendered homepage, so compiled styles are captured. Extremely dynamic color systems may require manual token entry.

Do diagrams work offline? Yes — all outputs are self-contained HTML with inline SVG, no external resources.

Can I add custom diagram types? The architecture supports extension: create type-<name>.md in references/ and wire into SKILL.md's selection guide.

Is there a CLI outside of Claude Code? Not currently — the skill is designed for conversational interaction within Claude Code, Codex, or Claude Cowork.

How recent is the codebase? Last commit was May 11, 2026; verify current activity on the repository page.

Conclusion

cathrynlavery/diagram-design solves a specific, well-defined problem: producing editorial-quality diagrams that match your brand without leaving your development environment. It's best suited for developers who write public-facing content, maintain documentation sites, or produce internal proposals where visual consistency matters.

The 2,763-star count and active maintenance suggest genuine utility, not just novelty. The MIT license removes adoption friction. The zero-dependency outputs future-proof your diagrams against CDN rot or package deprecation.

If you're already using Claude Code and tired of generic diagram output, the 60-second onboarding is low-risk to evaluate. Clone the repository, symlink the skill, and try generating your first brand-matched architecture diagram.

Explore cathrynlavery/diagram-design on GitHub →