Every time you rely on AI to generate diagrams, you probably end up with generic outputs, messy code, or dependencies on tools like Mermaid. diagram-design, a Claude Code skill, takes a different approach. It produces 14 types of editorial-quality diagrams as standalone, self-contained HTML+SVG files without any JavaScript or build steps. The repo’s clever progressive disclosure architecture keeps the skill’s core lean while loading only the necessary type-specific references, managing Claude’s context window efficiently.
What diagram-design does and how it structures diagram generation
diagram-design is a Claude Code skill designed to produce professional-grade diagrams in a highly opinionated, design-driven manner. It supports 14 distinct diagram types, each exported as a standalone HTML file containing inline SVG markup. This means no external dependencies, no Mermaid or other rendering engines, and no JavaScript — just clean, static HTML+SVG files that you can drop anywhere.
The skill ships each diagram in three variants: minimal light, minimal dark, and full-editorial. This allows users to choose a simple or richly styled version according to their needs. Styling is carefully controlled to avoid common AI-generated diagram pitfalls: no shadows, no default rounded boxes, and strict design constraints.
One of the key features is the brand onboarding flow. You provide a website URL, and the skill extracts colors and fonts from the site, mapping them to semantic design tokens named paper, ink, accent, and muted. This automated theming ensures diagrams visually align with a brand’s identity consistently.
Under the hood, the project uses purely HTML and SVG, leveraging semantic tokens and CSS variables for theming. It enforces WCAG AA contrast standards at typical diagram font sizes (9–12px), which is not trivial for dynamically generated diagrams and shows a commitment to accessibility.
The repo’s architecture embraces progressive disclosure: SKILL.md is a lightweight index that loads type-specific reference markdown files only when requested. This keeps Claude Code’s context window tight and efficient, which is crucial for AI workflows constrained by token limits.
Why the progressive disclosure architecture and design constraints matter
What sets diagram-design apart is its combination of design rigor and AI skill architecture. Most AI diagram tools generate diagrams on the fly with bulky context or external dependencies, which can lead to inconsistent styles or bloated outputs.
By splitting references into type-specific markdown files and loading them only when needed, diagram-design manages context window size elegantly. This pattern is worth adopting for other Claude Code skill authors facing similar constraints.
The choice to produce self-contained HTML+SVG files with zero JavaScript is a deliberate tradeoff. It means no interactivity or dynamic updates, but it guarantees portability and easy embedding. The SVGs can be viewed and edited in any modern browser or vector editor without build steps or runtime dependencies.
The brand onboarding flow provides a practical DX boost. Extracting colors and fonts from a website URL and mapping them to semantic tokens automates a tedious manual step and makes consistent theming achievable even for users who don’t want to hand-code design tokens.
The adherence to WCAG AA contrast checks at small font sizes is another technical strength. Ensuring accessible text contrast in diagrams is often overlooked but vital for real-world use cases, especially editorial content.
The repo’s codebase is surprisingly clean, focusing on markdown references and CSS-driven styling rather than complex rendering logic. This means it’s accessible for developers to customize the style guide or add new diagram types.
How to get started with diagram-design
The repo provides clear installation commands to add the skill as a plugin in Claude Code or Claude Cowork environments. Here is the exact quickstart from the README:
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
For Claude Cowork users, customize your directory plugins by adding cathrynlavery/diagram-design, syncing, and installing from your personal list.
This setup requires no build steps, so you can start generating diagrams immediately after installation. The plugin cache installation is quicker but doesn’t persist edits to style guide references across updates — if you want to customize styles by hand, cloning the repo is recommended.
who diagram-design is for and final thoughts
diagram-design is especially suited for developers and content creators who need high-quality, consistent diagrams embedded in editorial content or documentation. Its zero-dependency HTML+SVG output means you can embed diagrams in static sites, PDFs, or other formats without worrying about runtime environments.
The progressive disclosure design of the skill is a clever architectural pattern that other Claude Code skill authors should consider, especially when dealing with large or complex reference data.
Its limitations are clear: no dynamic or interactive diagrams, fixed design constraints that may not suit every style, and some upfront learning curve if you want to customize deeply.
Overall, diagram-design solves a real problem in AI-generated diagrams — producing clean, accessible, brand-consistent visuals without the bloat. It’s a solid choice if you want editorial polish and integration simplicity over flashy interactivity or complex toolchains.
→ GitHub Repo: cathrynlavery/diagram-design ⭐ 2,177 · HTML