invidious/DESIGN.md

# Invidious UI refinement

## Purpose

The primary user is someone who wants to search and browse YouTube privately,
then sign in only when saved preferences or subscriptions need an account. The
interface is used in wide desktop browsing sessions and narrow touch sessions.
It remains server-rendered and usable with JavaScript disabled.

The approved direction is the refined proposal: B's distinct channel treatment
and contained video cards, paired with a compact account form. Search results
should scan as media destinations, while a channel remains visibly different
from a video result. Existing search filters, saved home/feed preferences,
localization, thin mode, theme choice, authentication, CAPTCHA, and all
existing links/forms retain their behavior.

## Tokens

The implementation exposes the following values in `assets/css/redesign.css`.
They are semantic roles, not a new user preference. `.light-theme`,
`.dark-theme`, and the system-controlled `.no-theme` each assign the same
roles. Client-side theme changes must retain the structural `redesign-ui` body
class while replacing only the theme class.

| Role | Light | Dark | Use |
| --- | --- | --- | --- |
| `--redesign-canvas` | `#f7f8fa` | `#0b0c0e` | Page background |
| `--redesign-surface` | `#ffffff` | `#15161a` | Media cards |
| `--redesign-control` | `#fbfcfd` | `#111216` | Search and text inputs |
| `--redesign-text` | `#17181b` | `#f4f4f5` | Primary text and titles |
| `--redesign-muted` | `#656a73` | `#a9abb1` | Metadata and quiet navigation |
| `--redesign-line` | `#d9dce2` | `#303239` | Stable boundaries |
| `--redesign-accent` | `#255fbe` | `#83b5fc` | Links and primary submit action |
| `--redesign-accent-hover` | `#174a9f` | `#b2d0ff` | Link and submit hover/focus state |
| `--redesign-on-accent` | `#ffffff` | `#121315` | Submit-action foreground |
| `--redesign-focus` | `#0b6ece` | `#83b5fc` | 3 px keyboard focus outline |
| `--redesign-radius` | `8px` | `8px` | Results and form surfaces |
| `--redesign-control-radius` | `6px` | `6px` | Inputs and compact controls |
| `--redesign-shadow` | `0 1px 2px rgb(15 23 42 / 0.08)` | `0 1px 2px rgb(0 0 0 / 0.38)` | Card edge separation only |

The typeface remains the project’s existing system stack. Results use 16 px,
650-weight titles at a 1.32 line-height; channel names use 22 px at 1.3;
metadata uses 13–14 px and stays readable in both themes. The spacing scale is
`--redesign-space-1` = 8 px, `--redesign-space-2` = 12 px,
`--redesign-space-3` = 16 px, and `--redesign-space-4` = 24 px.

## Layout and components

- The navigation bar has a 64 px minimum height, a border separating it from
  content, and a single clear search field. Search stays in the header row; below 600px a native icon disclosure opens the field.
- Search channel matches occupy their own horizontally scrollable row above
  the continuous media grid. Each match keeps its avatar, linked identity,
  metadata and description. Channels never act as headings for unrelated
  video results; selecting a channel follows its existing channel link.
- Videos and playlists are contained cards with a 16:9 thumbnail, then title,
  author and metadata. They use two columns from 768 px and three from 1100 px;
  under 768 px each card is full width. The thumbnail’s duration and existing
  action controls remain in their established positions.
- The login form is at most 352 px wide, sits directly on the canvas without an outer card, has persistent labels, native inputs, and
  one full-width submit action. Existing server validation and CAPTCHA
  rendering remain in the same form flow. The heading-to-field gap is 24 px; the page fills the viewport and its footer follows the flexible main area near the bottom.

There are only two raised surface types: media cards and the expanded
filter panel. Each has a one-pixel boundary plus the same restrained shadow;
the page, navigation, and footer remain on the base plane.

The watch-layout layer consumes the same theme through `--watch-border`,
`--watch-panel`, `--watch-muted`, and `--watch-focus` aliases. It owns the
watch composition and player controls; the shared stylesheet only supplies the
common color roles.

## Access and adaptation

All existing links, buttons, checkbox/radio controls, labels, forms, and
server-side errors retain their native semantics. A skip link targets the main
content. Keyboard focus uses the `--redesign-focus` outline with a 3 px offset;
focus is never indicated by color alone. Controls remain at least 36–44 px in
their compact contexts, and the account submit/input controls are 44 px high.

Long translated titles and channel names wrap; no title or metadata is clamped.
The dark, light, and system theme roles are explicit. Reduced-motion users do
not receive new animated effects. Thin mode retains its placeholders and does
not request thumbnails.

## Evidence and open questions

`DESIGN.html` renders the token values, wide/narrow card compositions, focus,
the channel distinction, and login/CAPTCHA state using the same rules. The
application build and browser checks are recorded by the coordinating agent.
There are no unresolved visual decisions in this approved scope.

## Watch page and optional player enhancements

The accepted A watch composition places the player beside a compact related
rail, with the title, channel, compact action row, description and comments
beneath the player. The native theater checkbox expands the same video across
the grid; it preserves playback and also works without scripts. Below 900 px,
related videos follow the main content. All stream/source and download links
retain their existing behavior.

Player actions retain Video.js's familiar icons and accessible names. Time and
speed remain text. All players put a visible 4px seek track on its own row above icon controls; the duplicate remaining-time display is hidden to conserve space.
Only while focus is inside the player, J/L seek exactly ten seconds; K and a Space tap toggle playback. Holding Space
or the left mouse button on the video for 350 ms temporarily plays at exactly
2×, then restores the prior speed and paused state. Editable fields, menus,
controls and modified shortcuts are excluded. Holds never save a temporary
speed preference. Blur/cancel restores state. The post-hold mouseup and click
are consumed because Video.js toggles playback on mouseup.

## Runtime verification criterion

The actual application must retain the design after scripts initialize and
when themes change. Verify rendered desktop and narrow login/search/watch
pages, real media playback, hold release, theater continuity, and the native
no-JavaScript flow. Static screenshots and mocked gesture tests alone cannot
prove these behaviors. This is project guidance proposed by the user's runtime
correction; it does not modify shared Fleet guidance.

## Channel and feed navigation refinement

Channel content tabs and sort links form a horizontal toolbar; utility links
remain separate and quiet. Subscribe and RSS retain their existing actions.
The signed-in header reserves intrinsic width for account controls, uses native
logout button semantics. Search stays in the header and becomes an icon below 600px.
Subscription feeds have a clear title, management/history/RSS actions and an
empty state linking to subscription management. Saved feed choices remain
unchanged. On narrow screens controls wrap rather than collide.

The search results heading and top pagination share one row, with equal vertical
centers and outer edges aligned to the media cards. Pagination wraps within its
available space on narrow screens; card and channel geometry remain unchanged.

## Account disclosure and card metadata

Signed-in navigation shows the existing notification bell and a circular local
avatar. An initial is displayed only when show_nick is enabled; otherwise a
generic person icon preserves that privacy preference. A native details/summary
disclosure exposes the name, Preferences and CSRF-protected POST
logout. It works without JavaScript; optional script adds Escape, outside-click
and focus-out dismissal. No remote profile image or avatar service is used.

Video cards place title first, channel and views on the second row, date and
existing quick actions on the third. Existing verified badges use bright #3ea6ff in dark mode and #0878d1 in light mode, a .2em inline gap and -.08em baseline adjustment; no verification statuses are added or inferred.

Header avatars are 32px within 40px hit areas; the bell is approximately 22px.
Filter disclosure has horizontal padding, and card action links center their
glyphs alongside the date text. Theme choices set the requested mode explicitly
on both client and server; repeated selection never reverses the mode.

Theater mode sits beside fullscreen in the enhanced player and has an explicit
text label in the no-JavaScript fallback. Storyboard URLs preserve root-relative
paths; previews show one timestamp and clamp to player edges. The timeline has
a neutral track, lighter buffered range and bright blue progress.

Watch actions share a compact row: view/like counts on the left; Share, Download and More on the right. More holds audio-only mode, source/embed/instance links, annotations and metadata. Native disclosures retain download
formats, playlist forms and technical metadata, wrapping on narrow screens.
Subscribe is red (#d92332) with white text; subscribed state stays neutral. Channel verification marks stay bright blue; only comment verification is white. All keyboard handlers require focus
inside the player; search, page actions and outside clicks release shortcuts.

Player follow-up: the large play control is centered. Play-button focus accepts
shortcuts; external inputs remain excluded. Fullscreen clears fluid aspect-ratio
padding, captions reserve 68px above visible controls, and caption menus use
readable padded rows. Share is only below the video, with Invidious/YouTube URL
choices and optional clipboard buttons; native links work without JavaScript.
Action menus dismiss on outside click or Escape, and only one sibling stays
open. Header bottom padding is 4px with no divider. Related titles use primary
text, with muted channel/views and consistent thumbnail geometry.

Theater is the default watch layout, including without JavaScript; the player
button returns to the split layout. Light and Dark icon controls remain visible beside the avatar; Preferences stays inside its menu.

Final refinement: Audio mode and Watch on YouTube are quick actions alongside
Share, Download and More. Instance/embed/annotation links are hidden; More holds
remaining metadata. Menus have bounded scrollable height. Comment avatars are
36px with consistent author/body/metadata/reply spacing. Cards align metadata
rows and avoid inherited paragraph margins. Player corners are 12px, with a
12px gap below navigation. Light mode strengthens muted text and surface borders.

Embedded-fullscreen recovery: when the browser leaves native fullscreen pending
for 700ms, reuse Video.js full-window mode; F/button and Escape exit preserve
the same player and video. Regular browsers continue using native fullscreen.

The watch title tops out at 25px to retain hierarchy without competing with the
player. Watch on YouTube is a 36px icon action with a localized accessible name
and native tooltip. Start/end clip markers continue controlling playback but are
visually hidden because the blue progress rail already communicates position.
The unused Video.js share plugin is excluded; sharing remains in the watch action
row through native links and the optional copy enhancement.

The watch title tops out at 25px to retain hierarchy without competing with the
player. Watch on YouTube is a 36px icon action with a localized accessible name
and native tooltip. Start/end clip markers continue controlling playback but are
visually hidden because the blue progress rail already communicates position.
The unused Video.js share plugin is excluded; sharing remains in the watch action
row through native links and the optional copy enhancement.