engineer-design-diagram

name	engineer-design-diagram
description	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".
allowed-tools	Read,Write,Glob,Grep,Bash(git:*),Bash(ls:*),Bash(cat:*),Bash(jq:*),Bash(docker:*),Bash(kubectl:*),Bash(terraform:*),Bash(python3:*),Bash(xdg-open:*),Bash(open:*),Bash(wslview:*),AskUserQuestion
version	0.5.0
author	Jeremy Longshore <[e-mail]>
license	MIT
tags	["architecture","diagram","visualization","svg","html","pr-review","drift-detection","sequence-diagram","engineering-design"]
argument-hint	[generate|diff|trace|watch] [target-path]
model	inherit
compatibility	Designed for Claude Code

Engineer Design 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	templates/base.html
Docs-layout page (widescreen)	≥8 nodes, multiple planes/groupings/sub-blocks, want invariants + detail cards + legend alongside the diagram	templates/docs-layout.html

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.