motion-figure

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 is 0.5 to 0.6 s.
5. Stagger entry begins by 0.05 to 0.4 s. Exits are shorter than entries.
6. Loops last 2.5 to 6 s and use repeatCount="indefinite". Do not set fill="freeze" on a loop, because the runtime then plays it once.
7. Each keyTimes list has as many entries as values. It starts at 0, ends at 1, and never decreases.
8. Each keySplines list has one entry fewer than keyTimes. Use it only with calcMode="spline".
9. An animateMotion with keyPoints uses calcMode="linear". Its keyPoints count equals its keyTimes count. It has no values.
10. Do not put var() in an animated fill or stroke value. Animate the opacity of a second element that has the target colour.
11. Loops animate only opacity, transform, stroke-dashoffset, or motion along a path. The runtime makes any animation of x, y, x1, y1, x2, y2, width, height, r, cx, cy, rx, or ry play once.
12. The frame at the host's data-static-time (default 1.5 s) is complete and readable. Set the attribute on the host when a later moment shows the full state.
13. Scale an element around its centre. Draw the content of a group around (0, 0) and move the group with translate. Add the scale with additive="sum".

Slider widgets:

14. Write ES5 only: var, function expressions, string concatenation. No arrow functions, let, const, or template literals.
15. Define state._render before the first LF.slider or LF.select call. The slider wraps the render function when you create it.
16. In state._render, remove all SVG children and add them again. Do not edit nodes in place.
17. Create ids once, outside state._render. The runtime removes attributes that the new nodes do not have, ids included.
18. Grow bars by length or by stroke-dasharray on a path. Do not grow bars with scale, because reconciled nodes scale from their centre.
19. Keep each slider label short and lowercase with the unit in brackets, for example chunk size (tokens).

Both kinds:

20. Take every colour from a CSS variable with the light theme value as its default, for example var(--blueprint,#3553ff). Use literal hex only when no variable works.
21. Use at most one accent colour (--blueprint) for the main subject and --warn for one second state. Use ink and rule tokens for the rest.
22. Set SVG text at 12 units or larger, in var(--font-mono). If labels must be smaller, give the SVG a minimum width of 500 px and let it scroll sideways.
23. Measure label size on a phone. On a 375 px screen, a 520-unit SVG inside the card drew 279 px wide. A 12-unit label then drew at about 6.4 px.
24. Write the caption in plain technical English. Name what each colour means. Keep sentences at 25 words or fewer.
25. Give the label in .lf-label in uppercase, two to four words.

Mechanism figures (tier 2):

26. Show real names and real numbers: file names, keys, token counts. Never item 1 or a grey bar with no name.
27. Give the reader one control: step, slider, toggle, play, or stop a part.
28. End with a verdict line in text, computed from the numbers in the body. Never write a fixed outcome.
29. Run once when 35 percent of the figure is visible, add a Replay button, and never loop.
30. Animate transform and opacity only, with cubic-bezier(0.23, 1, 0.32, 1). Press 120 to 160 ms, reveal 200 to 300 ms, fold 380 to 500 ms.
31. Stagger lists by 30 to 70 ms per item, for the first 8 items only.
32. Keep every label whole at every frame: no ellipsis, no overlap, no text on dots. Text 11 px or more, verdict 12.5 px or more.
33. At 320 px, stack the panels in one column and give each control a 40 px touch target.
34. Use a mechanism that no other page on the site uses, and add it to the site's mechanism table.

Dither fields (tier 3):

35. Read the colours from --bg, --blueprint, and --ink, and redraw when data-theme changes.
36. Draw at 30 frames per second at most, and only while the band is visible.
37. With reduced motion, draw one static frame. Without WebGL, show a static hatch.
38. Mark the band aria-hidden="true" and put no text on the dots except the label chip.

Check before you finish

• The fence name matches the registered name exactly, and no other module registers it.
• The module has no =>, let, const, or backtick strings.
• The module has no setInterval and no requestAnimationFrame.
• The validator in references/smil-rules.md returns an empty list for the mounted host.
• Each animated figure has 55 SVG elements or fewer.
• Every loop has a duration from 2.5 to 6 s.
• No loop animates a geometry attribute from rule 11.
• With reduced motion on, the figure shows a complete picture and no element is missing.
• In dark theme, every line and label is visible.
• At 375 px width, every label is readable and the page has no sideways scroll outside the figure.
• For a widget, moving each slider to its minimum and maximum gives no NaN, no negative widths, and no console errors.
• The SVG has one title and one description, and their ids stay the same after a slider moves.
• The caption names every colour that the figure uses.
• Tier 2: every item in the checklist at the end of references/mechanism-figures.md passes.
• Tier 3: every item in the checklist at the end of references/dither-fields.md passes.

Files

• references/smil-rules.md: the twelve SMIL rules in full, what each rule prevents, and a validator you can run in the browser console.
• references/toolkit.md: the LF functions and the mount sequence. It also has a complete slider widget, a complete SMIL figure, and a preview page for use outside the course site.
• references/tokens.md: colour tokens for light and dark themes, fonts, and motion timing values.
• references/mechanism-figures.md: tier 2. Real names, rejected figures, mechanism shapes, anatomy, verdict, motion budget, and checks.
• references/dither-fields.md: tier 3. How the shader draws, the four motions, markup, rules, dithered bars, and checks.
• templates/mechanism.html: a complete tier 2 figure, an LRU cache with a size control, that opens in any browser.
• templates/dither.js: a complete tier 3 script. Load it and add <div class="dither" data-seed="...">.

Inside the AI Engineering from Scratch repo, also see site/lesson-figures.js for the runtime and site/figures-*.js for more figures.