dashmotion

Dashmotion

创建专业的动画技术图表，并保存为独立的 HTML 文件。名称即实现方式：stroke-dashoffset 动画 + animateMotion——仅此而已。输出为矢量格式，无限循环，文件仅几 KB，可在任何浏览器中打开。

步骤 1 — 选择模式

用户需求	模式	阅读
步骤、序列、分支、并行执行、状态转换（“发生了什么，以及按什么顺序发生”）	Flow	references/flow-mode.md + resources/template-flow.html
组件、服务、基础设施、包含关系、拓扑（“系统由什么构成”）	Architecture	references/architecture-mode.md + resources/template-architecture.html

混合需求（“展示我们的微服务，以及订单如何在其中流转”）→ 使用 Architecture 模式；动画请求路径就是流程。只有当流程包含拓扑无法表达的分支逻辑时，才生成两个独立文件。

Mermaid 输入——如果请求包含 Mermaid 源码（```mermaid 代码块、.mmd 文件或粘贴的代码），请先阅读 references/mermaid-input.md。支持的类型：flowchart/graph 和 stateDiagram-v2；不支持其他图表类型——请说明这一点并提供替代方案。仍按上述模式路由（mermaid 是语法，不是语义），且无论源代码声明的方向如何，都会始终从上到下重新计算布局。

开始前请先阅读模式参考文件。 其中的布局计算方式是 scripts/layout.py（步骤 5）的实现依据——阅读它，以便构建清晰的语义图，并将颜色、形状和动画样式层应用到脚本生成的几何布局上（以及在必要时手动计算备用方案）。其中说明了如何避免常见问题：重叠、箭头穿过方框、循环中断。

步骤 2 — 两种动画约定（适用于两种模式）

流动虚线连接线 — stroke-dashoffset

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

• 偏移量的变化值 MUST 等于一个完整的 stroke-dasharray 周期（此处为 5+5=10），否则循环时会明显跳变。
• 负偏移量会沿路径的绘制方向流动 → 连接线的 d 始终要从源节点绘制到目标节点。
• 0.6–0.9s 看起来像“电流”；慢于 1.5s 则像是断路。

移动的圆点 — <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 原样复用连接线的 d；圆点会精确地沿线移动。
• 圆形不设置 cx/cy——由 animateMotion 负责定位。
• 使用 begin="0.7s" 等设置错开时间。每张图总共放置 3–6 个圆点；将它们放在能清楚体现方向的位置（扇出、汇合、主要请求路径），不要每条边上都放。
• 在 Architecture 模式中，圆点在语义上代表正在传输的请求/消息——请沿真实的端到端路径安排圆点。

步骤 3 — 通用设计标记

• 页面：#020617，40px 网格图案（#0f1b33，线条宽 0.5px）；本机安装时使用 JetBrains Mono，否则使用系统等宽字体栈（ui-monospace, 'SF Mono', 'Cascadia Code', Menlo, Consolas, monospace）——不获取网络字体，文件完全独立。
• 文本：标签为 #e2e8f0、13px/500，副标签为 #64748b、10px，图例为 11px。
• 节点圆角 rx="8"；START/END 药丸形节点的 rx = 高度/2。
• 所有连接线共用一个使用 context-stroke 的箭头标记（继承每条线的颜色）：

<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>

• 连接线端点应在距离节点边缘 4px 处停止，以免箭头刺穿边框。
• 每个连接线 <path> 都 MUST 设置 fill="none"（或放在 <g fill="none"> 中）——SVG 默认填充黑色；若未设置此属性，L 形路径会渲染成巨大的黑色多边形。
• 绘制顺序：网格 → 连接线 → 圆点 → 节点。节点会遮住线条末端；圆点会消失在节点“内部”，而不会从节点上滑过。
• ViewBox：0 0 W H，其中 H = 最低元素底部 + 50。坐标不得为负数。

第 4 步 — 无障碍与动画效果（不可妥协）

• 将所有 CSS 动画都放在 @media (prefers-reduced-motion: no-preference) 中。
• SMIL 会忽略该媒体查询 → 保留模板内的脚本：在启用减少动态效果时移除 .dot 元素，并接入可见的 ⏯ 暂停开关（animation-play-state: paused + svg.pauseAnimations()）。
• SVG 添加 role="img"、<title> 和 <desc>。

第 5 步 — 生成文件

dashmotion 自带确定性布局引擎 scripts/layout.py（仅使用标准库）。它会完成模式参考中描述的坐标计算——行排列、分支间距、边界内边距、正交轨道／泳道布线——并渲染最终 HTML：几何图形 + 模式样式层 + 你的文案。因此，你不必手动计算坐标，也不必把 35 个 rect 和 38 个 path 的 d 手动抄进模板（这两项都很耗时）。你决定语义和文案；脚本生成文件。完整约定见 references/layout-script.md。

脚本路径 — 只要有 python3 就使用：

1. 将请求——或根据 references/mermaid-input.md 处理 Mermaid 源码——解析为 references/layout-script.md 中定义的语义图 JSON。这是你的判断层，其中包含图表所需的一切：
   • 结构：节点（架构图使用 type + tier——未分组／单组架构图省略 tier（引擎会自动分层），多组架构图需填写，详见 layout-script.md；每个节点用 group 表示边界成员关系；流程图的 shape 仅为药丸形和判断节点填写——绝不能写 "shape": "step"，步骤节点省略此项）、边（kind）、组、旅程、任何 legendExtra、classDef 保留信息；
   • 文案：title、subtitle，以及（架构图的）恰好包含三张卡片的 summary（accent 为 cyan/violet/rose，包含 title、items[]）——面向用户的措辞由你决定，并直接写入 JSON。
2. 将其写入临时路径，而非输出文件夹——例如 "$TMPDIR/dashmotion-graph.json"（或任意 mktemp 路径）——然后运行 python3 <this-skill-directory>/scripts/layout.py "$TMPDIR/dashmotion-graph.json" --render <topic>-dashmotion.html。语义 JSON 是临时构建文件；交付的 HTML 不依赖它，所以绝不要将 JSON 与 .html 放在一起——用户的文件夹中应只包含最终图表。脚本会计算几何布局、应用样式层（按 type 设置节点填充和描边、生成不透明底色 + 样式矩形遮罩对、按边的 kind 设置 flow/flow-async/flow-auth 连接线类、为每段旅程设置点的颜色并错开、串联 begin）、插入你的文案，并写入完整、独立、可直接交付的文件。标记为 "loop": true 的边会渲染为 ↻ label 注释，而不是路径。
3. 使用该文件执行第 6 步。渲染器生成的结构本身可靠，但第 6 步仍是最终依据——务必执行。
4. 你对所有视觉效果保有最终决定权：若要调整措辞、强调效果、旅程或类型，编辑 JSON 并重新渲染（成本低且结果确定）；若要手动微调标签或颜色，直接编辑生成的文件。你不再需要做的是抄录坐标——脚本负责几何布局（方案 A），现在也负责其外围模板代码。

不要先生成 JSON，然后又手动编写 HTML——这样会重新引入这条路径本要省去的抄录工作。渲染、检查、交付。

**手动计算备用方案 — 仅在没有 python3 时使用：**按照模式参考明确完成布局计算后再填写坐标，复制模板，替换 SVG 内容／标题／页眉／图例／摘要卡片（保留 CSS + 暂停开关 + 减少动态效果脚本），复制连接线的 d 值并错开 begin，挑选 3–6 条点路径。这是 2.2 之前的做法——较慢，但无需 Python。

告诉用户该文件可直接在任何浏览器中打开。

GIF/MP4 导出（仅在要求时）

切勿手动渲染帧。对打开的文件进行屏幕录制（macOS ⌘⇧5），或使用无头模式： npx timecut <file.html> --viewport=1200,900 --duration=3 --fps=30 --output=flow.mp4，然后运行 ffmpeg -i flow.mp4 flow.gif。 当所有时长都能整除 3 秒时，3 秒的录制片段可以无缝循环——如果目标是导出 GIF，优先使用 0.75 秒 / 1.5 秒 / 3 秒。

第 6 步 — 结构自检（交付前）

文件写好并不代表完成——通过这项检查才算完成。--render 输出在结构上必然可靠，但仍必须进行检查（这也能保护你使用手工计算的备用方案，因为其坐标会以可预见的方式出错——连接线层出错的频率远高于文本层）。请验证，不要想当然。

机械化路径（只要有 python3 就使用）： 对刚写好的文件运行随附的检查器 —

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

该检查器会确定性地检测以下故障类型（重叠、连接线穿过方框、虚线循环接缝、越界、点不在线上、黑色填充、端点穿透、悬空的 begin 引用、格式错误的 XML）。修复所有报告的问题并重新运行，直到显示 0 violations。如果有脚本可用，切勿手动逐项计算；切勿编写自己的临时验证脚本；切勿通过打开浏览器或截图来验证——脚本才是权威依据。对于脚本无法检查的项目（标签碰撞、精确的边界留白、图例位置），仍需通过阅读数值来检查。

如果输入是 Mermaid，还要机械化地重新核对保真度（检查清单第 6 项）：将源内容保存到临时 .mmd 文件并运行 —

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

修复问题，直到显示 PASS。它会验证源节点 / 边 / 分组标签是否都以原文出现，以及连接线数量是否与源边数量一致。因此，标签和图例条目必须与源内容完全一致——不要改写，不要把两个源字符串合并为一个，也不要添加括号（图例条目 v2 点线橙框 必须保持为 v2 点线橙框，绝不能改成 v2 治理骨架（点线橙框））。这与结构检查一样，属于容易漏检的问题：光靠文字说“我保留了原文”会漏掉实际偏差；脚本不会。

文字备用方案（仅在没有 python3 时使用）： 按照实际数值，用算术逐项验证下列内容（写出比较过程），不要凭目测代码。修复所有问题并重新检查，直到清单中没有任何问题。

1. 重叠 — 对每一对同行元素：left.x + left.width + gap ≤ right.x（gap ≥ 20 流程图 / 40 架构图）。对每一对上下堆叠的元素：top.y + top.height + gap ≤ bottom.y。边界必须将其子元素完整包含在内，且四边的内边距均 ≥ 20px；任意两个框之间出现部分重叠都属于错误。
2. 连接线穿过框 — 逐段检查每条路径：线段端点之间不得进入任何节点矩形。检查每条水平线的 y 是否穿过矩形（rect.y ≤ y ≤ rect.y + height 即为碰撞）；垂直线段的 x 也要同样检查。通过按线轨模式重新布线来修复，不要为了避让而挪动框，导致其他问题。
3. 动画循环 — 对每个动画类：|stroke-dashoffset delta| 必须是 stroke-dasharray 周期总和的整数倍（例如 5 5 → 10），包括内联覆盖了 dasharray 的连接线（用 -10 关键帧为异步的 2 4 边设置动画，每个循环都会出现接缝——请为它单独设置关键帧）。对每个 animateMotion，明确指出它沿着哪一条连接线的 d 运动——跨越两条连接线的点路径会直穿它们之间的组件；应改为拆分成按跳逐段衔接的点。每个 begin="X.end+…" 都必须引用一个存在的 id。
4. ViewBox 边界 — 任何坐标都不得为负；每个矩形的 x+width/y+height 以及每个路径坐标都必须位于 0 0 W H 内；H ≥ 最低元素底部 + 20；图例位于最低边界下方（架构图）。
5. 连接线与标记规范 — 每条连接线 <path> 最终都应设置 fill="none"；端点应在目标边框前约 4px 处停止，不得伸入框内；SVG 注释中不得包含 --（`` 会提前结束注释，并将多余文本泄漏到文档中）。
6. Mermaid 保真度（仅限 Mermaid 输入） — 通过上文的 check_fidelity.py 机械校验；运行该脚本并修复问题，直到结果为 PASS。脚本会与源文件重新计数：节点矩形/胶囊 == 源节点 ID（仅为 [*] 添加 START/END 胶囊）；连接线路径 + 渲染为 ↻ 的循环 == 展开链和 & 后的源边；每个节点、边、分组和图例标签都必须逐字一致（包括从 图例 子图合并而来的图例条目——保持原文）。没有 python3 时，请手动重新计数。详情见 references/mermaid-input.md。

只有在通过检查且无需再修复任何问题后，才能交付文件。

输出要求

一个独立的 .html 文件：包含内嵌 CSS、内联 SVG，不使用外部资源、没有 JS 依赖——仅允许约 15 行的内联暂停/减少动态效果脚本。直接从文件系统打开时也能正确渲染。