Portrait visual and interaction contract
This contract is a successor-facing constraint, not a claim that its proposed
pixels are shipped. Values are in logical panel pixels for the 568×1232
portrait mode. A native grim frame establishes composition; camera and
real-finger checks establish the separate optical and reachability gates.
Visual tokens
| Token | Current evidence / proposed rule | Acceptance method | Evidence class | Citation | Open gate |
|---|---|---|---|---|---|
| Canvas | Dark, stable background behind launcher content; preserve the persistent 56px top bar. | Native frame is 568×1232 and bar remains visible with keyboard. | native | docs/evidence/launcher-gestures/integrated-injected/keyboard-visible.png | Panel scanout/optical contrast UNVERIFIED. |
| Title | One page title, 40–44px visual role; one short state line below it. | Title/state remain distinct at keyboard-visible height. | native | docs/evidence/launcher-gestures/integrated-injected/keyboard-visible.png | Physical readability UNVERIFIED. |
| Card | Card title 30–34px, hint 19–22px; content inset at least 24px; no essential text only in color. | Native screenshot plus text/focus state review. | native | docs/evidence/offline-wifi-image/help.png | Optical readability UNVERIFIED. |
| Spacing | 8px micro-gap, 16px control gap, 24px content inset; retain a clear gap between cards and footer. | Inspect native frame at full resolution. | native | docs/evidence/launcher-gestures/integrated-injected/overview.png | Future card layout must remeasure. |
| Targets | Primary controls are at least 56px tall; retain visible Previous, Back, Next and the persistent controls. | Host geometry review and finger capture. | native, real-finger | docs/evidence/launcher-gestures/real-finger/README.md | All-edge reachability UNVERIFIED. |
| State | Focus has a text/state cue; pressed, loading, empty, stale, failure, EOF, and cancelled states name a next action. | Successor fixture plus native capture for each new state. | injected | docs/evidence/network-video/installed-controls/README.md | Cross-surface state wording UNVERIFIED. |
| Keyboard viewport | Keep an explicit Back/fallback route above the shown keyboard; do not place essential controls in its reserved lower region. | Shown keyboard native frame and real-finger sequence. | native, real-finger | docs/evidence/shell-real-touch-keyboard/README.md | Exact physical reach envelope UNVERIFIED. |
Navigation ownership
| Route | Primary owner | Visible fallback | Required states | Successor / dependency | Open gate |
|---|---|---|---|---|---|
| Apps | launcher/catalog | Back closes the overlay to current work | loading, empty catalog, launch failure | shell launcher/catalog | Physical catalog readability UNVERIFIED. |
| Windows / overview | touch-launcher-gestures-overview | Back/down returns to Apps; persistent Apps opens catalog | loading, empty, stale, helper failure | catalog helper; card architecture | Stale/empty board result UNVERIFIED. |
| Cards | the-shell-manages-apps-as-cards | Button entry plus Back/Home recovery | unavailable/private content, refusal to close | card composition decision | Entire live-card route UNVERIFIED. |
| Keyboard | shell keyboard | Keyboard control and Back/Home remain visible | shown, hidden, focused app exits | wvkbd and launcher viewport | Full drag/reach UNVERIFIED. |
| System | shell system controls | Cancel returns to shell | confirmation, denial/failure, reboot return | privileged action helper | Cold USB-powered recovery timing UNVERIFIED. |
| Stop / EOF | the-shell-plays-network-video | Home/Apps after cleanup | Stop, EOF, network failure | video session controller | Network failure treatment UNVERIFIED. |
| Help | launcher/catalog | Back returns to Apps | page bounds, empty catalog remains recoverable | launcher catalog | Focused real-finger Help test UNVERIFIED. |
Motion and accessibility acceptance
| Interaction | Required behavior | Measured budget / proof | Reduced-motion behavior | Open gate |
|---|---|---|---|---|
| Page release | A completed page or overview release settles in at most 200ms CPU-side release-to-final-submit; report wall and process-CPU measures separately. | Existing injected matrix: 41 settled transitions, max 163ms wall. | Settle immediately only after preserving the same page/card result and visible state. | Real-finger latency and scanout UNVERIFIED. |
| Card finger tracking | The future live card visibly follows the finger, with continuous tracking measured separately from release. | Card owner must record frame/input/memory evidence before acceptance. | Reduce decorative interpolation, never remove live visual, finger tracking, expand, close/refusal, or recovery. | UNVERIFIED. |
| Status and focus | Labels explain focused, loading, empty, stale, failed, cancelled, Stop and EOF states without color alone. | Fixture covers state transitions; native capture records visible text. | Same text and fallback stay present. | Cross-surface test/capture UNVERIFIED. |
| Reachability | Every gesture has a visible button, Back, or Home alternative. | Flow matrix routes every named control. | No gesture-only operation. | Physical all-edge review UNVERIFIED. |
Review record
See design-review.md for the completed coordinator review of the native captures and proposed layouts. That review does not substitute for the physical readability and interaction gates listed above.
Measurable review checks
| Check | Baseline / threshold | Host review method | Physical gate |
|---|---|---|---|
| Text contrast | Current source colors calculate to 16.96:1 title (#f8fafc/#111827), 11.95:1 secondary (#cbd5e1/#111827), 9.65:1 card-title (#ffffff/#24495a), 6.50:1 card-hint (#cbd5e1/#24495a), and 9.35:1 error (#fca5a5/#111827). Successors must retain at least 4.5:1 for text over its actual fill. | Compute sRGB relative luminance from the source colors and keep the calculation with the source test. | Camera/glass review checks glare does not make the measured design contrast unusable. |
| Focus | The selected window currently changes its card fill and adds the focused state text. A successor must use both a non-color state label and a visible shape/border/fill change. | State-machine fixture compares unfocused/focused render metadata and asserts the label/state change. | Real-finger selection capture. |
| Pressed | Pressing a card must show a bounded visual response before launch/focus; cancellation must restore the original card without launch. | Pointer/touch fixture checks press, moved-out cancel, and release-on-same-card transitions. | Real-finger tap/cancel capture. |
| Error and recovery | User-facing messages are short, avoid raw paths/GLib text, and name an available next action such as Back, Apps, Home, Retry, or Cancel. | Fixture asserts normalized state ID, copy key, and visible fallback for launch/helper/system/video states. | Integrated board state capture. |
| Reduced motion | With motion reduced, no decorative interpolation is required, but page/card result, finger tracking, expansion, close/refusal, focus, and all button fallbacks remain. | Card/gesture state-machine fixtures run with animation duration zero and assert identical end state and recovery controls. | Physical preference/flag exercise once implemented. |
The measurements above are source-color and host-state checks. They do not measure panel luminance, scanout, or camera exposure.