How to Generate Editorial-Quality Diagrams for AI Coding Assistants Using Diagram Design

Diagram Design is a self-contained skill that lets AI coding assistants like Claude Code, Codex, or Pi render 39 editorial-style diagram types in pure HTML + SVG through lazy-loaded reference files and slash commands.

Diagram Design is an open-source skill system authored by Cathryn Lavery that turns any compatible AI assistant into a professional diagram generator. Unlike external tools that require API keys or cloud rendering, this repository provides everything needed to create editorial-quality diagrams directly inside your development environment—no network dependencies, no subscription fees, and full offline capability.

Understanding the Architecture

The Diagram Design skill uses a deliberately lazy-loaded architecture to keep runtime overhead minimal while providing maximum capability.

Component	Role	Source Path
Skill entry point	Describes the design system, selects diagram types, routes to references	skills/diagram-design/SKILL.md
Reference library	Per-type specifications, style guide, semantic patterns, animation contract	skills/diagram-design/references/
Command definitions	Slash-command mappings (/export-diagram, /import-drawio, etc.)	commands/
Prompt templates	Host-specific LLM prompts (Pi, Claude Code, etc.)	prompts/
Assets	HTML scaffolds, example diagrams, live gallery	skills/diagram-design/assets/
Scripts	CI validation, rendering helpers, linting	scripts/

The agent loads SKILL.md first, then pulls only the specific reference files needed for your requested diagram type, semantic pattern, or animation style.

Installing Diagram Design on Your AI Assistant

Choose the installation commands for your specific host:

Claude Code

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

Codex (OpenAI)

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

Then reload the session:

/reload

Generating Your First Editorial-Quality Diagram

Once installed, request diagrams through natural language or slash commands:

Natural Language Generation (Any Host)

"Make me an architecture diagram of my app: frontend, backend, database, Redis cache."

Import from Existing Formats

Draw.io import with styling options:

/diagram-design:import-drawio platform.drawio \
  --size=slide-16x9 --detail=simplified --audience=executive

Mermaid import from Markdown:

/diagram-design:import-mermaid README.md --diagram=all

The skill reads SKILL.md, determines the required type reference from skills/diagram-design/references/type-*.md, loads it, and renders a self-contained HTML file with embedded SVG.

Exporting Diagrams for Publication

Diagram Design outputs pure HTML + SVG with no external scripts—making files embeddable anywhere.

Export Commands

SVG only:

/export-diagram path/to/diagram.html --svg-only

High-resolution PNG (uses Playwright for rasterization):

/export-diagram path/to/diagram.html --png-only --scale=3

Both options preserve the WCAG AA accessibility compliance built into every generated diagram.

Brand Onboarding and Style Consistency

The skill can extract your brand identity from any live website and apply it automatically to all subsequent diagrams.

Onboarding Command

"onboard diagram-design to https://mycompany.com"

This fetches the homepage, extracts the dominant colour palette and font stack, and writes tokens to skills/diagram-design/references/style-guide.md. All future diagrams inherit these brand tokens without manual configuration.

Key Reference Files for Advanced Customization

File	Purpose
skills/diagram-design/references/style-guide.md	Single source of truth for colour and font tokens
skills/diagram-design/references/semantic-patterns.md	Seven routed semantic patterns for behaviour-rich diagrams
skills/diagram-design/references/animation.md	Motion contract: none, reveal, step, loop
skills/diagram-design/assets/template.html	Minimal light-theme scaffold
skills/diagram-design/assets/template-full.html	Full-editorial variant with summary cards
skills/diagram-design/assets/template-motion.html	Scaffold with optional motion controller

Validating Diagram Quality

Run the built-in validation to guarantee geometry, accessibility, and motion contracts are satisfied:

python3 skills/diagram-design/scripts/self_check.py my-diagram.html

Expected output: OK

For CI pipelines, use scripts/lint-render.py which renders examples with headless Chromium and checks clipping, contrast ratios, and unique ID usage.

Summary

• Diagram Design generates editorial-quality diagrams through 39 HTML + SVG diagram types usable across Claude Code, Codex, Pi, and other AI assistants
• Lazy-loaded architecture in skills/diagram-design/SKILL.md minimizes runtime footprint by loading only needed reference files
• Brand onboarding extracts palettes and fonts automatically from any website
• Accessibility compliance includes <title>/<desc> pairs, role="img", and WCAG AA colour contrast validation
• Export flexibility provides standalone SVG or high-resolution PNG via Playwright rasterization
• Pure HTML + SVG output enables offline embedding in blogs, PDFs, and slide decks without external dependencies

Frequently Asked Questions

Which AI coding assistants support Diagram Design?

Claude Code, OpenAI Codex, Factory Droid, Pi, Kiro, and OpenCode are explicitly supported. The skill uses host-specific prompt templates in prompts/ and standard slash-command definitions in commands/ that map to each platform's plugin architecture.

Can I customize the visual style of generated diagrams?

Yes. Run brand onboarding against any URL to auto-populate style-guide.md, or manually edit skills/diagram-design/references/style-guide.md to define colour tokens, font stacks, and spacing scales. The skill validates contrast ratios before applying tokens.

How does animation work in Diagram Design diagrams?

Animation is governed by skills/diagram-design/references/animation.md with four modes: none (static), reveal (progressive disclosure), step (click-advanced), and loop (continuous). Use assets/template-motion.html as the scaffold when motion is requested.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}