Dashmotion

Dashmotion

Create professional animated technical diagrams as single self-contained HTML files. The name is the implementation: stroke-dashoffset animation + animateMotion — that's all there is. Output is vector, loops forever, weighs a few KB, and opens in any browser.

Step 1 — Pick the mode

Mixed request ("show our microservices AND how an order flows through them") → Architecture mode; the animated request path is the flow. Only produce two separate files if the process has branching logic that the topology can't express.

Mermaid input — if the request contains Mermaid source (a ```mermaid block, a .mmd file, or pasted code), ALSO read references/mermaid-input.md before anything else. Supported: flowchart/graph and stateDiagram-v2; other diagram types are unsupported — say so and offer alternatives. The mode routing above still applies (mermaid is syntax, not semantics), and layout is always recomputed top-down regardless of the source's declared direction.

Read the mode reference file before you start. Its layout arithmetic is what scripts/layout.py implements (Step 5) — read it to author a clean semantic graph and to apply the color/shape/animation style layer to the script's geometry (and to hand-compute the fallback). It encodes what prevents the common failures: overlaps, arrows through boxes, broken loops.

Step 2 — The two animation contracts (both modes)

Flowing dashed connectors — stroke-dashoffset

.flow { stroke-dasharray: 5 5; animation: dashmove 0.75s linear infinite; }
@keyframes dashmove { to { stroke-dashoffset: -10; } }

• The offset delta MUST equal one full stroke-dasharray period (here 5+5=10), or the loop visibly jumps.
• Negative offset flows in the path's drawing direction → always author connector d from source to target.
• 0.6–0.9s reads as "electric current"; slower than 1.5s reads as broken.

Traveling dots — <animateMotion>

<circle r="3.5" class="dot" fill="#34d399">
  <animateMotion dur="2s" repeatCount="indefinite"
    path="M400 178 L400 204 L170 204 L170 222"/>
</circle>

• path reuses the connector's d verbatim; the dot rides exactly on the line.
• The circle has no cx/cy — animateMotion positions it.
• Stagger with begin="0.7s" etc. 3–6 dots total per diagram; put them where direction is informative (fan-outs, merges, the main request path), never on every edge.
• In Architecture mode a dot is semantically a request/message in flight — route dots along realistic end-to-end journeys.

Step 3 — Shared design tokens

• Page: #020617, 40px grid pattern (#0f1b33, 0.5px lines), JetBrains Mono when locally installed, else a system monospace stack (ui-monospace, 'SF Mono', 'Cascadia Code', Menlo, Consolas, monospace) — no web-font fetch, the file is fully self-contained.
• Text: labels #e2e8f0 13px/500, sublabels #64748b 10px, legend 11px.
• Node corner rx="8"; START/END pills rx = height/2.
• One shared arrowhead marker using context-stroke (inherits each line's color):

<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
  <path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>

• Connector endpoints stop 4px short of node edges so arrowheads don't pierce borders.
• Every connector <path> MUST have fill="none" (or sit in a <g fill="none">) — SVG defaults to black fill and an L-shaped path renders as a giant black polygon without it.
• Z-order paint sequence: grid → connectors → dots → nodes. Nodes mask line ends; dots vanish "into" nodes instead of sliding over them.
• ViewBox: 0 0 W H where H = lowest element bottom + 50. Never negative coordinates.

Step 4 — Accessibility & motion (non-negotiable)

• Wrap ALL CSS animation in @media (prefers-reduced-motion: no-preference).
• SMIL ignores that media query → keep the template's inline script that removes .dot elements under reduced motion and wires the visible ⏯ pause toggle (animation-play-state: paused + svg.pauseAnimations()).
• SVG gets role="img" + <title> + <desc>.

Step 5 — Produce the file

dashmotion ships a deterministic layout engine, scripts/layout.py (pure stdlib). It does the coordinate arithmetic the mode references describe — row packing, branch gaps, boundary padding, orthogonal rail/lane routing — and renders the finished HTML: geometry + the mode style layer + your copy. So you do not hand-compute coordinates or hand-transcribe 35 rects and 38 path ds into a template (both are slow). You decide the semantics and the copy; the script writes the file. Full contract in references/layout-script.md.

Script path — use it whenever python3 is available:

1. Parse the request — or the Mermaid source per references/mermaid-input.md — into the semantic graph JSON of references/layout-script.md. This is your judgement layer, and it carries everything the diagram needs:
   • structure: nodes (type + tier for architecture — omit tier for ungrouped/single-group arch (engine auto-layers), write it for multi-group, see layout-script.md; per-node group for boundary membership; flow shape written only for pills & decisions — never "shape": "step", steps omit it), edges (kind), groups, journeys, any legendExtra, classDef retention;
   • copy: title, subtitle, and (architecture) a summary of exactly three cards (accent cyan/violet/rose, title, items[]) — the human-facing wording is yours to write, here, in the JSON.
2. Write it to a temporary path, not the output folder — e.g. "$TMPDIR/dashmotion-graph.json" (or any mktemp path) — then run python3 <this-skill-directory>/scripts/layout.py "$TMPDIR/dashmotion-graph.json" --render <topic>-dashmotion.html. The semantic JSON is a throwaway build intermediate; the delivered HTML does not depend on it, so never write it beside the .html — the user's folder should contain only the finished diagram. The script computes the geometry, applies the style layer (node fills/strokes by type, the opaque-base + styled-rect masking pair, flow/flow-async/flow-auth connector classes by edge kind, per-journey dot colors with staggered, chained begin), drops in your copy, and writes the complete, self-contained, ready-to-ship file. Edges flagged "loop": true are rendered as the ↻ label annotation, not a path.
3. Run Step 6 against that file. The renderer is structurally sound by construction, but Step 6 is still the authority — run it.
4. You keep final say over everything visual: to adjust wording, emphasis, journeys, or types, edit the JSON and re-render (cheap and deterministic); to tweak a label or a colour by hand, edit the emitted file directly. What you no longer do is photocopy coordinates — the script owns geometry (plan A) and now the boilerplate around it.

Do not author the JSON, then also hand-write the HTML — that re-incurs the exact transcription cost this path removes. Render, check, deliver.

Hand-computed fallback — only when python3 is unavailable: do the layout arithmetic from the mode reference explicitly before writing coordinates, copy the template, replace SVG content / title / header / legend / summary cards (keep CSS + pause toggle + reduced-motion script), pick 3–6 dot paths copying connector d values and staggering begin. This is the pre-2.2 path — slow, but it needs no Python.

Tell the user the file opens directly in any browser.

GIF/MP4 export (only if asked)

Never render frames by hand. Screen-record the open file (macOS ⌘⇧5), or headless: npx timecut <file.html> --viewport=1200,900 --duration=3 --fps=30 --output=flow.mp4 then ffmpeg -i flow.mp4 flow.gif. A 3s capture loops seamlessly when all durations divide 3s — prefer 0.75s / 1.5s / 3s when GIF export is the goal.

Step 6 — Structural self-check (before delivering)

The file is not done when it's written — it's done when it passes this check. The --render output is structurally sound by construction, but the check is still mandatory (it's also your guard for the hand-computed fallback, whose coordinates fail in predictable ways — the connector layer far more often than the text layer). Verify; don't assume.

Mechanized path (use it whenever python3 is available): run the bundled checker against the file you just wrote —

python3 <this-skill-directory>/scripts/check_diagram.py <your-file>.html

It deterministically detects the failure classes below (overlaps, connectors through boxes, dash-loop seams, out-of-bounds, dots off their line, black-fill, endpoint pierce, dangling begin refs, malformed XML). Fix every reported violation and re-run until it prints 0 violations. Do NOT hand-walk the arithmetic when the script is available, do NOT write your own ad-hoc verification script, and never verify by opening a browser or taking screenshots — the script is the authority; items it can't see (label collisions, exact boundary padding, legend placement) you still check by reading the numbers.

If the input was Mermaid, also mechanize the fidelity recount (checklist item 6): save the source to a temp .mmd and run —

python3 <this-skill-directory>/scripts/check_fidelity.py <source>.mmd <your-file>.html

Fix until it prints PASS. It verifies every source node/edge/group label appears verbatim and the connector count matches the source's edge count. So keep labels and legend entries exactly as the source wrote them — do not reword, merge two source strings into one, or add parentheses (a legend entry v2 点线橙框 must stay v2 点线橙框, never v2 治理骨架（点线橙框）). This is the same low-recall trap as the structural check: prose "I kept it verbatim" misses real drift; the script doesn't.

Prose fallback (only if python3 is unavailable): verify each item below with arithmetic on the actual numbers (write the comparisons out), not by eyeballing the code. Fix every violation and re-check until the list is clean.

1. Overlaps — for every pair of same-row elements: left.x + left.width + gap ≤ right.x (gap ≥ 20 flow / 40 architecture). For every stacked pair: top.y + top.height + gap ≤ bottom.y. A boundary must fully contain its children with ≥ 20px padding on all four sides; partial overlap between any two boxes is always a bug.
2. Connectors through boxes — walk every path segment by segment: between its endpoints it must not enter any node rect. Check every horizontal rail's y against the rects it passes (rect.y ≤ y ≤ rect.y + height means a collision); same for vertical drops' x. Fix by re-routing with the rail pattern, not by nudging boxes until something else breaks.
3. Animation loops — for each animated class: |stroke-dashoffset delta| must be an exact multiple of the stroke-dasharray period sum (e.g. 5 5 → 10), including connectors that override the dasharray inline (an async 2 4 edge animated by a -10 keyframe seams every cycle — give it its own keyframes). For each animateMotion, name the single connector whose d it traces — a dot path that spans two connectors sails straight through the component between them; split it into chained per-hop dots instead. Every begin="X.end+…" must reference an id that exists.
4. ViewBox bounds — no negative coordinates anywhere; every rect's x+width/y+height and every path coordinate stays inside 0 0 W H; H ≥ lowest element bottom + 20; the legend sits below the lowest boundary (architecture).
5. Connector & markup hygiene — every connector <path> resolves to fill="none"; endpoints stop ~4px short of the target border and never reach inside a box; no -- inside SVG comments (<!-- A -- B --> closes the comment early and leaks stray text into the document).
6. Mermaid fidelity (mermaid input only) — mechanized by check_fidelity.py above; run it and fix to PASS. It recounts against the source: node rects/pills == source node IDs (START/END pills added only for [*]); connector paths + ↻-rendered loops == source edges after expanding chains and &; every node, edge, group, and legend label appears verbatim (legend entries merged from a 图例 subgraph included — keep their exact text). Without python3, recount by hand. Details in references/mermaid-input.md.

Deliver the file only after a pass where nothing needed fixing.

Output contract

One self-contained .html: embedded CSS, inline SVG, no external assets, no JS dependencies — only the ~15-line inline pause/reduced-motion script. Renders correctly opened from the filesystem.