Diagram animation
Diagram animation is an optional presentation layer for explaining ordered change in a complete static diagram. It clarifies sequence, accumulation, evaluation, containment, or propagation without changing the diagram's meaning or weakening its use as an HTML, SVG, screenshot, print, or export artifact. See Diagram design for the wider design rules, Diagram style and primitives for the visual language, Diagram templates and Diagram example gallery for related patterns, and Diagram verification suite for checks.
Motion role
Motion must explain a static diagram rather than replace it. Static mode is the default, and animation is selected only when the order or change itself helps the reader understand the subject.
Static-first contract
The source HTML and SVG contain every semantic node, label, connector, status, and outcome before motion starts. CSS owns presentation, while minimal inline JavaScript binds explicit controls, updates state, and schedules deterministic steps. The enhancement may reveal or move marked items only after it initializes successfully. If JavaScript fails or is absent, the complete diagram remains visible.
This relationship keeps the same meaning in every delivery form:
flowchart LR
A[Complete source diagram] --> B{Motion requested?}
B -- No --> C[Stable static frame]
B -- Yes --> D[Progressive enhancement]
D --> E[Playback or one reveal]
D --> F[Reduced-motion or print]
F --> C
C --> G[PNG / SVG / screenshot]
data-motion-mode="none" is the safe default. The initial data-frame="static" state, static query, reduced-motion state, print output, no-JavaScript view, and standalone SVG export must show the complete frame. Motion does not add meaning to an unlabeled or over-dense diagram.
References: skills/…/animation.md• L1-3 skills/…/animation.md• L20-29 skills/…/SKILL.md• L519-527 skills/…/SKILL.md• L559-567
Mode selection
Each figure chooses one motion mode. The mode describes how the reader receives the change, so it must match the narrative rather than the visual type.
| Mode | Reader experience | Suitable use |
|---|---|---|
none | Complete stable figure | Default, print, screenshot, export, or no need for motion |
reveal | One deterministic autoplay run that ends complete | Short ordered explanation when autoplay was explicitly requested |
step | Paused semantic states with user controls | Teaching, comparison, policy traces, or careful inspection |
loop | One decorative token repeats without changing meaning | Quiet flow hint only |
Only loop repeats. Queue state, typing, field values, policy outcomes, containment, and audit entries use reveal or step and finish in the complete state. reveal is the only autoplay mode. It may run once on initial load when motion was explicitly requested and does not restart when the figure returns to the viewport.
References: skills/…/animation.md• L5-18 scripts/verify-motion.py• L16-18 scripts/verify-motion.py• L336-368
Motion patterns
Motion patterns give a small set of sanctioned ways to show change. Use one primary semantic story per figure and keep stable text, symbols, counts, and outlines as the source of meaning.
Primitive choices
The motion reference defines primitives for common explanations. Each primitive has a static result and a small limit so the figure stays easy to read. Every primitive also has text, a count, a symbol, a pattern, or an outline in addition to color.
| Pattern | Change shown | Static result and limit |
|---|---|---|
| Path draw | A route becomes visible | The labeled base connector remains; use no more than two paths and one active path |
| Staggered reveal | Ordered stages appear | All stages remain visible; use up to eight steps and twelve marked items |
| Queue counter | Items accumulate in stable slots | The final queue and numeric count remain; use up to five items with no reorder |
| Typing / field population | A value or field is populated | The full accessible string remains; use up to 32 characters or six fields |
| Policy evaluation | Rules are visited in order | Every state and outcome remains; use three to six rules and two traces |
| Flow token | One token travels along a fixed path | The token is decorative and hidden in static output; use one token with a cycle of at least three seconds |
| Containment | Children enter a labeled boundary | Children and the persistent boundary remain; use one boundary transition |
| Audit append | Log rows appear in time order | The complete ordered log remains; use up to five appended rows |
Motion must not animate layout coordinates, connector routes, the viewBox, node dimensions, or semantic text. Avoid zoom, parallax, bounce, shake, glow, particles, and indefinite blinking. Nothing may flash or change luminance more than three times per second. Never use color alone for a status such as pass, fail, queue fullness, or an outcome.
References: skills/…/animation.md• L31-46 skills/…/animation.md• L95-101 skills/…/semantic-patterns.md• L19-31 skills/…/semantic-patterns.md• L61-73
Semantic pattern alignment
The diagram's semantic pattern owns the story and its static evidence. Animation may support that story, but it cannot become a second pattern or reorder the facts.
- A fan-in queue can reveal arrivals and queue depth, but it must preserve slot order and show the final capacity and both outcomes.
- A structured-artifact flow can reveal source statements and fields, but the complete artifact and provenance remain readable without typing motion.
- A paired policy trace can step through rules and first divergence, but it must show
PASS,FAIL,SKIPPED, andNOT REACHEDas text and symbols. - A secure paved road can reveal approved and blocked routes, but the static frame must show every boundary and route.
The selected visual type still owns layout, connector, spacing, and type limits. When a pattern and a type both set a limit, use the stricter limit.
References: skills/…/semantic-patterns.md• L3-5 skills/…/semantic-patterns.md• L23-31 skills/…/semantic-patterns.md• L51-59 skills/…/semantic-patterns.md• L75-87 skills/…/semantic-patterns.md• L117-122
Motion templates and examples
Motion-enabled diagrams use a canonical template and a small set of examples. The template supplies the sanctioned playback contract; the examples show how to apply it to different semantic stories.
Canonical motion template
skills/…/template-motion.html is the starting point when motion is requested. Replace the page text, SVG content, and slug-prefixed IDs. Copy its inline controller verbatim and keep its motion state and control attributes unchanged because the skin linter treats that controller as the executable contract.
The template places controls outside the SVG and keeps a live status region inside the motion root. It decides static, reduced-motion, test-step, and playback behavior before it adds .motion-ready, so the complete source is not hidden until the enhancement has initialized. It also includes the complete-source fallback, static query behavior, reduced-motion rules, print rules, and a no-JavaScript note. Do not add a second controller or load a remote script.
References: skills/…/template-motion.html• L47-60 skills/…/template-motion.html• L137-170 skills/…/template-motion.html• L173-235 skills/…/template-motion.html• L237-430 skills/…/animation.md• L85-93
Reference examples
The shipped animated examples demonstrate motion as a teaching aid for semantic patterns rather than as decoration.
| Example | Motion story |
|---|---|
| example-queue-animated.html | A bounded queue fills, overflow is shed, workers process admitted traffic, and the system reaches controlled equilibrium |
| example-policy-trace-animated.html | Two traces follow shared rules until a first divergence, then show later skipped or not-reached states and final outcomes |
| example-paved-road-animated.html | An approved deployment follows its gates while an unauthorized bypass stops at the trust boundary and is audited |
These examples keep persistent structure visible while adding step groups for the changing event. The policy example is the clearest model for a comparison flow because its static frame retains both traces and names every state.
References: skills/…/example-queue-animated.html• L190-205 skills/…/example-queue-animated.html• L247-331 skills/…/example-policy-trace-animated.html• L180-197 skills/…/example-policy-trace-animated.html• L199-271 skills/…/example-paved-road-animated.html• L180-195 skills/…/example-paved-road-animated.html• L262-304
Accessible playback
Playback is an interface around the diagram, not a replacement for its accessible description. The SVG describes the complete subject, while visible instructions and a scoped status region explain how a person can inspect the motion.
Reduced-motion behavior
When prefers-reduced-motion: reduce is active, the figure opens at its complete static frame. It hides and disables playback controls, hides decorative movement, marks the reduced state, and reports that playback is unavailable. It never places a partial-step announcement beside a complete frame.
The SVG <title> and <desc> describe the complete meaning of the diagram. Decorative overlays such as duplicate draw paths and flow tokens use aria-hidden="true" and focusable="false", while semantic text exists only once in the accessibility tree.
References: skills/…/animation.md• L95-101 skills/…/template-motion.html• L151-170 skills/…/template-motion.html• L394-429
Control and keyboard behavior
Every interactive step figure provides native Play, Pause, Replay, Previous, and Next buttons outside the SVG. Each target is at least 44 by 44 pixels, has visible focus, and becomes disabled when playback is unavailable.
When focus is inside the motion root, the arrow keys move one step, Home resets, End completes, Space toggles playback when focus is not already on a button, and an unmodified R replays. Inputs, links, unrelated regions, and modified R shortcuts are left alone. The live status region announces user actions such as “Step 3 of 5” but does not announce every autoplay frame.
References: skills/…/animation.md• L85-93 skills/…/template-motion.html• L224-234 skills/…/template-motion.html• L323-351
Timing and capture
Motion uses one bounded clock so playback and capture remain predictable. The final artifact is captured from an explicit static state rather than from an assumed delay after page load.
Deterministic timing
Use the shared timing values of 160 ms for fast changes, 480 ms for steps, and 720 ms for holds. Keep transitions within 160–600 ms, holds within 400–1200 ms, and total autoplay between three and eight seconds. Most figures move marked items no more than 24 px. An exploded axonometric part may move by its declared explode distance. Nothing else may exceed the 24 px limit. Derive delays from integer steps and keep total autoplay at or below eight seconds. Use one timeout chain per motion root. Clear it on pause, replay, page hide, and completion. Do not use randomness, springs, transition-event timing, or setInterval.
Declare the step count and mark each semantic item with an integer step from 1 through 8. Keep DOM order in narrative order and reveal no more than two semantic items in one step. Pause when the document becomes hidden and do not catch up when it becomes visible again. A bounded ?motion=step&step=N override may expose an exact frame for visual regression only when N is a valid step from 0 through the declared count.
References: skills/…/animation.md• L20-29 skills/…/animation.md• L103-111 scripts/verify-motion.py• L327-369
Static capture and export
Use ?motion=static, <html data-motion="static">, or mode none to expose every semantic item, hide controls and decorative overlays, and set data-frame="static". Wait for document.fonts.ready before capture. The rendered clipping verifier uses this same static URL. Two captures with the same URL, viewport, fonts, and device scale must be pixel-identical.
PNG and SVG exports are final-state artifacts unless a user explicitly names a step. Capture the original HTML in static mode, then extract only the SVG; controls and scripts do not belong in the exported diagram.
References: skills/…/animation.md• L103-115 skills/…/export.md• L45-58 skills/…/template-motion.html• L137-149
Verification
Verification checks the motion contract before a figure reaches a reader. Automated checks focus on source completeness, bounded state, accessibility, deterministic behavior, and exact use of the approved controller.
Contract checks
Run the motion verifier, its adversarial tests, and the skin linter for an animated file:
python3 scripts/verify-motion.py path/to/animated-diagram.html
python3 scripts/test-verify-motion.py
python3 scripts/lint-skin.py path/to/animated-diagram.html
The verifier checks the mode and step declarations, contiguous steps, motion budgets, accessible SVG naming, visible no-JavaScript source, decorative accessibility, the full control set, live status, reduced-motion and print CSS, keyboard behavior, page-hide pause, bounded static and test overrides, immediate final-step stop, and exact canonical-controller identity. The semantic-motion checks also verify that the semantic-pattern router and 41-row visual-type guide remain present and ordered, that each routed pattern keeps its required fields and the animation vocabulary remains complete, and that the policy-trace example keeps its five-step route, explicit states, and stopped connector at the first failure. They also reject duplicate IDs, unsafe external assets, missing fallback controls, and non-deterministic timing in that example. Decorative motion items are excluded from the semantic step sequence and must be explicitly hidden from assistive technology.
References: skills/…/animation.md• L113-125 scripts/verify-motion.py• L279-490 scripts/verify-semantic-motion.py• L183-248 scripts/verify-semantic-motion.py• L251-408
Browser checks
After automated checks, inspect the same figure in the states that readers and downstream tools use:
- Disable JavaScript and confirm that the complete diagram remains visible and meaningful.
- Emulate reduced motion and confirm the complete frame, hidden controls, and unavailable-playback status.
- Use only the keyboard and confirm that focus stays in place while controls and step keys work.
- Pause, resume, and replay twice and confirm identical ordering and final state.
- Capture static mode twice after fonts load and compare the pixels.
- Check print, PNG, and SVG output for absent controls and decorative tokens with all semantic relationships intact.
References: skills/…/animation.md• L127-134 skills/…/SKILL.md• L473-491
Anti-patterns
The following choices break the static-first contract or make motion carry meaning that the static artifact must carry instead:
- Unrequested autoplay, autoplay outside the single sanctioned
revealrun, viewport re-entry, or an endless semantic loop. - A blank or partial no-JavaScript or reduced-motion frame.
- Motion that rescues an over-dense or unlabeled static diagram.
- Pass/fail, queue fullness, or outcome encoded only by hue.
- Remote scripts, general application logic, runtime geometry, or duplicated semantic text.
- Capture at wall-clock delay instead of the explicit static override.
References: skills/…/animation.md• L136-143
Change checklist
When these files or sections are changed, remember to consider these:
- When references/animation.md or assets/template-motion.html changes, keep the verifier's canonical controller, state names, control actions, and fallback rules aligned.
- When a motion example changes its semantic pattern, update its marked step order, static outcome, accessible labels, and the matching semantic-motion verifier contract.
- When the SVG content or IDs change, preserve the title-first accessible SVG structure and keep all HTML and SVG IDs unique within the page.
- When export behavior changes, preserve the static query, font-ready capture point, rendered clipping check, and omission of controls and scripts from extracted SVG output.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
Semantic items are hidden before .motion-ready is added | No-JavaScript users see a blank or partial diagram | Keep the source complete and scope hiding below .motion-ready |
A queue, policy result, or audit record uses loop | Important meaning repeats forever or never reaches a stable result | Reserve loop for one decorative token; use reveal or step for semantic change |
| A controller is edited or a second controller is added | The skin linter and motion verifier reject the figure | Copy the controller from template-motion.html verbatim |
| Reduced motion leaves controls or a partial frame visible | Users who request less motion receive an unsafe or confusing state | Render the complete static frame and hide or disable playback |
| Capture waits for an arbitrary wall-clock delay | PNG, SVG, or screenshot output changes between runs | Use ?motion=static and wait for document.fonts.ready |
| A semantic status is shown by color alone | Readers can miss pass, fail, capacity, or outcome meaning | Keep text, symbols, counts, or outlines in the static figure |
Key files
| File | Why to read it |
|---|---|
| skills/…/animation.md | Defines sanctioned modes, static-first rules, primitives, accessibility behavior, timing, capture, and anti-patterns |
| skills/…/template-motion.html | Provides the canonical motion page and controller that animated diagrams must use |
| skills/…/example-queue-animated.html | Shows a step-based queue and bottleneck explanation with stable capacity evidence |
| skills/…/example-policy-trace-animated.html | Shows paired rule evaluation, first divergence, and explicit terminal states |
| skills/…/example-paved-road-animated.html | Shows approved and blocked security routes with a stable audit result |
| scripts/verify-motion.py | Enforces the general motion, accessibility, timing, and controller contract |
| scripts/verify-semantic-motion.py | Enforces semantic-pattern routing, pattern fields, the animation vocabulary, and the policy-trace example contract |
| scripts/test-verify-motion.py | Proves that common motion-contract violations are rejected |