stylegallery 0.1.4 → 0.1.7

package/motion/accessible-motion.md

@@ -0,0 +1,90 @@
+---
+type: Domain Guide
+title: Accessible Motion And Equivalent Feedback
+description: Separate motion preferences, automatic updates, flashing, and semantic feedback before designing reduced-motion behavior.
+domain: motion
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Accessible Motion And Equivalent Feedback
+
+Primary role: source-backed motion accessibility decision guide.
+
+## Repository Boundary
+
+This page owns product-motion decisions and their evidence requirements. Shared [accessibility evidence](../quality/evidence/accessibility.md) governs conformance claims. No motion values or decorative declarations become reusable Layout CSS.
+
+## Reusable Method
+
+Inventory each effect by trigger, duration, affected area, information conveyed, and available controls. Evaluate the separate source conditions below; one reduced-motion media query is not a complete accessibility review. Then specify an equivalent path that exposes the same information and actions with less movement.
+
+### What The Sources Establish
+
+| Source | Bounded finding | Decision it informs |
+| --- | --- | --- |
+| [WCAG 2.2 SC 2.3.3 explanation](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) | The AAA criterion concerns disabling interaction-triggered motion animation unless essential. | Identify extra movement induced by scrolling, dragging, expanding, or changing routes. |
+| [SC 2.2.2 explanation](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html) | The A criterion has distinct conditions for automatically moving information and automatically updating information. The latter has no five-second exception. | Audit rotating content and live updates separately from a short transition. |
+| [SC 2.3.1 explanation](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html) | Flash evaluation includes frequency and defined area/luminance thresholds. | A pause button cannot substitute for evaluating flashing content. |
+| [Media Queries Level 5](https://www.w3.org/TR/mediaqueries-5/#prefers-reduced-motion) | `prefers-reduced-motion` exposes a preference; it does not select an application-specific replacement. | Author the replacement and verify preference changes. |
+| [SC 4.1.3 explanation](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | Status information can require programmatic exposure without moving focus. | Preserve feedback when a spinner, movement, or success effect disappears. |
+
+WCAG Understanding pages are informative explanations of the [normative WCAG 2.2 requirements](https://www.w3.org/TR/WCAG22/). Media Queries Level 5 is a Working Draft. These sources do not establish implementation support for a particular browser or certify a product.
+
+### Classify Before Replacing
+
+| Product behavior | Local replacement proposal | Failure to look for |
+| --- | --- | --- |
+| Scroll-linked zoom into a product detail | Keep the reading sequence; switch details at explicit boundaries or expose them together. | Essential copy is available only at an intermediate animation frame. |
+| Reordering a list | Update the order and selection immediately; provide a concise completion message if needed. | Visual order changes while reading order or selected identity does not. |
+| Loading shimmer | Use a stationary placeholder and textual waiting state. | The placeholder is mistaken for loaded content or the request appears to have stopped. |
+| Modal entrance | Present the usable modal immediately, with the same focus and dismissal contract. | Focus is delayed until a completion event that never fires in reduced mode. |
+| Automatically advancing announcement | Provide durable stop/control behavior appropriate to the applicable criterion. | Moving focus elsewhere restarts an update the user had paused. |
+| Success celebration | Retain the durable success state and next action. | Removing confetti also removes the only completion signal. |
+
+These are proposed product choices, not W3C-prescribed recipes. A fade is another effect to evaluate; reducing translation does not prove that every replacement is comfortable.
+
+### Preference Changes During Work
+
+Record whether an in-product setting inherits the system preference or further reduces motion. Define how an active effect settles when the effective preference changes. The settlement must preserve the current task, release transient visual resources, and make the destination usable. Avoid replaying an entrance merely because the preference changed back.
+
+Separate pausing the presentation from pausing the underlying process. A dashboard may stop replacing visible figures while data collection continues. A resumed display must say whether it shows current information or replays buffered history. For transaction feedback, stopping an animation never means a server write was cancelled.
+
+## Opinionated Guidance
+
+Start with a complete stationary interaction, then add motion with a named explanatory purpose. This makes the no-motion path directly inspectable. Keep user-chosen pauses durable across focus changes and make preference controls reachable before the effect they govern.
+
+Do not infer an accessibility need from a device class. The effective preference, explicit user action, and actual interaction matter more than a touch/desktop label.
+
+## Platform-Specific Guidance
+
+Web CSS and script-driven effects need a coordinated preference owner. Native Reduce Motion behavior belongs to its named OS/API; see [Preferences And Accessibility](../platform-guides/preferences-and-accessibility.md). Animated media, canvas, and embedded content require their own controls and evidence because disabling a CSS transition does not govern them.
+
+## Unsupported Absolutes
+
+“Under five seconds is accessible,” “a crossfade is always safe,” and “the media query makes the page WCAG AA compliant” are unsupported. A criterion's conformance level is not a reason to claim that another criterion covers its behavior.
+
+## Verification Contract
+
+The following cases are unexecuted test designs. Record actual outcomes in the consumer's evidence, including source revision, browser/OS, input, effective preference, and the asserted result.
+
+| Case | Required observation |
+| --- | --- |
+| Reduced motion is active before load | Essential content and actions appear without waiting for motion. |
+| Preference changes halfway through a transition | The active task settles once; no stranded overlay, stale focus, or rejected-promise error remains. |
+| Keyboard activates the same action | The destination and feedback match the pointer path. |
+| Animation support is removed | The state transition still completes. |
+| User pauses automatic information, then tabs away | The pause persists; resumption follows the documented policy. |
+| Visual completion feedback is removed | The result remains available visually and through relevant assistive technology. |
+
+Source inspection verifies the criterion distinctions. DOM checks can verify state and focus; recordings can reveal movement. Neither alone establishes vestibular comfort or screen-reader announcement behavior. Re-review when source conditions, effect ownership, or the target runtime changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis. All linked external sources were inspected on 2026-09-21. No upstream prose, example code, or assets are reproduced. `consumer_reference: not_applicable` because this guide selects no consumer implementation record.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Interruption And Retargeting](interruption-and-retargeting.md).

package/motion/decision-tree.md

@@ -0,0 +1,70 @@
+---
+type: Domain Guide
+title: Motion Decision Tree
+description: Choose a motion responsibility from a user task, state change, and failure case.
+domain: motion
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Motion Decision Tree
+
+Primary role: motion selection workflow.
+
+## Repository Boundary
+
+Use this route to decide whether a product interaction needs motion and which behavior contract to write. Layout continues to own final geometry, semantic order, and scrolling. This route selects a responsibility, not a timing preset.
+
+## Reusable Method
+
+1. Write the before and after state without animation. If either is unusable, fix that state first.
+2. Name the information motion would add: acknowledgement, continuity, progress, or guidance. If none is needed, use an immediate update.
+3. Choose the first matching responsibility below; compose only when one transition has multiple explicit jobs.
+4. Complete the [Motion Brief](motion-brief.md), including interruption and a reduced-motion path.
+5. Use an [Interaction Recipe](interaction-recipes.md) and verify through the [Review Workflow](review-workflow.md).
+
+## Selection Table
+
+| Observed task | Choose | Failure to prevent | First verification |
+| --- | --- | --- | --- |
+| Explain an already rendered effect | [Vocabulary](vocabulary.md) | Inferring an API from appearance | Exact, ambiguous, and unknown observations |
+| Acknowledge a command | [Action feedback](interaction-recipes.md#action-feedback) | Decorative feedback mistaken for successful completion | Pending, success, failure, repeated activation |
+| Show or hide supporting content | [Disclosure](interaction-recipes.md#disclosure) | Hidden content retaining focus or delayed access to content | Keyboard activation and reversal |
+| Enter or dismiss a modal task | [Modal transition](interaction-recipes.md#modal-transition) | Focus or input blocking tied to an animation timer | Focus entry, cancellation, return |
+| Preserve identity when items move | [Reorder and filter](interaction-recipes.md#reorder-and-filter) | Visual movement changing logical reading order | Stable identity and focused-item removal |
+| Explain an operation that takes time | [Progress and completion](interaction-recipes.md#progress-and-completion) | An invented percentage or success before confirmation | Delayed result, cancellation, failure |
+| Follow direct manipulation | [Drag and settle](interaction-recipes.md#drag-and-settle) | A cancelled gesture committing data | Release, reversal, cancellation, alternative input |
+| Explore a product through scroll-controlled chapters | [Scroll-driven story](interaction-recipes.md#scroll-driven-story) | Entry callbacks mistaken for continuous progress; inaccessible pinned content | Reverse, jump, middle reload, static reading |
+| Navigate a whole page as fixed-viewport scenes | [Full-viewport scene navigation](interaction-recipes.md#full-viewport-scene-navigation) | Gesture bursts skipping chapters; trapped input or lost history | Burst, boundary, direct link, Back, Escape, native copy scroll |
+| Decorate an idle surface | [Practice Reference](practice-reference.md) | Repetition competing with the user's task | Compare against removal and reduced motion |
+
+## Worked Selection
+
+A search result list changes after a filter selection. The task is to understand which results remain; it is not to watch every row arrive. Choose reorder/filter only if stable result identities can be preserved. Keep the filter control focused. Announce the resulting count separately from any visual interpolation. When no results remain, present an actionable empty state immediately. If identity cannot be mapped reliably, replace the list without implying continuity.
+
+The decision record is a proposal until tested on the consuming product. It does not establish that motion improves search comprehension.
+
+## Opinionated Guidance
+
+Prefer one explanatory event over a sequence of unrelated effects. Evaluate high-frequency interactions with realistic repetition; a first-use recording can hide accumulated cost.
+
+## Platform-Specific Guidance
+
+Choose implementation APIs only after the behavior contract. Native gestures, browser navigation, scroll timelines, and animation libraries have different cancellation and lifetime behavior. Platform adaptation starts at [Platform Guides](../platform-guides/index.md).
+
+## Unsupported Absolutes
+
+An immediate update is a valid outcome. A recipe name does not imply a spring, compositor execution, fixed duration, or proven usability improvement.
+
+## Verification Contract
+
+For the selected row, verify normal completion, interruption, repeated input, the reduced-motion path, and a failed or empty result where relevant. Record the actual outcome separately from the expected outcome. Revisit this route when a task cannot find a suitable contract or two recipes imply conflicting ownership.
+
+## Source, License, And Attribution
+
+Locally authored selection workflow based on this domain's existing vocabulary and review contracts. No external code or expressive examples are adapted.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Motion Brief](motion-brief.md).

package/motion/index.md

@@ -8,17 +8,36 @@ In scope: naming observable motion, reviewing declared behavior, distinguishing
 
 Out of scope: universal timing or easing rules, unmeasured performance claims, and permission to add animation or decorative properties to reusable Layout pattern CSS.
 
+## Start Here
+
+| Task | Route |
+| --- | --- |
+| Choose a behavior from the user task. | [Motion Decision Tree](decision-tree.md) |
+| Record states, owners, interruption, and evidence. | [Motion Brief](motion-brief.md) |
+| Build a scroll-driven product story and inspect runnable examples. | [Scroll-driven Story](interaction-recipes.md#scroll-driven-story) and [Scroll Story Lab](../examples/scroll-story/README.md) |
+| Keep the page fixed while navigating between full-screen chapters. | [Full-viewport Scene Navigation](interaction-recipes.md#full-viewport-scene-navigation) and [runnable example](../examples/scene-navigation/README.md) |
+| Apply feedback, disclosure, modal, reorder, progress, and drag contracts. | [Motion Interaction Recipes](interaction-recipes.md) |
+
+These workflows and worked cases are usable experimental guidance. Expected-result tables are test designs; actual product, engine, and reader evidence must be recorded separately. Review on a failed task, a source change, or a changed ownership contract.
+
 ## Documents
 
 - [Motion Vocabulary](vocabulary.md) maps observed behavior to implementation-neutral terms while preserving ambiguity.
 - [Motion Review Workflow](review-workflow.md) structures evidence-first review and remediation.
 - [Motion Practice Reference](practice-reference.md) classifies mechanics, heuristics, platform notes, and unsupported claims.
+- [Observed Choreography Transcription](observed-choreography.md) transcribes an observed scroll choreography into Scene Composition Contract vocabulary.
+
+## Source-Backed Deep Dives
+
+- [Accessible Motion And Equivalent Feedback](accessible-motion.md). Separate motion preferences, automatic updates, and equivalent feedback.
+- [Interruption And Retargeting](interruption-and-retargeting.md). Resolve repeated input, cancellation, and stale completion callbacks.
+- [Motion Rendering And Performance](rendering-and-performance.md). Choose native mechanisms and diagnose measured delivery failures.
 
 ## Domain Contract
 
-See [StyleGallery Domains](../DOMAINS.md) for lifecycle, provenance, page membership, and promotion rules.
+See [StyleGallery Domains](../DOMAINS.md) for lifecycle, provenance, page membership, and staleness rules.
 
 ## IA Navigation
 
 Parent: [StyleGallery](../index.md).
-Next: [Motion Vocabulary](vocabulary.md).
+Next: [Motion Decision Tree](decision-tree.md).

package/motion/interaction-recipes.md

@@ -0,0 +1,170 @@
+---
+type: Domain Guide
+title: Motion Interaction Recipes
+description: State-based product motion recipes for feedback, disclosure, modal transitions, rearrangement, progress, and dragging.
+domain: motion
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Motion Interaction Recipes
+
+Primary role: motion behavior catalog.
+
+## Repository Boundary
+
+These recipes describe product behavior and failure cases. They compose with Layout instead of supplying reusable spatial CSS or visual defaults. Start with a [Motion Brief](motion-brief.md); use [Vocabulary](vocabulary.md) for the visual effect's name.
+
+## Reusable Method
+
+Choose the task below, assign semantic and presentation owners, implement the immediate state change first, and then test any visual interpolation against that baseline. The traces below are expected behavior, not evidence of a tested implementation.
+
+### Action Feedback
+
+Use for a command whose acknowledgement and completion are different events.
+
+`ready → pending → success | error`; a retry is a new request. Press feedback may acknowledge input immediately, but a success treatment waits for actual confirmation. Decide explicitly whether repeated activation is ignored, queued, or replaces the request. Keep essential status available without motion. Test delayed completion, duplicate input, failure, and a response arriving after navigation.
+
+### Disclosure
+
+Use for optional content controlled by a nearby trigger. A native `details`/`summary` baseline can be enough:
+
+```html
+<details>
+  <summary>Delivery restrictions</summary>
+  <p>Some destinations need an additional delivery day.</p>
+</details>
+```
+
+If a custom disclosure is necessary, keep the trigger's expanded state consistent with content availability. The [APG disclosure contract](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) describes button activation and state semantics. When closing while focus is inside, move focus to an available logical target before hiding it. Test repeated toggle, long content, and removal of the trigger. Avoid fixed maximum heights that clip real content; Layout owns intrinsic sizing.
+
+### Modal Transition
+
+Use when a temporary task must block the surrounding interface. Assign one owner to opening, focus placement, blocking, cancellation, and focus return. An entrance effect may decorate this change; semantic availability must not wait for an arbitrary timeout. If exit animation is retained, define whether the dialog remains modal until cleanup and how reopening supersedes a pending close.
+
+The [APG modal dialog guidance](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) supplies the web interaction baseline. Test close during entry, reopen during exit, nested overlays, trigger removal, and reduced motion. After final close there must be no surviving blocker or focus trap.
+
+### Reorder And Filter
+
+Use when the same identifiable items move or are removed. Commit the intended logical order, retain stable item keys, and interpolate presentation only where the source/destination mapping is valid. Preserve focused items; if one disappears, choose a documented neighboring item or controlling filter. Do not reorder DOM solely to produce a pleasing stagger.
+
+Trace: filter A → filter B → late A data → B remains current. Test empty results, long item labels, list updates during movement, keyboard navigation, and a focused item's removal. An immediate redraw is the fallback when continuity cannot be established.
+
+### Progress And Completion
+
+Use when an ongoing operation needs visible status. Show determinate progress only when backed by a meaningful measurement; otherwise use a pending state. Completion, failure, and cancellation come from the operation, independently of the progress decoration.
+
+Trace: pending → cancellation requested → confirmed cancelled or completed; do not promise cancellation succeeded before the operation confirms it. Essential information persists beyond a transient flourish. Use urgent alerts sparingly; [APG alert guidance](https://www.w3.org/WAI/ARIA/apg/patterns/alert/) distinguishes announcements from focus-taking dialogs.
+
+### Drag And Settle
+
+Use when direct manipulation previews a change before commitment. Separate the preview value from the committed value. Release on a valid target commits; cancellation restores or reconciles with the current model. A new gesture retargets from the presented position where continuity is intended. Provide a task-equivalent non-drag operation.
+
+The non-drag operation has two separate audiences. [WCAG 2.2 Success Criterion 2.5.7 Dragging Movements](https://www.w3.org/TR/WCAG22/#dragging-movements) (Level AA) asks that functionality operated by dragging also be achievable with a single pointer without dragging: a click or tap, not a held path. Its [Understanding document](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html) states that keyboard equivalence does not meet this criterion by itself unless those controls can also be clicked or tapped, and that the keyboard and single-pointer requirements are evaluated independently. A sortable list with arrow-key reordering therefore still needs pointer-operable move controls, and move buttons that only respond to a pointer still need keyboard operation.
+
+Two exceptions bound the criterion. Dragging may remain the only pointer method when it is essential to the task, and the criterion does not cover dragging that the user agent determines and the author has not modified, such as native scrolling. The alternative cannot itself be a path-based gesture such as a swipe or flick; the Understanding document's own examples are tapping a slider track, move controls beside a sortable item, and a text input for a precise value. It does cover content that suppresses native scrolling and interprets the drag itself, which includes a custom carousel, a canvas pan, or the art-surface swipe in [full-viewport scene navigation](#full-viewport-scene-navigation). Record an essential claim with its reason rather than assuming it.
+
+Failure cases: the alternative exists only in a keyboard handler; the alternative appears only on hover, so touch cannot reach it; the alternative commits a different value or skips the validation that release performs; the alternative moves the item but leaves focus or the announced position on the old location.
+
+Test release inside/outside, cancellation, pointer loss, a changing destination, and repeated reversal. Run the same task three ways (drag, single-pointer activation without movement, keyboard only) and compare the committed value and the final focus. Focus and the selected item must remain traceable while visual position changes. The engine or browser adapter owns gesture events; the product owns acceptance of the new value.
+
+### Scroll-Driven Story
+
+Use when a visitor explores a product through ordered visual chapters: scroll a phone into view, enlarge the device, change its screen, then release the scene into the next section. The story is presentation; scrolling must not commit a payment or other application action.
+
+| Responsibility | Contract | Failure to exercise |
+| --- | --- | --- |
+| Scroll reveal | Entry triggers a time-based effect; declare once or replay | Re-enter, preference change, content hidden before script starts |
+| Scroll scrub | Position continuously determines a bounded progress value | Reverse, jump over a segment, load at the middle |
+| Pinned story | Document scroll advances a locally sticky stage | Short viewport, long copy, wrong ancestor overflow, release boundary |
+| Layered parallax | Each decorative layer maps progress to a bounded displacement | Cropping, text overlap, reduced-motion alternative |
+| Media sequence | Progress requests an image frame or media time | Slow decode, stale completion, missing frame, unavailable media |
+
+The [Scroll Story Lab](../examples/scroll-story/README.md) links runnable Flow and headphones examples, a native CSS scrub, source files, and observed verification. It implements scrub, pinning, scene crossfades, and a small image sequence. Parallax and video seeking remain contracts rather than claimed executed examples.
+
+#### Scene Composition Contract
+
+Layout owns document scroll, the containing block, sticky offset, available stage height, and track distance. Motion owns progress, scene ranges, continuity, and teardown. The consuming product owns imagery, typography, colors, and visual values. First compose `stack`, `content-limiter`, and `overlay-stack` responsibilities with local sticky positioning; a new Layout pattern requires a distinct demonstrated spatial failure.
+
+Record `start`, `distance`, `scene_ranges`, `resize_policy`, `direct_entry`, `static_path`, and `media_budget` alongside the [Motion Brief](motion-brief.md). For positive distance, clamp `(scroll_position - start) / distance` to `[0, 1]`; a nonpositive distance selects the static path. Derive the entire scene from current progress, not from which callbacks have already fired. This makes reversal and skipped segments well defined.
+
+The worked three-scene example centers chapters at progress 0, 0.5, and 1. Copy crossfades between centers while decorative scale and position interpolate. These values are local choices, not universal timing or easing defaults. No wheel interception or artificial scroll smoothing is needed for the example.
+
+#### Implementation And Fallback
+
+Choose the smallest rendering mechanism that meets the contract. CSS scroll/view timelines suit declarative interpolation; a scheduled JavaScript renderer can coordinate semantic availability and decoded media. Feature detection only chooses an implementation candidate, not a supported-device claim. The lab demonstrates CSS continuous rotation separately from its JavaScript three-scene controller; it does not claim visual parity between them.
+
+Keep all chapters in ordinary semantic HTML before enhancement. In animated mode, only the presented chapter is available to interaction and accessibility APIs; a visible reading-mode control exposes every chapter in order. Provide a skip link outside the changing panels. Do not put essential actions only inside a fading chapter. Narrow or low windows, overflowing copy, no script, and reduced motion must retain a readable path. React to preference changes during use.
+
+Cache geometry on layout changes, batch scroll updates, and avoid a perpetual idle animation loop. Recompute on resize, delayed fonts/images, and history restoration. Dispose observers, queued frames, and stale media callbacks on removal. A restored page must recompute from its restored position.
+
+#### Media Contract
+
+Record frame order, dimensions, poster, compression, source/license, decoded-memory estimate, cache limit, concurrent decode limit, timeout, and fallback. A successful older decode must never replace a newer requested frame. Retain a poster or last good frame while loading or after failure. Keep essential text outside the image. For video, additionally define duration readiness, seek granularity, pending-seek replacement, and seek failure; selecting `currentTime` is not proof of frame-accurate delivery.
+
+The lab uses twelve locally drawn 480×480 SVG illustrations, one in-flight decode, three cached frames, and an eight-second example timeout. These low-detail illustrations verify the loading lifecycle, not photographic quality or production video performance.
+
+#### Verification Trace
+
+Exercise `0 → 0.5 → 1 → 0.5 → 0`, direct entry at 0.5, and jumps across both scene boundaries. Compare presented state at the same progress in both directions. Also exercise resize mid-scene, text growth, image failure, a slow obsolete request, idle updates, reading-mode activation, preference changes, and teardown. Record browser and OS separately from emulated viewport/input. A screenshot proves one state; performance and perceptual continuity need separate evidence.
+
+Technical sources rechecked on 2026-09-09: [W3C Scroll-driven Animations draft](https://www.w3.org/TR/scroll-animations-1/), [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame), and [image decode](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/decode). These support the API distinctions and decode lifecycle; they do not establish local frame rate, comfort, or adoption.
+
+### Full-Viewport Scene Navigation
+
+Task: explore a short sequence as screen transitions while the document stays at one position. This is discrete navigation driven by input, not a scroll-position timeline. Use the [Scene Navigation example](../examples/scene-navigation/README.md) for a runnable contract.
+
+| Model | State source | Scroll responsibility |
+| --- | --- | --- |
+| Pinned scrub | Continuous document position | Document traverses a track; the local stage sticks and releases |
+| Native snapping | Browser scroll position and snap targets | Document or named pane scrolls between real positions |
+| Fixed-viewport scenes | Selected chapter identity | Document stays fixed in scene mode; overflowing copy owns native scrolling |
+
+Choose explicitly; similar appearance does not make their input, history, or recovery behavior equivalent. A short showcase may justify scene navigation. Articles, search results, forms, and long task flows should retain ordinary reading and scrolling unless a tested task requires otherwise.
+
+#### Input And Navigation Contract
+
+One controller owns the selected chapter. Commit that state immediately and let product CSS retarget presentation; never wait for an animation timer before accepting navigation. Keep the same decorative subject node across scenes when object continuity is intended.
+
+- Declare the input surface. The example owns vertical wheel gestures only within its stage and touch swipes only over its decorative art; visible chapter and previous/next controls remain available.
+- Aggregate small wheel deltas and accept at most one navigation per burst. Declare threshold, unit conversion, silence interval, reversal, and edge behavior as local choices. Test long momentum tails on actual target hardware before claiming trackpad support.
+- Exempt editable controls, native overflowing copy, modifier gestures, and horizontal scrolling. Do not capture Tab, browser history shortcuts, or pinch zoom. Do not auto-advance from a copy pane when its scroll reaches the edge.
+- Support direct chapter links, keyboard commands, Back/Forward restoration, and invalid-fragment fallback. Do not loop at the first or last chapter. Preserve unrelated URL state.
+- Make only the selected panel interactive in scene mode. If focus was inside the outgoing panel, move it to the incoming heading; otherwise retain control focus. Announce the chapter separately from animation.
+- Provide a persistent reading-mode control and an escape command. All chapters remain ordinary semantic HTML with no script. A short viewport selects reading mode; long copy remains a named native scroll region.
+- Reduced motion may preserve discrete navigation while making transitions immediate. State this separately from the pinned example's static fallback, and react to preference changes during use.
+
+The example's 60-pixel aggregate threshold, 180-millisecond silence interval, 55-pixel swipe threshold, and 540-pixel minimum height are product experiments. They are not gallery-wide defaults or measured usability recommendations.
+
+#### Verification Trace
+
+Record `0 → 1 → 2 → 1 → 0` with document position unchanged, a long wheel burst, fresh reverse gesture, rapid opposite commands, boundary commands, direct entry, Back/Forward, and Escape. Exercise long copy and text editing without changing chapters, cancelled/multi-touch gestures, no script, reduced motion, resize, and teardown. Desktop touch emulation does not establish iOS Safari, Android, physical trackpad, or assistive-technology behavior.
+
+Locally authored interaction contract. The worked example's verification is bounded to its recorded source and runtime; no external homepage implementation is inferred from its appearance.
+
+## Opinionated Guidance
+
+For frequent operations, compare with removing motion before increasing its complexity. When two recipes compose, one controller must arbitrate the shared state rather than letting competing completion callbacks decide it.
+
+## Platform-Specific Guidance
+
+For the web, [`prefers-reduced-motion`](https://www.w3.org/TR/mediaqueries-5/#prefers-reduced-motion) is a preference signal. Define the alternative per recipe and respond to preference changes during use. API support, native gesture physics, and rendering performance require the exact target runtime.
+
+## Unsupported Absolutes
+
+These recipes establish no universal duration, spring configuration, frame rate, device coverage, or aesthetic result. A static snippet does not prove animated or assistive-technology behavior.
+
+## Verification Contract
+
+For each implemented recipe record before, intermediate, interrupted, and final states; logical order and focus; reduced-motion behavior; and completion/error cleanup. Source inspection can check declared ownership. Rendered interaction and assistive-technology behavior require the consuming application. Review when an API changes or a trace fails.
+
+The [Interaction Lab](../examples/domain-interactions/README.md) provides a bounded web implementation of feedback, native disclosure, modal dismissal, stale search results, reward reveal, and range-input preview. Its [verification notes](../examples/domain-interactions/verification.md) record exercised states and preferences; they do not establish coverage for every possible implementation of these recipes.
+
+## Source, License, And Attribution
+
+Locally authored recipes and HTML. The linked W3C APG pages and Media Queries Level 5 were rechecked on 2026-09-08 for the specific semantics and preference signal above. WCAG 2.2 (W3C Recommendation, 12 December 2024) and its Understanding page for Success Criterion 2.5.7 (updated 10 August 2026) were rechecked on 2026-09-19 for the criterion text, its two exceptions, and its relationship to keyboard operation; the Understanding page is informative, and the failure cases above are local and unexecuted. No upstream examples or timing prescriptions are copied.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Motion Review Workflow](review-workflow.md).

package/motion/interruption-and-retargeting.md

@@ -0,0 +1,90 @@
+---
+type: Domain Guide
+title: Interruption And Retargeting
+description: Keep semantic intent, presented motion, cancellation, and teardown consistent under repeated input.
+domain: motion
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Interruption And Retargeting
+
+Primary role: motion lifecycle and ownership guide.
+
+## Repository Boundary
+
+This page describes presentation behavior when an interaction is interrupted. Application state and request authority remain in [State Management](../design-engineering/state-management/index.md). A presentation controller cannot silently cancel a transaction or overwrite newer semantic intent.
+
+## Reusable Method
+
+For each transition, record four independent facts: the committed application state, the current user intent, the presented visual state, and the current transition identity. Choose which fact authorizes each callback. A visible intermediate frame is not necessarily a valid application state.
+
+### Source Findings
+
+| Source | Bounded finding | Consequence |
+| --- | --- | --- |
+| [Web Animations, cancellation](https://www.w3.org/TR/web-animations-1/#canceling-an-animation-section) | Cancelling a non-idle animation rejects its current finished promise with `AbortError` and resets timing state. | Treat expected cancellation separately from an implementation failure. |
+| [Web Animations, playback](https://www.w3.org/TR/web-animations-1/#the-animation-interface) | Play, pause, reverse, finish, and cancel are distinct operations. | Select an operation by desired lifecycle behavior, not its convenient name. |
+| [CSS Transitions Level 2](https://www.w3.org/TR/css-transitions-2/) | Transition events include cancellation; entry styling can be supplied with `@starting-style` when prior rendered styling is absent. | A normal end event is not the only exit path. |
+| [View Transitions Level 1](https://www.w3.org/TR/css-view-transitions-1/#viewtransition) | Skipping the visual transition does not prevent its DOM update callback. | Visual cancellation is not transaction rollback. |
+| [Pointer Events Level 3](https://www.w3.org/TR/pointerevents3/#the-pointercancel-event) | A pointer stream can be cancelled by the user agent. | A drag needs an explicit cancellation path, not only pointer-up handling. |
+
+These are specification contracts at the documents read on 2026-09-21. Draft maturity and API presence do not prove behavior on a target browser; name the tested implementation separately.
+
+### Choose The Interruption Policy
+
+| Policy | Suitable local scenario | Cost or boundary |
+| --- | --- | --- |
+| Retarget from current presentation | A panel is asked to close before it finishes opening. | Sample or preserve the current pose; do not restart from a stale endpoint. |
+| Reverse the same effect | The underlying states and path are genuinely reversible. | Reversing visual time cannot undo committed external effects. |
+| Settle immediately | Motion is disabled, the surface is disposed, or presentation continuity is unimportant. | Preserve semantic state and focus even when no animation runs. |
+| Coalesce pending presentation | Several updates describe only the newest displayed reading. | Do not drop independent operation acknowledgements. |
+| Queue meaningful steps | The user explicitly needs a sequential demonstration. | Provide interruption or escape; state which queued events can be discarded. |
+
+The policy is a product proposal. Keep the queue bounded and its meaning explicit. A list of queued animations is not an audit log of business actions.
+
+### Worked Race: Open, Close, Open
+
+The user opens a details pane, closes it during entrance, and opens it again during exit. Give each new intent an identity. The oldest entrance completion may release its own animation handle, but it cannot mark the current pane closed, move focus, or remove the latest pane instance.
+
+| Event | Owner action | Invariant |
+| --- | --- | --- |
+| Open A | Commit open intent; establish an accessible pane and entrance effect. | Required semantics do not wait for an effect to finish. |
+| Close B during A | Invalidate A's authority; choose the exit policy and focus destination. | A's completion cannot restore open intent. |
+| Open C during B | Invalidate B; retarget or settle from the current presentation. | B cannot remove C's DOM instance. |
+| B's delayed completion | Clean up only B's resources. | Current intent remains C. |
+| Dispose surface | Invalidate all callbacks; release listeners and handles. | No later callback changes focus or another surface. |
+
+Specify when leaving content stops accepting input. If an exiting visual remains on screen after the semantic close, it must not leave a second active focus surface. Conversely, a modal's focus containment must remain correct until the chosen modal-close operation occurs. Review that timing with the [native interaction contract](../design-engineering/native-interaction-contracts.md).
+
+## Opinionated Guidance
+
+Prefer one owner per animated property and one lifecycle owner per surface. When multiple effects compose, explicitly name the composite rule and cleanup ownership. Do not use a timer equal to a nominal duration as the authority for saving data, unlocking an action, or removing a currently reused element.
+
+For direct manipulation, preserve the position reached by the user. Whether a release should preserve velocity, overshoot, or snap is a local perceptual decision; no spring parameter follows from this ownership model.
+
+## Platform-Specific Guidance
+
+CSS events, Web Animations promises, framework unmount hooks, and native gesture callbacks have different lifecycle semantics. Bind them through the same declared policy without claiming interchangeable APIs. Coordinate reduced-motion settlement through [Accessible Motion](accessible-motion.md).
+
+## Unsupported Absolutes
+
+`cancel()` does not mean “restore the original screen.” A resolved animation promise does not prove a server operation succeeded. A reverse animation does not guarantee that focus, history, or side effects were reversed.
+
+## Verification Contract
+
+Run repeated input at several points in the effect, including immediately before completion. The points are race probes, not statistically representative samples. Record request/intent identity, callback identity, final state, focused element, and remaining active effects.
+
+Exercise normal completion, cancellation, reversal, removal, reduced-motion change, and pointer cancellation. Inject a late callback from the previous transition and verify it cannot remove or refocus the current instance. Compare the no-animation path against the same semantic outcomes.
+
+These are unexecuted scenarios. A model test can prove callback acceptance rules in that model; actual event order and visual continuity require browser evidence. Re-review after a lifecycle adapter or animation API changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the linked specifications, inspected 2026-09-21. No upstream implementation is copied. `consumer_reference: not_applicable` because the example specifies a proposed interaction and selects no consumer record.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Rendering And Performance](rendering-and-performance.md).

package/motion/motion-brief.md

@@ -0,0 +1,125 @@
+---
+type: Domain Guide
+title: Motion Brief
+description: Author a product-owned transition contract with interruption, preference, and evidence requirements.
+domain: motion
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Motion Brief
+
+Primary role: motion implementation handoff template.
+
+## Repository Boundary
+
+This brief records one product-owned behavior. Its timings, distances, and treatments never become reusable Layout values. Use the [Decision Tree](decision-tree.md) before filling it in.
+
+## Reusable Method
+
+Complete every field, using `unknown` for missing observations and a reason for non-applicability. A blank field is not an accepted exception.
+
+```yaml
+interaction: # a user action and the state it changes
+purpose: # the information motion adds
+frequency: # observed or estimated, with its basis
+trigger: # input, data event, navigation, or scroll progress
+semantic_owner: # who commits the real application state
+presentation_owner: # who starts, retargets, cancels, and disposes motion
+layout_owner: # final geometry and scroll responsibility
+states: # initial, in-flight, completed, failed, cancelled
+identity: # stable object or item key, if continuity is claimed
+parameters: # product-local values and why they are being tried
+interruption: # reverse, retarget, finish, or cancel, and from which state
+focus_and_input: # entry, availability during motion, exit, fallback target
+reduced_motion: # equivalent state/feedback without unnecessary movement
+teardown: # navigation, removal, preference change, and stale callbacks
+verification: # exact actions, expected outcomes, runtime and artifacts
+observed_result: # not_run until evidence exists
+boundary: # what those observations cannot establish
+review_trigger: # source/API change, a failed case, or reader task
+consumer_reference: not_applicable
+consumer_reference_reason: This blank template selects no consumer reference record.
+```
+
+## Filled Example: Search Status Feedback
+
+| Field | Example decision |
+| --- | --- |
+| Interaction and purpose | Submit a search; distinguish waiting, zero results, results, and failure |
+| Frequency | Unknown; measure in the consuming search task |
+| Semantic owner | Search controller; only the active request may replace results |
+| Presentation owner | Status component; progress decoration may stop independently |
+| Layout owner | Consumer's result region; [Feed](../patterns/stacking/feed.md) can own vertical repetition |
+| Transition | Idle → pending → results/empty/error; a new query supersedes the old request |
+| Parameters | No movement needed for the baseline; a loading treatment is an optional later hypothesis |
+| Interruption | Query B supersedes query A; A's late completion is ignored |
+| Focus | Remains on the initiating control unless the user moves it |
+| Reduced motion | Static pending text and the same final result or error |
+| Teardown | Abort where supported and reject stale completion by request identity |
+| Verification | Submit A, submit B, resolve B, then resolve A; B remains presented |
+| Observed result | `not_run`: illustrative contract, not captured product evidence |
+| Review trigger | The product changes its request lifecycle, navigation, or status announcement |
+
+Example handoff: `consumer_reference: not_applicable` because no profile or consumer evidence record is selected. A real consumer replaces this with its applicable repository-relative record or its own reason.
+
+## Scroll Story Extension
+
+For scroll-linked scenes, fill these fields in addition to the general brief:
+
+```yaml
+scroll_owner: document
+stage_owner: # sticky containing block and offset
+start_and_distance: # measured start, positive distance, zero-distance alternative
+scene_ranges: # each chapter's entry, hold, exit, and semantic availability
+resize_policy: # recompute geometry and fall back when content cannot fit
+direct_entry: # derive state from restored scroll position without replay
+static_path: # source-order reading, no script, reduced motion, explicit user choice
+media_budget: # poster, dimensions, cache, decode concurrency, timeout, fallback
+performance_protocol: # exact runtime, input trace, measurements and local targets
+```
+
+See [Scroll-driven story](interaction-recipes.md#scroll-driven-story) and the [worked lab](../examples/scroll-story/README.md). A brief must distinguish view-entry triggers from continuous scroll progress.
+
+## Fixed-Viewport Navigation Extension
+
+Use this instead of assuming a document scroll track when the selected chapter drives the page:
+
+```yaml
+state_source: selected chapter ID
+input_owner: # stage, exempt editable/native scroll regions, visible alternatives
+gesture_policy: # wheel units/threshold/burst/reversal; swipe start/cancel/multi-touch
+navigation: # chapter hashes, direct entry, Back/Forward, invalid destination
+boundaries: # first/last behavior; no implicit wrap or browser-navigation trap
+focus_policy: # outgoing panel focus, retained control focus, status announcement
+reading_escape: # visible control, Escape, short viewport, no-script path
+reduced_motion: # immediate chapter changes or a declared static alternative
+teardown: # input listeners, pending state, document overflow restoration
+```
+
+See [Full-viewport scene navigation](interaction-recipes.md#full-viewport-scene-navigation). Record ordinary document scrolling, pinned scrubbing, native snapping, and input-driven navigation as distinct choices.
+
+## Opinionated Guidance
+
+Write cancellation before tuning curves. An animation completion callback should report presentation completion; it should not be the sole authority for network success, focus cleanup, or saving data.
+
+## Platform-Specific Guidance
+
+Record actual browser, OS, input mode, and relevant animation-library version in the consumer's verification record. A preference query indicates a requested behavior; it does not prove the implemented alternative is comfortable.
+
+## Unsupported Absolutes
+
+No fixed timing, animation technology, or one reduced-motion treatment works for every brief. A filled template is not executed evidence.
+
+## Verification Contract
+
+The brief is ready to implement when every state has an owner, every interruption has a resulting state, and every acceptance claim names an observable. Execution must add artifacts and pass/fail results. Use the [Review Workflow](review-workflow.md) for findings and retesting.
+
+## Source, License, And Attribution
+
+Locally authored template and fictional search scenario. The existing domain contracts provide its evidence boundary.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Motion Interaction Recipes](interaction-recipes.md).