diagram-site

Turn a document stuffed with ASCII art, Mermaid blocks, and tables into a clean, single-page site you can open in any browser. The renderer (app.js) is fixed and reused as-is — your only authoring job is two data files: data.js (the diagrams themselves) and config.js (sections, titles, altitude, footer). After that you copy the static assets into the output folder and vendor Mermaid.

Gather context first

This skill ships standalone, so it can't assume your project's conventions, house style, or preferences the way it could for its author. Before doing the main work:

1. Auto-detect what you safely can from the repo — language/stack, base branch, build/test commands, existing config and docs. Never ask for something you can read for yourself.
2. Ask, don't assume, for the rest. Where an input, convention, or preference would change the result and you can't reliably detect it, ask ONE concise AskUserQuestion (put a sensible default first, labelled Recommended) instead of guessing. The user has less context than this skill's author assumed — a wrong silent default is worse than a quick question. Don't ask about things you can detect, and don't ask more than you need.

For this skill, confirm up front (only the items you can't already detect):

• Which document(s) to turn into a site, and their paths, if you weren't handed them — the source doc(s) drive everything downstream.
• Altitude / audience — HIGH vs LOW. HIGH (business / HLD: hides node refs, the raw Source expander, and layer chips, and strips file:line / function / spec refs) vs LOW (engineering / LLD / review: shows refs, Source, and layer chips). Infer it from the doc type, but ask when it's genuinely ambiguous (e.g. a "design overview" that could go either way) — it decides which diagrams you show and whether code-level detail leaks.
• Where to write the output folder — default docs/<name>-site/; confirm the path or name if the repo has its own convention (e.g. architecture/, site/).
• Curation depth for an HLD — whether to drop internal-wiring / build / dependency diagrams (recommended for a business audience) or include the full set.

Subagents & parallelism (opt-in)

By default this skill runs inline in a single context — no subagents, no Workflow fan-out — to keep it cheap to run.

Parallel subagents can be faster on large jobs (a doc with many diagrams, or deep per-diagram conversion). Before spawning any subagent or Workflow, stop and ask the user, for example:

This doc has [N] diagrams. I can convert them inline here (cheaper, slower) or fan out [M] parallel subagents — one per diagram — then merge (faster, more tokens). Which do you want?

Spawn subagents/workflows only after an explicit yes. If the user declines or doesn't answer, do the whole job inline.

Assets (in assets/)

• index.html — fixed shell. Loads config.js, data.js, mermaid.min.js, then app.js.
• styles.css — the design system (dark/light tokens plus every component). Generic; never edit it per project.
• app.js — the renderer. Reads window.SITE_CONFIG and window.SITE_DATA. Never edit it per project.
• config.example.js, data.example.js — copy to config.js / data.js and fill in. The full schema is documented inline in both example files (read them).

The two things you author

data.js → window.SITE_DATA = { id: diagram }. Every diagram carries a kind:

Each node is {id,label,desc,ref?,front?}. Clicking a node opens the drawer (it shows desc, plus ref/outcome/layer when those exist). ref and the raw Source block surface only at LOW altitude.

config.js → window.SITE_CONFIG: title, subtitle, altitude, sections[] (left nav → diagram ids), titleOverrides, optional layers, footer.

The altitude knob (the decision that matters most)

• HIGH (altitude:"high") — design doc / HLD / business + product audience. Hides node refs, the raw Source expander, and the layer chips/legend. This audience already knows domain and tech vocabulary (API, latency, cache, retry, throughput) — keep those words. Strip the code-level detail: file:line pointers (service.go:412), function / variable / type names (client.Fetch, models.Order), spec section numbers (§3.1), ticket or decision refs, array-index notation (row[13:19]), and internal call-chain hops (handler→service→client). Explain what the system does, never how it is wired together.
• LOW (altitude:"low") — LLD / review / engineering audience. Shows refs, Source, and layer chips. file:line and spec refs belong here.

Choose altitude from the document type; confirm with the user when the doc type or audience is ambiguous (a "design overview" can read as either), since it decides which diagrams you show and whether code-level detail leaks.

Doc-type playbook

• Design doc → a mix of flow (data flow), graph (context), state, and cards (components). Altitude follows the audience — HIGH if it's a design overview, LOW if it's the detailed spec.
• HLD → HIGH altitude. Sections: Overview (a flow "how it works" plus a graph "why / context"), Mechanism (flow / scale / ladder at a tech-but-not-code altitude), Roadmap (trust-ladder plus a 3-column cards). Curate for the audience — drop build, dependency, and internal-wiring diagrams.
• LLD → LOW altitude. Show everything: sequence (call flow), state (state machines), ladder (decision algorithms), cards/table (data schemas, output contracts), all with refs.
• Review doc (code / scope / plan / pre-merge review) → flip-cards for findings (front = the issue, back = the fix; flipTags:["ISSUE","RESOLVED"]), cards for decision matrices and risk registers (outcome words like PASS/FAIL/BLOCK auto-color), scale for severity. LOW altitude — refs are useful here.

Generation steps

1. Read the source doc(s). If you weren't handed a specific document, ask which one(s) to convert before starting. Inventory every diagram, table, and flow, plus the surrounding narrative.
2. Pick altitude and audience. Infer it from the doc type; confirm with the user when ambiguous. This drives which diagrams to show and how to curate the sections.
3. Author data.js. Convert each diagram into a kind plus its content. For graph-shaped diagrams, write Mermaid (node IDs and arrows are the structure; put rich text inside "quoted labels"; the renderer uses htmlLabels:false, so avoid a raw </> inside a label — spell it out in words). If the doc has many diagrams and the user opted into subagents (see Subagents & parallelism), fan out one agent per diagram → structured JSON, then merge; otherwise convert the diagrams one by one in this context. At HIGH altitude, write plain-language descriptions and do not include any code pointers (see altitude).
4. Author config.js. Brand title/subtitle, set altitude, curate sections, set titleOverrides (keep data.title faithful to the source; override only the displayed title), and add an optional footer.
5. Assemble the output folder (default docs/<name>-site/; confirm the path or name if the repo has its own convention, e.g. architecture/): copy index.html, styles.css, app.js; write config.js and data.js.
6. Vendor Mermaid (so it stays self-contained): curl -fsSL https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js -o <out>/mermaid.min.js (No font CDN — styles.css falls back to the system stack, so the result has zero external references.)
7. Validate: run node --check app.js; load data.js + config.js in node and assert that every id listed in sections exists in the data; at HIGH altitude, scan the rendered fields for code pointers (:\d{2,4}, \.(go|py|js)\b, §, snake_case/camelCase identifiers) and remove them.
8. QA in a browser (recommended): open index.html, click through each section, confirm every Mermaid diagram draws as real SVG (not the ASCII fallback), click nodes (the drawer should open), toggle the theme, and flip the cards. Fix any Mermaid that fell back — it's almost always a label-syntax issue.

Conventions & gotchas

• Self-contained means two things: (a) no external network dependencies (Mermaid vendored, system fonts only); (b) no references to other documents in a standalone deck — drop "see spec §X", doc filenames, ticket IDs, and any "document authority" diagram. The site has to explain itself.
• app.js quote-protects Mermaid only inside the source you hand it — keep node IDs and arrows outside the "…". If a diagram fails to render it falls back to its raw_ascii/source, which is your signal to fix the label.
• Keep data.title equal to the source-doc title; use titleOverrides for the friendly display title.
• This skill commits nothing — leave the output as working-tree files unless the user asks you to commit.