flow-diagram

Interactive two-way HTML flow diagrams

Output: one self-contained .html file (no dependencies, opens directly in a browser), laid out as a 2-pane app filling the viewport: a title row + light/dark toggle (thin-line SVG icon that recolors with the theme — see "Theme icon button") → flow-select chips → left: diagram, default FIT TO VIEW — the reader sees the whole system at once, no scrolling — with a zoom bar (+/− buttons, ⤢ fit-to-view, scroll-to-zoom at the cursor, drag to pan) → right: sidebar of explainer cards. The reader clicks a flow (a chip, a line, or a step badge) → that flow keeps its color and gets a small dot traveling along the line in its direction (see "Traveling dots"), everything else dims to ~10%, the sidebar shrinks to just that flow's card; clicking a step badge highlights the matching line in that card. That's how a non-technical reader answers "where does this flow go, start to finish?" without reading the whole diagram. A fully worked, machine-checked example: references/flow-diagram-example.html. Not sure which layout to use (linear? convergent? hub? branching?) → read references/layout-patterns-guide.html first — a guide to 4 common topologies, each with a "why this layout" section explaining the reasoning, not just numbers to copy.

Hard-won lesson behind this skill: writing SVG means placing coordinates blind — nobody sees the result while typing numbers, and the human eye (even a shrunk screenshot) misses collisions that are only a few pixels off. So the process revolves around a machine-measured loop: draw → check → fix coordinates → check again, until 0 errors. Don't trust the feeling of "that's probably not overlapping."

Process

1. Ask what language the diagram should be in — before gathering any content. Don't assume English by default and don't infer it from the conversation's language either; ask explicitly, e.g. a short multiple-choice question ("Which language should the diagram be in? English / [conversation's language] / other — I'll write it out"). This decides the language for every label, chip, card, and title in the final file. Skipping this step and guessing is the single most common way this skill produces a diagram the user then has to ask to redo from scratch.
2. Lock down the content before drawing. List out: the blocks (boxes), the flow GROUPS (each group becomes 1 chip + 1 card + 1 data-flow code), and for each flow — both the outbound and the return direction. If the user only describes the outbound leg, ask about the return leg (real-world lesson: users almost always want to see how data comes back, not just how it goes out). Any flow's routing that's unclear → ask a multiple-choice question, don't guess. Before placing any coordinates, work out which layout pattern the content matches in references/layout-patterns-guide.html (linear multi-phase / convergent multi-source / central hub / conditional branch) — real diagrams often NEST several patterns (e.g. two sources converging, then branching on pass/fail) — identify each piece and combine them rather than inventing a new layout from scratch.
3. Plan the coordinate grid and WRITE IT AS A COMMENT at the top of the SVG. Rule out vertical columns and horizontal rows, assign each box to a cell; list the "corridors" — empty lanes for long vertical/horizontal runs; list any point where two lines are forced to cross. Write all of it into <!-- LAYOUT PLAN: ... --> right after the <svg> tag — the next editing pass will then know which lane already has an owner. 10 minutes of planning saves 5 rounds of untangling overlaps.
4. Copy assets/template.html as the starting shell — it already has everything: light-mode CSS (with the text halo), chips, the detail panel, interaction JS, 5 arrow markers, a sample forward/return pair, a hop, a region, a box, a badge, a card. Don't rewrite the CSS/JS from scratch — copy it, then replace the content.
5. Draw following the Design System below, wiring up the interactive attributes as you go (line/badge/label → data-flow; box → data-flows). Keep the SVG's layer order as specified.
6. Machine-check to 0 errors — do NOT skip this step even if getting browser permission is annoying. Prefer checking in a real browser: open the file, then run assets/check-collisions.js verbatim through a browser JS tool. Check it in the default fit-to-view state (100%) — the whole SVG must be inside the viewport, because elementsFromPoint is blind outside the visible area; if you'd zoomed in, click ⤢ before checking or you'll get a false "0 errors". The script reports errors in viewBox coordinates (fix the numbers in the file directly) and draws red/yellow outline boxes on the page. Fix → re-check, usually 1–3 rounds. Only stop once: 0 errors, and any remaining warnings can be justified out loud (more than 5 warnings means the layout is genuinely cluttered — rearrange the boxes instead of arguing with the checker). Can't connect to the browser (extension broken/unresponsive) → fall back immediately to the offline checker assets/check-svg.js (node assets/check-svg.js <file.html>, no browser permission needed): computes box-overlaps-box, arrow-too-close-to-box, floating-arrow (an arrowhead that touches no box), viewBox overflow, and box-too-close-to-region-border exactly from the real numeric coordinates — only the text-overlap check is an estimate of font width (reported as a warning, not a hard error, and needs a follow-up eyeball check). Never "check" by mentally estimating coordinates — past 10 arrows, doing it by hand reliably both misses real errors and invents false ones (this actually happened once: a by-hand pass "found" a floating line that didn't exist in the file at all). If neither checking path works, stop and ask the user rather than guessing blind.
7. Click through every flow, then step back and look at the whole thing. Click each chip: the right flow lights up, related boxes aren't dimmed by mistake, the panel shows the right card, Esc clears the selection. Then screenshot it and actually look — the checker only catches "wrong," not "ugly." Finally, name the file something clear and versioned (e.g. flow-<topic>_YYYY-MM-DD_v1.0.html). A substantial content change → bump the version, keep the old file.