cathrynlavery/diagram-design instruction manual

1. Purpose, scope, and Claude Code classification

Diagram Design is an MIT-licensed Agent Skill and native Claude Code plugin for producing editorial diagrams as self-contained HTML with inline SVG and CSS. Its documented output is static and script-free by default; explicit motion may add the repository’s reviewed inline controller. The skill emphasizes sparse layouts, one or two accent elements, orthogonal connectors, accessible SVG naming, and reuse of brand colors and typography.

**Claude Code classification:** `claude_extension`, using **context injection** and a **tool surface** (confidence: high). Evidence: `.claude-plugin/plugin.json` defines the plugin, `skills/diagram-design/SKILL.md` supplies routed instructions, and `commands/` supplies import, export, profile, and diagnostic command surfaces. It is not Claude Code itself and does not intercept Claude Code operations. Progressive disclosure loads the main skill only for matching requests, then the relevant semantic, type, animation, import, export, or profile reference.

The plugin metadata identifies version 2.6.7, while the skill metadata says 2.6. The repository metadata calls it an HTML project and links the hosted gallery. The supplied files document Claude Code, Codex, Factory Droid, Pi, and Claude Cowork installation paths.

2. Installation, updates, and editable checkouts

For Claude Code, add the marketplace and install the plugin:

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

Run `/plugin`, open **Marketplaces**, select **diagram-design**, and enable auto-update. Third-party marketplace auto-update is off by default. When prompted, run `/reload-plugins`; otherwise the next session loads the update.

Codex installation and immediate refresh:

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design
codex plugin marketplace upgrade diagram-design

Start a new Codex session after upgrading. Factory Droid uses:

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

Start a new session after updating. Pi uses:

pi install https://github.com/cathrynlavery/diagram-design
pi update --extensions

In an open Pi session, run `/reload`; invoke the skill explicitly with `/skill:diagram-design`. For an editable checkout:

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
pi install ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

Cowork organization installation requires mirroring this public repository into a private or internal organization repository, adding it under **Organization settings → Plugins**, and enabling automatic sync.

3. First use, brand onboarding, and client profiles

On first use in a project, the skill checks for a `.diagram-design` marker and then the working style guide. If the shipped paper `#f5f5f5`, ink `#2d3142`, and accent `#eb6c36` remain unchanged, it asks whether to extract a brand from a website, another installed skill, a local design-system folder, pasted tokens, a saved profile, or continue with defaults.

A source-supported request is:

onboard diagram-design to https://yoursite.com

Website onboarding samples the site, maps background, primary text, secondary text, containers, brand color, heading font, body font, and code font to semantic roles, checks WCAG AA contrast, proposes changes, and writes approved tokens to `references/style-guide.md`. The fidelity receipt records sampled URLs, exact role values, fonts, weights, source URLs, and fallbacks. Public webfonts are verified after rendering.

For multiple clients, save onboarding results as named profiles under `~/.diagram-design/profiles/`. Put `profile: <slug>` in a project’s `.diagram-design` marker. Marker-selected profiles are read directly and must not overwrite the installed style guide. Use `/diagram-design:profile` in Claude Code, `/profile` in Factory Droid or Pi, or ask naturally in another compatible host. Saved profiles survive managed plugin updates; direct edits to the installed `style-guide.md` may not.

4. Choosing among the 39 diagram types

Choose a semantic pattern first when behavior, enforcement, state, or risk carries the meaning; otherwise choose the visual type directly. The 39 documented layouts are:

• **Systems and software:** architecture (components/connections), IT current-state (legacy landscape), sequence (messages over time), state machine (states/guards), ER/data model (entities), deployment (zones/hosts/artifacts), dependency graph (fan-in/cycles), UML class (classes/typed relations), and database schema (physical tables/FKs).
• **Flows and work:** flowchart (decision logic), swimlane (cross-functional handoffs), process (multi-actor workflow), data flow (role-scoped pipeline), DP integration (sources/core/consumers), Sankey (quantities splitting/merging), kanban (work by state), user journey (actions and sentiment), and story map (backbone and release slices).
• **Structure and strategy:** loop/flywheel, nested containment, tree, org chart, layer stack, Venn, pyramid/funnel, fishbone root-cause analysis, Wardley map, high-level clustered stack, medallion data tiers, and DP security matrix.
• **Quantitative views:** quadrant, radar/spider, polar, bar, treemap, line—including slopegraph and ridgeline uses—Gantt, and scatter—including bubble use.

Use a table, bullets, or prose instead when they communicate the same thing more clearly. Avoid diagrams for a list, a simple before/after, or one labeled shape. Most diagrams have minimal-light, minimal-dark, and full-editorial variants. A quadrant also has a consultant special.

5. Creating a diagram and applying the design system

A source-supported natural-language request is:

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

Other examples are “I need a quadrant showing Q2 projects by impact vs effort” and “Give me a sequence of a bearer call with token refresh on 401.” Before rendering, the skill states the type, any semantic pattern, size preset, and content cuts. It then loads the matching type reference and produces one standalone `.html` file.

From a checkout, start with a documented template:

cp skills/diagram-design/assets/template.html my-diagram.html
cp skills/diagram-design/assets/template-full.html my-diagram.html
cp skills/diagram-design/assets/template-motion.html my-diagram.html

The design system uses semantic tokens, no shadows, a maximum 6–10px radius, a 4px grid, and at most two accent elements. Human labels use Geist; technical ports, commands, and URLs use Geist Mono; titles and italic callouts use Instrument Serif. Connectors must be straight only when axis-aligned, otherwise rounded orthogonal paths. Labels need opaque masks and 6–10px clearance. Connectors cannot overlap, share attachment points, or pass behind unrelated nodes except the documented dashed-transit exception. Legends belong below the diagram. Default complexity is nine nodes and twelve arrows; type-specific limits in `SKILL.md` apply, and excess content should become overview and detail diagrams.

6. Accessibility, primitives, semantic patterns, and motion

Every meaningful inline SVG must have `role="img"`, an `aria-labelledby` that resolves to both `<title>` and `<desc>`, and a `<title>` as its first child. IDs use the file/variant slug, such as `loop-dark-title`; bare `title` and `desc` IDs are rejected. The title is a short subject name, while the description explains the content rather than narrating geometry. Decorative SVGs use `aria-hidden="true"`.

Optional primitives add: editorial annotation callouts with italic serif text and dashed leaders; a sketchy displacement treatment for essays; 55 documented monochrome IT/cloud icons that inherit `currentColor`; and terminal/CLI-window styling for developer-tool posts. Terminal styling is not brand-tokenized. Icons can be regenerated with:

python scripts/build-icons.py

Seven semantic patterns cover fan-in queues, repeated stage slots, unstructured input becoming a durable artifact, paired policy traces, secure paved roads, governance catalogs, and compensating security layers. They add behavior-specific primitives without creating extra visual types.

Motion is optional. Modes are `none`, `reveal`, `step`, and `loop`; `none` is the default. Animated files must preserve a complete no-JavaScript first frame, deterministic timing, print/export states, reduced-motion behavior, and the exact reviewed controller from `template-motion.html`. Reduced-motion mode shows the completed static state and disables or hides playback.

7. Redrawing draw.io and Mermaid sources

The import feature extracts structure and redraws it; it does not preserve source coordinates, palette, fonts, renderer spacing, or connector routing. It preserves components, relationships, grouping, and direction, and ends with a fidelity ledger listing retained, merged, collapsed, and dropped content.

Claude Code command examples:

/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

Draw.io support covers `.drawio`, `.drawio.xml`, embedded `.drawio.png`, embedded `.drawio.svg`, and compressed payloads. Mermaid support covers `.mmd`, `.mermaid`, and fenced Mermaid blocks in Markdown. Parsing is text-only: source content is treated as untrusted data and is not rendered, executed, fetched, or followed.

Set four dials before drawing: format (`html`, `svg`, `png`, `html+png`); size (`doc-inline`, `doc-wide`, slide, social, print, or `fit` presets); detail (`faithful` up to 24 zoned nodes, `balanced` up to 12, or `simplified` up to 7); and audience (`engineer`, `mixed`, `executive`). Audience changes wording, not item count. Import must not invent source components or silently omit them.

8. Gallery, export, diagnostics, and output checks

Open the local gallery from a checkout with one of the documented platform commands:

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

The gallery provides light, dark, and full-editorial examples. Export is manual and runs only when requested. In 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

Pi uses the same forms under `/export-diagram`. SVG export extracts the SVG and injects Google Fonts for standalone use. PNG export rasterizes with Playwright at 2× by default; its documented one-time setup is:

pip install playwright && playwright install chromium

Exports contain only the diagram, not full-editorial headers or cards. For animated HTML, export `?motion=static`, wait for `document.fonts.ready`, and confirm `data-frame="static"`; use a step query only when an intermediate frame was requested.

Check generated output from the installed skill directory:

python3 scripts/self_check.py <file>

`OK` means the packaged accessibility, single-file safety, and basic motion checks passed. Pi also loads `/doctor`, an environment-diagnostics prompt. Repository documentation describes doctor verification as checking environment expectations, required scripts, and routing wiring.

9. Contributing and repository validation

For non-trivial behavior, type, or import changes, open an issue first; use a branch, keep one concern per pull request, and use Python 3.10 or newer. Every PR must bump synchronized Claude and Codex plugin versions:

python3 scripts/bump-plugin-version.py
python3 scripts/bump-plugin-version.py --minor
python3 scripts/bump-plugin-version.py --major

Use only the bump appropriate to the change. Examples start from the nearest template, follow the matching type reference, fill slugged title/description IDs, pass the taste gate, and enter the gallery. Check one example with:

python3 scripts/lint-skin.py skills/diagram-design/assets/example-my-type.html

The documented gates cover package/version integrity and strict Claude schema validation; accessible SVGs; semantic routing; animation structure and controller integrity; source skin and rendered layout; sequence grammar; draw.io and Mermaid extraction; doctor wiring; documentation/gallery/reference synchronization; screenshot freshness; installed output self-check behavior; label geometry; treemap, polar, Sankey, dumbbell, slopegraph, ridgeline, and bubble quantitative accuracy; and generated icons. `lint-render.py` uses pinned Playwright/Chromium, blocks network by default, and compares authored versus overflow-released pixels to detect clipping.

For icon changes, edit vendored sources, preserve third-party license provenance, then run:

python3 scripts/build-icons.py
git diff --exit-code -- skills/diagram-design/assets/icons.html skills/diagram-design/references/primitive-icons.md

Do not hand-edit generated icon outputs. Import changes must keep extractor, verifier, references, commands, and Pi prompts synchronized.

10. Limits, security, and evidence cautions

The skill produces design artifacts and guidance; visual correctness still needs human review. Its default complexity limits deliberately reject dense single-canvas diagrams. Brand extraction may adjust low-contrast colors, and network-loaded Google Fonts are the only documented external output dependency. PNG export and rendered linting require Playwright/Chromium. Managed updates may overwrite direct style-guide edits, so profiles or an editable checkout are safer for persistent customization.

The supplied sources contain inconsistencies worth noting. Repository metadata says “38” types, while the README and skill document 39. `SECURITY.md` says the project does not publish versioned releases, while native manifests contain version 2.6.7 and the README discusses version bumps. The skill metadata says 2.6. Treat the latest `main` commit as the documented security-support channel rather than assuming older commits or forks receive fixes.

Report suspected vulnerabilities privately through GitHub private vulnerability reporting at `https://github.com/cathrynlavery/diagram-design/security/advisories/new`. Include the affected file or workflow, impact, reproduction conditions, and a possible mitigation, but no secrets or personal data. Do not publish the report before coordinated disclosure, and avoid accessing, modifying, or deleting others’ data.

This manual is limited to the supplied first-party files and metadata. Many referenced type guides, import/export specifications, scripts, templates, CI configuration, and command bodies were named but not provided, so their implementation details were not independently inspected.