# ReelShield — Wireframes & Design Documentation > **High-fidelity mockups:** every numbered screen below has a matching > standalone HTML render under [`mockups/`](mockups/) — open any of > those files in a browser for a production-quality view of the same > screen described here. The ASCII below conveys structural intent; > the HTML conveys finished fidelity. ## Screen 1: Home / Search > **Mockup:** [`mockups/01-home.html`](mockups/01-home.html) ``` ┌────────────────────────────────────────────────────┐ │ [Skip to content] │ │ │ │ 🎬 ReelShield │ │ AI-powered analysis — Gemini + TMDB [⚙] │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ Search for a movie │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ │ │ e.g. Interstellar, The Dark Knight... │ │ │ │ │ └──────────────────────────────────────────┘ │ │ │ │ 3 results found │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ │ │poster│ │poster│ │poster│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │Title │ │Title │ │Title │ │ │ │ │ │ 1997 │ │ 2023 │ │ 2018 │ │ │ │ │ └──────┘ └──────┘ └──────┘ │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ ○ Generating content warnings... │ │ │ └────────────────────────────────────────────────────┘ ``` **Design decisions:** - Search is full-width and immediately visible — primary action - Poster grid for results: visual recognition faster than text lists - Spinner with status messages prevents perceived abandonment during AI call - ⚙ button top-right: discoverable but not distracting for primary users --- ## Screen 2: Movie Loaded (Desktop — 2-column) > **Mockup:** [`mockups/02-movie-loaded.html`](mockups/02-movie-loaded.html) ``` ┌──────────────────────────────────────────────────────────────┐ │ ⚠️ PHOTOSENSITIVE EPILEPSY WARNING │ │ This film contains flashing lights... [specific notes] │ └──────────────────────────────────────────────────────────────┘ ┌──────────────────────────┐ ┌────────────────────────────────┐ │ 🚫 Content Warnings │ │ 💬 Ask Questions │ │ │ │ │ │ Titanic (1997) │ │ ┌──────────────────────────┐ │ │ [PG-13] [⚠️ Predicts │ │ │ Ask me anything about │ │ │ R/NC-17 · 87%] │ │ │ this film. │ │ │ [194 min] [Drama] │ │ │ │ │ │ │ [You: Who is Rose?] │ │ │ Our ML classifier │ │ │ │ │ estimates this film's │ │ [AI: Rose is a young...] │ │ │ profile better matches │ │ │ │ │ R/NC-17 than its PG-13 │ └──────────────────────────┘ │ │ rating. │ │ │ │ │ ┌──────────────────────┐ │ │ ┌──────────────────┐ [Send] │ │ │ │ Overview blurb text │ │ │ └──────────────────┘ │ │ │ │ from TMDB... │ │ └────────────────────────────────┘ │ └──────────────────────┘ │ │ │ │ Spoiler mode: Off [○] │ │ │ │ ⚠️ Flashing Lights Mild │ │ ✓ Confirmed │ │ Brief flashing... │ │ │ │ Violence & Gore Moderate│ │ ✓ Confirmed │ │ Drowning, injuries... │ │ │ │ Sexual Content Moderate │ │ ✓ Confirmed │ │ │ │ Language Mild │ │ ✓ Confirmed │ │ │ │ Self-Harm None │ │ ✓ Confirmed absent │ │ │ │ 🎬 Content twins │ │ (Adult drama cluster) │ │ ┌────┐ ┌────┐ ┌────┐ │ │ │ B │ │ C │ │ D │ │ │ │Δ.42│ │Δ.51│ │Δ.63│ │ │ └────┘ └────┘ └────┘ │ └──────────────────────────┘ ``` **Design decisions:** - Epilepsy banner always renders above everything else — critical safety info - 2-column layout: warnings left, chat right — parallel use without scrolling - Warnings sorted by severity descending (most severe first) - Color-coded left border: red=severe, orange=moderate, green=mild, grey=none - ✓ Confirmed in green builds trust; ~% in grey signals uncertainty - Spoiler toggle above warnings: visible but default off - MPA-disagreement badge sits next to the TMDB cert badge in amber when the LR classifier disagrees ≥70% confident; rendered in the same row as the cert so the comparison is the headline, not a footnote - Content twins (K-Means neighbors) render below warnings as a small grid; Δ = Euclidean distance in 9-dim severity space, so smaller Δ = closer content-profile match --- ## Screen 3: Mobile (Single Column) ``` ┌─────────────────────────┐ │ 🎬 ReelShield │ │ [⚙]│ ├─────────────────────────┤ │ ⚠️ EPILEPSY WARNING │ │ Brief flashing lights │ │ during sinking sequence │ ├─────────────────────────┤ │ Search for a movie │ │ ┌─────────────────────┐ │ │ │ e.g. Titanic... │ │ │ └─────────────────────┘ │ ├─────────────────────────┤ │ 🚫 Content Warnings │ │ Titanic (1997) │ │ [PG-13][194 min][Drama] │ │ Overview blurb... │ │ │ │ ⚠️ Flashing Lights Mild │ │ ✓ Confirmed │ │ │ │ Violence & Gore Moderate│ │ ✓ Confirmed │ │ ... │ ├─────────────────────────┤ │ 💬 Ask Questions │ │ ┌─────────────────────┐ │ │ │ Chat history... │ │ │ └─────────────────────┘ │ │ ┌──────────────┐[Send] │ │ │ └──────────────┘ │ │ └─────────────────────────┘ ``` **Responsive behavior:** At <768px, columns stack. Epilepsy banner stays pinned to top. Chat moves below warnings. --- ## Screen 4: Prompt Editor Modal ``` ┌──────────────────────────────────────────────────────┐ │ ✏️ Edit AI Prompt │ │ │ │ Customize how Gemini generates content warnings. │ │ Required placeholders: {title} {year} {rating} │ │ {genres} {overview} {keywords} │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ You are a film content expert... │ │ │ │ │ │ │ │ Movie: "{title}" ({year}) │ │ │ │ MPA Rating: {rating} │ │ │ │ ... │ │ │ │ Return ONLY valid JSON... │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ [Save Prompt] [Reset to Default] [Cancel] │ │ │ │ ✓ Prompt updated. New searches will use this. │ └──────────────────────────────────────────────────────┘ ``` --- ## Screen 5: Find Movies (Discover) > **Mockup:** [`mockups/03-discover.html`](mockups/03-discover.html) ``` ┌──────────────────────────────────────────────────────────────────────┐ │ Find Movies │ │ Choose your mood and the warnings you want to avoid — we'll find │ │ the best matches from our movie cache. │ │ │ │ ┌──────────────────────────────────┐ ┌────────────────────────┐ │ │ │ How are you feeling? (optional) │ │ Warnings to avoid │ │ │ ├──────────────────────────────────┤ │ (pick up to 3) │ │ │ │ [ Light and easy ] │ ├────────────────────────┤ │ │ │ [ Some emotion, nothing heavy] │ │ ☐ Violence & Gore │ │ │ │ [ Can handle intense ] │ │ ☐ Self-Harm & Suicide │ │ │ │ [ Feel something deep ] │ │ ☐ Miscarriage │ │ │ │ [ Comfort and familiarity ] │ │ ☐ Sexual Content │ │ │ │ (one selected = highlighted; │ │ ☐ Animal Abuse │ │ │ │ click again to deselect) │ │ ☐ Substance Use │ │ │ └──────────────────────────────────┘ │ ☐ Language │ │ │ │ ☐ Horror / Intensity │ │ │ ┌──────────────────────────────────┐ │ ☐ Flashing Lights │ │ │ │ 💭 You're feeling X — we'll │ │ ⓘ "Pick up to 3" │ │ │ │ look for Y │ └────────────────────────┘ │ │ │ Tones that fit: [whimsical]… │ │ │ │ Tones to skip: [grim]… │ │ │ └──────────────────────────────────┘ │ │ │ │ [ Find Movies ] │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ Safe │ │ Safe │ │ Safe │ │ Safe │ │ Safe │ ← color-coded badge │ │ │ 100 │ │ 92 │ │ 88 │ │ 80 │ │ 72 │ per match quality │ │ │poster│ │poster│ │poster│ │poster│ │poster│ │ │ │Title │ │Title │ │Title │ │Title │ │Title │ │ │ │ Mood │ │ Mood │ │ Mood │ │ Mood │ │ Mood │ ← mood fit % │ │ │ … │ │ … │ │ … │ │ … │ │ … │ │ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ └──────────────────────────────────────────────────────────────────────┘ ``` **Design decisions:** - Two-column layout puts emotional state and content rules side-by-side — neither is more important - Mood is optional; warnings-to-avoid is the load-bearing filter - Cap of 3 avoid categories is a soft constraint announced via `aria-live`, not a disabled checkbox — keeps the UI accessible - Live mood-profile box updates as the user picks moods, so they understand what's about to be searched - Results are scored 0–100 (safer = higher) with mood-fit shown separately --- ## Screen 6: Group Watch Finder > **Mockup:** [`mockups/04-group-watch.html`](mockups/04-group-watch.html) ``` ┌───────────────────────────────────────────────────────────────────────┐ │ 👥 Group Watch Finder │ │ Add everyone in your group, merge their sensitivities, and find │ │ movies safe for all. │ │ │ │ ┌─────────────────────────────────┐ ┌─────────────────────────────┐ │ │ │ Group Members │ │ Group Profile │ │ │ ├─────────────────────────────────┤ ├─────────────────────────────┤ │ │ │ • Sarah ✕ │ │ This group needs movies │ │ │ │ Violence, Animal abuse │ │ free of violence, animal │ │ │ │ • Leo ✕ │ │ abuse, and miscarriage. │ │ │ │ Miscarriage, Self-harm │ │ │ │ │ │ │ │ All sensitivities: │ │ │ │ ┌───────────────────────────┐ │ │ [Violence] [Animal abuse] │ │ │ │ │ Member name… │ │ │ [Miscarriage] [Self-harm] │ │ │ │ └───────────────────────────┘ │ │ │ │ │ │ Their sensitivities: │ │ Avoid genres: │ │ │ │ ☐ Violence ☐ Self-Harm │ │ [Horror] [War] │ │ │ │ ☐ Animal ☐ Sexual │ │ │ │ │ │ ☐ Substance ☐ Language │ │ Suggested genres: │ │ │ │ ☐ Horror ☐ Flashing │ │ [Family] [Comedy] [Animation] │ │ │ ☐ Miscarriage │ └─────────────────────────────┘ │ │ │ [+ Add Member] │ │ │ │ │ Find Movies │ │ │ [⚙ Merge Profiles] │ Mood: [Any mood ▼] │ │ └─────────────────────────────────┘ Platform (optional): [____] │ │ │ │ [ Find Movies ] │ │ │ │ 3 movie(s) safe for everyone in the group: │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 100/100 │ │ 95/100 │ │ 88/100 │ │ │ │ poster │ │ poster │ │ poster │ │ │ │ Title │ │ Title │ │ Title │ │ │ │ Why safe… │ │ Why safe… │ │ Why safe… │ │ │ │ One concern │ │ One concern │ │ One concern │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └───────────────────────────────────────────────────────────────────────┘ ``` **Design decisions:** - Member-builder on the left, profile-and-results on the right — read left-to-right - Merge button stays disabled until ≥1 member is added (prevents empty-state confusion) - Privacy: rejection messages refer to "the group", never name the individual member who triggered them - Each result card includes both `why_safe` and `one_concern` so the group can debate trade-offs --- ## Screen 7: My Watchlist > **Mockup:** [`mockups/05-watchlist.html`](mockups/05-watchlist.html) ``` ┌───────────────────────────────────────────────────────────────────────┐ │ 📋 My Watchlist │ │ Movies are ranked safest-to-most-triggering based on your │ │ sensitivity profile. │ │ │ │ [ ⭐ Rank by My Sensitivities ] │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ ① ✕ │ │ ② ✕ │ │ ③ ✕ │ │ ④ ✕ │ │ │ │ poster │ │ poster │ │ poster │ │ poster │ │ │ │ Title │ │ Title │ │ Title │ │ Title │ │ │ │ 1997 │ │ 2019 │ │ 2023 │ │ 2017 │ │ │ │ 🟢 Safe │ │🟡 Mild │ │🟡 Mild │ │🔴 Strong │ │ │ │ No trig… │ │Brief… │ │Some… │ │Heavy… │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ (Rank ① in top-left, ✕ in top-right to remove) │ └───────────────────────────────────────────────────────────────────────┘ ``` **Design decisions:** - Rank badge (top-left) is the headline — at a glance the user sees what's safest tonight - Color-coded watchlist badge (🟢 / 🟡 / 🔴) mirrors the severity scale used on the warning cards - Remove (✕) is one click but lives in the top-right corner so it isn't fat-fingered while scanning - Re-ranking is explicit, not automatic — running Gemini on the whole list is costly, so the user opts in --- ## Screen 8: Reviews & Ratings (inline on movie page) ``` ┌──────────────────────────────────────────────────────────────────────┐ │ ⭐ Reviews & Ratings │ │ │ │ From critics & aggregators: │ │ ┌────────┐ ┌─────────────┐ ┌────────────┐ │ │ │ IMDb │ │ Rotten │ │ Metacritic │ │ │ │ 7.8/10 │ │ Tomatoes 89%│ │ 74/100 │ │ │ └────────┘ └─────────────┘ └────────────┘ │ │ ───────────────────────────────────────────────────────────────── │ │ │ │ Critic Reviews │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ A. Critic — "An absorbing, careful film…" │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ ───────────────────────────────────────────────────────────────── │ │ │ │ User Reviews │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ Your rating │ │ │ │ ★ ★ ★ ★ ☆ │ │ │ │ Your review │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ │ │ Share your thoughts... │ │ │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ [ Post Review ] │ │ │ │ (or: "Log in to post a review." if not authenticated) │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ @maria · ★★★★★ · 2 days ago │ │ │ │ Watched with my kids and felt prepared for every scene… │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ @jordan · ★★★☆☆ · 1 week ago │ │ │ │ Flashing-lights warning was spot-on, missed a couple of cuts… │ │ │ └────────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────┘ ``` **Design decisions:** - Three trust layers stacked: external aggregators → critic reviews → user reviews — heaviest signal at top - Star widget is keyboard-accessible (each star is a button with `aria-label`) - Login gate is in-place: an inline note replaces the form, so the user isn't surprised by a redirect - User reviews show username + star rating + relative timestamp — matches conventions users already know --- ## Screen 9: Sensitivity Profile Editor (Modal) ``` ┌──────────────────────────────────────────────────────┐ │ 🛡️ My Sensitivity Profile │ │ │ │ Select the content categories you want to be warned │ │ about. This personalizes your watchlist ranking │ │ and badges. │ │ │ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │ │ ☑ Violence & Gore │ │ ☐ Substance Use │ │ │ │ ☑ Self-Harm/Suicide │ │ ☐ Language │ │ │ │ ☐ Miscarriage │ │ ☑ Horror / Intensity│ │ │ │ ☐ Sexual Content │ │ ☑ Flashing Lights │ │ │ │ ☐ Animal Abuse │ │ │ │ │ └─────────────────────┘ └─────────────────────┘ │ │ │ │ [ Save Profile ] [ Cancel ] │ │ │ │ ✓ Profile saved. │ └──────────────────────────────────────────────────────┘ ``` **Design decisions:** - Modal carries `role="dialog"` and `aria-modal="true"` — screen readers announce it as an interrupting layer - Two-column grid keeps all 9 categories on one screen without scrolling on desktop - "Save" is the primary button (filled), "Cancel" is the ghost button — visual weight matches intent - Saved state announced via `aria-live="polite"` so assistive tech users get confirmation without focus shift --- ## Style Guide ### Colors | Token | Hex | Usage | |-------|-----|-------| | `--bg` | `#0f1117` | Page background | | `--surf` | `#1a1d27` | Card/panel surface | | `--surf2` | `#242736` | Input fields, nested surfaces | | `--bdr` | `#2e3347` | Borders | | `--text` | `#e8eaf0` | Primary text | | `--muted` | `#8891a8` | Secondary text, labels | | `--accent` | `#6c8eff` | Primary interactive elements | | `--mild` | `#4caf50` | Mild severity, confirmed absent | | `--moderate` | `#ff9800` | Moderate severity | | `--severe` | `#f44336` | Severe severity | | `--epi-bdr` | `#ff2222` | Epilepsy banner border | ### Typography - Font: `'Segoe UI', system-ui, sans-serif` - Heading: 800 weight - Body: 400 weight, 1.6 line-height - Code/prompt: `'Courier New', monospace` ### Spacing - Base unit: 8px - Card padding: 24px - Gap between cards: 20px - Border radius: 8-12px ### Accessibility Rationale - Dark theme chosen: reduces eye strain for photosensitive users (Persona 2) - 3px focus outlines: clearly visible on dark backgrounds - `aria-live="polite"` on search results and warnings: non-disruptive announcements - `role="alert"` on epilepsy banner: immediate announcement, highest priority - Color contrast targets WCAG AA (4.5:1 normal text, 3:1 UI components) ### Audit evidence A Lighthouse accessibility audit run against the live container on 2026-05-15 scores **100 / 100** — all 26 audits pass, zero element findings. The full report (raw JSON + HTML + a remediation-history README documenting the four fixes that took the page from an initial 89/100 to 100/100) is committed under [`accessibility/`](accessibility/) so the run is reproducible.