{"id":23789,"date":"2008-06-06T16:19:48","date_gmt":"2008-06-06T16:19:48","guid":{"rendered":"https:\/\/scannn.com\/cathrynlavery-diagram-design-38-editorial-diagram-types-for-claude-code-codex-and-pi-self-contained-html-svg-no-shadows-no-mermaid-slop-%c2%b7-github\/"},"modified":"2008-06-06T16:19:48","modified_gmt":"2008-06-06T16:19:48","slug":"cathrynlavery-diagram-design-38-editorial-diagram-types-for-claude-code-codex-and-pi-self-contained-html-svg-no-shadows-no-mermaid-slop-%c2%b7-github","status":"publish","type":"post","link":"https:\/\/scannn.com\/lv\/cathrynlavery-diagram-design-38-editorial-diagram-types-for-claude-code-codex-and-pi-self-contained-html-svg-no-shadows-no-mermaid-slop-%c2%b7-github\/","title":{"rendered":"cathrynlavery\/diagram-design: 38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop. \u00b7 GitHub"},"content":{"rendered":"\n
\n

Editorial diagrams your designer won’t hate.<\/strong><\/p>\n

<\/a><\/p>\n

\"Content<\/a><\/p>\n

\"The<\/a><\/p>\n

New in 2.0 \u2014 the Loop: flywheels with a shared-memory hub. The dashed lines are the write-backs.<\/em><\/p>\n

New in 2.3: semantic system patterns and optional accessible motion, while static output stays the default.<\/em><\/p>\n

New in 2.5.10: ten more layout grammars \u2014 Sankey, fishbone, Wardley map, kanban, user journey, deployment, dependency graph, UML class, story map, and database schema.<\/em><\/p>\n

39 editorial diagram types for Claude Code, Codex, Factory Droid, Pi, and Agent Skills-compatible hosts. Self-contained HTML + SVG. No shadows. No Mermaid slop. Semantic patterns describe behavior separately from layout, so a queue, policy trace, or trust boundary can use the nearest existing type without expanding the type count. Static HTML remains the default; optional motion is available for ordered explanations. The skill also redraws draw.io or Mermaid sources at a chosen format, size, and detail level.<\/p>\n

No Figma. No generic rounded boxes. No 30-minute color-picking sessions.<\/p>\n\n

I write at littlemight.com<\/a> (and run BestSelf.co<\/a> on the side). Every time I needed a diagram \u2014 an architecture sketch, a flowchart, a pyramid of what matters most \u2014 I’d ask Claude and get back a generic rounded-box thing that looked nothing like the rest of the site. I’d either fight with Figma for 30 minutes or just skip the diagram.<\/p>\n

So I built a Claude Code skill for it. Thirty-nine visual types, editorial quality, matches your brand in 60 seconds by reading your website.<\/p>\n

\n

The highest-quality move is usually deletion.<\/em> Every node earns its place. The accent color is reserved for the 1\u20132 things the reader should look at first. Target density: 4\/10.<\/p>\n<\/blockquote>\n\n

All 39 visual types ship in three static variants: minimal light, minimal dark, and full-editorial. Open any of them directly in a browser. There is no build step, JavaScript, or external image dependency.<\/p>\n

<\/p>\n

The v2.5.10 release added the final ten types above. Compare their light, dark, and full-editorial variants in the 30-variant contact sheet<\/a>.<\/p>\n

Browse the live gallery:<\/strong> cathrynlavery.github.io\/diagram-design<\/a> \u2014 or open skills\/diagram-design\/assets\/index.html<\/code><\/a> locally to flip through all 39 diagrams with light \/ dark \/ full-editorial tabs.<\/p>\n\n

Claude Code:<\/strong><\/p>\n

\n
\/plugin marketplace add cathrynlavery\/diagram-design\n\/plugin install diagram-design@diagram-design\n<\/code><\/pre>\n<\/div>\n
Then enable updates once: run \/plugin<\/code>, open Marketplaces<\/strong>, select diagram-design<\/strong>, and choose Enable auto-update<\/strong>. Claude Code disables auto-update by default for third-party marketplaces; after this toggle, it refreshes the marketplace and installed plugin in the background after startup. Run \/reload-plugins<\/code> when prompted, or let the next session load the update.<\/p>\n
Codex:<\/strong><\/p>\n
\n
codex plugin marketplace add cathrynlavery\/diagram-design\ncodex plugin add diagram-design@diagram-design<\/pre>\n<\/div>\n
Codex refreshes configured Git marketplaces at startup. To fetch immediately, run codex plugin marketplace upgrade diagram-design<\/code> and start a new session.<\/p>\n
Factory Droid:<\/strong><\/p>\n
\n
droid plugin marketplace add https:\/\/github.com\/cathrynlavery\/diagram-design\ndroid plugin install diagram-design@diagram-design --scope user<\/pre>\n<\/div>\n
Droid tracks Git plugins by commit rather than the manifest’s display version. To fetch a merged update, run droid plugin marketplace update diagram-design<\/code>, then droid plugin update diagram-design@diagram-design --scope user<\/code>, and start a new session.<\/p>\n
Claude Cowork (organization marketplace):<\/strong> Organization GitHub marketplaces currently require a private or internal repository, so first mirror this public repository into one owned by your organization. In Organization settings \u2192 Plugins<\/strong>, choose Add plugin \u2192 GitHub<\/strong>, connect that mirror, and enable Sync automatically<\/strong> from the marketplace menu. Automatic sync runs when a pull request containing a plugin version bump is merged to the mirror’s default branch; direct pushes do not trigger the webhook. Install Diagram Design from the resulting organization marketplace.<\/p>\n
Pi:<\/strong><\/p>\n
\n
pi install https:\/\/github.com\/cathrynlavery\/diagram-design<\/pre>\n<\/div>\n
Run \/reload<\/code> in an open Pi session. Pi makes the skill available for matching diagram requests; use \/skill:diagram-design<\/code> to invoke it explicitly. Pi also loads the \/export-diagram<\/code>, \/import-mermaid<\/code>, \/profile<\/code>, and \/doctor<\/code> prompt templates. The unpinned Git install is intentional: Pi has no automatic package refresh, so run pi update --extensions<\/code> to pull merged updates.<\/p>\n
Kiro:<\/strong> Import the Agent Skill from the repository subdirectory URL:<\/p>\n
\n
https:\/\/github.com\/cathrynlavery\/diagram-design\/tree\/main\/skills\/diagram-design\n<\/code><\/pre>\n<\/div>\n
Kiro copies imported skills into .kiro\/skills\/<\/code> for a workspace or ~\/.kiro\/skills\/<\/code> globally, so re-import the URL to pick up updates. Custom agents that declare resources should include skill:\/\/diagram-design\/**\/SKILL.md<\/code>.<\/p>\n
OpenCode:<\/strong> Copy or symlink skills\/diagram-design\/<\/code> to .opencode\/skills\/diagram-design<\/code> in a project or ~\/.config\/opencode\/skills\/diagram-design<\/code> globally. OpenCode has no Diagram Design marketplace package; copied installs update only when you replace the directory from a newer checkout.<\/p>\n
\n
One-time migration:<\/strong> an existing standalone npx skills add<\/code> copy will not start following the Codex marketplace automatically. Remove that standalone copy, then use the Codex marketplace commands above. Likewise, uninstall a personal Cowork copy and reinstall Diagram Design from your organization’s marketplace. Future marketplace version bumps then flow through each client’s native update path.<\/p>\n<\/blockquote>\n
Managed installs are convenient, but changes to references\/style-guide.md<\/code> may be replaced by package updates. Saved profiles in ~\/.diagram-design\/profiles\/<\/code> survive updates, and projects with a .diagram-design<\/code> marker are unaffected. Clone the repo and install the local path if you plan to customize the working style guide directly:<\/p>\n
\n
git clone git@github.com:cathrynlavery\/diagram-design.git ~<\/span>\/code\/diagram-design\n\n#<\/span> Pi: register the checkout as a local package<\/span>\npi install ~<\/span>\/code\/diagram-design\n\n#<\/span> Claude Code: symlink the inner skill<\/span>\nln -s ~<\/span>\/code\/diagram-design\/skills\/diagram-design ~<\/span>\/.claude\/skills\/diagram-design\n\n#<\/span> Other Agent Skills hosts: create only the roots you use<\/span>\nmkdir -p ~<\/span>\/.agents\/skills ~<\/span>\/.cursor\/skills ~<\/span>\/.cline\/skills ~<\/span>\/.kiro\/skills ~<\/span>\/.config\/opencode\/skills\nln -s ~<\/span>\/code\/diagram-design\/skills\/diagram-design ~<\/span>\/.agents\/skills\/diagram-design\nln -s ~<\/span>\/code\/diagram-design\/skills\/diagram-design ~<\/span>\/.cursor\/skills\/diagram-design\nln -s ~<\/span>\/code\/diagram-design\/skills\/diagram-design ~<\/span>\/.cline\/skills\/diagram-design\nln -s ~<\/span>\/code\/diagram-design\/skills\/diagram-design ~<\/span>\/.kiro\/skills\/diagram-design\nln -s ~<\/span>\/code\/diagram-design\/skills\/diagram-design ~<\/span>\/.config\/opencode\/skills\/diagram-design<\/pre>\n<\/div>\n
The shared skill lives at skills\/diagram-design\/<\/code>. Pi discovers it through the repo’s standard skills\/<\/code> package directory; Claude Code, Codex, Factory Droid, and other Agent Skills-compatible tools use the same files.<\/p>\n\n
\n
Onboarding \u2014 make it look like your<\/em> brand<\/h2>\n
<\/svg><\/a><\/div>\n
The whole point: ship editorial-quality diagrams in your<\/strong> colors and typography, not a generic template.<\/p>\n
Out of the box, diagrams render in a clean jet-black + atomic-tangerine<\/strong> palette (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines). Good enough to screenshot straight away. But 60 seconds of onboarding is better \u2014 the skill will pull your brand from your website and apply it across every diagram.<\/p>\n
\n
You:     \"onboard diagram-design to https:\/\/yoursite.com\"\nAgent:   \u2192 fetches the homepage\n         \u2192 extracts the dominant palette + font stack\n         \u2192 maps detected values to semantic roles:\n             paper, ink, muted, accent, link\n         \u2192 shows a proposed diff\n         \u2192 writes your tokens to references\/style-guide.md\nYou:     \"yes, apply it\"\n<\/code><\/pre>\n<\/div>\n
Every new diagram now uses your colors. Your website’s paper color becomes the diagram background. Your CTA color becomes the focal accent. Your body font stack becomes the node label family.<\/p>\n
Brand matching also emits a fidelity receipt: sampled URLs, exact color roles, font families and weights, font source URLs, and any fallback. Public site fonts are used directly and verified after rendering rather than silently replaced with generic system fonts.<\/p>\n
<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n
Detected from your site<\/th>\nBecomes<\/th>\n<\/tr>\n<\/thead>\n
<body><\/code> background<\/td>\npaper<\/code> token<\/td>\n<\/tr>\n
Primary text color<\/td>\nink<\/code> token<\/td>\n<\/tr>\n
Secondary \/ caption text<\/td>\nmuted<\/code> token<\/td>\n<\/tr>\n
Cards or containers<\/td>\npaper-2<\/code> token<\/td>\n<\/tr>\n
Most-used brand color (CTA, link, heading)<\/td>\naccent<\/code> token<\/td>\n<\/tr>\n
<h1><\/code> font family<\/td>\ntitle<\/code> font<\/td>\n<\/tr>\n
<body><\/code> font family<\/td>\nnode-name<\/code> font<\/td>\n<\/tr>\n
<code><\/code> \/ <pre><\/code> font<\/td>\nsublabel<\/code> font<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
<\/markdown-accessiblity-table><\/p>\n
\n
Contrast checks happen automatically<\/h3>\n
<\/svg><\/a><\/div>\n
Before writing tokens, the skill verifies WCAG AA contrast on ink<\/code> over paper<\/code>. If your site has a color that fails contrast at diagram sizes (9\u201312px), it proposes an adjusted value and explains why.<\/p>\n
Every diagram template gives the inline SVG an accessible name and description: role=\"img\"<\/code>, a resolving aria-labelledby<\/code>, and first-child <title><\/code> \/ <desc><\/code> 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.<\/p>\n
Prefer to set tokens by hand? Open skills\/diagram-design\/references\/style-guide.md<\/code><\/a> and edit the table. Everything downstream reads from there \u2014 all 39 diagrams, the annotation primitive, and the gallery all inherit semantic role names (accent<\/code>, not #eb6c36<\/code>).<\/p>\n
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<\/code> has been customized. If not, it pauses and asks:<\/p>\n
\n
“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?”<\/em><\/p>\n<\/blockquote>\n
See skills\/diagram-design\/references\/onboarding.md<\/code><\/a> for the full spec.<\/p>\n
\n
Working with multiple clients<\/h3>\n
<\/svg><\/a><\/div>\n
Onboard a brand once, save the result as a named profile, then add a .diagram-design<\/code> marker containing profile: <slug><\/code> to each client project. Marker projects read ~\/.diagram-design\/profiles\/<slug>.md<\/code> directly, so parallel workspaces can use different brands without overwriting a shared installed style-guide.md<\/code>.<\/p>\n
The profile library is shared across Claude Code, Codex, Factory Droid, and Pi. Use \/diagram-design:profile<\/code> in Claude Code, \/profile<\/code> in Factory Droid or Pi, or ask in natural language in any host. See profiles.md<\/code><\/a> for the storage, marker, and recovery contract.<\/p>\n\n
\n
#<\/span> From a cloned checkout, open the gallery to see all 39 diagrams<\/span>\nopen skills\/diagram-design\/assets\/index.html       #<\/span> macOS<\/span>\nxdg-open skills\/diagram-design\/assets\/index.html  #<\/span> Linux<\/span>\n\n#<\/span> In Claude Code, Codex, Factory Droid, or Pi, ask:<\/span>\n#<\/span> \"Make me an architecture diagram of my app: frontend, backend, database, Redis cache.\"<\/span>\n#<\/span> \"I need a quadrant showing Q2 projects by impact vs effort.\"<\/span>\n#<\/span> \"Give me a sequence of a bearer call with token refresh on 401.\"<\/span>\n#<\/span> (branching refresh uses the ALT combined-fragment grammar in type-sequence.md;<\/span>\n#<\/span>  see skills\/diagram-design\/assets\/example-sequence-oauth.html \u2014 not a full authorize-code handshake)<\/span><\/pre>\n<\/div>\n
Operator recipes for editable installs, first diagrams, brand setup, import, export, validation, Windows junctions, and reusable prompts live in docs\/cookbook.md<\/code><\/a>.<\/p>\n
Your agent will pick the right type, build the HTML, and save it. You can also start from a template directly:<\/p>\n
\n
cp skills\/diagram-design\/assets\/template.html my-diagram.html        #<\/span> minimal light<\/span>\ncp skills\/diagram-design\/assets\/template-full.html my-diagram.html   #<\/span> editorial with summary cards<\/span>\ncp skills\/diagram-design\/assets\/template-motion.html my-diagram.html #<\/span> optional accessible motion<\/span><\/pre>\n<\/div>\n
\n
Semantic patterns and optional motion<\/h3>\n
<\/svg><\/a><\/div>\n
When behavior matters, the skill chooses a semantic pattern first and a visual type second. The eight 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, and traceable block decomposition. Each pattern defines its triggers, primitives, budget, anti-patterns, static fallback, and nearest visual type in semantic-patterns.md<\/code><\/a>.<\/p>\n
Motion is optional and does not create another visual type. animation.md<\/code><\/a> defines none<\/code>, reveal<\/code>, step<\/code>, and loop<\/code> 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<\/code>; arbitrary or modified inline scripts, remote assets, CSS imports, and executable HTML attributes are rejected. The default is none<\/code>: ordinary output remains static and script-free. example-policy-trace-animated.html<\/code><\/a> is the self-contained interactive example.<\/p>\n\n
\n
Import from draw.io or Mermaid<\/h2>\n
<\/svg><\/a><\/div>\n
Already have diagrams in draw.io \/ diagrams.net or Mermaid? Point the skill at the source and it redraws<\/strong> them \u2014 same content, this design system, at whatever the destination needs.<\/p>\n
\"Redrawn<\/a><\/p>\n
A 12-node draw.io file redrawn at balanced<\/code> detail for a blog post. The source’s six pastel fills became one accent; its hand-dragged coordinates became a 4px grid.<\/em><\/p>\n
\n
\/diagram-design:import-drawio platform.drawio\n\/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive\n\/diagram-design:import-drawio platform.drawio --detail=faithful --format=png --page=all\n\/diagram-design:import-mermaid README.md --diagram=all\n\/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified\n<\/code><\/pre>\n<\/div>\n
Or just ask: “redraw this drawio file for my deck”<\/em>, “make this Mermaid block editorial”<\/em>, or “\u3053\u306e Mermaid \u3092\u30b9\u30e9\u30a4\u30c9\u7528\u306b\u304d\u308c\u3044\u306b\u3057\u3066”<\/em>.<\/p>\n
Reads the common containers draw.io writes \u2014 .drawio<\/code>, .drawio.xml<\/code>, .drawio.png<\/code> (embedded diagram), and .drawio.svg<\/code> \u2014 including compressed payloads that look like base64 garbage in an editor.
\nFor Mermaid, it accepts .mmd<\/code>, .mermaid<\/code>, and one or more fenced mermaid<\/code> blocks in Markdown. It parses text only: no rendering, JavaScript, browser, network, or followed click targets.<\/p>\n
The point isn’t conversion, it’s fitting the output to where it’s going<\/strong>. Same source file, three different diagrams:<\/p>\n
<\/p>\n\n\n\n\n\n\n\n\n
Dial<\/th>\nOptions<\/th>\nWhat it changes<\/th>\n<\/tr>\n<\/thead>\n
Format<\/strong><\/td>\nhtml<\/code> \u00b7 svg<\/code> \u00b7 png<\/code> \u00b7 html+png<\/code><\/td>\nThe deliverable. SVG for Figma, PNG for slides, HTML for the web.<\/td>\n<\/tr>\n
Size<\/strong><\/td>\ndoc-inline<\/code> \u00b7 doc-wide<\/code> \u00b7 slide-16x9<\/code> \u00b7 slide-4x3<\/code> \u00b7 social-og<\/code> \u00b7 social-square<\/code> \u00b7 print-a4-landscape<\/code> \u00b7 print-letter-landscape<\/code> \u00b7 fit<\/code><\/td>\nThe viewBox<\/code> and the type ramp<\/strong> \u2014 a projected slide gets 16px node names, not 12px.<\/td>\n<\/tr>\n
Detail<\/strong><\/td>\nfaithful<\/code> (\u226424 nodes, zoned) \u00b7 balanced<\/code> (\u226412) \u00b7 simplified<\/code> (\u22647)<\/td>\nHow much of the source survives, via a fixed degrade ladder \u2014 decorations, then duplicates, then leaf clusters, then infrastructure.<\/td>\n<\/tr>\n
Audience<\/strong><\/td>\nengineer<\/code> \u00b7 mixed<\/code> \u00b7 executive<\/code><\/td>\nThe wording<\/em>, not the count. Auth Service \/ JWT \u00b7 RS256 \u00b7 :8443<\/code> \u2192 Auth Service \/ token check<\/code> \u2192 Sign-in<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
<\/markdown-accessiblity-table><\/p>\n
Every import ends with a fidelity ledger<\/strong> \u2014 what got merged, collapsed, or dropped. You know the source; you’d notice anyway.<\/p>\n
\n
Detail: balanced \u00b7 12 source nodes \u2192 8 drawn\nCollapsed: \"Token valid?\" decision \u2192 edge label on Gateway \u2192 Auth\nDropped:   1 sticky note (\"legacy path, to be retired\") \u2014 unconnected in source\nKept in full: the request path (Web\/Mobile \u2192 Gateway \u2192 Orders \u2192 Postgres)\n<\/code><\/pre>\n<\/div>\n
What never carries over: source or renderer coordinates, source palette, source fonts, draw.io’s diagonal connector spaghetti, or Mermaid’s automatic layout. What always does: components, relationships, grouping, and direction. See references\/import-drawio.md<\/code><\/a>, references\/import-mermaid.md<\/code><\/a>, and references\/output-spec.md<\/code><\/a>.<\/p>\n\n
Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. Use the slash command for your agent:<\/p>\n
Pi:<\/strong><\/p>\n
\n
\/export-diagram path\/to\/diagram.html\n\/export-diagram path\/to\/diagram.html --svg-only\n\/export-diagram path\/to\/diagram.html --png-only --scale=3\n\/export-diagram path\/to\/diagram.html --registry\n<\/code><\/pre>\n<\/div>\n
Claude Code:<\/strong><\/p>\n
\n
\/diagram-design:export-diagram path\/to\/diagram.html\n\/diagram-design:export-diagram path\/to\/diagram.html --svg-only\n\/diagram-design:export-diagram path\/to\/diagram.html --png-only --scale=3\n\/diagram-design:export-diagram path\/to\/diagram.html --registry\n<\/code><\/pre>\n<\/div>\n
Or just ask in natural language:<\/p>\n
\n
\"Export this diagram as SVG and PNG.\"\n\"Save my-diagram.html as PNG.\"\n<\/code><\/pre>\n<\/div>\n