stylegallery 0.1.4 → 0.1.6

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).

package/recipes/homepage.md

@@ -37,8 +37,16 @@ Reject this recipe when the page is primarily a document, dashboard, form, comma
 
 Order sections by the visitor's decision path, not by visual symmetry. Put the primary heading, explanation, proof, and action in semantic order before layout classes. Repeated proof should be a list when each item has the same role.
 
+## Scroll Story Composition
+
+When a section explains a product through changing visual chapters, compose existing containment, stacking, overlay, and sticky responsibilities before proposing a new spatial pattern. Name the sticky containing block, stage height, document scroll track, offset, release boundary, and long-content fallback. Prevent clipping when copy is taller than the stage.
+
+Motion owns continuous progress and scene changes through the [Scroll-driven Story recipe](../motion/interaction-recipes.md#scroll-driven-story). The [Scroll Story Lab](../examples/scroll-story/README.md) demonstrates this composition with two products. Photography, device mockups, transforms, opacity, and timing remain in those consuming examples.
+
 ## Scroll Ownership
 
+A short full-page showcase can compose a viewport shell and [overlay-stack](../patterns/overlay-exception/overlay-stack.md) responsibilities with the [Full-viewport Scene Navigation contract](../motion/interaction-recipes.md#full-viewport-scene-navigation). Declare the document as fixed in scene mode, the chapter copy as the native overflow owner, and the document as the scroll owner in reading mode. The failure to prevent is a clipped or unreachable chapter when the viewport or text size changes. The [worked example](../examples/scene-navigation/README.md) uses a shrinkable stage between header and footer; it introduces no new reusable Layout pattern.
+
 Prefer normal document scrolling. Avoid nested scroll regions unless a section has an explicit independent task, such as a horizontally scrolling media reel with named keyboard and overflow behavior.
 
 ## Accessibility Expectations