cathrynlavery/diagram-design installation guide

Install Diagram Design for Claude Code on macOS Tahoe (Apple silicon)

What you are installing

**Diagram Design** is an MIT-licensed, third-party **Claude Code plugin and Agent Skill**. It extends Claude Code through:

• **Context injection:** Claude Code loads the packaged `SKILL.md` instructions when a diagram request matches the skill.
• **Tool/command surface:** the plugin includes commands for exporting diagrams, importing draw.io and Mermaid sources, managing brand profiles, and checking the environment.

Its primary Claude Code installation mode is therefore **`claude_extension`**, with **low setup effort** for the basic managed installation. It is not Claude Code itself and does not replace the Claude Code host.

The repository says it can create 39 types of editorial diagrams as self-contained HTML with inline SVG and CSS. It can also redraw supported draw.io or Mermaid input, apply brand colors and typography, and optionally export SVG or PNG.

Before you begin

You need a working Claude Code installation and a Claude Code session in which slash commands can be entered. The supplied repository files do **not** document how to install Claude Code itself, do not state a minimum Claude Code version, and do not explicitly certify compatibility with macOS Tahoe or Apple silicon. For that reason, this guide does not invent a Claude Code installation command or claim a tested Tahoe compatibility level.

The basic plugin installation does not document Homebrew, Rosetta, Node.js, Python, or a compilation step as prerequisites. Do not install those merely to add the plugin. Python and Playwright are relevant only to optional operations described later.

This is a third-party marketplace, not Anthropic’s official plugin collection. The source repository is public at:

<https://github.com/cathrynlavery/diagram-design>

Step 1: Open Claude Code

Open Claude Code on your Mac and start a normal session. Enter the following commands **inside Claude Code**, one at a time. Do not paste them into macOS Terminal: they are Claude Code slash commands, not shell commands.

First, register the repository as a plugin marketplace:

/plugin marketplace add cathrynlavery/diagram-design

Wait for that operation to finish. Then install the plugin from the newly registered marketplace:

/plugin install diagram-design@diagram-design

These are the complete first-party installation commands for the recommended managed Claude Code installation. You do not need to clone the repository for this route.

Step 2: Enable automatic updates

The repository states that Claude Code disables automatic updates by default for third-party marketplaces. Enabling updates is a one-time user-interface step:

1. In Claude Code, run:

/plugin

1. Open **Marketplaces**.
2. Select **diagram-design**.
3. Choose **Enable auto-update**.

After that toggle, Claude Code can refresh the marketplace and installed plugin in the background after startup. If Claude Code prompts you to reload plugins, run:

/reload-plugins

If there is no prompt, the repository says you may let the next session load the update instead.

The repository’s security policy says security fixes are applied to the latest commit on the `main` branch and that older commits and forks are not maintained as separate security-support channels. Enabling updates is therefore the simplest documented way to follow the maintained branch through the marketplace mechanism.

Step 3: Confirm that the skill responds

After installation—or after reloading—give Claude Code a diagram request. The README supplies this example:

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

Other source-provided examples are:

I need a quadrant showing Q2 projects by impact vs effort.

Give me a sequence of a bearer call with token refresh on 401.

The skill is designed to select the relevant diagram type, explain its plan, create a self-contained HTML file, and save it. A routine request should load the main skill instructions and the reference for the chosen diagram type rather than loading all 39 type references.

On first use in a project, the skill may stop before drawing because its default style guide is still active. That pause is expected, not an installation failure.

Step 4: Complete first-use styling

The shipped default uses a white-smoke background, dark ink, and an atomic-tangerine accent. For a branded project, the skill asks whether you want to customize the style before producing the first diagram.

To start the repository’s documented website onboarding flow, use a request in this form, replacing the sample address with your public website:

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

The documented flow has the agent fetch the homepage, propose semantic color and font tokens, show a diff, and wait for approval before writing the style guide. It also reports sampled URLs, selected colors, font families and weights, font-source URLs, and fallbacks. The skill checks text/background contrast before accepting tokens.

You may instead choose the default style, provide tokens manually, load a saved profile, or extract styling from a local folder or installed skill when the first-run prompt offers those choices.

Brand onboarding involves fetching the website you provide. Ordinary generated output is self-contained, although the documented design system permits Google Fonts. Do not provide a private URL or sensitive material unless you understand how your Claude Code environment handles that content.

Step 5: Verify the generated file

The expected primary result is one `.html` file containing embedded CSS and inline SVG. Static output is the default. The repository says such files can be opened in a modern browser and should retain their meaning without JavaScript.

In Finder, locate the generated HTML file and double-click it to open it in your default browser. Check that:

• the title and labels are readable;
• the requested components and relationships are present;
• only one or two elements receive the accent treatment;
• the page uses the selected default or branded style;
• the result does not depend on external images.

The skill’s generated SVG is intended to include an accessible title and description. Optional motion should preserve a complete static state and respect reduced-motion behavior.

Optional: import an existing diagram

The Claude Code plugin documents namespaced commands for draw.io and Mermaid imports. For example:

/diagram-design:import-drawio platform.drawio

/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified

The import workflow extracts structure and redraws it; it does not preserve the source renderer’s coordinates, fonts, or palette. Supported evidence includes common draw.io containers, `.mmd` and `.mermaid` files, and fenced Mermaid blocks in Markdown. The repository says Mermaid input is parsed as text without rendering it, executing JavaScript, using a browser, following click targets, or making network requests.

Optional: export SVG or PNG

To export an existing generated diagram from Claude Code, use a documented command such as:

/diagram-design:export-diagram path/to/diagram.html

For SVG only:

/diagram-design:export-diagram path/to/diagram.html --svg-only

PNG export uses Playwright and Chromium. Only if you request PNG export and the dependency is missing, the README documents this one-time setup command for macOS Terminal:

pip install playwright && playwright install chromium

This dependency is **not required for the basic plugin installation or normal HTML output**. The supplied files do not document a macOS Tahoe-specific Python setup, so if `pip` is unavailable, do not substitute an invented package-manager command; use HTML/SVG output or consult first-party Playwright and Python documentation separately.

Updating and troubleshooting

For normal updates, keep auto-update enabled and start a new Claude Code session. If Claude Code explicitly asks for a plugin reload, use:

/reload-plugins

If the test request triggers the first-run style question, installation succeeded; answer the question to continue. If no Diagram Design behavior appears, revisit `/plugin`, confirm the **diagram-design** marketplace and plugin are present, and reload when prompted. The repository does not provide documented cache-clearing, manual repair, or uninstall commands, so this guide does not recommend any.

The repository also describes an editable installation using an SSH clone and a symbolic link. That route is intended for people modifying the working style guide directly and assumes an SSH-capable GitHub setup that the supplied files do not explain. For a layperson who only wants to use the plugin, the managed marketplace installation above is the supported, simpler path.

For suspected security problems, do not open a public issue. The repository requests private reports through GitHub’s private vulnerability reporting page:

<https://github.com/cathrynlavery/diagram-design/security/advisories/new>

At this point, Diagram Design is installed, update handling is configured, and Claude Code should be ready to create or redraw editorial diagrams.