Generate production-grade engineering design diagrams (architecture, sequence, delta, drift) as
self-contained dark-themed HTML files with accessible inline SVG. Grounds every diagram in real
repo topology via DCI — package manifests, docker-compose, k8s, terraform, import graph. Four
modes: generate from a live repo, diff a PR, trace a stack into a sequence diagram, or watch for
drift against a fingerprint. Semantic OKLCH palette; Mermaid fallback for large graphs.
Use when visualizing system architecture, reviewing a PR for structural change, diagnosing an
incident from a trace, onboarding to a codebase, or detecting architectural drift.
Trigger with "/design:generate", "/design:diff", "/design:trace", "/design:watch", "draw the
architecture", "diagram this PR", "engineer design diagram", or "architecture diagram".
Generate production-grade engineering design diagrams (architecture, sequence, delta, drift) as
self-contained dark-themed HTML files with accessible inline SVG. Grounds every diagram in real
repo topology via DCI — package manifests, docker-compose, k8s, terraform, import graph. Four
modes: generate from a live repo, diff a PR, trace a stack into a sequence diagram, or watch for
drift against a fingerprint. Semantic OKLCH palette; Mermaid fallback for large graphs.
Use when visualizing system architecture, reviewing a PR for structural change, diagnosing an
incident from a trace, onboarding to a codebase, or detecting architectural drift.
Trigger with "/design:generate", "/design:diff", "/design:trace", "/design:watch", "draw the
architecture", "diagram this PR", "engineer design diagram", or "architecture diagram".
Generates production-grade engineering design diagrams as single-file HTML with inline SVG, grounded in real repository topology. Credit: design palette + arrow-masking pattern inspired by Cocoon AI's architecture-diagram-generator (MIT). See THIRD_PARTY_LICENSES.md.
Overview
Most diagramming tools produce pretty pictures disconnected from reality. This skill does the opposite: it reads the actual repo (package manifests, docker-compose, k8s, terraform, import graph) and emits a diagram that reflects the real system. It also knows how the system changed — PR-diff mode highlights structural deltas, trace mode turns a stack/log into a sequence diagram, and drift mode detects when the architecture has wandered from a stored fingerprint.
Four modes share a common pipeline (DCI grounding → node/edge graph → template fill → fingerprint write). Output is a single self-contained HTML file that opens in any browser, plus a Mermaid text block for copy-paste into docs. Dark theme with semantic OKLCH color coding by component role. Accessible by default (ARIA, <title>/<desc>, reduced-motion, keyboard navigation).
Layout Philosophy — pick the shape before you draw
Dense technical systems want to render wide. This is how Anthropic docs, Linear docs, and Vercel architecture pages present multi-component systems: a sticky left rail for context (nav, invariants, legend) and a generous main column for the diagram itself. Mimic that pattern when your content is dense, and use the simpler single-SVG hero when it isn't.
Two supported output shapes, one decision up front:
Shape
Use when
Template
Single-SVG hero (classic)
≤8 nodes, one-screen takeaway, no sub-grouping, no accompanying explanation needed
Widescreen-first for docs-layout. Target min-width: 1024px; do not add mobile breakpoints for docs-layout output — it's architecture documentation, not a landing page. The diagram needs horizontal breathing room. On narrow viewports the diagram stage scrolls horizontally inside its card while the sidebar stays visible.
in docs-layout mode: HTML/CSS for all node cards (easier to maintain, free hover states, content edits don't trigger collision math), SVG overlay positioned absolutely the node grid for arrows only. Arrows are the one place SVG still wins — fixed pixel coords, clean arrowheads, no brittle CSS-line math. Pure-SVG stays the default for the single-hero shape because the payoff of HTML flex doesn't materialize at small node counts.
Hybrid rendering
over
Layout-decision signal: if during Step 2 the graph has any of — (a) more than one semantic lane/plane, (b) subcomponent lists of 4+ items per node, (c) the user asks for "docs page" / "architecture page" / references Anthropic/Linear/Vercel docs as exemplars — pick docs-layout. Otherwise stay with single-SVG.
See docs-layout.md for the full widescreen spec (grid geometry, design tokens, sidebar anatomy, arrow overlay placement, hover states).
Prerequisites
Git repository (for generate/diff/watch modes)
At least one of: package.json, pyproject.toml, Cargo.toml, go.mod, docker-compose.yml, k8s/*.yaml, terraform/*.tf
Sequence diagram with lifelines and message arrows
watch
—
none — markdown drift report
Markdown only; no HTML render
For single-SVG hero: fill placeholders per drawing-rules.md — color palette, SVG arrow-masking, z-order, 40px spacing, dashed boundaries, legend placement. Keep the grid <pattern>, #020617 canvas, pulsing header dot (with reduced-motion guard).
For docs-layout page: fill placeholders per docs-layout.md — GitHub-inspired palette (#0f1117 / #161b22 / #1c2128), Inter + JetBrains Mono, 260px sticky sidebar, fixed-pixel node stage with SVG arrow overlay, hover states on node cards. No mobile breakpoints. Populate the sidebar with: (a) version badge, (b) "On this page" nav, (c) "Architectural invariants" list (surface up to 5 load-bearing constraints you inferred from the code/config — e.g. "Kernel owns durable state", "All ops return Result<T,E>"), (d) node-type legend.
If node count >50 OR the model signals layout failure (overlapping boxes, arrows crossing through nodes), switch to templates/mermaid-fallback.html regardless of layout shape.
Step 4: Update Fingerprint State
For generate/diff/watch modes, write structural state to ${CLAUDE_PLUGIN_DATA}/arch-state.json (or ~/.claude-state/arch-state.json fallback if the env var is unset):
Validator confirms: ARIA labels present, reduced-motion rule exists, no unexpected external script sources beyond Google Fonts. If validation fails, iterate on the template fill — don't ship an inaccessible diagram.
Open the result via ${CLAUDE_SKILL_DIR}/scripts/open_in_browser.sh (OS-aware: xdg-open on Linux, open on macOS, wslview on WSL). Echo the Mermaid equivalent to the chat as a copy-pasteable text block.
Feedback Loop
Run validate_html.py after Step 5.
If ARIA or contrast checks fail → fix template fill → re-validate.
If >50 nodes rendered as overlapping boxes → restart Step 3 with Mermaid fallback.
(docs-layout only) If arrows cross non-endpoint nodes OR text overflows a node box → re-run layout math (see docs-layout.md § verification) before re-screenshotting. Don't eyeball it; collision math is cheap and catches what a thumbnail hides.
Maximum 3 iterations before falling back to Mermaid and flagging for manual review.
Output
generate / diff / trace modes: one HTML file at $CWD/.arch/<mode>-<timestamp>.html (self-contained, offline-capable, Google Fonts as the sole external dep) + one Mermaid text block echoed to chat.
watch mode: markdown drift report with sections Added, Removed, Changed, each line citing the source file that justified the delta.
All modes: updated fingerprint at ${CLAUDE_PLUGIN_DATA}/arch-state.json.
Example 1 — Generate architecture view from a monorepo
Input:
/design:generate
Behavior: DCI auto-loads docker-compose.yml services (web, api, db, cache), classifies roles (frontend/backend/db/db), reads web/src/lib/api-client.ts for the HTTP edge to api, reads docker-compose.ymldepends_on for api→db and api→cache edges. Fills templates/base.html, writes ~/.arch/generate-2026-04-19T12-00.html, writes fingerprint with 4 nodes + 3 edges.
Output excerpt (Mermaid block):
flowchart TB
web["Web Frontend"]:::frontend --> api["API Service"]:::backend
api --> db["Postgres"]:::db
api --> cache["Redis"]:::db
Example 2 — PR delta on a branch that adds Redis
Input:
/design:diff
Behavior: Loads prior fingerprint, re-runs DCI on working tree, computes set-diff. Renders architecture view with class="delta-added" on the cache node and the api→cache edge. Summary line: Added 1 node (cache), 1 edge (api→cache).
Behavior: Parses Sentry JSON (exception frames + transaction spans), infers 4 lifelines (checkout-api, payment-service, stripe-webhook-listener, fraud-check), renders sequence diagram with the timeout marked on the final arrow. No fingerprint write in trace mode.
