engineer-design-diagram

What this skill does

# 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](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT). See [THIRD_PARTY_LICENSES.md](references/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.

**Hybrid rendering** 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 *over* 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.

**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](references/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`
- Python 3.9+ (for `scripts/fingerprint.py`)
- A browser to view output
- Optional: `kubectl` (cluster introspection), `terraform` (state parsing), `jq` (manifest parsing)

## Environment Detection (DCI)

!`git rev-parse --show-toplevel 2>/dev/null || echo "not a git repo"`
!`git rev-parse --short HEAD 2>/dev/null || echo "no-head"; git branch --show-current 2>/dev/null || echo "no-branch"`
!`ls package.json pyproject.toml Cargo.toml go.mod requirements.txt docker-compose.yml Dockerfile 2>/dev/null | head -10 || echo "no manifests"`
!`command -v jq >/dev/null 2>&1 && jq -r '.name,(.dependencies // {} | keys[]?)' package.json 2>/dev/null | head -20 || echo "no package.json / no jq"`
!`docker compose config --services 2>/dev/null | head -30 || echo "no docker-compose"`
!`find . -maxdepth 3 -type d \( -name k8s -o -name kubernetes -o -name manifests \) 2>/dev/null | head -5 || echo "no k8s dir"`
!`find . -maxdepth 3 -name '*.tf' 2>/dev/null | head -10 || echo "no terraform"`

## Instructions

### Step 1: Mode Detection

Parse the first token of `$ARGUMENTS`:

| Invocation | Mode | Playbook |
|------------|------|----------|
| `/design:generate` or empty | generate | [mode-playbooks.md#generate](references/mode-playbooks.md#generate) |
| `/design:diff` | diff | [mode-playbooks.md#diff](references/mode-playbooks.md#diff) |
| `/design:trace <path>` | trace | [mode-playbooks.md#trace](references/mode-playbooks.md#trace) |
| `/design:watch` | watch | [mode-playbooks.md#watch](references/mode-playbooks.md#watch) |

All modes share Steps 2-5. Mode-specific variations documented in the per-mode playbook.

### Step 2: Build the Node/Edge Graph

Use the DCI block output + targeted reads to populate a working graph:

- **Nodes** from: docker-compose service names, k8s `kind: Deployment/Service/StatefulSet`, terraform resource blocks, package manifest names (for standalone apps), detected binaries in `bin/` or `cmd/`.
- **Edges** from: docker-compose `depends_on` + exposed ports, k8s Service selectors + NetworkPolicy, terraform resource references, import-graph via Grep (`import.*from`, `require(`, `use crate::`), exposed HTTP/gRPC routes.
- **Role classification** per node using [drawing-rules.md § Role inference](references/drawing-rules.md#role-inference). Defaults to `slate` (external/unknown) when heuristics don't match.
- **Groups** from: k8s namespaces, terraform modules, docker-compose networks, directory boundaries for monorepos.

For graphs with >50 nodes, fall back to Mermaid (see Step 3 template selection).

### Step 3: Choose Template and Render

Apply the layout-selection rule from **Layout Philosophy** first, then pick the template for the chosen mode:

| Mode | Layout shape | Template | Output |
|------|--------------|----------|--------|
| generate / diff | single-SVG hero (simple graphs) | [templates/base.html](templates/base.html) | Centered SVG on dark canvas, cards row below |
| generate / diff | docs-layout page (dense graphs) | [templates/docs-layout.html](templates/docs-layout.html) | Two-column widescreen page: sticky sidebar + main column with diagram card + detail grid |
| diff (any shape) | — | selected template + delta classes | `delta-added` / `delta-removed` / `delta-changed` CSS markers on changed nodes/edges |
| trace | sequence | [templates/sequence.html](templates/sequence.html) | 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](references/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](references/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 (overl