From 0b6070c6e110e426f53304825835d83ed3a6c3d2 Mon Sep 17 00:00:00 2001
From: Quick <31828688+Quick104@users.noreply.github.com>
Date: Tue, 26 May 2026 19:56:45 -0400
Subject: [PATCH] docs: add PageBack component design spec

---
 .../2026-05-26-page-back-component-design.md  | 110 ++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-26-page-back-component-design.md

diff --git a/docs/superpowers/specs/2026-05-26-page-back-component-design.md b/docs/superpowers/specs/2026-05-26-page-back-component-design.md
new file mode 100644
index 00000000..a4a1614b
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-26-page-back-component-design.md
@@ -0,0 +1,110 @@
+# PageBack Component Design
+
+## Goal
+
+Replace the inconsistent collection of inline back affordances across user-facing pages with a single shared `PageBack` component, placed in the top-left of every non-root page at a stable pixel offset that does not drift with title length, hero content, or page layout.
+
+Today, back navigation is implemented eight different ways across the app (`DetailBreadcrumb` chevron inside the hero, outline `<Button>` at the page top, ghost `<Link>` with "Back to X" text, `surface-panel-subtle` pill in the page header, plain text link with `←`, etc.), at three different positions (overlaid on hero info column, top-left of page-shell, top-right of page header). A user reported the affordance is hard to find precisely because it moves around as titles and hero content shift. This spec consolidates all of them.
+
+## Behavior
+
+### The component
+
+`<PageBack />` renders a small circular chevron pill in the top-left of its containing element. It is visually identical to the existing `DetailBreadcrumb` chevron (`glass-subtle` background, `ChevronLeft size-5`, muted-foreground with hover) so users already familiar with the season/episode back arrow see no change in that affordance — only a more consistent location.
+
+- Takes no `to` or `onClick` props. A single, fixed behavior is the point.
+- Calls `navigate(-1)` on click.
+- `aria-label` defaults to "Go back" and is overridable via an optional `label` prop for screen reader context.
+- Uses `position: absolute; top: 1rem; left: 1rem; z-index: 20` with `sm:top-1.5rem sm:left-1.5rem`. Pages place it inside a `position: relative` ancestor — typically the existing hero `<section>` (which is already `relative isolate overflow-hidden`) or a wrapping `<div className="relative">` at the top of the page-shell.
+
+### Placement strategy
+
+Two cases:
+
+1. **Hero pages** (ItemDetail variants, PersonDetail). `<PageBack />` is a direct child of the hero `<section>`. The hero is already `relative isolate overflow-hidden`, so the chevron overlays the backdrop in the top-left. No layout change to the hero itself.
+2. **Non-hero pages** (Settings, Request detail, Request browse, Collection editors, Smart collection wizard, Recommendations section, Profile customize home). `<PageBack />` is rendered at the top of the page-shell inside a `<div className="relative">` wrapper, replacing the page's current bespoke back link or button.
+
+In both cases the chevron lands in roughly the same screen pixel range — top-left, just inside the page-shell padding. The title and surrounding content shift around the chevron instead of the other way around.
+
+### Behavior on history-less loads
+
+When a user lands on a non-root page via direct URL (deep link, refresh, new tab) and there is no prior history entry within the SPA, `navigate(-1)` does nothing useful. The chevron is still rendered (we cannot detect this state reliably with React Router v6's history API). This matches browser mouse-back behavior and is acceptable because (a) the failure mode is silent — clicking the button does nothing visible — and (b) users who reach a page via deep link can navigate via the main app shell. We do not gate rendering on history length.
+
+### What `DetailBreadcrumb` becomes
+
+`DetailBreadcrumb` keeps its textual breadcrumb path on Season and Episode pages — the path (e.g., "Severance › Season 1") communicates hierarchy and is independent of back navigation. The leading `ChevronLeft` is removed from `DetailBreadcrumb`; PageBack now owns that affordance. The breadcrumb segments themselves remain individually clickable links to their hierarchy targets.
+
+## Architecture
+
+`PageBack` is a presentational client component with one dependency: React Router's `useNavigate`. No new state, no new context, no new routes. The component lives in `web/src/components/PageBack.tsx` alongside other shared UI primitives.
+
+Each consuming page imports `PageBack` and renders it inside an already-`relative` container. No central placement registry, no per-route configuration — each page is responsible for opting in. This keeps the change localized and reviewable per page.
+
+## Pages affected
+
+### Hero pages — add `<PageBack />` (new affordance)
+
+- `web/src/pages/ItemDetail/MovieContent.tsx`
+- `web/src/pages/ItemDetail/SeriesContent.tsx`
+- `web/src/pages/PersonDetail.tsx`
+
+### Hero pages — add `<PageBack />`, simplify `DetailBreadcrumb`
+
+- `web/src/pages/ItemDetail/SeasonContent.tsx`
+- `web/src/pages/ItemDetail/EpisodeContent.tsx`
+
+In both, the inline `DetailBreadcrumb` retains the textual hierarchy path inside the hero info column; PageBack overlays the hero at top-left.
+
+### Non-hero pages — replace existing back affordance
+
+- `web/src/pages/SettingsLayout.tsx` — remove the `surface-panel-subtle` `ArrowLeft` pill from the page header.
+- `web/src/pages/RequestDetail.tsx` — remove both the outline `<Button>` at the top and the duplicate `<Button>` near the bottom of the page.
+- `web/src/pages/RequestBrowse.tsx` — remove the "Back to Requests" text link.
+- `web/src/pages/CollectionEditor.tsx` — remove the ghost "Back to Collections" `<Link>` (currently rendered in three branches).
+- `web/src/pages/ImportedCollectionEditor.tsx` — same.
+- `web/src/pages/SmartCollectionWizard.tsx` — remove the ghost "Back to Collections" link at the top (the inline "Back to Filters" / floating wizard back buttons stay; they are step controls, not page navigation).
+- `web/src/pages/RecommendationsSection.tsx` — remove the "Recommendations" `<Link>` with `ArrowLeft` near the section header.
+
+### Non-hero pages — add `<PageBack />` (new affordance)
+
+- `web/src/pages/ProfileCustomizeHome.tsx` — currently has no page-level back affordance (the existing `onBackToGallery` is an intra-page state callback, not a page-level navigation control). Add `<PageBack />` at the top.
+
+### Component changes
+
+- `web/src/components/PageBack.tsx` (new) — described above.
+- `web/src/pages/ItemDetail/components/DetailBreadcrumb.tsx` (modified) — drop the leading `ChevronLeft` button. Component becomes a pure path renderer. Update the component's tests if they cover the chevron rendering.
+
+### Pages explicitly not changed
+
+- Top-level user-facing pages (no back affordance is appropriate, they are reached as navigation roots): Home, Catalog, LibraryBrowse, LibraryRecommended, LibraryCollections, LibraryPage, Calendar, Collections, Recommendations (list view), Requests (list view), Profiles.
+- Auth and onboarding flows (state-machine controlled, not history controlled): Login, Signup, OAuthComplete, ActivateDevice, SetupWizard, TasteSeed.
+- Playback chrome (`web/src/playback/WatchPlaybackChrome.tsx`) — already has its own chevron in the player overlay; the watch UX is intentionally separate from the page-shell.
+- Watch Together flows (`WatchTogetherJoin`, `WatchTogetherRoomPage`) — the in-flyout "Back to results" is a contextual subnav inside a flyout, not page-level navigation.
+- Admin pages — the original feedback was user-facing only; admin can adopt `PageBack` in a follow-up pass if desired.
+
+## Edge cases
+
+- **No history entry on initial load.** Clicking `PageBack` calls `navigate(-1)`, which is a no-op. Acceptable; matches browser mouse-back behavior. Documented but not gated.
+- **Backdrop image is mostly white in the top-left.** The `glass-subtle` background provides enough contrast against bright backdrops thanks to its translucent dark fill; this is the same treatment `DetailBreadcrumb` already uses on Season/Episode pages, so behavior is unchanged.
+- **Mobile viewport.** Component uses `top-4 left-4` on small screens and `sm:top-6 sm:left-6` on `sm:` and up. The chevron is `size-5` (20px) inside `p-1.5` padding — a 32px tap target, which is below the 44px Apple HIG recommendation but matches the existing `DetailBreadcrumb` chevron. If mobile reach is a concern, bump padding to `p-2` (40px target). Default to `p-1.5` for visual parity with current code.
+- **RTL layout.** The component pins to `left`. If the app later supports RTL, this becomes `start`-relative; out of scope for this change.
+- **Keyboard focus.** Standard `<button>` element, focusable by default, gets the existing global focus ring from Tailwind base styles. No custom focus handling.
+
+## Out of scope
+
+- Replacing back affordances on admin pages.
+- Persisting or reconstructing app-internal history when users land via deep link (would require a custom history wrapper).
+- Adding a keyboard shortcut (e.g., `Esc` or `Backspace`) for back navigation. Worth considering in a follow-up but not part of this change.
+- Replacing the in-player back chevron in `WatchPlaybackChrome`.
+- Touching Watch Together's contextual subnav.
+
+## Verification
+
+Commands assume the repository root is the cwd.
+
+- `cd web && pnpm run lint`
+- `cd web && pnpm run format:check`
+- Frontend component test for `PageBack`: renders a button with `aria-label`, calls `navigate(-1)` on click, applies the documented Tailwind class string (snapshot or class assertion).
+- Update existing `DetailBreadcrumb` test (if present) to confirm the leading chevron is no longer rendered and the path segments still render and link correctly.
+- Smoke test in the dev frontend: navigate from Home → a movie detail page → confirm the chevron is in the top-left and clicking it returns to Home. Repeat for Series, Season, Episode, Person, Request detail, Request browse, Collection editor, Smart collection wizard, Settings, and Recommendations Section. Confirm the chevron stays in the same screen position across all of them.
+- Visual check on a Season detail page: confirm the textual breadcrumb path ("Series Title › Season N") still renders inside the hero info column and segment links still navigate to the series page.