Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 34 additions & 22 deletions PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -253,28 +253,36 @@ interval/

### 6.1 The idea

**The posters are the content. Everything else gets out of their way.**
**The posters are still the content. The chrome now has a pulse — and a light switch.**

A movie grid is already the most visually loud thing on any page — twenty pieces of professional poster art, each competing for attention. Almost every film site fights this by adding more: gradients behind cards, glows on hover, coloured badges. The result is noise. Interval goes the other direction: the interface chrome is desaturated, matte, and quiet, and the only saturated colour in the entire UI is the single accent used for scores and actions. The posters supply the colour.
Phase 1 shipped a matte, single-accent dark interface on the theory that a movie grid is already loud enough on its own. In practice "quiet" read as inert: real interactivity and a small family of colour make the same grid feel current without drowning the poster art. The rule did not become "add more" — it became "add on purpose." Every new colour has exactly one job (§6.2), every new motion happens only in response to the user (hover, focus, arrival, a value changing), and the poster is still never cropped, filtered or covered by a gradient. See `docs/DECISIONS.md`, 2026-09-28, for why this changed and what it superseded.

The reference point is not Netflix, it is a **cinema listings sheet** — the printed programme outside a single-screen theatre. Dense, typographic, information-first, with the title set large because the title is the point.
A second pass the same day replaced the single dark theme with two: a bright, high-contrast light theme as the default (most people land on this site in daylight, on a phone, and a near-black page is the wrong first impression), with the original dark palette preserved as a toggle-able alternative rather than discarded. Both themes carry the same five-accent system and the same 4.5:1 contrast floor independently — switching theme never trades accessibility for mood.

The reference point moved from a cinema listings sheet to the same listings sheet under working house lights — still dense and typographic, but no longer pretending the room is empty.

### 6.2 Tokens

**Colour** — a deep aubergine ground rather than the default near-black, because near-black plus one acid accent is the house style of every AI-generated dark UI. Aubergine reads as a dark room without reading as a terminal.
**Colour** — light is the default ground, a warm paper tone rather than clinical white (near-white plus one acid accent is the house style of every AI-generated light UI just as much as the dark version was; warm paper reads as a printed sheet without reading as a form). Dark mode keeps the original deep-aubergine palette from the first redesign pass, reachable via the toggle in the header (`src/store/theme.ts`, `useTheme`), persisted to `localStorage`, and applied before first paint by an inline script in `index.html` so there is no flash of the wrong theme. The accent family stays a curated set of five, each doing exactly one job so variety stays systemic rather than decorative — every accent has an independently-tuned hex per theme so both directions of contrast (text-on-background and background-with-contrasting-text) clear 4.5:1 in both themes.

```
--ground #1C1420 page background, matte
--surface #281C2E cards, sheets, raised areas
--edge #3C2D43 hairlines and dividers
--ink #F2EDE4 primary text, warm off-white (never pure white)
--ink-muted #A0919E secondary text, metadata
--marigold #E8A33D THE accent — scores, focus rings, primary actions
--verdigris #2E7D6F the one secondary, used only for "available to you"
--rot #C0503C low Tomatometer, destructive actions
LIGHT (default) DARK (toggle)
--ground #FFF7EC #1C1420 page background
--surface #FFFFFF #281C2E cards, sheets, raised areas
--surface-high #FDEEDA #33243B hover/raised state for surface elements
--edge #E7DAC5 #3C2D43 hairlines and dividers
--ink #23182B #F2EDE4 primary text
--ink-muted #6E5F68 #A0919E secondary text, metadata
--marigold #9F6604 #E8A33D primary actions, focus rings — not score colour (that's tier-based, below)
--verdigris #0A7F62 #33B39B "great" score tier, "available to you"
--coral #DE1248 #F2577C delight — watchlist saved state, trending/new badges
--violet #7D30E8 #A672E0 categorisation — genre chips (cycled with the others below)
--azure #0F77B8 #4FADE8 information — alternate badge/chip colour
--rot #D83218 #E2583F "low" score tier, destructive actions
--on-accent #FFF7EC #1C1420 text drawn on top of a solid accent fill
```

Marigold appears perhaps six times on a page. If it appears twenty, something has gone wrong.
Each accent still has one job. The test changed from "count marigold on the page" to "could you say, for any coloured pixel, which job it's doing" — if not, it should not be there. Tokens are CSS custom properties on `:root`, overridden wholesale under `:root[data-theme='dark']`, so a theme switch is a single attribute flip with no re-render — components read `var(--color-*)` and never branch on theme in JS. `tierGlow()` (`src/lib/scoreTier.ts`) and every hardcoded shadow colour use `color-mix(in oklab, var(--color-x) N%, transparent)` rather than a literal RGBA, so glows and shadows stay correct in both themes automatically.

**Type** — two families, clearly distinct, both free and self-hosted via Fontsource so there is no Google Fonts request on every page load.

Expand Down Expand Up @@ -309,12 +317,14 @@ Left-aligned throughout. No centred body text. The poster on the detail page is

**The scorecard** is the one component that earns custom design. Three sources — IMDb, Rotten Tomatoes, Metacritic — shown as a single horizontal unit with hairline dividers, not three separate pills. Numbers set in the display face at 21px. A missing score renders as an em dash in the same slot, so the unit never changes width and the grid never reflows.

### 6.3 Rules
### 6.3 Rules (revised 2026-09-28 — see docs/DECISIONS.md)

- **Motion**: one orchestrated moment on first paint (the hero backdrop resolves from a low-quality TMDB thumbnail to full size). Nothing else animates unless the user caused it. No card hover lifts, no staggered fade-ups on scroll — those are the tell.
- **Cards**: the poster *is* the card. `border-radius: 2px`, matching a real printed poster's corner, not 12px. Rating sits on the poster's lower edge in a translucent strip, not in a box below it. No shadows.
- **Empty and error states**: written as directions, not apologies. "No results for *tenet*. Try the Hindi title, or search by director." Never "Oops! Something went wrong."
- **Quality floor, not announced**: responsive to 360px, visible keyboard focus in marigold, `prefers-reduced-motion` respected, 4.5:1 contrast minimum, every poster has a real alt text built from title and year.
- **Motion**: welcome wherever the user caused it — hover, focus, arrival, a value changing. A poster lifts and glows in its score's tier colour on hover; scores count up when they arrive; rails and grids enter with a brief staggered rise; the hero backdrop still resolves from a low-quality thumbnail and now drifts in a slow Ken Burns zoom. The line that still holds: nothing animates *before* the user does something, or forever — entrances play once, loops don't run unattended, and `prefers-reduced-motion` collapses every duration to near-zero (already global, `src/index.css`).
- **Cards**: the poster is still the card, never cropped or covered. `border-radius: 2px` is reserved for posters and imagery specifically — a printed poster's corner, not 12px — while interactive chrome (buttons, dialogs, inputs, chips) uses a softer radius on purpose, so content and touch targets read as two different materials. A hover shows a soft glow in the card's own score-tier colour; the rating strip on the poster's lower edge still never causes reflow.
- **Colour**: five accents, one job each (§6.2), tuned independently for light and dark so both clear the contrast floor. A colour is allowed wherever it identifies something specific — a score tier, a genre chip, a saved state — never as decoration with no referent.
- **Theme**: light is the default; dark is one click away via the header toggle and remembered per browser. Nothing in either theme is theme-only content — the two are a palette swap over the same layout, never a different feature set.
- **Empty and error states**: written as directions, not apologies. "No results for *tenet*. Try the Hindi title, or search by director." Never "Oops! Something went wrong." They may now carry a small accent mark and a brief entrance; the copy voice does not change.
- **Quality floor, not announced**: responsive to 360px, visible keyboard focus in marigold, `prefers-reduced-motion` respected, 4.5:1 contrast minimum for text, every poster has a real alt text built from title and year.

### 6.4 Copy voice

Expand All @@ -330,7 +340,7 @@ Plain, specific, slightly dry. The interface talks about films the way a friend

### 7.1 Scope

- **Home** — a hero title, then horizontal rails: Trending this week, Popular in India, Top rated of all time, New this month, and one rail per major genre.
- **Home** — a hero title, an inline "Build your own shortlist" discover bar (multi-genre filter over TMDB `/discover`, with independent TMDB, IMDb and Rotten Tomatoes rating floors, replacing the curated rails below it while a filter is active), then a handful of short curated rails with wry section titles rather than one rail per genre. Trimmed deliberately in the 2026-09-28 redesign — see `docs/DECISIONS.md` — on the theory that a home page proving depth by listing every genre once was the clutter, not the fix.
- **Search** — a `⌘K` combobox in the header plus a full `/search` results page. Debounced at 300 ms, TMDB multi-search across movies and TV.
- **Title detail** (`/movie/:id`, `/tv/:id`) — backdrop, poster, the scorecard, summary, runtime, release date, genres, original language, director and top-billed cast, trailer link, and a "More like this" rail from TMDB's recommendations endpoint.
- **Browse by genre** (`/genre/:slug`) — grid with filters: minimum rating, year range, language, sort order. Filters live in the URL query string so a filtered view is a shareable link.
Expand Down Expand Up @@ -409,7 +419,9 @@ Mitigations, in order of when they apply: keep the OMDb key out of the bundle fr

### 7.7 Not now

Trailers embedded inline (heavy iframe, YouTube tracking, link out instead) · infinite scroll (paginate; infinite scroll wrecks the back button and burns API quota) · dark/light toggle (the design is dark by intent; a light variant is a second design system to maintain) · user accounts of any kind · SSR or prerendering for SEO.
Trailers embedded inline (heavy iframe, YouTube tracking, link out instead) · infinite scroll (paginate; infinite scroll wrecks the back button and burns API quota) · user accounts of any kind · SSR or prerendering for SEO.

*(The light/dark toggle originally listed here as out of scope shipped in the 2026-09-28 redesign — see §6.1 and `docs/DECISIONS.md`. Both themes share one design system, not two, which is what made it cheap enough to add.)*

### 7.8 Done when

Expand Down Expand Up @@ -887,7 +899,6 @@ export const app = {
tagline: 'What to watch, and where',
defaultRegion: 'IN',
regions: ['IN', 'US', 'GB', 'AE'],
genreRails: [28, 35, 18, 27, 878, 10749], // order of the home rails
minVoteCount: 200, // rating credibility floor
ratingsCacheTtlMinutes: 60,
priceStaleAfterDays: 120, // hide prices older than this
Expand All @@ -904,12 +915,13 @@ Kept deliberately short. Every setting is a thing you then have to support.
| Setting | Where it lives | From |
|---|---|---|
| Region | localStorage → profile | P2 → P4 |
| Theme (light/dark) | localStorage, header toggle | 1 (added 2026-09-28) |
| Services I subscribe to | localStorage → profile | P2 → P4 |
| Watchlist | localStorage → account | P1 → P4 |
| Display name and avatar | Profile | P4 |
| Default list for "add" | Profile | P4 |

No theme toggle, no language toggle, no notification preferences, no density setting.
No language toggle, no notification preferences, no density setting.

---

Expand Down
1 change: 0 additions & 1 deletion config/app.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ export const app = {
tagline: 'What to watch, and where',
defaultRegion: 'IN',
regions: ['IN', 'US', 'GB', 'AE'],
genreRails: [28, 35, 18, 27, 878, 10749], // order of the home rails
minVoteCount: 200, // rating credibility floor
tmdbStaleMinutes: 60,
ratingsCacheTtlMinutes: 60,
Expand Down
90 changes: 90 additions & 0 deletions docs/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,93 @@ Tomatometer marker.
**Watchlist control.** "Add to watchlist" adds. Once saved, the control becomes a link,
"On your watchlist", plus a separate "Remove", so no button's label ever describes a state
instead of an action.

## 2026-09-28 · Lively minimalist redesign

**Motion and colour rules loosened deliberately, not by drift.** PLAN.md §6.3 originally banned
hover lifts, card glows and anything beyond one orchestrated moment; the brief changed to "more
alive, still decluttered." This entry records the trade explicitly so a future reader does not
mistake the old rule for still binding. PLAN.md §6 is rewritten to match.

**Card scores now colour by tier, superseding "Card scores are ink, not marigold."** Each score
gets one of three tier colours (verdigris/marigold/rot for great/good/low) via
`src/lib/scoreTier.ts`, reused for the Tomatometer dot and every poster-card rating, so the same
number means the same colour everywhere it appears.

**Skeletons shimmer, superseding "Skeletons do not pulse."** A loading block now sweeps with
`animate-shimmer` once `prefers-reduced-motion` allows it, rather than sitting flat and static.

**A curated accent family, not one gold.** Coral, violet and azure joined marigold and verdigris
(rot unchanged) for genre chips, badges and hover glows — five hues, each with exactly one job
(`src/index.css`'s `@theme` block), so variety stays systemic instead of decorative.

**Poster corners stay sharp; interactive chrome does not.** `radius-sm` (2px) is now reserved for
posters and imagery only. Buttons, dialogs, chips and form controls moved to Tailwind's default
`md`/`lg`/`full` radii, so content and touch targets read as two deliberately different materials.

## 2026-09-28 · Light-default theme, decluttered home page

**Light became the default theme; dark moved behind a toggle instead of being replaced.** The
first redesign pass that day kept the original dark palette but made everything else louder
around it. Landing on a near-black page by default reads wrong for most first visits, so light
is now what a new visitor sees, and dark survives as a fully-supported alternative rather than
a deprecated one — `src/store/theme.ts` persists the choice, and an inline script in
`index.html`'s `<head>` applies it before first paint so there is no flash of the wrong theme.

**Every accent got an independent light-mode hex, not an auto-derived one.** A naive lighten of
the dark accents failed the 4.5:1 contrast floor in one direction or the other for most of the
five (see PLAN.md §6.2). Each colour was picked and checked by computing both the text-on-ground
and text-on-accent-fill contrast ratios directly, so light mode is not a filtered version of dark
mode — it is a second palette held to the same bar.

**Hardcoded colour literals were a theme bug waiting to happen.** Three places (`Button.tsx`,
`Layout.tsx`'s skip link, `GenrePage.tsx`'s checked state) used `text-ground`, which in the old
single-theme world happened to mean "readable on a filled accent" but breaks the moment `ground`
and "readable on accent" diverge, which light mode does immediately. Introduced `--on-accent` as
its own token and a `text-on-accent` utility so "text that sits on a solid accent fill" is named
for what it does, not aliased to a background token that happens to share its value in one theme.
Same fix for three hardcoded shadow `rgba()` literals, replaced with
`color-mix(in oklab, var(--color-x) N%, transparent)`.

**The home page traded genre-rail breadth for one interactive filter.** PLAN.md §7.1 originally
listed "one rail per major genre" as proof the catalogue was deep; in practice it was six rails
of the same ~10 posters restated with a different sort. Replaced with `DiscoverBar`
(`src/features/browse/DiscoverBar.tsx`): pick any number of genres — OR'd via TMDB `with_genres`'s
pipe syntax — plus a rating floor, and it swaps the curated rails for a live `/discover` grid.
Clearing every genre brings the rails back. The curated rails that remain were cut from ten to
six and given a dry, specific voice ("Everyone's already seen this", "The ones everyone pretends
they've seen") instead of literal labels, on the theory that a section name is copy, not a
data label.

## 2026-09-28 · IMDb and Rotten Tomatoes floors on the discover bar

**The discover bar's rating floor only ever filtered on TMDB's own score, because that's the only
score TMDB's `/discover` endpoint knows about.** IMDb and Rotten Tomatoes numbers live in our own
nightly-built ratings shards (§2.2), keyed by IMDb ID, and a live TMDB discover result carries no
IMDb ID — that only comes back from a title's detail endpoint. Filtering by IMDb or RT therefore
can't happen at the TMDB API call; it has to happen client-side, after resolving each candidate's
IMDb ID and looking it up in the shard that OMDb's own numbers already live in.

**The fix cross-references live discover results against the ratings shards instead of building a
second data pipeline.** For each candidate TMDB returns, `getImdbId()` (`src/lib/tmdb.ts`) resolves
its `external_ids`, and `fetchRatingsByImdbIds()` (`src/lib/ratings.ts`) resolves the shard lookups,
deduplicated per shard so twenty titles sharing a shard cost one fetch, not twenty. This keeps
IMDb/RT filtering live and comprehensive (any TMDB genre combination, not just what a nightly job
happened to pre-enrich) at the cost of one extra small request per visible candidate — acceptable
because TMDB has no daily cap, unlike OMDb.

**Filtering is strictly narrowing, so a floor pulls in a second discover page.** Once a IMDb or RT
floor is active, `useDiscoverPages()` fetches two TMDB pages instead of one before the client-side
filter runs, because cross-referencing can only shrink the 20-title pool TMDB hands back, never
grow it back to a full page. Twenty was found to be too few candidates to clear a strict floor like
IMDb 8+ and RT 90%+ stacked together and still show a shelf worth looking at.

**Fetching ratings and applying the threshold are two different steps, deliberately.** The IMDb/RT
lookup is one `useQuery`, keyed only on the candidate IDs; the threshold filter is a plain
`useMemo` over its result. Moving the rating floor from 7 to 8 re-filters already-fetched data
instantly — no network call — because the expensive part (resolving external IDs and shard data)
doesn't depend on where the bar is set, only on which titles are being considered. The two floors
were nearly merged into one query keyed on the thresholds too; that would have re-run the external
ID lookups on every dropdown change for no reason, so they were split.


Loading
Loading