handheld-shell-design

The shell userspace SHALL use the active appearance generation's authored palette and section brushes, a consistent text hierarchy, spacing system, and touch vocabulary across the deck, drawer, shade, Settings, and notifications at the panel's 568×1232 portrait size. At the current output scale of 1, one logical pixel equals one panel pixel; interactive targets SHALL be at least 56 such pixels tall and later scaling SHALL preserve physical size. Essential information SHALL remain legible without color alone. The final normal session SHALL have no permanently visible Apps/Windows/Keyboard/System rail or Back/Home footer.

The shell userspace SHALL preserve authored background gradients, alpha, foreground and accent when painting its Home, drawer, shade, Settings and theme picker. Routine app-icon plates, control rows and theme preview frames SHALL avoid unnecessary borders; focus, selection, destructive actions and drag/drop SHALL remain distinguishable. Existing gestures and interactive targets SHALL retain their behavior. The compositor SHALL continue to own live overview/card pixels and movement.

The shell SHALL keep the live-card Overview separate from pinned Home. A purely upward bottom-edge gesture from an app or transient shell surface SHALL reach Overview with the eligible app shrinking into its live card. An upward gesture from Overview’s bottom navigation area SHALL reveal pinned Home without closing or unmapping running apps. A new upward gesture from Home’s bottom edge SHALL reveal All apps. The same contact SHALL NOT traverse both destinations. Swiping a card itself upward SHALL retain its close action. Empty Overview SHALL retain a useful Home route, and All apps SHALL include named Terminal recovery. Repeating Home SHALL leave pinned Home stable.

The compositor SHALL retain one touch owner when an app-entry gesture bends from upward to sideways movement. The manipulated point SHALL follow both finger coordinates one-to-one within declared travel bounds, with no held-contact easing, automatic progress, or axis-change jump. A qualified lateral release SHALL settle and activate the visibly selected adjacent running app directly from the current full or near-full carousel geometry, without a forced overview or second expansion stage; a purely upward release SHALL settle into Overview from its current geometry. A horizontal gesture starting anywhere along the qualified bottom edge band SHALL offer the same adjacent-app switching without requiring an upward gesture or a full card zoom, gated only by measured lateral displacement or release velocity in the swipe direction and not by where along the band the touch started. Release thresholds SHALL NOT amplify visible motion. Short/reversed gestures, and a release whose recent velocity trends back toward the start, SHALL restore the originating app without activating a neighbor. Settling on either axis SHALL begin at the displayed position and bounded measured release velocity, with smooth deceleration or spring and no initial position or derivative jump; velocity SHALL influence motion only after release and SHALL be estimated from recent samples rather than a single possibly-stale last delta. A new accepted touch SHALL stop or retarget settlement from current geometry.

Both routes SHALL use the deck's stable left/right app order, unchanged by focus-only switching, and SHALL commit at most one neighbor per release initially. Dragging the scene right SHALL reveal the left neighbor and vice versa. They SHALL NOT wrap at either end, launch a new app, throw-close an app, or substitute a newly mapped app for a disappearing target. The compositor SHALL preserve the sibling's privacy, source-lifetime, focus eligibility and visible raise behavior. Keyboard-owned regions, active overlays, side Back regions and ordinary app content outside the qualified bottom region SHALL keep their touch ownership.

A downward gesture from the top edge SHALL reveal a notification shade over the current scene; the shade SHALL expose notification history and a truthful Settings entry. The bottom-edge app/overlay gesture SHALL remain the escape to Overview while a context is open; its Home route SHALL retain pinned Home and running apps.

The shell userspace SHALL follow one accepted finger during a deck drag, drawer/Settings/history scroll, or eligible section swipe. During an accepted drag, the manipulated edge or grabbed point SHALL move one logical pixel per logical pixel of finger movement within its travel bounds, including immediate reversal; a stationary held finger SHALL produce no continued movement. Recognition and release thresholds SHALL NOT multiply visible displacement. Easing, inertia, and automatic settling SHALL begin only after release or cancellation. A release SHALL resolve from the displayed position with bounded momentum and a visible settled destination; a new touch SHALL stop coasting. Tapping a card or app SHALL activate it. A deliberate long press SHALL show a context cue before an action, allow movement away or cancellation without activation, and never masquerade as a tap. All apps SHALL provide a Help target with gesture guidance and a deliberately opened Navigation buttons aid for Home, All apps, Notifications and Settings. The large labeled controls SHALL appear only while that aid is open; a route change SHALL dismiss the aid. The aid SHALL NOT form permanent navigation chrome.

The shell userspace SHALL present app→card entry, adjacent deck travel, card→app expansion, drawer rising from Home, shade descending over the task, and app launch/return as related positions in one scene. The selected live app SHALL keep its identity and visual content through eligible transforms; direction, scale, stacking order, and focus SHALL resolve coherently when motion is interrupted, reversed, or retargeted. No transition SHALL show an unowned black/blank frame or another app's private pixels. Reduced motion SHALL preserve interactive drag, destination, focus, feedback, and recovery with shorter settling and no decorative travel.

After a gesture is accepted, another surface SHALL NOT reinterpret that sequence as a tap or swipe. Accepted press, long press, snap, close request, refusal, and failure SHALL have immediate visible feedback.

The drawer, eligible card headers, and trusted app notifications SHALL resolve an installed app's desktop-entry Icon through the image's icon theme where available, use a consistent sized fallback glyph when absent or unreadable, and keep a text label as the identifying route. Icon loading SHALL be bounded/cached so scrolling does not repeatedly decode assets. A private card SHALL show a neutral placeholder without its title or app-specific icon. Context actions SHALL use readable labels with any icon as a secondary cue.

Each shell surface SHALL distinguish loading, empty, stale, failure, and cancellation where those states apply, using short text and a next gesture or contextual action. Focus and pressed states SHALL have a non-color cue; a failed launch SHALL retain the drawer or Home recovery.

The shell userspace SHALL present a consistent visual frame and navigation around the app-card interaction when that capability is available. When it is unavailable, it SHALL state that visual cards are unavailable and retain a safe task/drawer route; it SHALL NOT portray metadata as a live app surface or silently replace a failed live deck with a second Home design.