Kaleido/docs/design-system.md
Elijah 430616330b
All checks were successful
Validate and publish Kaleido / android (push) Successful in 2m14s
Release 0.1.2 with navigation sounds and smoother Home scrolling
2026-10-24 10:18:59 -07:00

43 lines
9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Kaleido visual system
The interface gives artwork priority. App chrome uses neutral near-black, charcoal, and white. Color belongs to the user's media. Navigation, cards, and player controls share the same restrained focus language.
## Layout and typography
- Horizontal safe gutter: 44 dp. Navigation: 62 dp, with centered text destinations and independent search/settings icons.
- Home retains a large cinematic feature: an 80 percent stage with original title artwork, synopsis, playback and information actions. The scene continues beneath Continue Watching; entering the rail scrolls the feature away and the backdrop follows focused titles. Features interleave recently released, highly rated unwatched, and Plex-suggested movies/shows, excluding Continue Watching. They shuffle per refresh and rotate every 12 seconds while the hero is active, pausing during row browsing.
- Movies uses a compact fixed preview above poster rows, with the backdrop and synopsis following focused titles. Recently released films and movie recommendations lead. TV uses a shorter preview, larger episode thumbnails, next episodes, newly added seasons, and then new episodes and show recommendations. Redundant TV hubs are omitted when their episode lists match exactly. These are deliberately different compositions.
- Library: title and discovery/full-library navigation share a 64 dp header. A 43 dp filter row sits immediately above the six-column poster grid.
- Browsing card widths: landscape 214 dp, TV episodes 264 dp, posters 120 dp. Landscape artwork uses 16:9; posters use 2:3. The full grid scales six columns to available width. Captions reserve a fixed height.
- Search uses three columns of landscape results. Episodes use their actual stills, preserving their native proportions instead of cropping them into posters.
- Features use original Plex clear-logo artwork within 264 × 80 dp, falling back to title text. Detail title: 34/37 sp. Library title: 29/34 sp. Discovery rail heading: 17/22 sp. Supporting information: 10/14 sp.
- Poster and thumbnail corners: 6 dp. Compact action corners: 5 dp. Cards have no idle border; a compact bottom-right check marks watched titles, or a number shows remaining episodes for a show/season when Plex provides counts. Unwatched movies have no badge. Resumed movies/episodes only show a check after the configured playback threshold (80 percent by default), even if Plex retains a historical watched flag. Completed titles with no resume position retain Plex's watched state. Progress uses a two-dp inset line.
- The abstract six-facet aperture mark is shared by the header, sign-in, app icon, TV banner, and a cold-start aperture assembly. It uses muted sea-glass and warm ivory facets around a dark center, with no letterform or sparkle.
- Audience ratings display Rotten Tomatoes as a percentage beside its official Popcornmeter artwork, and IMDb on its native ten-point scale beside the gold IMDb logo. Both appear when Plex exposes both; TVDB is retained as a fallback when neither is available. Critic scores and unsupported providers are omitted. Stable preview focus hydrates detail metadata, where Plex exposes the full provider list. The official red Hot mark appears at 60 percent or above and the green Stale mark below 60 percent; each fits a stable, font-scaled square without recoloring or distortion. Verified Hot is not inferred from a percentage. Asset provenance is in [brand-assets.md](brand-assets.md). The IMDb vector uses the official gold primary mark and supplied clear space from the [IMDb brand toolkit](https://brand.imdb.com/imdb).
## Focus and motion
- Discovery cards keep fixed bounds and use a two-dp white focus outline. No scale or shadow changes trigger lazy-row layout or move a neighboring row.
- Text actions scale to 1.025 over 160 ms. Navigation uses text, an understated selected underline, and a translucent charcoal focus surface.
- Navigation focus changes use Android's native UI tick. Settings > Interface > Navigation sounds toggles it immediately and persists across process restarts; it defaults to On and follows the TV's global sound-effects setting. Initial startup focus and repeated notifications for the same target are silent. The shared focus observer covers navigation, cards, buttons, dialogs, playback options and the timeline without changing key handling.
- Navigation contrast comes from a gradient extending past the controls and fading to transparent. Home/Movies/TV activate on focus. Explicit row and column links prevent beyond-bounds focus searches when holding a remote direction.
- A D-pad move predicts the actual row/column destination before starting its scroll or focus change. The target backdrop is fetched and contrast-processed through the same Coil request/cache as the visible scene. Speculative artwork uses one low-priority worker so it cannot flood normal decode workers during a burst of input. Metadata starts in parallel; the visible preview and details page share that in-flight request. Rapid navigation replaces the queued metadata target and cancels superseded artwork prefetches. Full metadata uses a 64-item LRU with a 30-second lifetime, cleared on account/server changes and refreshed after watched updates. Neutral library/search grids prefetch metadata without fetching an unused full-screen backdrop.
- Home's vertical list prepares content within one viewport ahead and retains one viewport behind, using Compose's bounded lazy-layout cache window. This keeps the hero and nearby rows ready when moving between them, rather than repeatedly composing and measuring the exposed image cards during the animation. Movies/TV retain their existing list strategy. Card sizes, row targets and the large cinematic Home layout are unchanged.
- Section previews settle for 120 ms (Home artwork for 90 ms), overlapping the navigation animation, and retain previous artwork until replacement data is ready. Contrast gradients are baked into a cached bitmap on a worker thread, reducing GPU overdraw. Hero recommendation changes crossfade the artwork over 220 ms, including cache hits, and fade the title/summary out for 100 ms and back in over 180 ms. Rotation pauses on the information/next controls and preserves their focus. Vertical row changes animate to explicit row/column targets; page entrances fade and slide 28 dp over 280 ms. The cold-start sequence lasts 2.6 seconds: six light trails converge, the exact aperture facets assemble radially without spinning, a soft glow and facet glint settle, and the wordmark reveals letter by letter. Completion drives the cover dismissal, with up to 600 ms extra for loading followed by a 360 ms crossfade. Android animation duration scale is honored, including animations off. It does not replay when returning from background.
- Returning from details restores the library's mode, scroll position, and previously focused title.
## Player
Controls occupy a shallow bottom gradient. A compact title, slim timeline, small time labels, central transport icons, and right-aligned track icons replace the rectangular button grid. The timeline is a true D-pad focus target: Up from transport reaches it, Left/Right seek, and Down returns to Play/Pause. Holding a direction increases the seek step. Dedicated media keys remain supported.
The controls fade and slide away after five seconds during playback. OK reveals them; Back hides them before exiting. Audio and subtitle panels open above their icons and restore focus when dismissed. A gear exposes playback mode, audio, subtitles, speed, transcode quality, and chapters. Direct stream is the saved default. The timeline includes buffered progress and server-generated video/chapter previews. Skip actions have opaque contrast surfaces.
Episode endings and Skip credits open a five-second, cancellable next-episode countdown with season episodes and related shows. Each player session has a unique Media3 session ID so overlapping Compose disposal and next-episode creation cannot collide.
Settings includes a persistent watched percentage. Timeline reporting scrobbles the item in Plex once the selected percentage is reached, retries a failed write, and avoids repeated scrobbles within the same player session. This preference belongs to Kaleido and does not change the Plex server's global settings. Explicit watched changes refresh the title and parent episode counts across browsing caches.
## Device review
Use `scripts/verify_ui.py browse` and `scripts/verify_ui.py player` with the authorized ADB connection. These drive the actual UI with remote key events, assert focus and navigation, and capture screens into the ignored `evidence/private/` directory. The player check uses the live Plex server's existing conversion mode. Run `Build.ps1 -Test` for compilation, unit tests, and lint. Inspect the optimized release APK on the TV before judging startup or animation performance.
Visual references: [Netflix's TV experience](https://about.netflix.com/en/news/unveiling-our-innovative-new-tv-experience), [Netflix's current TV layout guidance](https://help.netflix.com/en/node/321880164349028), and [Apple TV](https://www.apple.com/apple-tv-app/). The layout and artwork remain independent and Plex-backed.