# UX issue ledger

Severity represents user impact from the cited observation; it does not turn an
unknown into a defect. “Existing owner” means a proposal already owns the
implementation boundary. The proposed successors below are bounded UX scopes; they do not duplicate card rendering, compositor work, or video lifecycle.

| ID | Finding | Severity | Owner | Dependency | Evidence class | Citation | Acceptance | Open gate |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| UX-01 | The launcher gives Foot Client, Foot Server, and Htop equal generic “Installed application” cards on page two; the user cannot tell which Foot entry is a useful independent action before launching it. | P1 | proposed successor: `the-launcher-explains-app-actions` | catalog policy and icon/action metadata | native, injected | `docs/evidence/shell-features/desktop-launcher/README.md` | Curated cards name the action and hide or demote implementation endpoints; a failed action keeps Back/Apps. | Successor proposal and physical review `UNVERIFIED`. |
| UX-02 | `Windows / Home` is combined in Help while the persistent bar exposes only `Windows` and Home appears in the Windows subpage. The recovery relationship is documented but not visible at the first decision point. | P0 | proposed successor: `the-shell-makes-recovery-routes-legible` | persistent bar and launcher wording | native, real-finger | `docs/evidence/offline-wifi-image/help.png` | First-level controls name or visibly disclose the Home recovery route; Apps, Back, and Home remain usable on an empty/failure path. | Successor proposal and board wording/reachability test `UNVERIFIED`. |
| UX-03 | Large equal-height cards preserve touch area but make four generic entries require a second page; current screenshots show no icon or action differentiation and use a generic hint. | P1 | proposed successor: `the-launcher-explains-app-actions` | catalog policy and visual tokens | native | `docs/evidence/shell-features/desktop-launcher/second-page.png` | A compact but 56px-or-larger card treatment preserves title/action distinction, page bounds, and text contrast. | Optical readability capture `UNVERIFIED`. |
| UX-04 | Keyboard-visible composition preserves card/footer routes, but the keyboard takes the lower portion of the 1232px frame and physical lower-screen sharpness is not uniform in the available camera angle. | P1 | touch-launcher-gestures-overview; existing keyboard evidence gate | keyboard reservation and camera geometry | native, real-finger | `docs/evidence/launcher-gestures/integrated-injected/keyboard-visible.png` | Keyboard-visible routes retain Back/Home; the existing gesture/keyboard physical procedure records focused drag and reachability. | Directional-drag and uniform sharpness `UNVERIFIED`. |
| UX-05 | Launcher and overview report raw GLib/helper failures in a red subtitle, while Help, video, System, and empty/stale states use different wording/locations; the error frame truncates a filesystem path. | P0 | proposed successor: `the-shell-makes-recovery-routes-legible` | shared state-message contract | native, injected | `docs/evidence/shell-features/desktop-launcher/error.png` | Each state has short human wording, named next action, and no private/path-like detail; fixtures cover failure, empty, stale, EOF, cancelled and denial. | Successor proposal and integrated board capture `UNVERIFIED`. |
| UX-06 | Camera evidence shows physical Apps hierarchy but is oblique and has glare; this is an evidence limitation, not by itself a visual implementation defect. | P2 | existing gesture evidence gate | capture geometry | camera, real-finger | `docs/evidence/shell-real-touch-apps/video-audit.md` | A later focused optical capture may assess sharpness without changing UI scope. | Uniform sharpness `UNVERIFIED`. |
| UX-07 | Live card composition is proposed rather than shipped. | P1 | the-shell-has-a-card-composition-plan; the-shell-manages-apps-as-cards | app-content/security and compositor boundary | real-finger, injected | `docs/evidence/launcher-gestures/real-finger/README.md` | Card source must satisfy its own live-content, recovery, and physical acceptance gates. | `UNVERIFIED`. |
| UX-08 | Rotation, blur, thumbnails, and advanced GPU effects lack source/board evidence. | Deferred | future visual effects decision | measured renderer budget | UNVERIFIED | UNVERIFIED | A later owner records source support, cost, and a rollback path before proposing them. | `UNVERIFIED`; explicitly deferred. |
| UX-09 | Cold USB-powered boot and recovery lack a separate end-to-end UX timing observation; this is an evidence gap, not an observed usability failure. | P2 | docs/handheld-ux-plan, future observation round | existing splash evidence and a scheduled observation | camera, serial | `docs/evidence/shell-features/desktop-launcher/README.md` | Named operator run records cold USB-powered startup through usable shell. | `UNVERIFIED`. |

## Routing decision

UX-02 and UX-05 route to one bounded recovery-language successor; UX-01 and UX-03 route to one bounded catalog-curation successor. Neither owns card rendering, compositor policy, or video lifecycle. UX-09 is an observation gap owned by a future UX review, rather than an
unobserved P1 product defect. It does not add a battery or USB-free acceptance
requirement. The two selected successors are now concrete proposals:
`the-launcher-explains-app-actions` (integration commit `e24741f`) and
`the-shell-makes-recovery-routes-legible` (`19187d9`). Both can start host work in
parallel with card composition; their launcher/bar edits must be reconciled with
card integration, and board acceptance remains serialized. They preserve the
existing card/video lifecycle ownership. Audit and both successor proposals were merged and pushed on master through
`7e4cc02`; their strict validation and site build passed. The two implementation
proposals remain open, with their physical gates unchanged.