stylegallery 0.1.4 → 0.1.7

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 |

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.
@@ -16,11 +27,17 @@ Out of scope: affiliation, brand imitation, unsupported platform equivalence, an
 
 A platform guide names the platform, source authority, version or review date, web-adaptation boundary, and local verification protocol. Similar appearance or behavior does not establish affiliation or correctness.
 
+## Source-Backed Deep Dives
+
+- [Adaptive Navigation Across Platforms](adaptive-navigation.md). Preserve task state across window and navigation transformations.
+- [Preferences And Accessibility Across Platforms](preferences-and-accessibility.md). Compare text scaling, contrast, motion, and transparency independently.
+- [Input And Focus Across Platforms](input-and-focus.md). Compare keyboard, pointer, drag alternatives, and focus contracts.
+
 ## 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/input-and-focus.md

@@ -0,0 +1,91 @@
+---
+type: Domain Guide
+title: Input And Focus Across Platforms
+description: Compare keyboard, pointing, dragging, focus, and target conventions using named native and web contracts.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+platform: Apple applications, Android Compose, Windows applications, and web adaptations
+platform_version: dated official documentation; consumer OS, input device, and browser versions required
+reviewed_on: 2026-09-21
+---
+
+# Input And Focus Across Platforms
+
+Primary role: comparative input and focus guide.
+
+## Repository Boundary
+
+This page compares platform interaction contracts. It does not make one platform's shortcuts, target dimensions, or focus model universal. Layout owns logical spatial order; Design Engineering owns the [component behavior](../design-engineering/native-interaction-contracts.md); shared quality owns accessibility evidence.
+
+## Reusable Method
+
+For each task, identify the action, focused or selected object, available input paths, and owner of cancellation. Distinguish moving focus, moving selection, changing a value, and invoking a command. Then compare the target platform's expected behavior with the proposed adaptation.
+
+### Platform And Web Sources
+
+| Source | Bounded finding | Adaptation question |
+| --- | --- | --- |
+| [Apple HIG keyboards](https://developer.apple.com/design/human-interface-guidelines/keyboards) | Keyboard guidance includes text entry and discoverable, platform-appropriate shortcuts. | Which commands remain discoverable without knowing a shortcut? |
+| [Apple HIG pointing devices](https://developer.apple.com/design/human-interface-guidelines/pointing-devices) | Pointer interaction is a named platform concern alongside other input. | Does pointer feedback preserve the same task as touch or keyboard input? |
+| [Android Compose keyboard actions](https://developer.android.com/develop/ui/compose/touch-input/keyboard-input/commands) | Editing components have default key behavior; key handlers can consume or propagate events. | Does a parent handler steal a key from an editor or child control? |
+| [Windows keyboard interactions](https://learn.microsoft.com/en-us/windows/apps/develop/input/keyboard-interactions) | The guidance distinguishes navigation, commands, and visible focus for keyboard use. | Are command invocation and focus navigation separate and predictable? |
+| [APG keyboard interface](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/) | Composite widgets have internal navigation conventions; focus and selection are distinct. | Is the chosen widget model actually implemented, including entry and exit? |
+| [Pointer Events Level 3](https://www.w3.org/TR/pointerevents3/) | Pointer events model multiple pointing inputs, capture, and cancellation. | Does cancellation leave a coherent drag state and release ownership? |
+
+Read on 2026-09-21. Apple source bodies were inspected through the official documentation JSON. APG is informative guidance; Pointer Events is a standards-track source. Actual input behavior requires a named OS/browser/device combination.
+
+### Web Accessibility Conditions To Keep Separate
+
+| Source | Bounded condition | Local probe |
+| --- | --- | --- |
+| [Keyboard, SC 2.1.1](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) | Functionality needs keyboard operability, with the criterion's scoped exception. | Complete the task without a pointing device. |
+| [Dragging Movements, SC 2.5.7](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html) | Dragging functionality needs a single-pointer alternative without dragging, subject to exceptions. | Try a click/tap alternative as well as keyboard operation. |
+| [Target Size Minimum, SC 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) | The AA criterion specifies 24 by 24 CSS pixels or its stated exceptions, including a defined spacing alternative. | Evaluate the actual hit region and nearby targets, not only the icon. |
+| [Hover Or Focus Content, SC 1.4.13](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) | Additional content has dismissibility, hoverability, and persistence conditions with scoped exceptions. | Move onto the revealed content and dismiss it without losing the task. |
+| [Focus Order, SC 2.4.3](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) | Sequential focus order must preserve meaning and operation where order matters. | Follow focus through the actual rendered structure. |
+| [Focus Not Obscured Minimum, SC 2.4.11](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) | At AA, an author-created surface must not entirely hide the focused component. | Open sticky and overlay surfaces while moving focus. |
+
+These Understanding documents explain normative WCAG requirements. The minimum target criterion is not a universal product target size; native units and platform recommendations need their own rationale. Keyboard access and a no-drag single-pointer alternative answer different conditions.
+
+### Worked Adaptation: Reorder An Item
+
+The product offers a drag handle and chooses a Move action with explicit destinations as its alternative. All paths call the same reorder operation with stable item identity. Focus stays on the moved item or on a documented successor, and the result is exposed without relying solely on movement.
+
+| Path | Ownership decision | Failure to catch |
+| --- | --- | --- |
+| Pointer drag | Capture, drop eligibility, and cancelled-drag outcome | A cancelled pointer stream leaves the item detached. |
+| Click/tap Move | Destination choice and confirmation | The alternative still requires a hidden drag gesture. |
+| Keyboard | Widget navigation and command activation | Arrow keys move the page and item simultaneously. |
+| Assistive technology | Name, action, current position, and resulting state | The visual reorder is absent from the semantic order. |
+
+This is a local proposal. It does not prescribe one keyboard shortcut or say that every list must be a composite ARIA widget.
+
+## Opinionated Guidance
+
+Use shortcuts to accelerate visible actions. Scope listeners to the intended surface, and let text editing and composition retain their own keys. Give each cancellation action one clearly documented owner before allowing it to propagate outward.
+
+## Platform-Specific Guidance
+
+Primary pointer and hover media features describe capabilities, not an exclusive device category; hybrid input requires an actual interaction matrix. System/browser shortcuts and assistive-technology commands may already own a key combination. Record the platform conflict check instead of translating Control to Command mechanically.
+
+For IME-sensitive keys, follow [Text Input And Internationalization](../design-engineering/text-input-and-internationalization.md). For drag presentation after cancellation, follow [Interruption And Retargeting](../motion/interruption-and-retargeting.md).
+
+## Unsupported Absolutes
+
+Keyboard support alone does not satisfy the no-drag pointer condition. Visible focus does not prove focus order. A large icon does not prove a large hit region. A touch-capable device does not imply that hover or keyboard input is absent.
+
+## Verification Contract
+
+Use actual task sequences with keyboard, pointer, touch where supported, and relevant assistive technology. Record input mode changes mid-task, cancelled drag, focus after item removal, nested Escape, hover-to-content movement, and overlays covering the focus target.
+
+These cases are unexecuted. Synthetic events can validate handlers but do not establish physical input or assistive-technology integration. Re-review when command scope, component roles, or target input support changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the linked first-party sources, inspected 2026-09-21. No native interaction artwork, source examples, or code are copied. `consumer_reference: not_applicable` because no consumer input record is selected.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Platform Compatibility Matrix](compatibility-matrix.md).

package/platform-guides/preferences-and-accessibility.md

@@ -0,0 +1,90 @@
+---
+type: Domain Guide
+title: Preferences And Accessibility Across Platforms
+description: Compare text scaling, motion, contrast, transparency, and accessibility semantics without collapsing distinct user preferences.
+domain: platform-guides
+lifecycle: experimental
+provenance_kind: local
+platform: Apple applications, Android Compose, Windows applications, and web adaptations
+platform_version: dated official documentation; consumer OS, framework, and browser versions required
+reviewed_on: 2026-09-21
+---
+
+# Preferences And Accessibility Across Platforms
+
+Primary role: comparative preference and accessibility adaptation guide.
+
+## Repository Boundary
+
+This guide compares what named platforms expose and the questions a consumer must answer. Shared [accessibility evidence](../quality/evidence/accessibility.md) governs conformance. Product color, typography, transparency, and motion remain consumer-owned; this page supplies no visual defaults to Layout.
+
+## Reusable Method
+
+Inventory each preference as a separate input. Name its source, application override policy, affected components, and update behavior. Specify a usable base presentation for targets that do not expose a particular signal. Then test meaningful combinations rather than treating “accessibility mode” as one boolean.
+
+### Source Findings
+
+| Source | Bounded finding | Transfer boundary |
+| --- | --- | --- |
+| [Apple HIG accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) | The guidance addresses larger text, VoiceOver descriptions, multiple information channels, and response to Reduce Motion. | Native support depends on the implementation; a web font choice does not implement Dynamic Type. |
+| [Apple HIG materials](https://developer.apple.com/design/human-interface-guidelines/materials) | Material behavior can respond to appearance and accessibility settings, including transparency and contrast. | A CSS blur copied from a screenshot does not inherit native material behavior. |
+| [Android Compose accessibility](https://developer.android.com/develop/ui/compose/accessibility) | Compose exposes semantics and accessibility support that custom components must preserve. | A drawn label is not by itself an accessibility semantic node. |
+| [Windows contrast themes](https://learn.microsoft.com/en-us/windows/apps/design/accessibility/high-contrast-themes) | Contrast themes use system color roles and can change while an app runs. | A single hard-coded dark palette is not the Windows contrast-theme contract. |
+| [Media Queries Level 5](https://www.w3.org/TR/mediaqueries-5/#mf-user-preferences) | Color scheme, reduced motion, contrast, and reduced transparency are separate preference features. | Support must be checked per feature and target; one query does not imply another. |
+| [CSS Color Adjustment](https://www.w3.org/TR/css-color-adjust-1/#forced-colors-mode) | Forced colors can replace author colors with a user-selected palette and adjust effects. | Preserve meaningful distinctions when author decoration changes or disappears. |
+
+Read on 2026-09-21. Apple documentation bodies were inspected through the official documentation JSON. These living platform pages and standards-track publications are dated readings, not proof that all named features exist in a selected OS/browser release.
+
+### Preference Resolution
+
+Record “follow system” separately from an explicit in-product selection. Define which setting currently determines the presentation and how users return to system behavior. Do not use one persisted theme name to infer motion, contrast, or text-size preferences.
+
+For web forced colors, verify semantic system-color pairings and visible boundaries rather than preserving brand appearance at any cost. Any local exception to automatic color adjustment needs a stated reason and target evidence. For reduced transparency without a supported media feature, the base surface still needs to make its content legible.
+
+### Text Scaling Is A Behavior Change
+
+[Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) concerns preserving information and function when content is presented in a narrow equivalent viewport, with scoped exceptions. [Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) concerns loss of content or function when users override specified spacing. Neither criterion means that every interface must have the same default type scale.
+
+Local proposal: treat text scaling as a reason to reconsider composition, not merely multiply font sizes. A toolbar can need wrapping or a different command presentation; a dialog may need a scrollable reading area; a short title can become several lines. Those spatial choices go to Layout, while label priorities and command availability stay in the product.
+
+### Combination Matrix
+
+| Combination | Failure to probe | Observable result to retain |
+| --- | --- | --- |
+| Dark appearance with forced colors | The app assumes its dark palette remains authoritative. | Text, selection, links, and focus remain distinguishable. |
+| Larger text with compact window | Fixed control bounds clip names or actions. | Full task remains possible without losing required information. |
+| Reduced motion during pending work | The indicator disappears without an equivalent waiting state. | Pending and completed states remain understandable. |
+| Reduced transparency over rich content | A custom surface depends on blur alone for separation. | Foreground content remains legible with the chosen fallback. |
+| Screen reader with changing result set | Decorative text changes lack meaningful semantics. | The selected task and concise result status are exposed correctly. |
+| Runtime preference change | Only newly mounted components update. | Existing dialogs, portals, and embedded surfaces follow their declared policy. |
+
+These are proposed probes, not a statement that all combinations are exposed by every OS. Record unavailable combinations as not applicable with a reason.
+
+## Opinionated Guidance
+
+Make preference ownership explicit and keep the base experience usable. Avoid adding a single “accessible theme” that quietly overrides unrelated preferences. Use product settings to provide clear user control where platform signals are absent or insufficient.
+
+## Platform-Specific Guidance
+
+Native text scaling, browser zoom, author font settings, and OS display scaling can affect different layers. Name which mechanism was changed in a test. Likewise, simulated CSS media features establish a code path, while an actual OS setting additionally exercises host integration.
+
+Use [Accessible Motion](../motion/accessible-motion.md) for motion replacement and [Typography Semantics](../design-terminology/typography-semantics.md) for source-specific type-style meanings.
+
+## Unsupported Absolutes
+
+Dark mode is not forced colors. A contrast preference is not a contrast measurement. Removing blur does not guarantee legibility. Passing one text-size case does not prove all localization and scaling combinations.
+
+## Verification Contract
+
+Record the actual system setting, application override, media/API observation, and effective component state. Test before load and while a dialog or asynchronous operation is active. Compare semantic and visual evidence for the same state; do not substitute an accessibility-tree snapshot for an announcement test.
+
+This documentation defines unexecuted cases. It makes no native accessibility or browser conformance claim. Re-review when a source, preference-resolution rule, or target platform changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the linked first-party sources, inspected 2026-09-21. No platform values or assets are imported. `consumer_reference: not_applicable` because no consumer preference or profile record is selected.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Input And Focus](input-and-focus.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

package/scripts/compiler/README.md

@@ -0,0 +1,112 @@
+---
+type: Interface Guide
+title: SG Website Compilation
+description: Run a separately installed website compiler through the SG CLI and MCP server.
+---
+
+# SG Website Compilation
+
+Primary role: compiler setup and execution reference.
+
+Use `sg compile`, `sg timeline`, and the other commands below directly. The `stylegallery-mcp` server exposes the same names alongside `discover`, `resolve`, `claims`, `context`, `ops`, and `retrieve`. Compiler operations can write files, open websites, and invoke a model; each tool declares those effects. The original [v1 knowledge interface](../../consumer-reference/agent-native/README.md) remains available separately.
+
+## Setup
+
+Install StyleGallery with Node.js 22 or newer using `npm install --global stylegallery`. For an unreleased StyleGallery checkout, run commands from that checkout as `npm run sg -- <command>` instead. If another program already owns the `sg` command, use the equivalent `stylegallery` executable or the npm script. The compiler is a [separate private repository](https://github.com/changeroa/site-compiler); an account with access must install it once:
+
+```sh
+gh repo clone changeroa/site-compiler /absolute/path/to/site-compiler
+cd /absolute/path/to/site-compiler
+npm ci --ignore-scripts --no-audit --no-fund
+npx playwright install chromium
+export SG_COMPILER_ROOT=/absolute/path/to/site-compiler
+sg discover --format json
+```
+
+Set `SG_COMPILER_ROOT` in your shell profile for CLI use and in your MCP server environment for MCP use. A CLI invocation can override it with `--compiler-root /absolute/path/to/site-compiler`. `discover` preserves the knowledge response and adds a top-level `compiler` object containing installation status, the actual Git revision, tracked changes, and available operations. Missing compiler setup leaves knowledge queries usable.
+
+The verified upstream revision is declared in [scripts/compiler/operations.mjs](operations.mjs). `matches_verified_revision` is true only for that revision without tracked modifications; a mismatch is reported but does not block execution. Use that revision when reproducing the verified workflow. To use a newer upstream version, update your compiler checkout with `git pull --ff-only` and `npm ci`, then inspect `sg discover` and `sg workflow`; SG does not fetch or upgrade code during a tool call. The compiler source, browser binaries, captured frames, and private pack data are not included in the StyleGallery npm package.
+
+## CLI
+
+Run these from the consumer project's working directory:
+
+```sh
+sg workflow
+sg workflow --document readme
+sg compile --url https://example.com --out ./captures/example
+sg timeline --url https://example.com --out ./captures/example --step 500 --grow
+sg transcribe --in ./captures --only example
+sg sale --in ./captures/example --out ./captures/example/sale
+sg gate --in ./captures/example --sale ./captures/example/sale --json ./captures/example/qa-report.json
+sg build --packs ./captures --out ./builds --only example
+sg shots --builds ./builds --slug example
+```
+
+`compile` captures scenes and frames; it does not produce a SceneBook by itself. A SceneBook describes scene geometry and content; its Timeline companion describes observed scroll behavior. `transcribe` produces these documents. Transcription and the optional sale-preview builder require an installed, authenticated `claude` CLI and can incur model usage. Their input roots contain one subdirectory per pack. Supply `--stylegallery` only when a different SG corpus should be used; the installed StyleGallery package is the default.
+
+Read `sg workflow` before selecting stages. Its installed compiler document owns the task policy: faithful reconstruction, adaptation for a new design, or sale-package production. These are task purposes, not CLI flags. Reconstruction uses available source media and direct observation to fill document gaps; the current implementation agent remains the builder. A media record carries source URLs, responsive variants, reuse or replacement decisions, and playback checks separately from the observation document.
+
+`sale` replaces observed copy with structural descriptors. `build` consumes only those sale editions and intentionally restricts original-page and external-media access. It is a package preview, not the faithful-reconstruction route. Use sale, build, and release operations when that package purpose is requested. A document-only evaluation is an explicit experiment, not the default website workflow. The SG skill only retrieves this workflow; it does not duplicate these policies.
+
+By default, `sale` writes its private audit to `copy-audit.private.json` in the parent of `--out`. Override this with `--audit`; it must remain outside the sale directory. The resolved destination is returned in `result.paths.audit`.
+
+| Command | Input and output |
+| --- | --- |
+| `compile` | `--url`, `--out`; writes `scenes.json` and `frames/` |
+| `timeline` | `--url`, `--out`; writes `timeline-curve.json` and `dense/` |
+| `transcribe` | `--in` pack root; writes documents and `transcribe.json` |
+| `sale` | `--in`, `--out`; writes sale documents and a private audit outside `out` |
+| `gate` | `--in`; optionally `--sale`, `--json`; returns failure when the upstream gate fails |
+| `build` | `--packs`, `--out`; writes sale-edition previews and `build.json` |
+| `shots` | `--builds`, `--slug`; writes screenshots and a report under each build |
+| `probe` | `--url`; logs scroll geometry; optional `--chrome` |
+| `batch-triage` | `--candidates`, `--out`; captures candidate curves and writes `runs.json` |
+| `triage` | `--in`; writes heuristic rankings |
+| `batch-capture` | `--candidates`, `--out`; captures scenes/timelines and writes `capture.json` |
+| `pack-status` | `--candidates`, `--in`; generates sale editions, runs gates, and updates status |
+| `pack-release` | `--products`; uses the compiler checkout's `out/packs` and `out/builds`, replacing matching files in `out/release` |
+| `workflow` | Reads the installed `SKILL.md`, or `README.md` with `--document readme` |
+
+All CLI results are one JSON envelope on stdout, including failures. Child logs are returned in `result.stdout` and `result.stderr`, with a 64 KiB tail per stream and truncation flags. Relative path options resolve from the caller's working directory; upstream scripts execute from the compiler checkout. `pack-release` is the upstream exception with fixed checkout-relative directories, and produces local archives without publishing them.
+
+Use `sg discover` or `sg ops` for the full input schemas. CLI options use hyphens (`--max-height`); MCP inputs use underscores (`max_height`). Unknown options, repeated CLI options, missing required paths, and invalid numeric values fail before execution. `--format json` is optional. `--runner-timeout-ms` bounds the entire process tree, defaults to 30 minutes, and accepts up to six hours; `--timeout-ms` on model operations instead controls upstream per-job timeouts. Interrupting the CLI or cancelling an MCP request terminates its running process tree.
+
+`ok` reports process success. Batch scripts can exit zero with failed individual jobs: use the returned ledger path to inspect each pack. A gate pass is an upstream consistency check, not SG conformance, accessibility proof, or rights clearance. Each result records the compiler revision, tracked-change status, executed script hash, and normalized arguments. Captures and generated documents remain consumer-owned outputs and are not admitted to the governed material registry.
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "stylegallery": {
+      "command": "npx",
+      "args": ["--yes", "--package", "stylegallery", "stylegallery-mcp"],
+      "env": { "SG_COMPILER_ROOT": "/absolute/path/to/site-compiler" }
+    }
+  }
+}
+```
+
+Call `compile` with `{"url":"https://example.com","out":"/absolute/path/to/captures/example"}` or `gate` with `{"in":"/absolute/path/to/captures/example"}`. Prefer absolute paths because the MCP client's launch directory may differ from your terminal. Long captures require a client request timeout longer than the capture; the runner's timeout does not change client settings. `workflow` and the knowledge tools are read-only; execution tools are marked as potentially destructive and non-idempotent because existing artifacts may be replaced.
+
+From the StyleGallery checkout, use `npm run sg -- compile ...` and `npm run sg:mcp` for local development. To connect an MCP client to that unreleased checkout, use `"command": "node"` and `"args": ["/absolute/path/to/StyleGallery/scripts/sg-server.mjs"]` with the same environment settings. The frozen six-tool v1 server is `npm run sg:mcp:v1`, and its CLI is `npm run sg:v1 -- ...`.
+
+## Contracts And Verification
+
+The adapter follows the handoff fields in [Component Contract](../../design-engineering/component-contract.md): explicit inputs, outputs, process ownership, cancellation, and observable failure. Motion transcription remains governed by [Observed Choreography](../../motion/observed-choreography.md). These are routes into the existing domains; the transport creates no new domain or reusable Layout styling.
+
+From the StyleGallery checkout, run `npm run test:compiler` for subprocess, argument, cancellation, JSON, and MCP transport checks. With a compiler installation and Chromium available, run `SG_COMPILER_INTEGRATION_ROOT=/absolute/path/to/site-compiler npm run test:compiler` to also capture a local fixture with the real upstream scripts. Model transcription, model builds, and product release packaging are separate upstream operations and are not exercised by that smoke test.
+
+Implementation handoff:
+
+```text
+Consumer reference: declared
+Consumer reference record: consumer-reference/agent-native/registry.json
+consumer_reference: consumer-reference/agent-native/registry.json
+```
+
+## Navigation
+
+Parent: [StyleGallery](../../README.md).
+Next: [Component Contract](../../design-engineering/component-contract.md).

package/scripts/compiler/cli.mjs

@@ -0,0 +1,51 @@
+import { runCli } from "../agent-native/cli-adapter.mjs";
+import { compilerOperations, compilerToolDefinitions } from "./operations.mjs";
+import { compilerDiscovery, executeCompiler, failure } from "./runtime.mjs";
+
+export function withCompilerDiscovery(report, config = {}) {
+  if (!report.ok || !["discover", "ops"].includes(report.operation)) return report;
+  return { ...report, compiler: compilerDiscovery(config) };
+}
+
+export async function runSgCli(argv, config = {}) {
+  const args = [...argv];
+  const options = { ...config };
+  let report;
+  const rootIndex = args.indexOf("--compiler-root");
+  if (rootIndex >= 0) {
+    const root = args[rootIndex + 1];
+    if (!root || root.startsWith("--") || args.lastIndexOf("--compiler-root") !== rootIndex) {
+      report = failure(null, "argument_invalid", "--compiler-root requires one checkout path.");
+    } else { options.compilerRoot = root; args.splice(rootIndex, 2); }
+  }
+  const command = args[0];
+  if (!report && !Object.hasOwn(compilerOperations, command) && command !== "workflow") {
+    report = withCompilerDiscovery(runCli(args).report, options);
+  } else if (!report) {
+    const definition = compilerToolDefinitions().find(({ name }) => name === command);
+    const properties = definition.inputSchema.properties;
+    const input = {};
+    const seen = new Set();
+    for (let i = 1; i < args.length; i += 1) {
+      const flag = args[i];
+      const key = flag.startsWith("--") ? flag.slice(2).replaceAll("-", "_") : "";
+      if ((!Object.hasOwn(properties, key) && key !== "format") || seen.has(key)) {
+        report = failure(command, "argument_invalid", `Unknown or repeated argument: ${flag}`);
+        break;
+      }
+      seen.add(key);
+      const type = key === "format" ? "string" : properties[key].type;
+      if (type === "boolean") { input[key] = true; continue; }
+      const value = args[++i];
+      if (value === undefined || value.startsWith("--")) {
+        report = failure(command, "argument_value_required", `${flag} requires a value.`);
+        break;
+      }
+      if (key === "format") {
+        if (value !== "json") { report = failure(command, "format_unsupported", "Only --format json is supported."); break; }
+      } else input[key] = ["number", "integer"].includes(type) ? Number(value) : value;
+    }
+    report ??= await executeCompiler(command, input, options);
+  }
+  return { report, exitCode: report.ok ? 0 : 1, output: `${JSON.stringify(report, null, 2)}\n` };
+}