# Diagram Design Features: A Complete Guide to the AI-Powered Diagramming Skill

> Explore Diagram Design features. Generate editorial-quality diagrams with AI. No build steps, JavaScript, or external dependencies needed. Learn more about this powerful Claude skill.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: getting-started
- Published: 2026-08-20

---

**Diagram Design is a Claude Code, Codex, Factory Droid, and Pi skill that lets agents generate editorial-quality diagrams without build steps, JavaScript, or external image dependencies.**

The `cathrynlavery/diagram-design` repository provides a modular, agent-ready system for creating professional diagrams. Its architecture loads only the components needed for each request, keeping runtime overhead minimal while delivering 38 visual types with brand consistency and accessibility built in.

## 38 Visual Types with Three Static Variants

The core capability centers on **38 diagram grammars** covering Architecture, Flowchart, Sequence, UML Class, Sankey, Wardley maps, Kanban, and more. Each grammar supports **light, dark, and full-editorial** static variants.

All diagrams render as self-contained HTML + SVG without shadows or "Mermaid slop." The type reference files define each grammar's structure:

- [`skills/diagram-design/references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-architecture.md) — system and component layouts
- [`skills/diagram-design/references/type-sankey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sankey.md) — flow magnitude visualizations
- Additional types in the same `references/` directory

View the complete gallery by opening [`skills/diagram-design/assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/index.html) in a browser.

## Optional Motion with Accessibility Guarantees

When behavior and sequence matter, Diagram Design adds **optional motion modes**: none, reveal, step, or loop. These are defined in [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md).

Motion implementations follow strict accessibility requirements:

- Every SVG receives `role="img"` with nested `<title>` and `<desc>` elements
- Reduced-motion users automatically receive a complete static frame
- No animation violates `prefers-reduced-motion` settings

## Brand Onboarding and Style Guide System

Diagram Design includes a **one-time onboarding flow** that extracts a website's palette and fonts, maps them to semantic tokens (`paper`, `ink`, `accent`, `warning`, etc.), and persists them to [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md).

The onboarding sequence (documented in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) and illustrated in README lines 78-87) works as follows:

```text
You: onboard diagram-design to https://mycompany.com
Agent: → fetches homepage → extracts palette & fonts → proposes diff → writes tokens
You: yes, apply it

```

Subsequent diagrams automatically adopt the extracted brand colors and typography without additional prompts.

## Import and Redraw from Draw.io and Mermaid

The skill can **redraw existing Draw.io or Mermaid source files** into any of the 38 visual types. This preserves structural relationships while applying the editorial skin system.

Import implementation files:

- [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py) — parses Draw.io XML to internal intermediate representation
- [`scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/mermaid_extract.py) — parses Mermaid text syntax to internal IR

Command specifications live in:

- [`skills/diagram-design/commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/commands/import-drawio.md)
- [`skills/diagram-design/commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/commands/import-mermaid.md)

The **four-dial system** (format, size, detail, audience) lets users tailor output for specific destinations: slides, documentation, or social media.

Example import with export:

```text
/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified
/export-diagram /tmp/architecture.html --png-only --scale=3

```

## Export to PNG and SVG

Although diagrams ship as HTML for maximum flexibility, convenience commands support exporting to:

- Pure SVG for vector editing workflows
- Rasterized PNG via Playwright for presentation embedding

Export specifications are in [`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) and [`skills/diagram-design/commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/commands/export-diagram.md).

## Semantic Patterns for Behavioral Diagrams

Beyond layout grammars, Diagram Design includes **seven routed semantic patterns** that separate behavior from visual type. These patterns engage automatically when requests mention corresponding behaviors:

- Fan-in queues
- Policy traces
- And five additional domain patterns

Pattern definitions are in [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md). When combined with motion modes, these create animated explanations of system behavior without custom JavaScript.

Example policy trace with motion:

```text
/diagram-design:profile policy-trace

# … the skill selects the appropriate semantic pattern …

# Motion is added automatically if requested:

Motion: reveal

```

## Extensible Profile System

Users save **brand profiles** under `~/.diagram-design/profiles/` and apply them across multiple client projects. Project association works through a `.diagram-design` marker file in the root directory.

The profile contract is documented in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md), enabling consistent visual identity without repeating onboarding for every project.

## Rigorous Validation and CI

Every change passes Python verification scripts that enforce diagram correctness:

| Script | Validation Target |
|--------|-----------------|
| [`scripts/verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) | Label placement and spatial relationships |
| [`scripts/verify-treemap.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-treemap.py) | Area encoding accuracy |
| [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) | Semantic pattern and motion coupling contracts |
| [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) | Runtime validation that agents can invoke |

CI runs these checks across Linux, macOS, and Windows platforms.

## Plugin Distribution and Marketplace Support

Diagram Design installs through multiple agent marketplaces:

- **Claude Code** — manifest in `.claude-plugin/`
- **Codex** — manifest in `.codex-plugin/`
- **Factory Droid** — manifest in `.factory-plugin/`
- **Pi** — compatible installation path

Command snippets for each marketplace appear in the README.

## Quick Start Examples

Open the visual gallery locally:

```bash

# macOS

open skills/diagram-design/assets/index.html

# Linux

xdg-open skills/diagram-design/assets/index.html

```

Generate an architecture diagram through natural language:

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

```

## Summary

- **38 diagram grammars** with light, dark, and full-editorial variants, all rendering as clean HTML + SVG
- **Accessible motion system** with reveal, step, and loop modes that respect `prefers-reduced-motion`
- **Brand onboarding** that extracts palettes and fonts, storing them in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md)
- **Import pipelines** for Draw.io ([`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py)) and Mermaid ([`scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/mermaid_extract.py)) with redraw to any visual type
- **Export commands** for PNG (via Playwright) and pure SVG
- **Seven semantic patterns** that automatically engage for behavioral diagrams
- **Profile system** for multi-project brand consistency via `~/.diagram-design/profiles/`
- **Verification suite** ([`verify-geometry.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-geometry.py), [`verify-treemap.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-treemap.py), [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py)) with cross-platform CI

## Frequently Asked Questions

### What is Diagram Design and which AI agents support it?

Diagram Design is a skill for Claude Code, OpenAI Codex, Factory Droid, and Pi that generates editorial-quality diagrams without requiring build tools, JavaScript knowledge, or external image hosting. It installs through marketplace manifests in `.claude-plugin/`, `.codex-plugin/`, and `.factory-plugin/` directories.

### How does Diagram Design handle brand consistency across projects?

The skill runs a one-time onboarding flow that scrapes a website's colors and fonts, maps them to semantic tokens (`paper`, `ink`, `accent`), and writes them to [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md). Users can also save profiles to `~/.diagram-design/profiles/` and activate them via `.diagram-design` marker files in project roots.

### Can Diagram Design convert existing Mermaid or Draw.io files?

Yes. The [`scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/mermaid_extract.py) and [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py) parsers convert source files to an internal intermediate representation, then redraw them in any of the 38 visual types while applying the active brand skin. Commands are `/diagram-design:import-mermaid` and `/diagram-design:import-drawio`.

### Are animated diagrams accessible to screen reader users?

Yes. All motion modes (reveal, step, loop) include proper SVG accessibility markup: `role="img"`, `<title>` for the diagram name, and `<desc>` for detailed description. Users with `prefers-reduced-motion` enabled receive complete static frames automatically without manual intervention.