stylegallery 0.1.3 → 0.1.6

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,6 +8,18 @@ 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.
@@ -16,9 +28,9 @@ Out of scope: universal timing or easing rules, unmeasured performance claims, a
 
 ## 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,164 @@
+---
+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.
+
+Test release inside/outside, cancellation, pointer loss, a changing destination, and repeated reversal. 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. No upstream examples or timing prescriptions are copied.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Motion Review Workflow](review-workflow.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).

package/motion/practice-reference.md

@@ -0,0 +1,145 @@
+---
+type: Domain Guide
+title: Motion Practice Reference
+description: Bounded motion mechanics, heuristics, platform notes, and verification requirements.
+domain: motion
+lifecycle: experimental
+source_repository: https://github.com/emilkowalski/skills
+source_path: skills/review-animations/STANDARDS.md
+source_revision: 220e8607c90b17337d210125777b7b695f26c221
+---
+
+# Motion Practice Reference
+
+Primary role: motion evidence reference.
+
+## Repository Boundary
+
+This is a practice reference, not a standards document. Each item states what kind of claim it is and how to verify it before use.
+
+## Reusable Method
+
+For every proposed rule, record:
+
+```text
+Guidance:
+Classification: reusable mechanic | opinionated heuristic | platform-specific | unsupported
+Context:
+Warrant:
+Evidence:
+Verification:
+Boundary:
+```
+
+The classification controls authority. A reusable mechanic may explain a causal relationship; a heuristic proposes a starting question; a platform note is valid only for its named source/version; an unsupported claim cannot become a blocker.
+
+## Practice Map
+
+### Purpose And Frequency
+
+Guidance: State why a transition exists and how often the user encounters it.
+
+Classification: opinionated heuristic.
+
+Verification: compare task completion and state comprehension with the behavior present, reduced, and removed.
+
+Boundary: frequency alone does not dictate a universal duration or deletion rule.
+
+### Spatial Continuity
+
+Guidance: Preserve understandable relationships between trigger, moving representation, destination, and dismissal path.
+
+Classification: reusable mechanic.
+
+Verification: inspect before, intermediate, interrupted, and after states together with DOM and focus order.
+
+Boundary: visual continuity cannot override semantic order or accessibility.
+
+### Interruption
+
+Guidance: A repeatedly triggered or directly manipulated transition should respond to new input without visible jumps or input lockout.
+
+Classification: reusable mechanic.
+
+Verification: reverse and retarget the interaction at multiple points while recording the presented state.
+
+Boundary: no specific animation API is required.
+
+### Timing, Easing, And Springs
+
+Guidance: Treat timing curves and dynamic parameters as context-dependent starting hypotheses.
+
+Classification: opinionated heuristic.
+
+Verification: compare variants on the target device and task; record response latency, interruption, overshoot, and completion cues.
+
+Boundary: fixed duration, easing, damping, bounce, or velocity values are not cross-product standards.
+
+### Performance
+
+Guidance: Prefer changes that avoid unnecessary repeated layout and paint work when measurements show they are material.
+
+Classification: reusable mechanic.
+
+Verification: use browser performance traces, frame evidence, target hardware, and representative concurrent work.
+
+Boundary: `transform`, `opacity`, CSS, JavaScript, or Web Animations do not guarantee compositor/GPU execution or superior performance.
+
+### Preferences And Input Capabilities
+
+Guidance: Provide an equivalent state and feedback path for relevant user preferences and input capabilities.
+
+Classification: reusable mechanic.
+
+Verification: inspect the actual reduced-motion behavior, keyboard/pointer/touch flows, focus visibility, and state announcement.
+
+Boundary: reduced motion may mean removal, substitution, or reduction; hover/pointer media features do not identify a universal device class.
+
+### Product Cohesion
+
+Guidance: Evaluate whether motion supports the product's declared task and tone.
+
+Classification: opinionated heuristic.
+
+Verification: use comparative review with named criteria and representative users when the claim concerns human perception.
+
+Boundary: cohesion and delight are not mechanically provable from source code.
+
+## Opinionated Guidance
+
+Shorter, smaller, and less frequent motion is often a useful remediation direction for high-frequency interfaces, but it is not automatically correct. Source-anchored paths and asymmetry may improve comprehension when they correspond to real state relationships; they require rendered evidence.
+
+## Platform-Specific Guidance
+
+Browser compositor behavior, framework shorthands, native springs, pointer models, and operating-system preferences must be sourced and versioned independently. A native-platform value does not automatically translate to CSS or a JavaScript animation library.
+
+## Unsupported Absolutes
+
+- Only transform and opacity may be animated.
+- Transform and opacity always run on the GPU.
+- CSS animations categorically outperform JavaScript.
+- Web Animations is universally hardware accelerated.
+- Parent custom-property updates always cause unacceptable recalculation.
+- A framework shorthand necessarily drops frames.
+- Reduced motion always means crossfade rather than removal.
+- Hover and pointer queries identify a touch-device class.
+- All interface motion must remain under one fixed duration.
+
+These statements may become scoped hypotheses only after the context, source, and verification protocol are named.
+
+## Verification Contract
+
+Use slow-motion or frame-by-frame inspection for discontinuity, browser traces for delivery claims, keyboard and assistive-technology checks for interaction/accessibility claims, and real-device or user evidence for perceptual quality. State what the selected evidence cannot prove.
+
+## Source, License, And Attribution
+
+- Upstream inspiration: [review-animations/STANDARDS.md](https://github.com/emilkowalski/skills/blob/220e8607c90b17337d210125777b7b695f26c221/skills/review-animations/STANDARDS.md)
+- Snapshot: `220e8607c90b17337d210125777b7b695f26c221`
+- Upstream license: MIT, Copyright (c) 2026 Emil Kowalski.
+- Reuse form: independent method rewrite; upstream prose, tables, code, examples, and distinctive ordering were not retained.
+- Evidence boundary: the upstream practice source can suggest questions but cannot prove local performance, accessibility, usability, or quality.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Design Engineering](../design-engineering/index.md).

package/motion/review-workflow.md

@@ -0,0 +1,94 @@
+---
+type: Domain Guide
+title: Motion Review Workflow
+description: Evidence-first workflow for reviewing product-layer motion without changing Layout policy.
+domain: motion
+lifecycle: experimental
+source_repository: https://github.com/emilkowalski/skills
+source_path: skills/review-animations/SKILL.md
+source_revision: 220e8607c90b17337d210125777b7b695f26c221
+---
+
+# Motion Review Workflow
+
+Primary role: motion review procedure.
+
+## Repository Boundary
+
+This workflow reviews declared product-layer motion. It does not review unrelated code, create feature requirements, or turn preferences into blockers. Shared accessibility and evidence gates take precedence; Layout source order, constraints, and scroll ownership remain authoritative for reusable patterns.
+
+## Reusable Method
+
+### Intake
+
+Name the interaction, trigger, frequency, affected state, expected purpose, supported input modes, reduced-motion behavior, and verification surface. If the purpose or observable is absent, record an evidence gap before discussing polish.
+
+### Inspect
+
+Review four boundaries in order:
+
+1. State and source continuity: the before/after states, DOM order, focus, and recoverability remain coherent.
+2. Interaction continuity: repeated input, interruption, reversal, cancellation, and rapid state changes do not jump or lock input.
+3. Accessibility: motion alternatives and input-capability assumptions match the actual user preference and interaction contract.
+4. Delivery evidence: rendered frames, performance traces, and real-device behavior support claims that source inspection cannot prove.
+
+### Finding Record
+
+| Impact | Location | Observed behavior | Proposed change | Warrant | Evidence | Boundary |
+| --- | --- | --- | --- | --- | --- | --- |
+| What fails for the task | `file:line` or rendered state | Reproducible observation | Smallest corrective direction | Why the evidence supports it | Trace, recording, test, or source | What remains unproven |
+
+### Decision
+
+- `blocked`: a declared local contract, accessibility requirement, or required evidence gate fails.
+- `review_required`: the decision depends on missing rendered, device, user, or performance evidence.
+- `approve_with_debt`: behavior is acceptable for the declared scope and the remaining bounded debt has an owner and trigger.
+- `pass`: all declared motion contracts and required evidence are satisfied.
+
+## Remediation Order
+
+1. Confirm the motion has a task or state purpose.
+2. Remove motion that has no necessary job.
+3. Reduce frequency, distance, scope, or affected elements.
+4. Preserve spatial, semantic, and focus relationships.
+5. Make repeated and interrupted state changes continuous.
+6. Measure the performance claim on the target surface.
+7. Provide an evidence-based alternative for relevant preferences and inputs.
+8. Tune product-specific character only after the contracts above pass.
+
+## Opinionated Guidance
+
+Frequency, duration, easing, physicality, and cohesion can be useful review prompts. They remain context-dependent heuristics. “Feels right,” popularity, or a practitioner's preference is not a sufficient warrant for blocking a change.
+
+## Platform-Specific Guidance
+
+CSS transitions, Web Animations, Motion/Framer Motion, pointer events, and component-library transform origins are implementation examples. A review may recommend one only after verifying browser support, current implementation constraints, and the behavior that must change.
+
+## Unsupported Absolutes
+
+Do not automatically block `ease-in`, a particular scale value, motion longer than a fixed threshold, a keyboard-triggered transition, a non-transform property, or a particular stagger interval. Do not claim GPU execution, hardware acceleration, or accessibility from a property name or API choice alone.
+
+## Verification Contract
+
+Exercise the actual interaction in its default, repeated, interrupted, reversed, and reduced-motion states. Record the exact environment and observable. Source review may establish declared code paths; rendered and human outcomes require corresponding evidence families.
+
+## Scroll Story Evidence
+
+For [scroll-driven stories](interaction-recipes.md#scroll-driven-story), add boundary samples immediately before and after each scene transition, forward/reverse comparison, large jumps, direct middle entry, reload/history restoration, narrow and short viewports, long copy, and delayed font/image changes. Deliberately fail or delay a media request and verify stale completion cannot replace current presentation.
+
+Record JavaScript update cost separately from animation-frame intervals: neither alone measures compositor frame delivery. Count idle updates to catch observer/decode feedback loops. Record media dimensions, bounded cache entries, and estimated decoded bytes separately from measured process/GPU memory. Set product-local budgets and keep real-device, touch, assistive-technology, and comfort outcomes `not_run` when unobserved.
+
+The [Scroll Story verification](../examples/scroll-story/verification.md) records the two worked implementations and the limits of the local run.
+
+## Source, License, And Attribution
+
+- Upstream inspiration: [review-animations/SKILL.md](https://github.com/emilkowalski/skills/blob/220e8607c90b17337d210125777b7b695f26c221/skills/review-animations/SKILL.md)
+- Snapshot: `220e8607c90b17337d210125777b7b695f26c221`
+- Upstream license: MIT, Copyright (c) 2026 Emil Kowalski.
+- Reuse form: independent method rewrite; upstream prose, tables, code, examples, and distinctive ordering were not retained.
+- Evidence boundary: this procedure adapts a review shape, not its categorical practitioner judgments.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Motion Practice Reference](practice-reference.md).