@wanerfu: I recently came across a Skill that's especially great for "knowledge visualization": diagram-design. It already has nearly 60,000 Stars. What it does is simple: it turns long-form text, processes, and relationships into a professional-looking diagram. For a content creator like me, I mainly use it in 6 ways: 01 | Create professional illustrations for articles...

X AI KOLs Timeline 10/28/26, 04:41 AM Tools

agent-skills diagram-generation visualization open-source claude-code content-creation

Summary

A content creator recommends the open-source Agent Skill "diagram-design," which automatically renders long-form text, processes, and relationships into professional single-file HTML+SVG diagrams. It supports 45 chart types, brand customization, and imports from draw.io/Mermaid/Excalidraw, and has already garnered nearly 60,000 Stars.

I recently came across a Skill that's especially great for "knowledge visualization": diagram-design. It already has nearly 60,000 Stars. What it does is simple: It turns long-form text, processes, and relationships into a single professional-looking diagram. For a content creator like me, I mainly use it in 6 ways: 01 | Create professional illustrations for articles 02 | Produce visual assets for PPTs and presentation decks 03 | Compress long-form content into a single shareable image 04 | Learn a complex new subject 05 | Map out projects and workflows 06 | Prepare work reports diagram-design Skill open-source repo: http://github.com/cathrynlavery/diagram-design...

Original Article

View Cached Full Text

Cached at: 10/29/26, 12:00 PM

Contrast checks happen automatically

Before writing tokens, the skill verifies WCAG AA contrast on ink over paper. If your site has a color that fails contrast at diagram sizes (9 to 12px), it proposes an adjusted value and explains why. The default skin is held to the same contract in CI: text roles clear 4.5:1 and essential marks clear 3:1 on both light and dark paper.

Accessible by default

Every diagram template gives the inline SVG an accessible name and description: role="img", a resolving aria-labelledby, and first-child <title> / <desc> slots. IDs are prefixed per diagram and variant, so multiple SVG exports can be safely inlined on one page without duplicate accessible-name IDs. Decorative specimen icons are hidden from assistive technology instead.

Offline fonts

By default a diagram loads Instrument Serif, Geist and Geist Mono from Google Fonts, the only network request it makes. Ask for system fonts (or set the font source to system in your style guide) and the file makes no network requests at all: the stacks fall back to the platform’s own serif, sans and monospace faces. See Font source.

Manual override

Prefer to set tokens by hand? Open skills/diagram-design/references/style-guide.md and edit the table. Everything downstream reads from there: every diagram, the annotation primitive, and the gallery all use semantic role names (accent, not a hex value).

First-run gate

The skill won’t silently ship default-skinned diagrams into a branded project. On first use in a new project, it checks if style-guide.md has been customized. If not, it pauses and asks:

“This is your first diagram in this project. The style guide is still at the default. Want to run onboarding, paste tokens manually, or proceed with default?”

See skills/diagram-design/references/onboarding.md for the full spec.

Working with multiple clients

Onboard a brand once, save the result as a named profile, then add a .diagram-design marker containing profile: <slug> to each client project. Marker projects read ~/.diagram-design/profiles/<slug>.md directly, so parallel workspaces can use different brands without overwriting a shared installed style-guide.md. The profile library is shared across Claude Code, Codex, Factory Droid, and Pi. Use /diagram-design:profile in Claude Code, /profile in Factory Droid or Pi, or ask in natural language in any host. See profiles.md for the storage, marker, and recovery contract.

Quickstart

# From a cloned checkout, open the gallery to see every diagram
open skills/diagram-design/assets/index.html      # macOS
xdg-open skills/diagram-design/assets/index.html  # Linux

Then ask your agent for a diagram, like the prompts at the top of this page. A sequence with token refresh uses the ALT combined-fragment grammar in type-sequence.md; see example-sequence-oauth.html.

Operator recipes for editable installs, first diagrams, brand setup, import, export, validation, Windows junctions, and reusable prompts live in docs/cookbook.md. You can also start from a template directly:

cp skills/diagram-design/assets/template.html        my-diagram.html  # minimal light
cp skills/diagram-design/assets/template-full.html   my-diagram.html  # editorial with summary cards
cp skills/diagram-design/assets/template-motion.html my-diagram.html  # optional accessible motion

Semantic patterns and optional motion

When behavior matters, the skill chooses a semantic pattern first and a visual type second. The nine routed patterns cover fan-in queues and bottlenecks, repeated stage slots, unstructured-input transformation, paired policy traces, secure paved roads, governance catalogs, compensating security layers, traceable block decomposition, and lifecycle phase maps. Each pattern defines its triggers, primitives, budget, anti-patterns, static fallback, and nearest visual type in semantic-patterns.md.

Motion is optional and does not create another visual type. animation.md defines none, reveal, step, and loop modes with a complete static first frame, deterministic timing, and controls when interaction is available. Reduced-motion output shows the complete static frame and hides/disables playback controls. Motion HTML uses the exact reviewed controller from template-motion.html; arbitrary or modified inline scripts, remote assets, CSS imports, and executable HTML attributes are rejected. The default is none: ordinary output remains static and script-free. example-policy-trace-animated.html is the self-contained interactive example.

Import from draw.io, Mermaid, or Excalidraw

Already have diagrams in draw.io / diagrams.net, Mermaid, or Excalidraw? Point the skill at the source and it redraws them: same content, this design system, at whatever size the destination needs.

Redrawn from a .drawio file

A 12-node draw.io file redrawn at balanced detail for a blog post. The source’s six pastel fills became one accent; its hand-dragged coordinates became a 4px grid.

/diagram-design:import-drawio platform.drawio
/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-drawio platform.drawio --detail=faithful --format=png --page=all
/diagram-design:import-mermaid README.md --diagram=all
/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified
/diagram-design:import-excalidraw whiteboard.excalidraw --size=slide-16x9 --detail=simplified

Or just ask: “redraw this drawio file for my deck”, “make this Mermaid block editorial”, “make this whiteboard sketch presentable”, or “この Mermaid をスライド用にきれいにして”.

Reads the common containers draw.io writes (.drawio, .drawio.xml, .drawio.png with an embedded diagram, and .drawio.svg), including compressed payloads that look like base64 garbage in an editor. For Mermaid, it accepts .mmd, .mermaid, and one or more fenced mermaid blocks in Markdown. UTF-8 files may include a byte-order mark. For Excalidraw, it accepts .excalidraw and .excalidraw.json scene files (not .excalidraw.png/.excalidraw.svg exports). It parses text only: no rendering, JavaScript, browser, network, or followed click targets.

The four dials

The point isn’t conversion, it’s fitting the output to where it’s going. Same source file, three different diagrams:

Dial	Options	What it changes
Format	`html` · `svg` · `png` · `html+png`	The deliverable. SVG for Figma, PNG for slides, HTML for the web.
Size	`doc-inline` · `doc-wide` · `slide-16x9` · `slide-4x3` · `social-og` · `social-square` · `print-a4-landscape` · `print-a3-landscape` · `print-letter-landscape` · `fit`	The `viewBox` and the type ramp: a projected slide gets 16px node names, not 12px.
Detail	`faithful` (≤24 nodes, zoned) · `balanced` (≤12) · `simplified` (≤7)	How much of the source survives, via a fixed degrade ladder: decorations, then duplicates, then leaf clusters, then infrastructure.
Audience	`engineer` · `mixed` · `executive`	The wording, not the count. `Auth Service / JWT · RS256 · :8443` → `Auth Service / token check` → `Sign-in`.

Every import ends with a fidelity ledger listing what got merged, collapsed, or dropped. You know the source; you’d notice anyway.

Detail: balanced · 12 source nodes → 8 drawn
Collapsed: "Token valid?" decision → edge label on Gateway → Auth
Dropped: 1 sticky note ("legacy path, to be retired"), unconnected in source
Kept in full: the request path (Web/Mobile → Gateway → Orders → Postgres)

What never carries over: source or renderer coordinates, source palette, source fonts, draw.io’s diagonal connector spaghetti, Mermaid’s automatic layout, or Excalidraw’s hand-drawn geometry. What always does: components, relationships, grouping, and direction.

See references/import-drawio.md, references/import-mermaid.md, references/import-excalidraw.md, and references/output-spec.md.

Export to PNG / SVG

Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. SVG export also carries CDATA-wrapped diagram CSS, including selectors bound to the original SVG root, and preserves quoted selector values containing comment delimiters.

Use the slash command for your agent:

Pi:

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

Claude Code:

/diagram-design:export-diagram path/to/diagram.html
/diagram-design:export-diagram path/to/diagram.html --svg-only
/diagram-design:export-diagram path/to/diagram.html --png-only --scale=3
/diagram-design:export-diagram path/to/diagram.html --registry

Or just ask in natural language:

"Export this diagram as SVG and PNG."
"Save my-diagram.html as PNG."

SVG extracts the <svg> node and injects Google Fonts so it renders standalone in browsers, Figma, and Illustrator. Animation bindings follow namespaced keyframes even when property names use CSS escapes. Pass --system-fonts to skip the font import for offline use.
PNG rasterizes the diagram via Playwright at 2× by default. One-time setup: pip install playwright && playwright install chromium. Both formats are diagram-only: editorial cards and headers from -full variants aren’t included. For a screenshot of the full editorial layout, use your browser’s print-to-PDF or full-page screenshot.

See skills/diagram-design/references/export.md for the full procedure.

--registry: for diagrams using the traceable block decomposition pattern, also emits <basename>.registry.json, a structured projection of every block’s data-block-* metadata. Combine with either raster format or run alone. See skills/diagram-design/references/export-registry.md.

For motion-enabled HTML, export the explicit final state: open ?motion=static, wait for document.fonts.ready, and confirm the motion root has data-frame="static" before capture. Use ?motion=step&step=N only when a named intermediate frame was requested.

Architecture

Progressive disclosure. SKILL.md routes behavior first when needed, then layout. Semantic, type, and animation references load only when relevant.

diagram-design/
├── .agents/plugins/marketplace.json     # Codex marketplace catalog
├── .claude-plugin/                      # Claude marketplace + plugin manifest
├── .codex-plugin/                       # Codex plugin manifest
├── .factory-plugin/                     # Factory Droid marketplace + plugin manifest
├── .qoder-plugin/                       # Qoder native plugin manifest
├── commands/
│   ├── export-diagram.md                # plugin export command
│   ├── import-drawio.md                 # plugin draw.io import command
│   ├── import-mermaid.md                # plugin Mermaid import command
│   ├── import-excalidraw.md             # plugin Excalidraw import command
│   ├── profile.md                       # plugin client-profile command
│   └── doctor.md                        # plugin environment diagnostics command
├── prompts/
│   ├── export-diagram.md                # Pi `/export-diagram` prompt template
│   ├── import-mermaid.md                # Pi Mermaid import prompt template
│   ├── import-excalidraw.md             # Pi Excalidraw import prompt template
│   ├── profile.md                       # Pi `/profile` prompt template
│   └── doctor.md                        # Pi `/doctor` diagnostics prompt template
├── skills/
│   └── diagram-design/
│       ├── SKILL.md                     # philosophy, selection guide, checklist
│       ├── references/                  # loaded only when a type or primitive is chosen
│       │   ├── style-guide.md           # single source of truth for colors + fonts
│       │   ├── semantic-patterns.md     # behavior patterns independent of layout
│       │   ├── animation.md             # optional motion + accessibility contract
│       │   ├── onboarding.md            # the URL-to-tokens flow
│       │   ├── profiles.md              # named client profiles + project markers
│       │   ├── doctor.md                # environment diagnostics
│       │   ├── import-drawio.md         # draw.io redraw procedure
│       │   ├── import-mermaid.md        # Mermaid redraw procedure
│       │   ├── import-excalidraw.md     # Excalidraw redraw procedure
│       │   ├── output-spec.md           # format × size × detail level
│       │   ├── export.md                # SVG / PNG export + sizing
│       │   ├── export-registry.md       # block-metadata JSON sidecar export
│       │   ├── primitives-core.md       # exact markup for nodes, arrows, labels
│       │   ├── layout-budget.md         # 4px grid + per-type budgets
│       │   ├── primitive-annotation.md
│       │   ├── primitive-icons.md
│       │   ├── primitive-sketchy.md
│       │   ├── primitive-terminal.md
│       │   ├── type-architecture.md
│       │   ├── type-architecture-delta.md
│       │   ├── type-axonometric-plan.md
│       │   ├── type-bar.md
│       │   ├── type-data-flow.md
│       │   ├── type-db-schema.md
│       │   ├── type-dependency.md
│       │   ├── type-deployment.md
│       │   ├── type-dp-integration.md
│       │   ├── type-dp-security-matrix.md
│       │   ├── type-er.md
│       │   ├── type-exploded.md
│       │   ├── type-fishbone.md
│       │   ├── type-flowchart.md
│       │   ├── type-gantt.md
│       │   ├── type-heatmap.md
│       │   ├── type-high-level.md
│       │   ├── type-it-state.md
│       │   ├── type-journey.md
│       │   ├── type-kanban.md
│       │   ├── type-layers.md
│       │   ├── type-line.md
│       │   ├── type-loop.md
│       │   ├── type-medallion.md
│       │   ├── type-nested.md
│       │   ├── type-org-chart.md
│       │   ├── type-polar.md
│       │   ├── type-process.md
│       │   ├── type-pyramid.md
│       │   ├── type-quadrant.md
│       │   ├── type-radar.md
│       │   ├── type-sankey.md
│       │   ├── type-scatter.md
│       │   ├── type-sequence.md
│       │   ├── type-service-blueprint.md
│       │   ├── type-state.md
│       │   ├── type-story-map.md
│       │   ├── type-swimlane.md
│       │   ├── type-timeline.md
│       │   ├── type-tree.md
│       │   ├── type-treemap.md
│       │   ├── type-uml-class.md
│       │   ├── type-venn.md
│       │   ├── type-wardley.md
│       │   └── type-waterfall.md
│       ├── scripts/
│       │   ├── drawio_extract.py        # draw.io → structured IR
│       │   ├── mermaid_extract.py       # Mermaid → structured IR
│       │   ├── excalidraw_extract.py    # Excalidraw → structured IR
│       │   ├── export_svg.py            # standalone SVG export
│       │   ├── export_png.py            # Playwright PNG renderer
│       │   └── self_check.py            # packaged output self-check (runs installed)
│       └── assets/
│           ├── index.html               # live gallery, tabbed
│           ├── icons.html               # icon library browser
│           ├── template*.html           # scaffolds for new diagrams
│           ├── example-<type>.html      # 3 variants per type
│           ├── example-loop-terminal.html
│           ├── example-quadrant-consultant.html
│           ├── example-import-drawio.html
│           ├── example-import-mermaid.html
│           ├── example-import-excalidraw.html
│           ├── example-policy-trace-animated.html
│           └── example-sequence-oauth*.html
├── scripts/                             # CI gates and build helpers (see CONTRIBUTING.md)
│   ├── lint-skin.py                     # palette, fonts, a11y, single-file safety
│   ├── lint-render.py                   # Chromium rendered-layout checker
│   ├── verify-docs-sync.py              # routing, gallery, README and count sync
│   ├── verify-geometry.py               # label, connector and port geometry
│   ├── render-canonical-screenshots.py  # deterministic per-type PNG catalog renderer
│   ├── build-readme-thumbs.py           # regenerates docs/screenshots/thumbs/
│   └── fixtures/                        # draw.io, Mermaid and Excalidraw test inputs
├── docs/cookbook.md                     # operator recipes for editable installs and common tasks
├── docs/adr/                            # short records of settled design decisions
└── docs/superpowers/                    # design specs