stylegallery 0.1.4 → 0.1.6

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/review-workflow.md

@@ -72,6 +72,14 @@ Do not automatically block `ease-in`, a particular scale value, motion longer th
 
 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)

package/motion/vocabulary.md

@@ -51,7 +51,7 @@ The terms are implementation-neutral. A framework, operating-system behavior, or
 
 ## Opinionated Guidance
 
-The family ordering favors what a reader can observe before implementation details. It is useful for retrieval, but it is not a complete ontology. Add a term only after a reader task demonstrates that existing terms and aliases cannot express the distinction.
+The family ordering favors what a reader can observe before implementation details. It is useful for retrieval, but it is not a complete ontology. Add a term only when contrastive repository cases show that existing terms and aliases cannot express the distinction.
 
 ## Platform-Specific Guidance
 
@@ -66,7 +66,7 @@ Names tied to iOS, macOS, a browser API, Motion, Framer Motion, React, or a comp
 
 ## Verification Contract
 
-A vocabulary lookup should exercise exact, ambiguous, and unknown cases. Pass requires one justified term, an ordered candidate set with a stated distinction, or `unknown`; invented winners fail. A new term also requires a findability task showing the current route cannot reach an adequate term within two hops.
+A vocabulary lookup should exercise exact, ambiguous, and unknown cases. Pass requires one justified term, an ordered candidate set with a stated distinction, or `unknown`; invented winners fail. A new term also requires contrastive exact, ambiguous, and unknown cases showing that the current vocabulary cannot express the distinction.
 
 ## Source, License, And Attribution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylegallery",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A governed gallery of portable interface knowledge with deterministic CLIs and read-only MCP servers.",
   "type": "module",
   "homepage": "https://github.com/changeroa/StyleGallery#readme",
@@ -47,12 +47,16 @@
     "consumer-reference/agent-native/v2/schema/material-record.schema.json",
     "consumer-reference/contract.md",
     "consumer-reference/index.md",
+    "design-engineering/component-contract.md",
     "design-engineering/consumer-migration-readiness.md",
+    "design-engineering/decision-tree.md",
     "design-engineering/index.md",
     "design-engineering/interface-craft.md",
     "design-engineering/reference-profiles/governed-local/editorial/profile.json",
     "design-engineering/reference-profiles/governed-local/index.md",
     "design-engineering/reference-profiles/index.md",
+    "design-engineering/worked-examples.md",
+    "design-terminology/comparison-workflow.md",
     "design-terminology/concept-families.md",
     "design-terminology/conflict-cases.md",
     "design-terminology/index.md",
@@ -60,14 +64,17 @@
     "design-terminology/source-kinds.md",
     "design-terminology/source-vocabularies.md",
     "game-ui/classification.md",
+    "game-ui/decision-tree.md",
     "game-ui/index.md",
     "game-ui/reference-record.md",
     "game-ui/screen-hierarchy.md",
+    "game-ui/screen-recipes.md",
     "game-ui/unity/architecture.md",
     "game-ui/unity/cli-loop.md",
     "game-ui/unity/org-wiki.md",
     "game-ui/unity/repository-map.md",
     "game-ui/unity/ui-systems.md",
+    "game-ui/verification-workflow.md",
     "guides/decision-tree.md",
     "guides/documentation-mode-taxonomy.md",
     "guides/layout-brief.md",
@@ -76,7 +83,10 @@
     "index.md",
     "layout/index.md",
     "log.md",
+    "motion/decision-tree.md",
     "motion/index.md",
+    "motion/interaction-recipes.md",
+    "motion/motion-brief.md",
     "motion/practice-reference.md",
     "motion/review-workflow.md",
     "motion/vocabulary.md",
@@ -136,8 +146,12 @@
     "patterns/viewport-shell/scroll-body-shell.md",
     "patterns/viewport-shell/sticky-footer.md",
     "patterns/viewport-shell/sticky-header.md",
+    "platform-guides/adaptation-workflow.md",
+    "platform-guides/android-interaction.md",
     "platform-guides/apple-interaction.md",
+    "platform-guides/compatibility-matrix.md",
     "platform-guides/index.md",
+    "platform-guides/windows-interaction.md",
     "quality/claim-records/design-terminology-domain-scope.md",
     "quality/claim-records/index.md",
     "quality/claim-records/samples.md",

package/platform-guides/adaptation-workflow.md

@@ -0,0 +1,76 @@
+---
+type: Domain Guide
+title: Platform Adaptation Workflow
+description: Compare a native convention with a target implementation through source, capability, fallback, and evidence records.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Platform Adaptation Workflow
+
+Primary role: platform comparison planning and handoff.
+
+## Repository Boundary
+
+Use a platform convention as a sourced comparison for a named task. The native platform owns its convention; the target's standards and actual runtime determine the adaptation. This workflow does not make a visual imitation equivalent to native behavior.
+
+## Reusable Method
+
+1. Name the task and target: native application, browser, embedded web view, or game engine.
+2. Select [Apple](apple-interaction.md), [Android](android-interaction.md), or [Windows](windows-interaction.md) by source platform.
+3. Record an official source, exact page section, version or dated reading, and re-review trigger.
+4. Separate the observed/native fact from the transferable interaction question.
+5. Choose an adaptation and an explicit fallback using the [Compatibility Matrix](compatibility-matrix.md).
+6. Execute the target-specific acceptance cases and record what was not tested.
+
+## Adaptation Record
+
+| Field | Required content |
+| --- | --- |
+| Task | The user action, intended outcome, and affected state |
+| Source context | Platform, OS/API or documentation version, source URL/section, review date |
+| Source claim | The precise native fact supported by that source |
+| Target context | Browser/OS/framework/device/input and relevant versions |
+| Transferable question | What problem the convention helps investigate |
+| Target decision | Implement, adapt, omit, or defer with a reason |
+| Capability gap | Missing API, different input model, permission, or semantic difference |
+| Fallback | A complete task path when the preferred capability is absent |
+| Verification | Actions, expected and actual behavior, artifacts, source/build identity |
+| Freshness | Source/API change or failed observation that triggers re-review |
+| Handoff | `consumer_reference` record or `not_applicable` with a reason |
+
+## Worked Comparison: Returning From Detail
+
+Native source: Android's [predictive Back documentation](https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture), reviewed 2026-09-08, describes gesture preview and cancellation. Transferable question: can a person understand and cancel a return before committing it?
+
+Web decision: use the application's documented list/detail route and normal browser history. Restore the list's selection and relevant search state on return. Provide a visible return link where the task needs it. Do not intercept browser/system gestures merely to reproduce a preview.
+
+Fallback: direct entry to a detail URL has no assumed prior list history; its visible parent link goes to the known collection route. Verification cases: navigate from a filtered list, return with browser Back, enter detail directly, cancel a local dialog before leaving, and return after the selected item is removed.
+
+Actual result: `not_run`; this is a fictional adaptation proposal. `consumer_reference: not_applicable` because no consumer record is selected. The comparison claims neither native gesture support nor tested browser history restoration.
+
+## Opinionated Guidance
+
+Preserve the task and recovery path before reproducing the native effect. When a capability is absent, document an intentional complete alternative rather than a partially functioning control.
+
+## Platform-Specific Guidance
+
+The source platform and target platform are separate fields even when both run on the same device. A browser on Android does not expose every Android application API. A web view's embedding host may own navigation and permissions.
+
+## Unsupported Absolutes
+
+An official source establishes its own guidance, not target conformance. Similar appearance, shared vocabulary, or a matching API name is insufficient evidence of equivalent behavior.
+
+## Verification Contract
+
+A completed adaptation distinguishes source fact, local inference, target implementation, and actual observation. Verify unavailable capabilities, interrupted navigation, relevant preferences, and all claimed inputs. Re-review on a source change, target API change, or failed acceptance case; a review date alone is not proof of continuing support.
+
+## Source, License, And Attribution
+
+Locally authored comparison method and fictional example. The linked Android source was rechecked on 2026-09-08; prose and examples are independently written. Source access does not establish device execution.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Platform Compatibility Matrix](compatibility-matrix.md).

package/platform-guides/android-interaction.md

@@ -0,0 +1,74 @@
+---
+type: Domain Guide
+title: Android Interaction As A Comparative Reference
+description: Source-bounded Android Back and adaptive-window guidance with explicit web translation and failure cases.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+platform: Android applications
+platform_version: dated official documentation; target OS and AndroidX versions required
+reviewed_on: 2026-09-08
+---
+
+# Android Interaction As A Comparative Reference
+
+Primary role: Android platform comparison guide.
+
+## Repository Boundary
+
+This guide compares Android application behavior with a consumer's target. It does not equate Android APIs with browser APIs or prescribe Material visual treatment. Record the actual OS, AndroidX/UI stack, and target device before implementation.
+
+## Reusable Method
+
+Use the [Adaptation Workflow](adaptation-workflow.md). Choose a specific native concern below, inspect its source, then write the target behavior and fallback independently of native visuals.
+
+## Source-Bounded Conventions
+
+| Concern | Official source and bounded fact | Transferable question |
+| --- | --- | --- |
+| Back preview | [Predictive Back](https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture) describes previewing a destination and cancelling a gesture; custom handling depends on the application stack | Is the destination understandable, and does cancelling preserve the current state? |
+| Back ownership | The same source describes enabled callbacks and one recipient for a Back gesture | Which active layer consumes Back, and when does control return to the outer navigation owner? |
+| Window adaptation | [Window size classes](https://developer.android.com/develop/adaptive-apps/guides/use-window-size-classes) classify available application window space for adaptive decisions | Does the screen adapt to its available space while preserving selection and task state? |
+| Navigation transformation | [Responsive navigation](https://developer.android.com/develop/ui/views/layout/build-responsive-navigation) discusses changing navigation presentation with window conditions | Can the user reach the same destinations after presentation changes? |
+
+These pages were read on 2026-09-08. They are a dated documentation set, not a pin of every Android release or package. Verify the implementation details for the selected runtime.
+
+## Worked Adaptation: Compact List And Expanded Detail
+
+Task: inspect a collection on a resizable surface. Native comparison: available window space can change the presentation. Target web decision: compose [List Detail](../recipes/list-detail.md), retain selected identity in application state, and let the Layout owner choose the fit constraint. Android's native units and class boundaries are not CSS breakpoints.
+
+On a tight surface, the detail route can replace the list visually while preserving the query and selection. On a roomy surface, both can be visible. Returning must resolve a missing selected item explicitly. Changing presentation must not duplicate the current route or save unrelated navigation history entries.
+
+| Action | Expected target behavior |
+| --- | --- |
+| Resize with item B selected | B remains the selected detail |
+| Return to the list | Previous query remains available |
+| Cancel an inner dialog | Dialog closes once; outer route stays put |
+| Open detail directly | Parent navigation works without assuming prior history |
+
+This is an unexecuted web proposal, not evidence of an Android build.
+
+## Opinionated Guidance
+
+Map Back, Up/parent navigation, dialog dismissal, and operation cancellation separately. They may share an icon or button position while changing different state.
+
+## Platform-Specific Guidance
+
+Android gesture progress, callback dispatch, activities, and AndroidX navigation belong to native or embedding-host code. A browser adaptation should use its supported navigation semantics. Record any web-view host integration as a separate implementation dependency.
+
+## Unsupported Absolutes
+
+Android window classes are not universal web breakpoints. A browser Back action is not necessarily an application's parent destination. A cancel animation does not prove the underlying operation was cancelled.
+
+## Verification Contract
+
+Test gesture completion/cancellation on the declared native device when claiming native behavior. For a web adaptation, test actual browser history, direct links, resizes, input modes, and dialog focus independently. Review when any cited convention or target navigation implementation changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the official Android pages linked above, rechecked 2026-09-08. No source code, tables, or native visual assets are reproduced. `consumer_reference: not_applicable` because this reference guide selects no consumer implementation record.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Platform Compatibility Matrix](compatibility-matrix.md).

package/platform-guides/apple-interaction.md

@@ -9,7 +9,7 @@ source_path: skills/apple-design/SKILL.md
 source_revision: 220e8607c90b17337d210125777b7b695f26c221
 platform: Apple platforms
 platform_version: verify-current
-reviewed_on: 2026-07-11
+reviewed_on: 2026-09-08
 ---
 
 # Apple Interaction As A Comparative Reference
@@ -33,6 +33,14 @@ For each proposed comparison:
 5. Define the web adaptation, including unavailable or materially different capabilities.
 6. Verify the adapted behavior on its real surface and record what remains unproven.
 
+## Official Source Review And Worked Adaptation
+
+Official [HIG Motion](https://developer.apple.com/design/human-interface-guidelines/motion) and [HIG Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) were rechecked on 2026-09-08 through Apple's documentation data for [Motion](https://developer.apple.com/tutorials/data/design/human-interface-guidelines/motion.json) and [Accessibility](https://developer.apple.com/tutorials/data/design/human-interface-guidelines/accessibility.json). This is a dated living-document review, not a pin of shipped OS behavior. The motion guidance supports purposeful, optional motion and cancellation; it does not supply universal web animation parameters.
+
+Worked proposal: a web settings disclosure opens immediately and keeps its trigger operable. Optional movement communicates the revealed region. Under reduced motion, the same content and controls remain available without unnecessary movement. Use [Motion Disclosure](../motion/interaction-recipes.md#disclosure) for the behavior contract and the [Adaptation Workflow](adaptation-workflow.md) for the source/target record.
+
+Expected cases: open and close by keyboard, reverse while opening, enlarge the text, hide content while focus is inside, and change the motion preference. Actual result: `not_run`; this proposal is not a tested Apple or browser implementation. `consumer_reference: not_applicable` because the worked proposal selects no consumer-owned record.
+
 ## Comparative Questions
 
 | Theme | Question to investigate | Required evidence | Boundary |