dashmotion Skill
创建深色主题、带动画的技术图表,输出为自包含的 HTML+SVG 文件——连接线可见流动的流程图,以及请求化作光点在系统中穿行的架构图(Diagrid/Temporal 官网风格)。当用户要求流程图、工作流、管道、过程图、状态机、系统架构、基础设施、云、微服务或网络拓扑图时使用——尤其当提到"animated"、"flowing"、"dynamic"、"alive"、"GIF-like",或想要用于落地页、README、文档或产品演示的图表。
安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。
技能指令原文(SKILL.md)
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
| User wants | Mode | Read |
|---|---|---|
| Steps, sequence, branching, parallel execution, state transitions ("what happens, in what order") | Flow | references/flow-mode.md + resources/template-flow.html |
| Components, services, infrastructure, containment, topology ("what the system is made of") | Architecture | references/architecture-mode.md + resources/template-architecture.html |
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-dasharrayperiod (here 5+5=10), or the loop visibly jumps. - Negative offset flows in the path's drawing direction → always author connector
dfrom source to target. - 0.6–0.9s reads as "electric current"; slower than 1.5s reads as broken.
Traveling dots —
<circle r="3.5" class="dot" fill="#34d399">
<animateMotion dur="2s" repeatCount="indefinite"
path="M400 178 L400 204 L170 204 L170 222"/>
</circle>
pathreuses the connector'sdverbatim; the dot rides exactly on the line.- The circle has no
cx/cy—animateMotionpositions 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
#e2e8f013px/500, sublabels#64748b10px, legend 11px. - Node corner
rx="8"; START/END pillsrx= 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
MUST havefill="none"(or sit in a) — 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 Hwhere 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
.dotelements under reduced motion and wires the visible ⏯ pause toggle (animation-play-state: paused+svg.pauseAnimations()). - SVG gets
role="img"+</code> + <code><desc></code>.</li> </ul> <h2>Step 5 — Produce the file</h2> <p> dashmotion ships a deterministic layout engine, <code>scripts/layout.py</code> (pure stdlib). It does the coordinate arithmetic the mode references describe — row packing, branch gaps, boundary padding, orthogonal rail/lane routing — <strong>and renders the finished HTML</strong>: geometry + the mode style layer + your copy. So you do <strong>not</strong> hand-compute coordinates <em>or</em> hand-transcribe 35 rects and 38 path <code>d</code>s into a template (both are slow). You decide the <em>semantics and the copy</em>; the script writes the <em>file</em>. Full contract in <code>references/layout-script.md</code>. </p> <p> <strong>Script path — use it whenever <code>python3</code> is available:</strong> </p> <ol> <li>Parse the request — or the Mermaid source per <code>references/mermaid-input.md</code> — into the semantic graph JSON of <code>references/layout-script.md</code>. <strong>This is your judgement layer</strong>, and it carries everything the diagram needs:</li> </ol> <ul> <li>structure: nodes (<code>type</code> + <code>tier</code> for architecture — <strong>omit <code>tier</code> for ungrouped/single-group arch</strong> (engine auto-layers), write it for multi-group, see <code>layout-script.md</code>; per-node <code>group</code> for boundary membership; flow <code>shape</code> <strong>written only for pills & decisions — never <code>"shape": "step"</code></strong>, steps omit it), edges (<code>kind</code>), groups, journeys, any <code>legendExtra</code>, classDef retention;</li> <li><strong>copy</strong>: <code>title</code>, <code>subtitle</code>, and (architecture) a <code>summary</code> of exactly three cards (<code>accent</code> cyan/violet/rose, <code>title</code>, <code>items[]</code>) — the human-facing wording is yours to write, here, in the JSON.</li> </ul> <ol> <li>Write it to a <strong>temporary path, not the output folder</strong> — e.g. <code>"$TMPDIR/dashmotion-graph.json"</code> (or any <code>mktemp</code> path) — then run <code>python3 <this-skill-directory>/scripts/layout.py "$TMPDIR/dashmotion-graph.json" --render <topic>-dashmotion.html</code>. The semantic JSON is a throwaway build intermediate; the delivered HTML does not depend on it, so <strong>never write it beside the <code>.html</code></strong> — the user's folder should contain only the finished diagram. The script computes the geometry, applies the style layer (node fills/strokes by <code>type</code>, the opaque-base + styled-rect masking pair, <code>flow</code>/<code>flow-async</code>/<code>flow-auth</code> connector classes by edge <code>kind</code>, per-journey dot colors with staggered, chained <code>begin</code>), drops in your copy, and writes the <strong>complete, self-contained, ready-to-ship file</strong>. Edges flagged <code>"loop": true</code> are rendered as the <code>↻ label</code> annotation, not a path.</li> <li>Run Step 6 against that file. The renderer is structurally sound by construction, but Step 6 is still the authority — run it.</li> <li>You keep final say over everything visual: to adjust wording, emphasis, journeys, or types, <strong>edit the JSON and re-render</strong> (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.</li> </ol> <p> Do not author the JSON, then <em>also</em> hand-write the HTML — that re-incurs the exact transcription cost this path removes. Render, check, deliver. </p> <p> <strong>Hand-computed fallback — only when <code>python3</code> is unavailable:</strong> 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 <code>d</code> values and staggering <code>begin</code>. This is the pre-2.2 path — slow, but it needs no Python. </p> <p> Tell the user the file opens directly in any browser. </p> <h3>GIF/MP4 export (only if asked)</h3> <p> Never render frames by hand. Screen-record the open file (macOS ⌘⇧5), or headless: <br /> <code>npx timecut <file.html> --viewport=1200,900 --duration=3 --fps=30 --output=flow.mp4</code> then <code>ffmpeg -i flow.mp4 flow.gif</code>. <br /> A 3s capture loops seamlessly when all durations divide 3s — prefer 0.75s / 1.5s / 3s when GIF export is the goal. </p> <h2>Step 6 — Structural self-check (before delivering)</h2> <p> The file is not done when it's written — it's done when it passes this check. The <code>--render</code> 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. </p> <p> <strong>Mechanized path (use it whenever <code>python3</code> is available):</strong> run the bundled checker against the file you just wrote — </p> <pre><code class="language-bash">python3 <this-skill-directory>/scripts/check_diagram.py <your-file>.html</code></pre> <p> 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 <code>0 violations</code>. Do NOT hand-walk the arithmetic when the script is available, do NOT write your own ad-hoc verification script, and <strong>never verify by opening a browser or taking screenshots</strong> — the script is the authority; items it can't see (label collisions, exact boundary padding, legend placement) you still check by reading the numbers. </p> <p> <strong>If the input was Mermaid</strong>, also mechanize the fidelity recount (checklist item 6): save the source to a temp <code>.mmd</code> and run — </p> <pre><code class="language-bash">python3 <this-skill-directory>/scripts/check_fidelity.py <source>.mmd <your-file>.html</code></pre> <p> Fix until it prints <code>PASS</code>. It verifies every source node/edge/group label appears <strong>verbatim</strong> 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 <code>v2 点线橙框</code> must stay <code>v2 点线橙框</code>, never <code>v2 治理骨架(点线橙框)</code>). This is the same low-recall trap as the structural check: prose "I kept it verbatim" misses real drift; the script doesn't. </p> <p> <strong>Prose fallback (only if <code>python3</code> is unavailable):</strong> verify each item below <strong>with arithmetic on the actual numbers</strong> (write the comparisons out), not by eyeballing the code. Fix every violation and re-check until the list is clean. </p> <ol> <li><strong>Overlaps</strong> — for every pair of same-row elements: <code>left.x + left.width + gap ≤ right.x</code> (gap ≥ 20 flow / 40 architecture). For every stacked pair: <code>top.y + top.height + gap ≤ bottom.y</code>. A boundary must fully contain its children with ≥ 20px padding on all four sides; partial overlap between any two boxes is always a bug.</li> <li><strong>Connectors through boxes</strong> — walk every path segment by segment: between its endpoints it must not enter any node rect. Check every horizontal rail's <code>y</code> against the rects it passes (<code>rect.y ≤ y ≤ rect.y + height</code> means a collision); same for vertical drops' <code>x</code>. Fix by re-routing with the rail pattern, not by nudging boxes until something else breaks.</li> <li><strong>Animation loops</strong> — for each animated class: <code>|stroke-dashoffset delta|</code> must be an exact multiple of the <code>stroke-dasharray</code> period sum (e.g. <code>5 5</code> → 10), <strong>including connectors that override the dasharray inline</strong> (an async <code>2 4</code> edge animated by a <code>-10</code> keyframe seams every cycle — give it its own keyframes). For each <code>animateMotion</code>, name the single connector whose <code>d</code> 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 <code>begin="X.end+…"</code> must reference an <code>id</code> that exists.</li> <li><strong>ViewBox bounds</strong> — no negative coordinates anywhere; every rect's <code>x+width</code>/<code>y+height</code> and every path coordinate stays inside <code>0 0 W H</code>; H ≥ lowest element bottom + 20; the legend sits below the lowest boundary (architecture).</li> <li><strong>Connector & markup hygiene</strong> — every connector <code><path></code> resolves to <code>fill="none"</code>; endpoints stop ~4px short of the target border and never reach inside a box; no <code>--</code> inside SVG comments (<code><!-- A -- B --></code> closes the comment early and leaks stray text into the document).</li> <li><strong>Mermaid fidelity (mermaid input only)</strong> — mechanized by <code>check_fidelity.py</code> above; run it and fix to <code>PASS</code>. It recounts against the source: node rects/pills == source node IDs (START/END pills added only for <code>[*]</code>); connector paths + <code>↻</code>-rendered loops == source edges after expanding chains and <code>&</code>; every node, edge, group, <strong>and legend</strong> label appears <strong>verbatim</strong> (legend entries merged from a 图例 subgraph included — keep their exact text). Without <code>python3</code>, recount by hand. Details in <code>references/mermaid-input.md</code>.</li> </ol> <p> Deliver the file only after a pass where nothing needed fixing. </p> <h2>Output contract</h2> <p> One self-contained <code>.html</code>: 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. </p>