Kaleido/docs/design-system.md
Elijah 3e020bd7fa
All checks were successful
Validate and publish Kaleido / android (push) Successful in 2m33s
Release Kaleido 0.8.0 with a single-countdown Up Next screen
- Credits and episode endings open Up Next: the video keeps playing in a
  top-left mini-player beside the next episode, season and related shows.
  Play next episode carries the only countdown; any remote press stops it.
  Left then OK on the video, or Back, returns to the credits.
- Wait for the player's final timeline report before reloading Home, so
  Continue Watching reflects the episode just watched.
- Remove the source label above Home's featured title.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 21:48:11 -07:00

52 lines
16 KiB
Markdown
Raw Permalink 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, with Continue Watching peeking below. Entering the rows compacts it into a Silo-style preview of the focused card instead of scrolling it away: the hero lifts and fades as the rows slide up beneath a bottom-anchored block (64 dp title art, content-rating badge, year/episode, genre, runtime or time left, ratings, three synopsis lines, three cast names and 4K/HDR/Atmos format badges). The card's own image (an episode's still, not its show's art) is scaled whole into a top-right box of 72 × 78 percent of the screen, baked off-thread to fade into the page toward its left and bottom edges. Movies and TV use the same preview (56 dp title art) beneath their Discover/Library/Categories line, with rows starting 300 dp down; their row content stays distinct. With Settings › Interface › Artwork colour wash (default On), the page beneath carries the artwork's average colour normalized to 0.22 luminance, diagonally from the top-right (full) to the bottom-left (18 percent), as Silo does. It is baked into the same cached 960 × 540 frame, so it costs nothing per frame and changes through the artwork crossfade. A 1280 × 720 frame was tried for sharper art and raised Movies' horizontal p95 from about 31 to 36 ms through larger texture uploads, so it was not kept. The preview stays composed, invisible, under the hero with the first row's first card, so entering the rows is only a fade. Up from the first row or Back restores the hero. Features interleave recently released, highly rated unwatched, and Plex-suggested movies/shows, excluding Continue Watching, without a label naming the source. 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.
- Movie and episode information pages place a horizontal Cast row beneath the description and actions, using Plex portraits, names and character roles. TV show pages place Seasons first, then Cast, then server-provided Related shows; season pages likewise keep Episodes ahead of Cast. Missing portraits use a neutral person placeholder. Actor cards open a six-column filmography of available movies and shows across the connected server's libraries, using Plex actor identifiers and pagination.
- Movie, show, season and episode pages share the browse previews' language: the same top-right artwork frame and optional colour wash (so opening a title keeps its artwork in place), original title art (340 × 64 dp; episodes show their show's art at 280 × 48 dp above the episode name), a facts line with the content-rating badge, ratings and 4K/HDR/Atmos badges, and a three-line synopsis capped at 560 dp. A truncated movie or show synopsis offers a Synopsis action. Codec, audio layout and bitrate sit quietly beneath the actions. Season and episode pages follow the focused episode: its still crossfades and its copy fades and lifts as on the browse pages, while the actions stay in place. Fixed header heights (250 dp shows, 276 dp movies, 296 dp seasons/episodes) keep the rows still and a show's season captions on the initial screen. The Back control stays in the safe area; artwork disappears over the first 180 dp of scrolling. Soft text shadows preserve contrast.
- Movie, episode, show and season information pages expose labelled Mark watched / Mark unwatched actions. Changes are sent to Plex and reflected in the title, descendant episodes/seasons, library cards, actor results and recommendations. An in-flight write survives navigation and prevents duplicate submissions. Partial episode-list records update watch fields without replacing full cast/detail metadata.
- Settings uses a fixed category rail (Connection, Playback, Interface, Updates) beside compact value/action rows. Focus selects categories; Right enters their controls and Left returns to the rail. Neutral surfaces, white focus, existing typography and restrained motion match the browsing destinations. Existing account, quality, watched-threshold, navigation-sound and updater preferences keep their behavior.
- Features use original Plex clear-logo artwork within 264 × 80 dp, falling back to title text. 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 the cold-start aperture sequence. It uses muted sea-glass and warm ivory facets around a dark center, with no letterform or sparkle. The launcher banner and app icon place it on a diagonal light, deep sea-glass at the top right through near-black to a warm tan glow at the bottom left, with a soft vignette and nothing over the aperture; `scripts/generate_brand_tiles.py` regenerates both from `brand_mark.xml`.
- 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 spaced 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 horizontal input settles to the latest target before starting speculative work. 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 use the same window. The window only fills ahead after the list has scrolled, so once a section settles it is nudged 1 px and back, letting the next rows compose in idle frames instead of during the first move down. Card sizes, row targets and the large cinematic Home layout are unchanged.
- Home, Movies and TV previews follow focus once it rests for 110 ms and retain previous artwork until replacement data is ready. New artwork fades in over the old for 320 ms, including cache hits; the outgoing title and synopsis lift slightly as they fade while the new ones rise 12 dp into place (380 ms). Hero recommendation changes use the same artwork and copy transitions, holding the copy up to 700 ms for the new artwork to decode. These fades, and the hero/preview exchange, are single animations read only in graphics layers, so they add no per-frame composition or layout. Contrast gradients are baked into a cached bitmap on a worker thread, reducing GPU overdraw. 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, using per-draw alpha rather than an offscreen layer, and start once the new section's composition frames have passed (at most 300 ms). While a section enters, its cards lay out at their fixed size first and fill in artwork and titles three per frame under the fade, so the section's first frame stays short. Focusing a top tab lets its highlight draw before the section switches. The cold-start sequence is a kaleidoscope, the same as Kaleido Desktop's, and lasts about 2.6 seconds. A faint mirrored field of shards fades in, still, for 260 ms and holds there (at most 700 ms) until startup data has arrived and frames are steady, so cold-start hitches never interrupt the motion. The field then turns 150° while the shards spiral inward and vanish and the six exact facets ride in from it and lock into the mark (1.7 s), a hexagonal ring pulses out and a sheen crosses the settled mark. Once loading finishes (up to 600 ms extra; small shards begin circling the mark if it runs long) the camera flies through the mark's open center over 640 ms, revealing the app beneath as it settles from 114 percent scale. The completed mark itself is never redesigned. 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.
- Entering Movies/TV from the top bar focuses the fixed Discover control immediately. Down from Discover explicitly reveals the first catalog card; focus on already-visible targets changes before scrolling. A quick tab/Down sequence queues entry for the new destination, and focused tabs never repeat their delayed initial-focus request.
- Offscreen card navigation requests the next lazy layout instead of forcing synchronous composition between key events. Up at the top bar is consumed because there is no destination above it; it must not start a lazy-list focus search.
- Horizontal rows prepare one viewport ahead and retain half a viewport behind. New card artwork/text fills over up to three frames at fixed bounds. Horizontal focus commits on a frame boundary; a pending column accumulates rapid D-pad steps before committing the latest target, keeping accessibility layout work out of the gap between KeyDown and KeyUp.
- Horizontal presses less than 160 ms apart snap to the latest anchor and wait 70 ms before speculative metadata/artwork. Spaced presses retain the 140 ms scroll animation and immediate prediction.
- New seasons groups additions by Plex parent show ID, preserving newest-first order. Multiple seasons use the real show metadata and open its season list; single-season additions retain direct season navigation. The query samples 100 seasons before selecting up to 18 distinct shows, so one series import cannot occupy every card.
## Player
Controls occupy a bottom gradient. The title uses the same original title art (240 × 44 dp) and rating badge/facts line as the browse and details pages, with the delivery quality quietly at the right; a 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. While they are hidden, a Left/Right tap skips 10 seconds without revealing anything (quick taps add up into one seek), and holding Left/Right reveals the focused timeline for scrubbing. OK and Down reveal them; Back hides them before exiting. Audio and subtitle panels open above their icons and restore focus when dismissed. A gear exposes quality, audio, subtitles, speed, and chapters. Quality is one list shared with Settings: Original quality (the default, direct stream of the source video), then 4K, 1080p, 720p and 480p conversions. The timeline includes buffered progress and server-generated video/chapter previews. Skip actions have opaque contrast surfaces.
Credits (automatically, or through Skip credits) and episode endings open Up Next: the playing video shrinks to a 352 × 198 dp frame at the top left and keeps playing, beside the next episode's still (top right, fading into the page), title art, episode title, facts line and three-line synopsis, with the season and related shows below. The page is drawn beneath the PlayerView so its SurfaceView shows through. Play next episode carries the only countdown (Settings › Autoplay next episode) as a sweeping fill; any remote press stops it. Left from Play next focuses the video; selecting it, or Back, returns to the full-screen credits. 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.