# ProDyn motion guide

**Motion makes a state change legible. It does not stand in for one.**

This chapter connects ProDyn's visual language to authored interaction: a signal is acquired, an item retains its identity through a layout change, a headline resolves, an aperture follows a deliberate input. The aim is memorable, precise work that remains useful when still—not a page full of demonstrations.

[Visual guide](index.html) · [Patterns](patterns.md) · [Engines](engines.md) · [Authoring](authoring.md) · [Verification](verification.md) · [Brief](templates/motion-brief.md) · [Handoff](templates/handoff.md)

## Authority and scope

Read the [agent manual](../prodyn-threadline-design-system.md), [canonical tokens](../tokens.css), [motion registry](../registry/motion.html) and [font license gate](../../licenses/README.md) alongside this guide. The manual owns policy; `tokens.css` owns numeric design values; `tokens.json` mirrors them; visible specimens define construction. Implementation notes cannot overrule those sources.

**Canonical scope.** DSM v2.2 adds M15–M18 through the [machine-readable registry](registry.json), matching manual, token policy and visible specimens. Adopt that integrated revision as a unit, not an isolated draft or laboratory experiment. A library installation or capability-catalog entry is not primitive approval. Do not infer authorization for neighboring effects from these names.

- Preserve M1–M14, including their exact implementations and limits. This add-on does not retune them.
- **M8 remains the default whole-page atmosphere; M1 remains the default polished footer where appropriate.** Use the shared sources, not a shader or library imitation. Quiet reading/task surfaces may justify omitting atmosphere; omission is not permission to replace it with a novel effect.
- M10 remains explicitly technical/diagnostic, not a decorative page grid. M11/M12 require their operational context; never fabricate a live feed to justify them.
- **M13 requires explicit per-page approval**, lazy loading, containment and its static fallback. Another renderer does not provide a loophole around that gate.
- A library is an implementation mechanism, not a new brand primitive. New silhouettes, springs, shaders, scroll spectacles, audiovisual motifs or material behaviors need separate DSM review if the registry does not describe them.

## Start with the task and the still

Choose one primary surface before choosing an engine:

| Surface | Reader's task | Motion's job | Static baseline |
|---|---|---|---|
| Explore | Understand a relationship | Reveal one cause and consequence | Annotated diagram with ordinary controls |
| Inspect | Follow a selected object | Conserve identity and location | Selected item and readable detail |
| Operate | Make a deliberate change | Acknowledge input without delaying it | Immediate state, visible result/error |
| Monitor | Detect a real change | Localize meaningful new information | Timestamped state and trend; real data only |
| Learn | Read an argument | Pace an optional illustration | Complete linear text and figures |

Write a one-sentence motion brief: **“When [cause], [state changes]; [visual consequence] preserves [what the user must understand].”** If the consequence has no useful referent, remove it or make the artistic purpose explicit and request review.

Design entry, settled, error and reduced/static compositions first. Essential headings, copy, controls and destinations must exist outside canvases, export players and animation callbacks. Do not begin with invisible content that only becomes readable after a successful animation.

## Art direction: one foreground event

ProDyn's field is near-black, with ivory type mass, sparse cyan signal and quiet negative space. Use square geometry, hairline separators and deliberate left/asymmetric alignment. Copper and state colors mark exceptions within the manual's restraint limit; do not turn an escalation color into a decorative transition wash.

Build three layers:

1. **Reading layer:** stable type, logical order, controls and focus. Nothing atmospheric crosses or obscures this layer.
2. **Causal layer:** one selected route, conserved item, headline treatment or bounded aperture. Its scale and contrast communicate priority.
3. **Atmospheric layer:** the exact eligible registry implementation, subordinate to the other two. Do not combine unrelated loops merely because they fit behind the text.

Choreograph attention, not just properties. Establish a still; acknowledge input; show the relationship changing; stop in a meaningful pose. Use negative space as the stage rather than adding chrome around every moving object. Repetition should establish a grammar, not identical fade-ups on every section. A strong chapter cut can be immediate.

**Typography:** Oxanium for display; Departure Mono for short HUD/status roles. Use the canonical body fallback while PP Neue Machina remains license-gated; no PPNM font serving, embedding or outline conversion as a rights workaround. Preserve real text. Weight treatment should strengthen hierarchy, not make a paragraph breathe indefinitely.

## Timing and choreography

Read durations and easing from canonical tokens at runtime when JavaScript needs them. Preserve units: CSS durations may be seconds; WAAPI consumes milliseconds; an authored frame count needs the actual project frame rate and a recorded rounding policy. Do not scatter replacement literals throughout an engine adapter.

| Role | Existing token starting point | Direction |
|---|---|---|
| Acknowledge a local action | `--t-fast`, `--ease-hover` | Immediate semantic response; short visual confirmation |
| Resolve a bounded change | `--t-med`, `--ease-enter` | Converge on a stable state; no mandatory wait |
| Deliberate entrance | `--t-slow`, `--ease-enter` | Reserve for hierarchy, not every block |
| Existing atmosphere | Its exact registry source | Preserve the primitive's timing and composed freeze |

These are roles, not authorization to apply every token to every primitive. The [registry](registry.json) assigns **M15 `--t-slow` with `--ease-enter`; M16 `--t-med` with `--ease-enter`; M17 `--t-slow` with `--ease-enter`; M18 direct input mapping with no autonomous loop**. M18's native range is 0–1, mapped to normalized geometry; explicit Replay may run one finite transit using `--t-slow` and `--ease-enter`, canceled by new input. M1/M8 and other exact-source effects retain their specific timing. Numeric tokens are unchanged by this add-on; proposing a new amplitude, phase or easing is a design change, not an engine optimization.

**Sequence by dependency.** Commit selection first; animate its consequence second; reveal optional supporting detail only when useful. Labels describe actual state, not timeline progress. Network work completes when the operation completes—not when a flourish reaches its endpoint. A progress illustration must identify synthetic/demo progress and must never claim a real operation succeeded merely because its animation finished.

**Interruption is part of the design.** A new selection replaces old intent rather than queuing a ceremonial replay. Reset restores a defined state; cancel does not equal success. For direct manipulation, update the bounded scalar immediately; for a finite transition, settle or retarget from the current visible state. Document which behavior applies. Preserve explicit Pause across visibility and history changes.

## The four additions

| Primitive | Canonical semantic purpose | Bounded construction | Not included |
|---|---|---|---|
| [M15 · Signal acquisition](index.html#m15) | Explain acquisition/progress for one signal | SVG progress with a finite WAAPI presentation; semantic status independent of the clock | Fake telemetry, indefinite loading theater, arbitrary tracing effects |
| [M16 · Spatial continuity](index.html#m16) | Preserve item identity during semantic reordering | Persistent DOM items, actual order change, FLIP presentation | CSS-only visual reorder, route-transition system, arbitrary zoom/pin choreography |
| [M17 · Kinetic typography](index.html#m17) | Resolve or emphasize a short meaningful text unit | Original semantic text plus transient visual glyph/weight handling | Endless scramble, animated body prose, invented font axes, interactive descendants split apart |
| [M18 · Aperture transit](index.html#m18) | Expose a controlled relation between opening and position | One bounded scalar controls SVG aperture/path presentation and a DOM value | Full-page wipes, unrelated morphs, organic shader fields, hidden navigation |

Each primitive must identify its purpose, input range, owner, clock, settled pose, error behavior, interruption, reduced/static behavior and release method. The [pattern chapter](patterns.md) describes composition; the specimen remains the source for exact geometry and implementation.

## Ownership is a design constraint

Assign **one owner per animated property, one clock per continuous system, one semantic source of truth**. Keep layout, effect and content wrappers distinct when they need separate property ownership. Do not ask CSS, WAAPI, GSAP and Motion to drive `transform` on the same node. Avoid a second state machine hidden inside an asset that disagrees with the host.

A minimal controller has these responsibilities:

| Operation | Required meaning |
|---|---|
| `set(input)` | Validate finite/ranged data; commit host state; present it |
| `pause()` | Stop owned progression without discarding selection or focus |
| `resume()` | Resume only when policy, visibility and user intent permit |
| `reset()` | Invalidate pending completions and restore the documented baseline |
| `destroy()` | Idempotently release owned work; never destroy shared services |

These are interface roles, not required method names. Guard asynchronous work with an abort signal or generation identity. A late asset load must dispose its own resources rather than take control from the new selection. Semantic updates must remain possible after visual teardown.

Reduced motion is a live policy, not a startup-only checkbox. Use a composed final/current meaningful state; stop decorative interpolation explicitly. Near-zero CSS durations alone do not cancel WAAPI, a library ticker, a worker or audio. Provide a user pause/stop/hide mechanism for automatically moving content where the WCAG criterion applies; reduced-motion support is not a substitute for that control.[5][6]

## Delivery and adoption

Use native HTML/CSS/minimal JavaScript unless the existing application or authored requirement justifies more. Choose a library by the smallest necessary capability, its ownership/lifecycle fit, rights and measured cost—not by a showcase ranking. The [engine recipes](engines.md) cover alternatives without importing those runtimes into the DSM kit.

Use the [authoring contract](authoring.md) for editable assets, and the [verification gates](verification.md) for release evidence. A polished experience needs human composition and usability review as well as behavioral tests. A still proves composition at one moment; a test proves a specific behavior; neither alone proves audience understanding.

The [capability catalog](capability-catalog.json) preserves the original research IDs and independently labels lab exercise, documentary authoring, device gates and this repository's specimen relationship. The [source ledger](sources.json) contains selected atomic claims, quotations, dates and source conflicts. It does not ship vendor pages or establish all-library mastery. Treat its version records as a dated research snapshot, not “latest” recommendations.

## Sources

[5] https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html
[6] https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion