# dashmotion

Adopt this skill: https://proskills.md/skills/other/csthink-dashmotion-skills-dashmotion

Page: https://proskills.md/skills/other/csthink-dashmotion-skills-dashmotion
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/dashmotion/SKILL.md
size: 8078
upstream: https://github.com/csthink/dashmotion/blob/main/skills/dashmotion/SKILL.md

````text
---
name: dashmotion
version: 2.2.4
description: 'Create dark-themed, animated technical diagrams as self-contained HTML+SVG files — flowcharts whose connectors visibly flow, and architecture diagrams where requests travel as light dots through the system (Diagrid/Temporal landing-page style). Use this skill whenever the user asks for a flowchart, workflow, pipeline, process diagram, state machine, system architecture, infrastructure, cloud, microservices, or network topology diagram — and especially when they mention "animated", "flowing", "dynamic", "alive", "GIF-like", or want a diagram for a landing page, README, docs, or product demo. Also use it to convert Mermaid source (a mermaid code block or .mmd file) into an animated diagram — "animate this mermaid", "make this flowchart move". Prefer this over static diagram output whenever the diagram represents anything that moves: requests, events, data, jobs, messages, or control flow.'
---

# Dashmotion

Create professional animated technical diagrams as single self-contained HTML files. The name is the implementation: `stroke-dash`offset 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`

```css
.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>`

```svg
<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):

```svg
<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 `d`s 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 constru
````

## File: README.md
upstream: https://github.com/csthink/dashmotion/blob/main/README.md

````text
# Dashmotion

English | [简体中文](https://github.com/csthink/dashmotion/blob/main/README.zh-CN.md)

[![version](https://img.shields.io/badge/version-2.2.4-10b981?style=flat&labelColor=0b1226)](https://github.com/csthink/dashmotion/releases)
[![license: MIT](https://img.shields.io/badge/license-MIT-64748b?style=flat&labelColor=0b1226)](https://github.com/csthink/dashmotion/blob/main/LICENSE)
[![live demo](https://img.shields.io/badge/▶%20live%20demo-22d3ee?style=flat&labelColor=0b1226)](https://csthink.github.io/dashmotion/)

**Diagrams that move.**

A Claude skill for animated technical diagrams — from plain English or Mermaid, as one self-contained HTML/SVG file.

Turn a plain-English description — or a Mermaid source — into an animated diagram: one HTML/SVG file, no dependencies, where dashed connectors stream in the direction of execution and light dots travel through the system like requests in flight. The style you see on modern infra landing pages (Diagrid, Temporal, Inngest).

[![Dashmotion animating a checkout request through a Kubernetes architecture — ingress → cart → payments → Postgres, plus a Kafka async event to a worker](https://github.com/csthink/dashmotion/raw/main/examples/images/k8s-hero.gif)](https://csthink.github.io/dashmotion/)

**[▶ Watch real diagrams run live →](https://csthink.github.io/dashmotion/)** — unedited skill output, not a video.

> ⭐ If dashmotion saved you from hand-drawing a diagram, [a star](https://github.com/csthink/dashmotion) helps others find it.

## Two modes

| Flow mode | Architecture mode |
| --- | --- |
| [![flow demo](https://github.com/csthink/dashmotion/raw/main/examples/images/flow-demo.gif)](https://github.com/csthink/dashmotion/blob/main/examples/images/flow-demo.gif) | [![architecture demo](https://github.com/csthink/dashmotion/raw/main/examples/images/architecture-demo.gif)](https://github.com/csthink/dashmotion/blob/main/examples/images/architecture-demo.gif) |

## What it does

The name is the implementation: `stroke-dashoffset` offset animation + `animateMotion` paths — no libraries, no GIF rendering, no design tools.

- **Inputs (today):** a natural-language description, or a Mermaid `flowchart` / `graph` / `stateDiagram-v2` source — the same animated result either way.
- **Output styles (today):** **Flow** — workflows, pipelines and state machines, where execution visibly streams from START to END through branches and merges; and **Architecture** — systems and topology, with semantic component colors, region/security boundaries, a legend, and the differentiator: animated request journeys, a dot hopping client → gateway → service → database and back.
- **Refine in plain language:** *"make the auth path stand out"*, *"put Redis next to Postgres"*, *"split the workers into a second diagram."*
- **The output is dependency-free:** one HTML file — vector, loops forever, a few KB, opens in any browser.

## Quick start

Then just ask — one sentence is enough to see it work:

```
Use dashmotion to draw a simple 3-step login flow.
```

The two longer prompts below generated the demos at the top — paste either to reproduce it:

**Flow** — the left demo:

```
Use dashmotion to visualize our CI/CD pipeline: a commit runs lint, unit tests and integration tests in parallel; all three merge into building a Docker image; then a security scan; then a deploy to staging; then a manual approval gate — approved deploys to production and posts a Slack notification, rejected notifies the author and ends.
```

**Architecture** — the hero above:

```
Use dashmotion to draw our Kubernetes microservices platform and animate the main request path: an NGINX ingress in front; users, catalog, cart and payments services in the 'shop' namespace; a Kafka bus between the services and two async workers (email worker, analytics worker); PostgreSQL for orders and MongoDB for the catalog; Prometheus and Grafana in an observability namespace. Animate a checkout request from ingress through cart and payments to PostgreSQL, plus an async event from payments through Kafka to the email worker.
```

**A few things worth knowing:**

- Each generation lays things out a little differently — yours won't be pixel-identical to the demo, but it's the same diagram.
- You don't have to spell everything out: point it at a design doc (*"use dashmotion to draw the architecture in `docs/design.md`"*) or just ask for a flowchart / architecture diagram of what you're building.
- Already have the diagram as Mermaid? Paste it — see [Mermaid input](#mermaid-input) below.
- Don't like the result? Say so in plain language and it refines from there.

## Install

Needs a Claude plan that includes skills (Pro, Max, Team, or Enterprise).

**Claude Code** — one command:

```bash
npx skills add csthink/dashmotion -a claude-code -g
```

**claude.ai** — download `dashmotion.zip` from [Releases](https://github.com/csthink/dashmotion/releases) → Settings → Capabilities → Skills → + Add → upload → toggle on.

<details>
<summary>Why <code>-a claude-code</code>, and global vs. project?</summary>

- **`-a claude-code`** writes a plain *copy* (into `~/.claude/skills/` with `-g`, or `./.claude/skills/` without). The bare `npx skills add csthink/dashmotion` makes a *symlink* instead, and Claude Code's symlink handling is rough — the link may not get created, a symlinked skill doesn't appear in `/skills` ([claude-code#14836](https://github.com/anthropics/claude-code/issues/14836)), and `npx skills update` won't refresh it. A copy lists in `/skills` and updates cleanly. If the CLI ever prompts copy-vs-symlink, choose **copy** (or pass `--copy`). Other agents (Cursor, Codex, …) read `~/.agents/skills/` directly and work fine with the bare command.
- **Global (`-g`)** lives in `~/.claude/skills/`, available everywhere. **Project-local** (no `-g`) lives in `./.claude/skills/` — scoped to that one directory, and handy to commit alongside a repo so your team gets the skill.

Prefer the zip on Claude Code? `rm -rf ~/.claude/skills/dashmotion && unzip dashmotion.zip -d ~/.claude/skills/` — clear the folder first when upgrading so old files don't linger.
</details>

<details>
<summary>Upgrading, auto-update &amp; uninstall</summary>

No Claude client tells you when a skill has a new version — you pull updates yourself. On **Claude Code**, one command refreshes it in place:

```bash
npx skills update dashmotion -g -y
```

Name the skill: a bare `npx skills update -g -y` updates **every** globally-installed skill, not just dashmotion — which may pull updates into others you didn't mean to touch. Drop `-g` for a project-local install; re-running the install command works too. On **claude.ai** there's no in-place update — delete the old skill and upload the new `dashmotion.zip`.

**Check which version you're on** — it lives in the skill's `SKILL.md`; compare it against the latest [release](https://github.com/csthink/dashmotion/releases) (`npx skills list` shows the path, not the version):

```bash
grep '^version:' ~/.claude/skills/dashmotion/SKILL.md     # project-local: ./.claude/skills/dashmotion/SKILL.md
```

**Hands-off: auto-update on every session (Claude Code)** — add a `SessionStart` hook so Claude Code refreshes the skill each time it starts. In `~/.claude/settings.json`:

```json
{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup", "hooks": [
        { "type": "command", "command": "npx skills update dashmotion -g -y >/dev/null 2>&1 || true" }
      ] }
    ]
  }
}
```

It costs a short network call at startup and silently keeps you on the latest tag. Widen the command to `npx skills update -g -y` to auto-update *all* your global skills.

**Uninstall:**

```bash
npx skills remove dashmotion -g         # installed via the skills CLI (drop -g if project-local)
rm -rf ~/.claude/skills/dashmotion      # installed by unzipping (use ./.claude/... for project-local)
```
</details>

## Mermaid input

Already have the diagram as Mermaid? Paste it — dashmotion turns a st
````
