stylegallery 0.1.3 → 0.1.6

package/motion/vocabulary.md

@@ -0,0 +1,82 @@
+---
+type: Domain Guide
+title: Motion Vocabulary
+description: Evidence-bounded method and reference for naming observable interface motion.
+domain: motion
+lifecycle: experimental
+source_repository: https://github.com/emilkowalski/skills
+source_path: skills/animation-vocabulary/SKILL.md
+source_revision: 220e8607c90b17337d210125777b7b695f26c221
+---
+
+# Motion Vocabulary
+
+Primary role: motion terminology reference.
+
+## Repository Boundary
+
+This page helps a reader name observed motion. It does not prescribe implementation, authorize motion in reusable Layout CSS, or make a product-quality judgment.
+
+The terms are implementation-neutral. A framework, operating-system behavior, or branded example may illustrate a term only when clearly labeled and separately verified.
+
+## Reusable Method
+
+1. Record what changes: presence, position, scale, shape, state, scroll relationship, or feedback.
+2. Record what coordinates the change: time, sequence, input, velocity, or viewport progress.
+3. Compare the observation with the closest term families below.
+4. Return one exact term only when the observed cues distinguish it.
+5. When multiple terms remain plausible, return ordered candidates and state the missing observation.
+6. When nothing matches, return `unknown`; do not invent a canonical winner.
+
+## Term Families
+
+| Term | Observed cues | Distinguish from | Implementation-neutral meaning | Evidence boundary |
+| --- | --- | --- | --- | --- |
+| Fade | Visibility changes without a necessary spatial path. | Reveal | A gradual visibility change. | Does not imply opacity is the implementation. |
+| Slide | The element follows a directional path into, out of, or within a region. | Shared-element transition | A positional transition without necessarily preserving identity across views. | Direction and clipping must be observed. |
+| Scale transition | Apparent size changes around an origin. | Morph | Size changes while the element's basic identity remains stable. | Does not establish the correct origin or amount. |
+| Reveal | A boundary progressively exposes content. | Fade | Visibility is controlled by an advancing edge, mask, or equivalent boundary. | The masking mechanism may be unknown. |
+| Stagger | Similar elements begin related changes at distinct offsets. | Orchestration | A repeated sequence pattern, usually across peers. | The offset value is product-specific. |
+| Orchestration | Several motion events form one coordinated sequence. | Stagger | Coordination may include different elements, jobs, and timings. | Intent must be documented, not inferred from timing alone. |
+| Crossfade | One state loses visibility while another gains it in the same region. | Morph | Identity is exchanged rather than geometrically transformed. | Overlap and source order need inspection. |
+| Shared-element transition | A recognizable element appears to retain identity between states or views. | Layout animation | Continuity connects a source representation with a destination representation. | Identity continuity is a perception claim requiring rendered evidence. |
+| Layout animation | A spatial change is visually interpolated instead of appearing instantly. | Shared-element transition | Position or size changes within the layout state of an element. | Does not endorse animating layout-triggering CSS properties. |
+| Scroll-driven motion | Progress corresponds to scroll progress. | Scroll reveal | The scroll position continuously controls progress rather than merely triggering entry. | Browser and input behavior require local testing. |
+| Parallax | Layers appear to travel at different rates during a shared movement. | Ordinary scroll | Relative speed creates a depth cue. | Depth, comfort, and reduced-motion outcomes are not guaranteed. |
+| Spring motion | Response is modeled as a target-seeking dynamic system rather than a fixed timeline. | Bounce | A spring may settle without visible overshoot. | Parameters and perceived duration remain implementation-specific. |
+| Bounce | Motion overshoots or reverses before settling. | Spring motion | Visible overshoot is the defining cue, regardless of implementation. | Playfulness and appropriateness are product judgments. |
+| Interruptible motion | New input redirects a change from its current presented state. | Restarted animation | Continuity is maintained when the target changes mid-flight. | Requires interaction evidence, not source inspection alone. |
+| Rubber-band response | Movement continues beyond a boundary with increasing resistance, then returns. | Bounce | Resistance is tied to boundary overshoot and direct manipulation. | Platform examples are not a universal physics contract. |
+| Jank | Motion visibly misses expected visual continuity. | Intentional stepped motion | The discontinuity is unintended and associated with delivery or computation limits. | Frame or performance evidence is needed to attribute cause. |
+
+## 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 when contrastive repository cases show that existing terms and aliases cannot express the distinction.
+
+## Platform-Specific Guidance
+
+Names tied to iOS, macOS, a browser API, Motion, Framer Motion, React, or a component library are examples or implementation facets. Keep the cross-platform term primary and label the platform context separately.
+
+## Unsupported Absolutes
+
+- Do not call this vocabulary authoritative outside StyleGallery.
+- Do not force the nearest term when the observation is incomplete.
+- Do not attach universal FPS, GPU, duration, easing, or reduced-motion rules to a definition.
+- Do not infer implementation technology from rendered appearance alone.
+
+## 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 contrastive exact, ambiguous, and unknown cases showing that the current vocabulary cannot express the distinction.
+
+## Source, License, And Attribution
+
+- Upstream inspiration: [animation-vocabulary/SKILL.md](https://github.com/emilkowalski/skills/blob/220e8607c90b17337d210125777b7b695f26c221/skills/animation-vocabulary/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: the upstream artifact records practitioner terminology; it does not prove local performance, accessibility, usability, or quality.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Motion Review Workflow](review-workflow.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylegallery",
-  "version": "0.1.3",
+  "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,11 +47,34 @@
     "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",
+    "design-terminology/relation-types.md",
+    "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",
@@ -60,7 +83,13 @@
     "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",
     "patterns/centering/center.md",
     "patterns/centering/index.md",
     "patterns/centering/super-center.md",
@@ -117,7 +146,13 @@
     "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",
     "quality/claim-records/stylegallery-multidomain-scope.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

@@ -0,0 +1,97 @@
+---
+type: Domain Guide
+title: Apple Interaction As A Comparative Reference
+description: Bounded comparison of Apple interaction themes with explicit web-adaptation and provenance limits.
+domain: platform-guides
+lifecycle: experimental
+source_repository: https://github.com/emilkowalski/skills
+source_path: skills/apple-design/SKILL.md
+source_revision: 220e8607c90b17337d210125777b7b695f26c221
+platform: Apple platforms
+platform_version: verify-current
+reviewed_on: 2026-09-08
+---
+
+# Apple Interaction As A Comparative Reference
+
+Primary role: platform comparison guide.
+
+## Repository Boundary
+
+This page uses selected Apple-platform interaction themes as comparative questions. It does not reproduce Apple guidance, establish affiliation, prescribe imitation, or treat a native implementation value as valid for the web.
+
+Current official Apple documentation is required for Apple-specific claims. Current web standards and browser documentation are required for web adaptation. Local rendered, device, accessibility, and performance evidence is required for product conclusions.
+
+## Reusable Method
+
+For each proposed comparison:
+
+1. Name the user task, platform, OS/API version, input method, and state transition.
+2. Describe the observable behavior without branded terminology.
+3. Identify the platform convention and its current official source.
+4. Separate the reusable interaction question from native implementation details.
+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 |
+| --- | --- | --- | --- |
+| Response | Does feedback begin close enough to input to preserve cause and effect? | Interaction recording and input-state trace | No universal latency value is implied. |
+| Direct manipulation | Does the presented state follow, cancel, and resume from user input coherently? | Repeated drag/reversal test on target input modes | One-to-one tracking is not always required. |
+| Interruption | Can new input redirect a transition without jumping or locking control? | Mid-transition retarget and reversal evidence | Springs are one option, not a requirement. |
+| Velocity continuity | Does release-to-settle behavior avoid an observable seam? | Gesture and presented-state recording | Native velocity APIs and web libraries differ. |
+| Spatial consistency | Can the reader understand where content came from and where it returns? | Before/intermediate/after render plus source/focus order | Visual path cannot override semantic order. |
+| Recoverability | Can a user cancel, reverse, undo, or safely recover where the task requires it? | Task and error-path evidence | Confirmation is not universally preferable to undo. |
+| Wayfinding | Can the interface answer location, available destinations, contents, and exit? | Navigation task evidence | Familiar platform placement may not transfer across products. |
+| Soft boundaries | Would progressive resistance communicate a limit better than a hard stop? | Comparative prototype and input/device evidence | The resistance curve is not standardized across platforms. |
+| Multimodal feedback | Do visual, audio, and haptic cues share a clear cause and useful purpose? | Device timing and accessibility evidence | Web haptics/audio are not native equivalents and may be unavailable. |
+| Adaptive presentation | Does the interface remain usable across text size, contrast, transparency, motion preference, input, and viewport changes? | Relevant preference and constraint matrix | A platform feature name does not prove web accessibility. |
+
+## Opinionated Guidance
+
+Momentum-aware settling, source-anchored transitions, progressive boundary resistance, and carefully coordinated feedback can be useful hypotheses for directly manipulated interfaces. Translucent materials, system typography, haptics, and visual delight are product and platform choices outside reusable Layout pattern CSS.
+
+## Platform-Specific Guidance
+
+- iOS/macOS gesture physics, native spring APIs, Dynamic Type, system materials, haptics, and SwiftUI/UIKit behavior must be labeled as Apple-specific.
+- Any value described as shipped by Apple requires a direct, current official source and version.
+- A web mapping must identify browser support, input differences, accessibility behavior, and fallback semantics.
+- `backdrop-filter`, the Vibration API, web media queries, and JavaScript animation libraries are not equivalents merely because they can approximate one visible effect.
+
+## Unsupported Absolutes
+
+- Do not call an upstream formula or parameter an exact Apple implementation without a primary official source.
+- Do not require direct manipulation to track one-to-one in every context.
+- Do not require audio and haptic events on one exact frame as a universal web contract.
+- Do not claim translucent chrome is generally superior to opaque structure.
+- Do not adopt a single spring configuration as a safe default across tasks.
+- Do not import a named set of Apple principles as StyleGallery's shared principles.
+- Do not infer native behavior, platform affiliation, or accessibility from visual similarity.
+
+## Verification Contract
+
+Record the official platform source and version, the web-standard or browser source for adaptation, the exact target devices and input modes, relevant user preferences, and the observed pass/fail behavior. Use a real interactive prototype for interaction claims. State explicitly when native behavior cannot be reproduced or verified on the web.
+
+Review this page when Apple changes the cited convention, the web platform changes the adaptation surface, the source revision changes, or local testing contradicts the guidance. `platform_version: verify-current` prevents this experimental page from masquerading as a version-pinned platform contract.
+
+## Source, License, And Attribution
+
+- Upstream inspiration: [apple-design/SKILL.md](https://github.com/emilkowalski/skills/blob/220e8607c90b17337d210125777b7b695f26c221/skills/apple-design/SKILL.md)
+- Snapshot: `220e8607c90b17337d210125777b7b695f26c221`
+- Upstream license: MIT, Copyright (c) 2026 Emil Kowalski.
+- Reuse form: independent method rewrite; upstream prose, tables, code, exact-value sequences, Apple/WWDC-derived expression, and quotations were not retained.
+- Evidence boundary: the upstream artifact is a practitioner interpretation and provenance record, not an official Apple or web-platform source.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Layout](../layout/index.md).

package/platform-guides/compatibility-matrix.md

@@ -0,0 +1,97 @@
+---
+type: Domain Guide
+title: Platform Compatibility Matrix
+description: Separate transferable interaction intent from platform capabilities, target fallbacks, and required evidence.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Platform Compatibility Matrix
+
+Primary role: adaptation comparison and verification checklist.
+
+## Repository Boundary
+
+This matrix compares responsibilities, not API support versions. It is not a browser compatibility database. A row's target behavior is a proposed adaptation until verified on the consumer's named runtime.
+
+## Reusable Method
+
+Choose the relevant concern, read its platform source guide, record native facts and target decisions separately, and execute both the preferred and fallback paths. Use the [Adaptation Workflow](adaptation-workflow.md) for the handoff.
+
+## Comparison Matrix
+
+| Concern | Source route | Transferable intent | Target boundary and fallback | Required observation |
+| --- | --- | --- | --- | --- |
+| Motion preference | [Apple](apple-interaction.md) | Essential information remains available with less motion | Web preference handling belongs to [Motion recipes](../motion/interaction-recipes.md); retain static status | Change preference and interrupt an active transition |
+| Return navigation | [Android](android-interaction.md) | Understand destination and preserve recoverable state | Browser history, parent links, and host Back are distinct; direct entry needs a known parent route | Normal return, direct entry, cancellation, missing prior item |
+| Adaptive presentation | [Android](android-interaction.md) | Preserve the task as available space changes | Native units/class cutoffs do not define Layout breakpoints; use the target's content constraints | Resize without losing query, selection, or focus |
+| Keyboard traversal | [Windows](windows-interaction.md) | Reach actions and move predictably within controls | Follow the chosen web semantic pattern; visible controls remain operable | Tab/reverse traversal, inner navigation, editing, dismissal |
+| Shortcuts | [Windows](windows-interaction.md) | Efficient access to a named command | OS/browser-reserved keys may be unavailable; retain a visible command | Reserved key path, disabled command, active text editor |
+| Multimodal feedback | [Apple](apple-interaction.md) | Communicate cause and result through available channels | Haptics/audio may be unavailable or inappropriate; retain essential visual/text feedback | Muted/unavailable channels and the actual target device |
+| Translucent treatment | [Apple](apple-interaction.md) | Keep foreground hierarchy understandable | Native materials do not translate to CSS equivalence; an opaque treatment is a candidate fallback | Actual contrast/readability across backgrounds and preferences |
+
+## Target Evidence Matrix
+
+| Axis | Record | What a missing check means |
+| --- | --- | --- |
+| Runtime | Exact browser/app engine, OS, relevant library/SDK versions | No claim beyond the exercised runtime |
+| Input | Keyboard, pointer, touch, controller, assistive technology as claimed | An untested mode is `not_run`, not a pass |
+| Preferences | Motion, contrast, text sizing, other relevant settings | Source support does not prove local handling |
+| Navigation | Direct entry, return, cancellation, nested overlays | A successful happy path leaves recovery unproven |
+| Capability | Available, unavailable, denied, interrupted where relevant | Fallback behavior must be exercised independently |
+| State | Normal, pending, failed, empty, stale or removed data | A screenshot of default state is insufficient |
+
+## Scroll Story Target Cases
+
+Use [Motion's scroll-story contract](../motion/interaction-recipes.md#scroll-driven-story) when the target is a browser scene controlled by scrolling. Record CSS timeline support at the tested version, feature-unavailable fallback, wheel/trackpad/keyboard/touch input actually used, browser history restoration, and resize/orientation changes. Viewport emulation is evidence of layout at that size, not of mobile hardware or touch physics.
+
+Require readable static chapters when the stage cannot fit. Test reduced-motion changes during an active scene, not just the startup preference. The [Scroll Story Lab](../examples/scroll-story/README.md) supplies a target implementation and separates its observed results from untested runtime/device cases.
+
+## Fixed-Viewport Scene Target Cases
+
+The [scene-navigation contract](../motion/interaction-recipes.md#full-viewport-scene-navigation) adds input arbitration to scene rendering. Test wheel bursts and momentum tails, reverse gestures, horizontal input, modifier zoom, native copy scrolling at both edges, keyboard editing, visible navigation, direct hashes, and browser Back/Forward. Touch testing includes swipe start outside the owned art surface, cancellation, a second pointer, pinch zoom, and orientation changes.
+
+The [worked example](../examples/scene-navigation/README.md) has desktop-emulated input evidence and an explicit reading escape. Physical trackpad behavior, browser chrome resizing on a phone, iOS Safari, Android, and assistive technology need separate actual-device runs. Never relabel CDP touch injection or a 375-pixel viewport as physical-device verification.
+
+## Example Record
+
+```yaml
+concern: keyboard-traversal
+source_guide: platform-guides/windows-interaction.md
+target: # actual browser, OS, widget semantics and versions
+decision: # the target interaction contract
+fallback: # complete visible operation path
+source_rechecked: # date and exact official locator
+actual_result: not_run
+limitations: # untested inputs, runtimes, and capabilities
+consumer_reference: not_applicable
+consumer_reference_reason: This blank comparison selects no consumer record.
+```
+
+## Opinionated Guidance
+
+Test fallback paths deliberately rather than waiting for accidental unsupported hardware. A successful fallback should preserve the task, though its presentation may differ.
+
+## Platform-Specific Guidance
+
+Apple, Android, and Windows guide pages own their dated official-source sets. Recheck them for native claims and separately verify the target runtime. Game-engine adaptation routes to [Game UI](../game-ui/index.md).
+
+## Unsupported Absolutes
+
+No row claims visual, semantic, accessibility, or performance equivalence between platforms. No generic “mobile” or “desktop” label replaces the actual runtime/input matrix.
+
+## Verification Contract
+
+An adaptation is reviewable when each selected row has a target decision, fallback, observed result, and limitation. Missing capability or runtime evidence stays explicit. Review when a linked source, target capability, or failed user task changes the mapping.
+
+The [Interaction Lab verification](../examples/domain-interactions/verification.md) records a macOS browser target for keyboard traversal, modal cancellation, history, content resizing, and reduced-motion preference changes. Small browser viewports are not mobile-device evidence; Android, iOS/iPadOS, Windows-native APIs, haptics, controllers, and assistive technology remain outside that run.
+
+## Source, License, And Attribution
+
+Locally authored comparison matrix derived from this domain's linked source reviews. Platform owners retain authority over their own conventions; no upstream table is reproduced.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Platform Adaptation Workflow](adaptation-workflow.md).

package/platform-guides/index.md

@@ -8,6 +8,17 @@ In scope: comparative vocabulary, interaction questions, current official-source
 
 Out of scope: affiliation, brand imitation, unsupported platform equivalence, and authority over web standards, accessibility, or Layout contracts.
 
+## Start Here
+
+| Task | Route |
+| --- | --- |
+| Record native facts, target decisions, and fallbacks. | [Platform Adaptation Workflow](adaptation-workflow.md) |
+| Compare Back and adaptive window behavior. | [Android Interaction As A Comparative Reference](android-interaction.md) |
+| Compare keyboard, focus, and commands. | [Windows Interaction As A Comparative Reference](windows-interaction.md) |
+| Select target and fallback verification cases. | [Platform Compatibility Matrix](compatibility-matrix.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.
+
 ## Available Guides
 
 - [Apple Interaction As A Comparative Reference](apple-interaction.md) turns selected interaction themes into questions for web adaptation without claiming platform equivalence.
@@ -18,9 +29,9 @@ A platform guide names the platform, source authority, version or review date, w
 
 ## 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: [Apple Interaction As A Comparative Reference](apple-interaction.md).
+Next: [Platform Adaptation Workflow](adaptation-workflow.md).

package/platform-guides/windows-interaction.md

@@ -0,0 +1,75 @@
+---
+type: Domain Guide
+title: Windows Interaction As A Comparative Reference
+description: Source-bounded Windows keyboard, focus, and command guidance with web adaptation cases.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+platform: Windows applications and WinUI
+platform_version: dated Microsoft Learn documentation; target Windows App SDK version required
+reviewed_on: 2026-09-08
+---
+
+# Windows Interaction As A Comparative Reference
+
+Primary role: Windows platform comparison guide.
+
+## Repository Boundary
+
+This guide compares keyboard and command behavior in Windows application guidance. It supplies no Fluent visual defaults and does not imply that WinUI focus APIs exist in the browser. The consumer records its actual Windows, SDK, browser, and control-library versions.
+
+## Reusable Method
+
+Start with the [Adaptation Workflow](adaptation-workflow.md). Identify the command, navigation group, and focus scope before choosing a shortcut or implementation API.
+
+## Source-Bounded Conventions
+
+| Concern | Official source and bounded fact | Transferable question |
+| --- | --- | --- |
+| Sequential and inner navigation | [Keyboard interactions](https://learn.microsoft.com/en-us/windows/apps/design/input/keyboard-interactions) distinguishes moving between controls from moving within some composite controls | Is the key moving between tasks, among items, or editing a value? |
+| Initial focus | The same source discusses logical starting focus and avoiding an initially focused destructive action | Does the entry target help the intended task without accidental destructive activation? |
+| Focus movement | [Focus navigation](https://learn.microsoft.com/en-us/windows/apps/develop/input/focus-navigation) documents native focus navigation and control behavior | Can focus reach every required action, and where does it return after dismissal? |
+| Commands | [Keyboard accelerators](https://learn.microsoft.com/en-us/windows/apps/develop/input/keyboard-accelerators) describes command invocation and scoping in Windows applications | Does a shortcut invoke the same command and availability rules as its visible control? |
+
+Source set reviewed 2026-09-08. These are platform guidance and API documentation, not evidence that a consumer implements them.
+
+## Worked Adaptation: Searchable Command Surface
+
+Task: find and invoke commands without a pointer. Begin with the [Command Surface recipe](../recipes/command-surface.md) for spatial composition. Use the correct web widget semantics for the chosen design; a native control's tab-stop policy should not be copied onto unrelated HTML elements.
+
+Define the opening control, query input, result navigation, selected command, disabled-command explanation, and dismissal target. Command buttons and shortcuts share one operation owner. Editing text must not accidentally invoke a global command. A shortcut is supplemental: the visible action remains available when that key combination is reserved by the browser or OS.
+
+| Test | Expected target behavior |
+| --- | --- |
+| Open with keyboard | Focus reaches the declared entry target |
+| Search to zero results | Query remains editable and dismissal remains available |
+| Attempt an unavailable command | No operation; availability is explained consistently |
+| Dismiss after invoker removal | Focus reaches a documented surviving target |
+| Use a reserved/unavailable shortcut | The visible control still performs the task |
+
+Actual result: `not_run`. This is a fictional web adaptation contract.
+
+## Opinionated Guidance
+
+Centralize command availability so menu, button, and shortcut do not disagree. Do not add shortcuts before checking focus, text editing, and the complete visible operation path.
+
+## Platform-Specific Guidance
+
+WinUI accelerators and focus APIs have native routing rules. Web controls use HTML, the selected ARIA pattern where necessary, browser defaults, and the application's focus scope. See the [shared accessibility evidence gate](../quality/gates/accessibility-evidence.md) for the required evidence boundary.
+
+## Unsupported Absolutes
+
+Arrow keys are not a replacement for Tab in every UI. A Windows shortcut is not safe to intercept globally in every browser. A working pointer flow does not prove keyboard operation.
+
+## Verification Contract
+
+Verify entry, traversal, command invocation, text editing, cancellation, disabled state, and focus restoration on every claimed runtime/input. Include a missing invoker and nested surface. Review on Windows SDK, browser, source guidance, or command-routing changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the official Microsoft sources linked above, rechecked 2026-09-08. No upstream examples, control code, or visual assets are copied. `consumer_reference: not_applicable` because no consumer implementation record is selected.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Platform Compatibility Matrix](compatibility-matrix.md).