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.