motion-figure

动效图形

此技能用于制作会动或能响应输入的图形。它分为三个层级。可将此技能与 Claude、Cursor、Codex、OpenClaw、Hermes 或任何能读取 SKILL.md 的 Agent 配合使用。

层级	制作内容	使用位置
1. 课程图形	声明式 SMIL 动画，或可重新绘制 SVG 的滑块小组件。两者都通过 ```figure 代码围栏挂载。	课程内容
2. 机制图形	一个展示系统各命名部分的 HTML 面板。读者操作一个控件，并查看计算得出的结论。	独立页面、README、文章，以及课程站点中课程内容以外的页面
3. 抖动场	纸张色、强调色和墨色的有序抖动点 WebGL 色带，包含四种带种子的动态效果。	页面页眉和章节分隔处

层级 1 的规则最多，因为课程运行时有严格限制。层级 2 和 3 各有自己的参考文件。

适用场景

• 课程讲解随时间变化的过程：在不同阶段间移动的令牌、逐渐填满的队列、重复执行的循环。
• 课程讲解输入变化会影响输出的公式：学习率、温度、块大小、批次大小。
• 作者提出“为这个图形添加动画”“添加滑块”或“让图表可交互”。
• 页面需要一个演示，让读者改变一个条件并查看系统的反应：缓存、队列、上下文窗口、路由器。使用层级 2。
• 页面需要一个采用课程配色、缓慢移动的页眉。使用层级 3。

不适用场景

• 概念是没有时间轴和输入的固定结构。请制作静态 SVG 图形。配套技能 blueprint-figure 涵盖静态图形。
• 页面是拥有自身状态模型和机械几何结构的完整讲解页。配套技能 isometric-explainer 涵盖此类页面。
• 你只需要调色板、字体或文案规则。配套技能 course-style 包含这些内容。此技能会将所需部分复制到 references/tokens.md。

方法

1. 用一句话说明图形展示的唯一变化。如果需要两句话，就制作两个图形。

2. 选择层级。在课程内容中使用层级 1。使用层级 2 时，阅读 references/mechanism-figures.md 并从 templates/mechanism.html 开始。使用层级 3 时，阅读 references/dither-fields.md 并复制 templates/dither.js。以下步骤适用于层级 1。在层级 1 中，时间是变量时使用动画图形；数字是变量时使用滑块小组件。

3. 选择一个 kebab case 名称，例如 request-path 或 context-budget。先在注册表中搜索该名称。后续注册同一名称的模块会替换较早的图形。

4. 将代码放入名为 figures-<topic>.js 的模块文件。用 IIFE 包裹，读取 window.LF，若不存在则提前返回。

5. 编写图形函数 function (host, cfg)。它会向 host 追加一张 .lf 卡片，并可以返回一个 dispose 函数。

6. 构建卡片：.lf-head 中包含大写的 .lf-label 和简短提示，另有 .lf-body，以及包含说明文字的 .lf-cap。

7. SVG 使用 viewBox="0 0 520 H"。大多数课程图形的 H 为 200 至 250。单个条形图所需高度更小。

8. 添加 <title> 和 <desc>，其 id 只需在渲染函数之外各创建一次。

9. 对于动画图形，先添加条目，再创建一个缓慢循环。逐行遵循 references/smil-rules.md。

10. 对于滑块小组件，先定义 state._render，再调用 LF.slider 或 LF.select。最后调用一次 state._render()。

11. 在模块末尾调用 LF.register({ 'your-name': fn })。

12. 在课程 Markdown 中添加代码围栏。名称放在第一行，可选的 JSON 配置紧随其后：

    ```figure
    context-budget {"windowK": 32}
    ```
    

13. 运行“完成前检查”中的检查。在浅色主题、深色主题、375 px 宽度以及开启减少动态效果的情况下查看图形。

页面如何挂载图形

• Markdown 解析器会将围栏代码块转换为 <div class="lesson-figure" data-figure="name {json}">。
• 站点构建流程会扫描课程 Markdown 中的围栏名称，找到包含该名称的模块文件，并生成清单。没有提供程序的围栏名称会导致构建失败。
• 页面只加载课程所需的模块，并按固定顺序加载。新的模块文件排在列出的文件之后，并按字母顺序排列。
• 挂载函数将第一个词读取为名称，并将其余内容解析为 JSON。JSON 格式错误时，cfg 为空。
• 如果图形函数抛出异常，运行时会清空宿主元素并记录警告。课程的其余部分仍会正常呈现。
• 挂载后，如果标题、描述、role="img" 和控件标签不存在，运行时会添加它们。如果图形包含 SMIL 动画，运行时会添加“暂停”按钮；如果有任何动画只播放一次，则会添加“重播”按钮。
• 图形离开视口、标签页被隐藏或读者按下“暂停”按钮时，运行时会暂停动画。在启用减少动态效果或打印时，会显示静态帧。

references/toolkit.md 介绍了所有运行时函数，并提供两个完整的示例模块。

规则

动画图形：

1. 仅使用 <animate>、<animateTransform> 和 <animateMotion>。不要在图形中使用 setInterval 或 requestAnimationFrame。
2. 每个图形最多包含 55 个 SVG 元素。
3. 入场动画从不透明度 0、缩放比例 0.95 变为不透明度 1、缩放比例 1。缩放比例绝不能从 0 开始。
4. 入场动画使用 calcMode="spline" 和 keySplines="0.23 1 0.32 1"。入场时长为 0.5 到 0.6 秒。
5. 入场动画的延迟依次增加 0.05 到 0.4 秒。退场动画的时长要短于入场动画。
6. 循环动画持续 2.5 到 6 秒，并使用 repeatCount="indefinite"。不要在循环动画上设置 fill="freeze"，否则运行时会让它只播放一次。
7. 每个 keyTimes 列表的项数必须与 values 相同。列表从 0 开始，以 1 结束，且数值不能递减。
8. 每个 keySplines 列表的项数必须比 keyTimes 少一项。仅在使用 calcMode="spline" 时使用它。
9. 带有 keyPoints 的 animateMotion 使用 calcMode="linear"。其 keyPoints 的项数必须与 keyTimes 相同。它不能有 values。
10. 不要在动画的 fill 或 stroke 值中使用 var()。改为对具有目标颜色的第二个元素进行不透明度动画。
11. 循环动画只能对不透明度、变换、stroke-dashoffset 或沿路径的运动进行动画处理。对 x、y、x1、y1、x2、y2、width、height、r、cx、cy、rx 或 ry 进行的动画，运行时都会让它只播放一次。
12. 宿主元素的 data-static-time（默认为 1.5 秒）所对应的帧必须完整且易于阅读。如果较晚的时刻才显示完整状态，请在宿主元素上设置该属性。
13. 围绕元素中心进行缩放。将组的内容绘制在 (0, 0) 附近，并通过 translate 移动该组。使用 additive="sum" 添加缩放。

滑块控件：

14. 仅使用 ES5：var、函数表达式和字符串拼接。不要使用箭头函数、let、const 或模板字面量。
15. 在第一次调用 LF.slider 或 LF.select 前定义 state._render。创建滑块时，它会包装渲染函数。
16. 在 state._render 中移除所有 SVG 子元素，再重新添加。不要原地编辑节点。
17. 在 state._render 外创建一次 ID。运行时会移除新节点中不存在的属性，包括 ID。
18. 通过增加长度或调整路径的 stroke-dasharray 来延长条形。不要通过缩放来延长条形，因为经过协调的节点会从中心缩放。
19. 每个滑块标签都要简短、使用小写字母，并将单位放在括号内，例如 chunk size (tokens)。

两类共通规则： 20. 从 CSS 变量中获取所有颜色，并将浅色主题的值设为默认值，例如 var(--blueprint,#3553ff)。只有在没有可用变量时才使用十六进制字面值。 21. 主体最多使用一种强调色（--blueprint），第二种状态可使用 --warn。其余部分使用 ink 和 rule 令牌。 22. 将 SVG 文本设为 12 个单位或更大，并使用 var(--font-mono)。如果标签必须更小，则将 SVG 的最小宽度设为 500 px，并允许横向滚动。 23. 在手机上测量标签尺寸。在 375 px 的屏幕上，卡片内一个 520 单位宽的 SVG 显示为 279 px 宽。此时，12 单位的标签显示为约 6.4 px。 24. 使用简洁的技术英语撰写说明文字。说明每种颜色代表什么。每个句子不超过 25 个单词。 25. 在 .lf-label 中使用全大写标签，包含两到四个单词。

机制图（第 2 层）：

26. 显示真实名称和真实数字：文件名、键、令牌计数。不要使用 item 1，也不要使用没有名称的灰色条。
27. 提供一种让读者控制的操作：分步、滑块、切换、播放或停止其中一部分。
28. 以文字形式的结论行结尾，结论根据正文中的数字计算得出。不要写固定结果。
29. 当图示有 35 percent 可见时运行一次，添加 Replay 按钮，并且不要循环播放。
30. 仅对 transform 和 opacity 设置动画，并使用 cubic-bezier(0.23, 1, 0.32, 1)。按下时长为 120 至 160 ms，显示时长为 200 至 300 ms，折叠时长为 380 至 500 ms。
31. 列表项之间依次延迟 30 至 70 ms，仅限前 8 项。
32. 确保所有标签在每一帧都完整显示：不使用省略号、不重叠、不在圆点上放置文本。文本不小于 11 px，结论不小于 12.5 px。
33. 在 320 px 宽度下，将面板纵向排列为一列，并将每个控件的触控区域设为 40 px。
34. 使用网站上其他页面都未使用的机制，并将其添加到网站的机制表中。

抖动场（第 3 层）：

35. 从 --bg、--blueprint 和 --ink 读取颜色，并在 data-theme 变化时重新绘制。
36. 最多以每秒 30 帧绘制，且仅在色带可见时绘制。
37. 启用减少动态效果时，绘制一帧静态画面。没有 WebGL 时，显示静态交叉影线。
38. 将色带标记为 aria-hidden="true"，除标签芯片外，不要在圆点上放置文本。

完成前检查

• 围栏名称与注册名称完全一致，且没有其他模块注册该名称。
• 模块中没有 =>、let、const 或反引号字符串。
• 模块中没有 setInterval 和 requestAnimationFrame。
• references/smil-rules.md 中的验证器对已挂载的宿主返回空列表。
• 每个动画图示的 SVG 元素不超过 55 个。
• 每个循环的时长为 2.5 至 6 s。
• 没有循环动画会为规则 11 中的几何属性设置动画。
• 开启减少动态效果后，图示显示完整画面，且没有元素缺失。
• 在深色主题下，每条线和每个标签都清晰可见。
• 在 375 px 宽度下，每个标签都清晰可读，且图示之外的页面不会横向滚动。
• 对于小部件，将每个滑块移至最小值和最大值时，都不会出现 NaN、负宽度或控制台错误。
• SVG 有一个标题和一个描述，且滑块移动后，它们的 id 保持不变。
• 说明文字指出图示使用的每种颜色。
• 第 2 层：references/mechanism-figures.md 末尾清单中的每项检查均通过。
• 第 3 层：references/dither-fields.md 末尾清单中的每项检查均通过。

文件

• references/smil-rules.md：完整列出 12 条 SMIL 规则、每条规则所防止的问题，以及可在浏览器控制台中运行的验证器。
• references/toolkit.md：LF 函数和挂载顺序。还包含完整的滑块小组件、完整的 SMIL 图，以及可在课程网站之外使用的预览页。
• references/tokens.md：浅色和深色主题的颜色令牌、字体和动效时长值。
• references/mechanism-figures.md：第 2 层。真实名称、被拒绝的图示、机制形状、解剖结构、判定结果、动效预算和检查项。
• references/dither-fields.md：第 3 层。着色器的绘制方式、四种动效、标记、规则、抖动条和检查项。
• templates/mechanism.html：完整的第 2 层图示，即带有尺寸控制的 LRU 缓存，可在任何浏览器中打开。
• templates/dither.js：完整的第 3 层脚本。加载该脚本并添加 <div class="dither" data-seed="...">。

在 AI Engineering from Scratch 仓库中，还可查看运行时文件 site/lesson-figures.js 和更多图示文件 site/figures-*.js。