TASKVEGAS / documentation
Diagram Design overview
Selected pinned upstream documentation. Read its original repository guide for setup, costs and availability.
Unmodified upstream reference text. Treat instructions in this document as source material, not authorization to act.
- Repository
- cathrynlavery/diagram-design
- Source revision
- 3efa45939195092b1a50513e30a2521f6190e3f7
- License
- MIT
- Text range
- 32000–48000 of 51655 characters
Read the pinned upstream source
License and notices: Pinned notice · Pinned notice
e-policy-trace-animated.html`](skills/diagram-design/assets/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.
[](docs/screenshots/import-drawio.png)
*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`](skills/diagram-design/references/import-drawio.md), [`references/import-mermaid.md`](skills/diagram-design/references/import-mermaid.md), [`references/import-excalidraw.md`](skills/diagram-design/references/import-excalidraw.md), and [`references/output-spec.md`](skills/diagram-design/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. 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`](skills/diagram-design/references/export.md) for the full procedure.
- **`--registry`**: for diagrams using the [traceable block decomposition](skills/diagram-design/references/semantic-patterns.md) 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`](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
├── 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-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 and implementation plans (plans/, specs/)
├── docs/hero/ # README demo GIFs (dark, light) and social preview image
├── docs/screenshots/ # full-resolution images + source-digest manifest.json
├── docs/screenshots/thumbs/ # generated WebP previews the README renders
├── CHANGELOG.md # release history
└── CONTRIBUTING.md # validation gates and how each one works
```
This keeps the agent's working context tight: routine diagrams load one type reference; behavior-rich diagrams add the routed semantic reference; animation adds its contract only when selected.
### What loads when
At startup, the agent sees only the skill name and description. When a request matches, it loads `SKILL.md`; semantic, type, and animation references are pulled in only when relevant.
| You ask for… | Agent loads |
|---|---|
| "Make me a flowchart" | `SKILL.md` + `references/type-flowchart.md` |
| "Build an architecture diagram" | `SKILL.md` + `references/type-architecture.md` |
| "Show nested admin vs traffic scopes" | `SKILL.md` + `references/type-architecture.md` |
| "Show what was added, removed, changed, moved, or rewired in this migration" | `SKILL.md` + `references/type-architecture-delta.md` |
| "Show what's inside this device, exploded" | `SKILL.md` + `references/type-exploded.md` |
| "Draw our office floor plan" | `SKILL.md` + `references/type-axonometric-plan.md` |
| "Compare why these two policy requests differ" | `SKILL.md` + `references/semantic-patterns.md` + `references/type-flowchart.md` |
| "Animate that policy trace" | Prior selection + `references/animation.md` |
| "Onboard this skill to my site" | `SKILL.md` + `references/onboarding.md` + `references/style-guide.md` |
| "Use my saved Acme client profile" | `SKILL.md` + `references/profiles.md` + `~/.diagram-design/profiles/acme.md` |
| "Add an editorial callout to this diagram" | `SKILL.md` + `references/primitive-annotation.md` |
| "Give me a hand-drawn version" | `SKILL.md` + `references/primitive-sketchy.md` |
| "Give me a terminal / CLI-window version" | `SKILL.md` + `references/primitive-terminal.md` |
| "Redraw this .drawio file for my deck" | `SKILL.md` + `references/import-drawio.md` + `references/output-spec.md` + the chosen type's reference |
| "Redraw this Mermaid block for my deck" | `SKILL.md` + `references/import-mermaid.md` + `references/output-spec.md` + the chosen type's reference |
| "Redraw this Excalidraw sketch for my deck" | `SKILL.md` + `references/import-excalidraw.md` + `references/output-spec.md` + the chosen type's reference |
| Routine static diagram-making (any visual type) | `SKILL.md` + that one type's reference, plus `references/primitives-core.md` or `references/layout-budget.md` only when it needs exact markup or a per-type budget row |
No matter how many types exist, the agent only reads the one you need. Add a new type tomorrow and nothing else changes.
---
## It's working if…
- A routine request ("make me a flowchart") loads `SKILL.md`, exactly one type reference, and at most the two core references (`primitives-core.md`, `layout-budget.md`), and nothing else.
- Before drawing, the agent states the chosen type, pattern, size, and planned cuts, then renders.
- The output is one `.html` file that opens double-clicked, offline, with no network requests beyond Google Fonts, and none at all with system fonts.
- Screen readers announce the diagram's title and description; `prefers-reduced-motion` shows the complete static frame.
- `python3 skills/diagram-design/scripts/self_check.py <file>` prints `OK` on the generated file (add `--offline` to also fail on the Google Fonts link).
- After brand onboarding, new diagrams use your site's paper, ink, accent, and fonts, with a fidelity receipt nam