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

> Generate editorial-quality diagrams for AI coding assistants with Diagram Design. Render 39 diagram types in pure HTML + SVG using slash commands and lazy-loaded reference files.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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

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

```

### Codex (OpenAI)

```bash
codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

```

### Factory Droid

```bash
droid plugin marketplace add https://github.com/cathrynlavery/diagram-design
droid plugin install diagram-design@diagram-design --scope user

```

### Pi

```bash
pi install https://github.com/cathrynlavery/diagram-design

```

Then reload the session:

```text
/reload

```

## Generating Your First Editorial-Quality Diagram

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

### Natural Language Generation (Any Host)

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

```

### Import from Existing Formats

**Draw.io import with styling options:**

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

```

**Mermaid import from Markdown:**

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

```

The skill reads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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:**

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

```

**High-resolution PNG (uses Playwright for rasterization):**

```text
/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

```text
"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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Single source of truth for colour and font tokens |
| [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) | Seven routed semantic patterns for behaviour-rich diagrams |
| [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) | Motion contract: `none`, `reveal`, `step`, `loop` |
| [`skills/diagram-design/assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template.html) | Minimal light-theme scaffold |
| [`skills/diagram-design/assets/template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-full.html) | Full-editorial variant with summary cards |
| [`skills/diagram-design/assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

```

**Expected output:** `OK`

For CI pipelines, use [`scripts/lint-render.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), or manually edit [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-motion.html) as the scaffold when motion is requested.