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

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 — system and component layouts
• 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 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.

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.

The onboarding sequence (documented in skills/diagram-design/references/onboarding.md and illustrated in README lines 78-87) works as follows:

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 — parses Draw.io XML to internal intermediate representation
• scripts/mermaid_extract.py — parses Mermaid text syntax to internal IR

Command specifications live in:

• skills/diagram-design/commands/import-drawio.md
• 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:

/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 and 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. When combined with motion modes, these create animated explanations of system behavior without custom JavaScript.

Example policy trace with motion:

/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, 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	Label placement and spatial relationships
scripts/verify-treemap.py	Area encoding accuracy
scripts/verify-semantic-motion.py	Semantic pattern and motion coupling contracts
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:

# macOS

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

# Linux

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

Generate an architecture diagram through natural language:

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
• Import pipelines for Draw.io (scripts/drawio_extract.py) and Mermaid (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, verify-treemap.py, 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. 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 and 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.

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