/motion-figure

name: motion-figure
version: 1.1.0
description: >
  Builds figures that move or respond to the reader, in three tiers: SMIL animations and slider
  widgets inside lessons, interactive mechanism figures that show the named parts of a real
  system with a computed verdict, and ordered dither bands in the course palette. Triggers:
  "animated figure", "add a slider widget", "interactive figure", "show how this system works",
  "make this diagram move", "dither masthead", "mechanism figure", "figure fence".
tags: [figures, svg, smil, animation, interactive, dither]

Motion figure

This skill makes figures that move or respond to input. It has three tiers. Use this skill with Claude, Cursor, Codex, OpenClaw, Hermes, or any agent that reads SKILL.md.

| Tier | What it makes | Where it goes | |---|---|---| | 1. Lesson figure | Declarative SMIL animation, or a slider widget that redraws an SVG. Both mount from a ```figure fence. | Course lessons | | 2. Mechanism figure | An HTML panel that shows the named parts of a system. The reader drives one control and reads a computed verdict. | Standalone pages, READMEs, essays, the course site outside lessons | | 3. Dither field | A WebGL band of ordered dither dots in the paper, accent, and ink colours, with four seeded motions. | Page mastheads and section breaks |

Tier 1 has the most rules, because the lesson runtime has hard limits. Tiers 2 and 3 have their own reference files.

When to use

• A lesson explains a process that changes over time: a token that moves through stages, a queue that fills, a loop that repeats.
• A lesson explains a formula where one input changes the output: learning rate, temperature, chunk size, batch size.
• An author writes "animate this figure", "add a slider", or "make the diagram interactive".
• A page needs a demo where the reader changes one thing and sees what the system does: a cache, a queue, a context window, a router. Use tier 2.
• A page needs a slow moving header in the course colours. Use tier 3.

When not to use

• The idea is a fixed structure with no time axis and no input. Make a static SVG figure. The sibling skill `blueprint-figure` covers static figures.
• The page is a full explainer page with its own state model and machine geometry. The sibling skill `isometric-explainer` covers that.
• You only need palette, fonts, or prose rules. The sibling skill `course-style` holds those. This skill copies the parts it needs into `references/tokens.md`.

Method

1. Write one sentence that names the single change the figure shows. If you need two sentences, make two figures. 2. Pick the tier. Inside a lesson, use tier 1. For tier 2, read `references/mechanism-figures.md` and start from `templates/mechanism.html`. For tier 3, read `references/dither-fields.md` and copy `templates/dither.js`. The steps below are for tier 1. In tier 1, use an animated figure when time is the variable. Use a slider widget when a number is the variable. 3. Pick a name in kebab case, for example `request-path` or `context-budget`. Search the registry for that name first. A later module that registers the same name replaces the earlier figure. 4. Put the code in a module file named `figures-<topic>.js`. Wrap it in an IIFE, read `window.LF`, and return early if it is missing. 5. Write a figure function `function (host, cfg)`. It appends one `.lf` card to `host` and can return a dispose function. 6. Build the card: `.lf-head` with an uppercase `.lf-label` and a short hint, `.lf-body`, and `.lf-cap` with the caption. 7. Use `viewBox="0 0 520 H"` for the SVG. Most course figures use an H from 200 to 250. A single bar needs less. 8. Add a `<title>` and a `<desc>` with ids that you create once, outside any render function. 9. For an animated figure, add entries first, then one slow loop. Follow `references/smil-rules.md` line by line. 10. For a slider widget, define `state._render` before you call `LF.slider` or `LF.select`. Then call `state._render()` once at the end. 11. Call `LF.register({ 'your-name': fn })` at the end of the module. 12. In the lesson Markdown, add the fence. Put the name on the first line and optional JSON config after it:

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

13. Run the checks in "Check before you finish". Look at the figure in light theme, dark theme, at 375 px width, and with reduced motion on.

## How the page mounts a figure

- The Markdown parser turns the fence into `<div class="lesson-figure" data-figure="name {json}">`.
- The site build scans lesson Markdown for fence names. It finds the module file that contains the quoted name and writes a manifest. A fence name with no provider stops the build.
- The page loads only the modules that the lesson needs, in a fixed order. New module files go after the listed ones, in alphabetical order.
- The mount function reads the first word as the name and parses the rest as JSON. Bad JSON gives an empty `cfg`.
- If the figure function throws, the runtime empties the host and logs a warning. The rest of the lesson still renders.
- After mount, the runtime adds a title, a description, `role="img"`, and control labels if they are missing. It adds a Pause button when the figure has SMIL animation, and a Replay button when any animation plays once.
- The runtime pauses animation when the figure leaves the viewport, when the tab is hidden, and when the reader presses Pause. With reduced motion or print, it shows the static frame.

`references/toolkit.md` describes every runtime function and has two complete example modules.

## Rules

Animated figures:

1. Use only `<animate>`, `<animateTransform>`, and `<animateMotion>`. Do not use `setInterval` or `requestAnimationFrame` in a figure.
2. Keep each figure at 55 SVG elements or fewer.
3. Entries go from opacity 0 and scale 0.95 to opacity 1 and scale 1. Never start a scale at 0.
4. Entries use `calcMode="spline"` and `keySplines="0.23 1 0.32 1"`. Entry duration i