Michael/xtremflow
1
0 Fork 0
mirror of https://github.com/R0m1k3/xtremflow.git synced 2026-10-11 17:30:00 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
e332895d7da8a7f2a903d63a0fe8cf142f096b50
xtremflow/docs/archive/APPLE_TV_DESIGN_SPECIFICATION.md
T
MichaelandClaude Fable 5 60d3f42901 feat: security hardening, streaming overhaul, design polish, tests 
Security:
- Replace unsalted SHA-256 password hashing with bcrypt (lazy rehash on login)
- Add authenticated /api/xtream-api gateway: Xtream credentials are injected
  server-side and never sent to the frontend; /api/playlists no longer
  returns passwords
- Redact credentials from all logs (login body, proxy/FFmpeg/scheduler URLs)
- Add auth to recordings, EPG, season-passes and streaming routes
  (HttpOnly session cookie for hls.js; loopback bypass for local FFmpeg)
- Lock player postMessage to same-origin in both directions
- Vendor and pin hls.js 1.6.7 / mpegts.js 1.7.3 (drop CDN @latest)
- Fix rate limiter (client IP was never resolved), add login rate limit,
  restrict CORS, add CSP Report-Only, block private-IP SSRF targets,
  fix path traversal in recording log retrieval, chmod 777 -> 770
- Remove dead HiveService (seeded admin/admin into IndexedDB with SHA-256)
- Fix authMiddleware not populating 'user' context (getPlaylist ignored the
  logged-in user; admin purge always returned 403)

Streaming:
- New FfmpegSessionManager: process registry, idle reaper (4 min live /
  15 min VOD), orphan cleanup at startup, clean SIGTERM shutdown,
  fast-fail with stderr instead of 30 s timeout
- Quality selection (source/high/medium/low) for live and VOD; source mode
  streams with -c:v copy (zero transcoding); selector wired into the player
- Concurrent recordings (MAX_CONCURRENT_RECORDINGS, default 2); conflicts
  retry on the next tick instead of silently failing
- Lower live latency (HLS window 20 -> 10 segments, liveSync 10 -> 3)
- Fix recording log lookup (.mp4 vs .mkv mismatch)

Design:
- Replace hardcoded colors with AppColors tokens (12 files)
- web/theme.css syncs HTML players with the Flutter palette
- DPAD/keyboard navigation (arrow-key focus, player shortcuts)
- Tooltips on player icon buttons, Semantics on content cards
- Remove 7 dead widgets broken since the Stitch merge

Quality:
- bin/test/: 21 unit tests (bcrypt, redaction, traversal, SSRF, recording
  conflicts) plus a quality-selector widget test
- GitHub Actions CI (analyze + test + build web)
- Archive stale status docs into docs/archive/

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-10 10:07:18 +02:00

40 KiB
Raw Blame History

XtremFlow Apple TV Design Specification

Comprehensive Assessment & Implementation Guide

PART 1: CURRENT DESIGN SYSTEM ANALYSIS

1.1 Current Color System (app_colors.dart)

✅ What's Working Well

Background Palette:

  • Pure black (#000000) - OLED optimized ✓
  • Surface layers (#1C1C1E, #2A2A2E, #383838) - Good hierarchy ✓
  • Proper contrast against text

Primary Accents:

  • Cyan (#00D4FF) - Primary interactive
  • Mint (#00E5BB) - Secondary accent
  • Red (#FF6B6B) - Soft error state
  • Gold (#FFD700) - Premium/ratings

Text Hierarchy:

  • TextPrimary (#FFFFFF) - Pure white ✓
  • TextSecondary (#999999) - 60% opacity ✓
  • TextTertiary (#666666) - 40% opacity ✓
  • TextQuaternary (#404040) - 25% opacity ✓

Semantic Colors:

  • Success: #34C759 (Apple green)
  • Warning: #FF9500 (Apple orange)
  • Error: #FF3B30 (Apple red)
  • Info: #30B0C0 (Cyan variant)

Glass Effects:

  • glassBackground: white @ 8% opacity
  • glassBorder: white @ 15% opacity
  • glassPremium: white @ 12% opacity

⚠️ What's NOT Apple TV-like

1. Color Vibrancy (BIGGEST ISSUE)

  • Current primary cyan (#00D4FF) is TOO BRIGHT and ELECTRIC
  • Apple TV uses VERY SUBTLE accent colors, understated elegance
  • Real Apple TV focus states use: soft whites, gentle grays, minimal color
  • Current colors feel more like "gaming UI" than "premium streaming service"

2. Lack of True Metal/Premium Finishing

  • No subtle grain or texture layer
  • Missing true metallic highlights
  • No depth separation between depth levels
  • Surfaces feel flat despite glass effects

3. Category Color Over-branding

  • Current: Live (#FF3B30), Movies (#00B4E8), Series (#00E5BB), Sports (#BF5AF0)
  • Problem: Too saturated, creates visual noise
  • Apple TV: Uses ONE primary accent, category distinction via typography + placement

4. Accent Color Saturation

Current:
- Primary:     #00D4FF (Saturation: 100%, Lightness: 50%)
- Secondary:   #FF6B6B (Saturation: 100%, Lightness: 57%)
- Tertiary:    #00E5BB (Saturation: 100%, Lightness: 54%)

Apple TV Ideal:
- Primary:     #00B8E6 (Saturation: ~80%, Lightness: 53%) - Slightly less vibrant
- Secondary:   #FF3B30 (Apple Red - Saturation: 90%)
- Tertiary:    #5AC8FA (Sky Blue - more refined)

5. Glass Opacity Levels

  • Current: 8%, 12%, 15% - quite visible
  • Apple TV glass: 6-10% - more subtle refinement
  • Problem: Current glass looks too opaque, less cinematic

1.2 Current Typography System (app_theme.dart)

✅ What's Working

Font Stack:

  • Outfit - Headlines (modern, geometric)
  • Inter - UI (clean, professional)
  • Smart fallback strategy

Type Scale:

Display Large:    56px / w800 / -1.5 letter spacing
Display Medium:   48px / w700 / -1.0 letter spacing
Display Small:    36px / w700 / -0.5 letter spacing
Headline Medium:  28px / w700 / -0.3 letter spacing
Headline Small:   24px / w600
Title Large:      20px / w600
Title Medium:     16px / w600
Title Small:      14px / w600
Body Large:       16px / w400 / 1.5 line height
Body Medium:      14px / w400
Body Small:       12px / w400
Label Large:      14px / w700
Label Medium:     12px / w600
Label Small:      10px / w600

Issues:

  1. Line heights too tight for TV viewing (some at 1.1 - hard to read from distance)
  2. Display Large (56px) - extreme for TV interface, should be reserved for hero only
  3. Missing size for smaller UI labels (8px for badges)
  4. Letter-spacing on large text creates visual awkwardness at TV distances

1.3 Spacing System (app_theme.dart)

Current (8pt Grid)

spacing2:   2px
spacing4:   4px
spacing8:   8px
spacing12:  12px
spacing16:  16px
spacing20:  20px
spacing24:  24px
spacing32:  32px
spacing40:  40px
spacing48:  48px
spacing56:  56px
spacing64:  64px

⚠️ Issue: TV Viewing Distance

  • Standard TV viewing: 8-10 feet away
  • Current spacing assumes ~2 feet (desktop)
  • Apple TV minimum comfortable spacing: 16pt minimum
  • Current 8pt gaps are INVISIBLE at TV distance

Recommended Adjustments:

Desktop/Tablet (current - good)
spacing8:   8px   (internal card spacing)
spacing16:  16px  (minimum external spacing)
spacing24:  24px  (default sections)
spacing32:  32px  (major sections)

TV (needs expansion)
spacing40:  40px  (minimum comfortable)
spacing48:  48px  (default safe area)
spacing56:  56px  (breathing room)
spacing64:  64px  (major section breaks)

1.4 Radius System (app_theme.dart)

Current

radiusXs:   4px
radiusSm:   8px
radiusMd:   12px
radiusLg:   16px
radiusXl:   24px
radiusXxl:  32px
radiusFull: 999px

⚠️ Issue: Inconsistency with Apple TV

  • Apple TV uses: 8px, 12px, 20px (not 24px)
  • No 4px radius on Apple TV (too sharp)
  • Large content cards use 16-20px, not 32px

1.5 Elevation/Shadow System (Current Implementation)

Current Definition

elevationXs:  2.0
elevationSm:  4.0
elevationMd:  8.0
elevationLg:  16.0
elevationXl:  24.0

⚠️ Major Issue: Too Simplistic

Current glass shadow (from _AppThemeExtension):

BoxShadow(
  color: Colors.black.withOpacity(0.2),
  blurRadius: 20,
  spreadRadius: -5,
)

Problems:

  1. Single shadow only - lacks depth
  2. Blur radius too large (20pt) - fuzzy instead of crisp
  3. Spread radius -5 creates weird contraction effect
  4. Focus shadow is too bright (0.4 opacity) - distracting

Apple TV Shadow Pattern:

  • Layer 1: Ambient shadow (far, soft, dark)
  • Layer 2: Penumbra shadow (mid, medium, subtle)
  • Layer 3: Umbra shadow (close, small, sharp)

1.6 Animation System (app_theme.dart)

✅ Working Well

durationXs:     100ms
durationSm:     150ms
durationBase:   200ms
durationMd:     300ms
durationLg:     400ms
durationXl:     600ms

Curves:

curveDefault:  easeInOutCubic
curveSnappy:   fastOutSlowIn
curveSmooth:   easeOutCubic
curveBouncy:   elasticOut

⚠️ Issues:

  1. No deceleration curve - Apple TV loves easeOutQuad for smooth deceleration
  2. No spring animation - Missing snappy spring curves (dampingRatio: 0.8)
  3. easeInOutCubic too aggressive - Should be easeOutCubic for UI
  4. Missing intermediate duration: 250ms (between 200-300)
  5. elasticOut too bouncy - Creates visual chaos on TV

1.7 Component Styling (Current)

Cards (CardThemeData)

color: AppColors.surface
shape: RoundedRectangleBorder(
  borderRadius: 16px,
  border: 1px solid AppColors.border
)

Issue: No elevation effect - cards sit flat

Buttons (FilledButtonThemeData)

backgroundColor: AppColors.primary (#00D4FF)
padding: 24px horizontal, 12px vertical
borderRadius: 12px

Issues:

  1. Padding too small for TV (44px button height minimum)
  2. Radius 12px conflicts with content card radius (16px)
  3. No focus indicator for remote control

Inputs

fillColor: AppColors.surface
borderRadius: 12px
border: 1.5px solid AppColors.border

Issues:

  1. No focus/active state styling
  2. Cursor invisible at TV distance
  3. No clear "current field" indicator

PART 2: What's NOT Apple TV-like

2.1 Missing Apple tvOS 18+ Characteristics

1. Insufficient Focus State Design

Apple TV Focus System:

  • ~60-70% of screen space dedicated to large touch targets
  • Focus state: Massive scale increase (1.1x minimum), shadow glow, border highlight
  • Current system: Modest scale (1.04-1.06x), insufficient visual feedback

Why it matters for TV:

  • Users navigate with remote, not mouse
  • Focus MUST be unmissable from 10 feet away
  • Visual feedback delay > 200ms creates "laggy" feeling

2. Insufficient Color Hierarchy for Distance Viewing

Apple TV Pattern:

  • 70% neutral greys/blacks
  • 25% surface variations (slight opacity shifts)
  • 5% accent color used ONLY for focus states
  • Current: 20% accent usage (too much noise)

3. No Cinematic Depth Separation

Apple TV Approach:

  • Objects in "background" are nearly invisible (opaque ~5%)
  • Objects in "focus layer" are fully opaque + highlighted
  • Current: All surfaces equally visible

4. Missing Micro-interaction Details

What Apple TV does:

  • Item tap: subtle scale (1.02x), no spring
  • Item focus: scale + glow shadow (appears to float)
  • Item loading: gentle pulse or spinning indicator
  • Current: Basic scale sans sophistication

5. Oversaturation of Effects

Current issues:

  • Every card has border + shadow + gradient
  • Text has too many weights in use (w400, w600, w700, w800 all common)
  • Too many accent colors creating visual noise
  • Glass effect on 50+ elements

Apple TV:

  • 80% of elements use ONE style
  • Accent colors reserved for interactive states only
  • Glass effect used sparingly (max 5-10% of UI)

6. Lack of Content-First Design

Apple TV Philosophy:

  • Content images dominate
  • UI is invisible until needed
  • Minimal borders, overlays, decorations
  • Current: UI elements compete with content

7. No Hierarchy of Attention

Current state:

  • All cards look equally important
  • Feature cards not visually distinguished from regular cards
  • Category badges fight for attention

Apple TV:

  • Hero image occupies 40% of screen
  • Related items in smaller cards (20-30% screen)
  • Metadata minimized below cards
  • Information architecture visible only through layout

8. Animation Sophistication Gap

Apple TV animations:

Focus arrival:    300-400ms easeOut (decelerate as approaching)
Item tap:         100-150ms easeOut with 1.02x scale
Navigation:       400-600ms easeOut with parallax
Page transition:  600ms easeOut with fade
Loading:          smooth loop, no janky "bounce"

Current: Generic easeInOutCubic on all interactions

9. Missing Typography Breathing Room

Apple TV uses:

  • Large line-height (1.4-1.6) making text spacious, easy to read
  • Letter-spacing only on ALL-CAPS text
  • H1 (hero) size: 44-56px (current correct)
  • H2 (section): 24-28px (current correct)
  • Body: 14-16pt line-height 1.5+ (current: 1.5, could be 1.6)

10. No Seasonal/Content-Specific Theming

Apple TV adapts colors based on featured content blend. Current: Static colors.

2.2 Technical Gaps

Missing React Patterns

  1. No focus context provider - hard to manage focus state without it
  2. No animated page transitions - feels abrupt
  3. No parallax scrolling - flatness on large screens
  4. No responsive scaling - doesn't adjust for viewing distance

Missing Accessibility Features

  1. No motion preferences - some users need reduced motion
  2. No high-contrast mode - current colors fail WCAG AAA on TV
  3. No text scaling - users with vision impairment can't zoom

PART 3: Apple tvOS 18+ Modern Design Standards

3.1 Design Philosophy

Core Tenets:

  1. Content First - UI is invisible servant to content
  2. Cinematic Staging - Treat UI like film cinematography
  3. Intentional Simplicity - Every element must justify its existence
  4. Premium Materiality - Surfaces feel substantial and crafted
  5. Subtle Animation - Motion guides, not distracts
  6. Focus-Driven UX - Remote control is primary input

3.2 Color Palette Standards

Semantic Color Mapping (NEW)

Primary Accent (Interactive States):

Name:       Teal Blue (primary focus)
Hex:        #00A0D2  (refined from #00D4FF)
RGB:        0, 160, 210
HSL:        193°, 100%, 41%
Usage:      Focus highlights, CTA buttons, selected states
Notes:      ~20% less bright than current, more sophisticated

Secondary Accent (Content Categories):

Name:       Coral Red (secondary/live content)
Hex:        #FF3B30  (Apple standard)
RGB:        255, 59, 48
HSL:        4°, 100%, 59%
Usage:      Live indicators, warnings, secondary CTAs
Notes:      Slightly desaturated version for TV

Tertiary Accent (Success/Premium):

Name:       Mint Green (achievements, premium)
Hex:        #00D4AA  (refined from #00E5BB)
RGB:        0, 212, 170
HSL:        164°, 100%, 42%
Usage:      Success states, premium badges, highlights
Notes:      Slightly desaturated, more elegant

Neutral Palette (NEW - TV Optimized)

Blacks (OLED Optimized):

Pure Black (base):          #000000
Deep Black (slight lift):   #0A0A0A

Greys (Sophisticated Progression):

Grey Level 1 (darkest):     #1A1A1A  (new: slightly above pure black)
Grey Level 2:               #2A2A2A  (cards, surface)
Grey Level 3:               #3A3A3A  (hover states)
Grey Level 4:               #4A4A4A  (disabled, secondary)
Grey Level 5:               #666666  (secondary text)
Grey Level 6:               #888888  (tertiary text)
White (primary text):       #FFFFFF

Why different from current:

  • Current uses #FF3B30 (red) for too many states
  • New palette uses greys for 80% of UI, color for 5-10% focus states only

Semantic Status Colors (Refined, Apple Standard):

Success:     #34C759  (Apple green - unchanged, perfect)
Caution:     #FF9500  (Apple orange - unchanged, perfect)
Error:       #FF3B30  (Apple red - unchanged, perfect)  
Info:        #32ADE6  (Apple blue - refined from #30B0C0)
Focused:     #FFFFFF  (pure white - for max clarity)

Category Colors (SIMPLIFIED - TV Focused):

Old way (6 category colors):

Live:        #FF3B30  
Movies:      #00B4E8
Series:      #00E5BB
Sports:      #BF5AF0
News:        #FFC300
Music:       #FF2D55
Problem: Creates 6-color UI chaos

New way (Typography + Layout only):

All categories use: Single accent color (#00A0D2)
Distinction via:
- Badge text ("LIVE", "NEW SERIES")
- Position in grid (featured gets larger treatment)
- Content image blend (extract primary color from poster)

Glass Effects (Refined):

Glass Background (base):     rgba(255, 255, 255, 0.06)  (6% opacity - refined from 8%)
Glass Border:                rgba(255, 255, 255, 0.12)  (12% opacity - refined from 15%)
Glass Premium:               rgba(255, 255, 255, 0.10)  (10% opacity)
Frosted (strong glass):      rgba(255, 255, 255, 0.08) + blur(20) + saturation(120%)

Why change:

  • 8% was too visible, creates "plastic" feel
  • 6% achieves true premium glass appearance
  • Reduced opacity makes background content readable

3.3 Typography Hierarchy (COMPLETE REDESIGN)

Font Selection

Headlines: SF Pro Display (fallback: Outfit)

  • Geometric, spacious letterforms
  • Perfect for TV display
  • Excellent hinting at large sizes

Body/UI: SF Pro Text (fallback: Inter)

  • Optimized for smaller sizes
  • Excellent legibility at distance
  • Professional appearance

Monospace: Menlo (fallback: Courier Prime)

  • Code, timestamps, tech specs

Complete Type Scale (for TV viewing)

HERO / Display Large
  Size:           64px
  Weight:         800 (Bold)
  Line Height:    1.2  (77px)
  Letter Space:   -2.0px
  Usage:          Title screen, movie hero
  Example Font:   SF Pro Display

XLARGE / Display Medium
  Size:           56px
  Weight:         700 (Semibold)
  Line Height:    1.15  (64px)
  Letter Space:   -1.5px
  Usage:          Page titles, featured content
  
LARGE / Display Small
  Size:           44px
  Weight:         700 (Semibold)
  Line Height:    1.2  (53px)
  Letter Space:   -1.0px
  Usage:          Section headers, card titles
  
TITLE XXL / Headline Large
  Size:           32px
  Weight:         600 (Semibold)
  Line Height:    1.25  (40px)
  Letter Space:   -0.5px
  Usage:          Subsection headers, prominent labels
  
TITLE XL / Headline Medium
  Size:           28px
  Weight:         600 (Semibold)
  Line Height:    1.3  (36px)
  Letter Space:   -0.3px
  Usage:          Card titles, strong emphasis
  
TITLE LARGE / Headline Small
  Size:           22px
  Weight:         600 (Semibold)
  Line Height:    1.4  (31px)
  Letter Space:   0px
  Usage:          Button text, labels
  
TITLE / Title Large
  Size:           18px
  Weight:         600 (Semibold)
  Line Height:    1.4  (25px)
  Letter Space:   0px
  Usage:          Prominent UI elements
  
LABEL / Title Medium
  Size:           16px
  Weight:         600 (Semibold)
  Line Height:    1.5  (24px)
  Letter Space:   0px
  Usage:          Navigation, buttons, inputs
  
BODY LARGE / Body Large
  Size:           16px
  Weight:         400 (Regular)
  Line Height:    1.6  (26px)
  Letter Space:   0.2px
  Usage:          Primary content text, descriptions
  
BODY MEDIUM / Body Medium
  Size:           14px
  Weight:         400 (Regular)
  Line Height:    1.6  (22px)
  Letter Space:   0.2px
  Usage:          Secondary content, metadata
  
BODY SMALL / Body Small
  Size:           12px
  Weight:         400 (Regular)
  Line Height:    1.5  (18px)
  Letter Space:   0.15px
  Usage:          Tertiary text, timestamps, specs
  
CAPTION LARGE / Label Large
  Size:           12px
  Weight:         500 (Medium)
  Line Height:    1.4  (17px)
  Letter Space:   0.3px
  Usage:          Badge text, tabs, secondary labels
  
CAPTION SMALL / Label Small
  Size:           11px
  Weight:         500 (Medium)
  Line Height:    1.4  (15px)
  Letter Space:   0.3px
  Usage:          Small badges, tertiary labels
  
MICRO / Label XSmall (NEW)
  Size:           10px
  Weight:         600 (Semibold)
  Line Height:    1.2  (12px)
  Letter Space:   0.5px
  Usage:          Tiny badges, version numbers

Key Improvements Over Current:

Metric Current New Benefit
Display Large 56px 64px Better hero presence
Body Line Height 1.5 1.6 More breathing space
Spacing -1.5 to -0.5 -2.0 to 0 Refined hierarchy
Font Weights 4 types 3 types Simpler, cleaner
Minimum Body 12px 10px Flexibility for small UI
Letter Spacing Random Systematic Professional, consistent

3.4 Spacing System (TV-First)

Interactive Spacing Grid (12pt base on TV)

Compact (internal element spacing):
  xs:       4px   (icon padding)
  sm:       8px   (button padding, internal card gaps)
  md:       12px  (default padding, between elements)

Normal (standard spacing):
  lg:       16px  (standard card padding)
  xl:       20px  (section gap)
  2xl:      24px  (section padding)
  3xl:      32px  (major section padding)

Comfortable (breathing room):
  4xl:      40px  (section separation on TV)
  5xl:      48px  (hero bottom padding, card grid gap)
  6xl:      56px  (page top/bottom safe area)
  7xl:      64px  (major layout break)

Large Scale (TV safe areas):
  8xl:      80px  (page margins on 4K)
  9xl:      96px  (hero section bottom padding)

Responsive Scaling (for different screen sizes)

Mobile (portrait):
  Base padding:    16px
  Section gap:     12px
  Grid gap:        12px
  Min button height: 44px

Tablet (landscape):
  Base padding:    24px
  Section gap:     20px
  Grid gap:        16px
  Min button height: 48px

Desktop (27"+):
  Base padding:    32px
  Section gap:     24px
  Grid gap:        20px
  Min button height: 48px

TV (55"+):
  Base padding:    48px
  Section gap:     32px
  Grid gap:        24px
  Min button height: 56px

3.5 Elevation & Shadow System (Cinematic)

Apple TV Multi-Layer Shadow (Depth System)

Level 1 - Flat (No Shadow)

Usage: Background layers, disabled states
Shadows: None

Level 2 - Ambient (Subtle, far-field)

Box-shadow 1:
  Color:        rgba(0, 0, 0, 0.08)
  Blur radius:  6px
  Spread:       0px
  Offset:       0px, 2px
Note: Indicates presence, minimal depth

Level 3 - Card (Standard, TV default)

Box-shadow 1 (ambient):
  Color:        rgba(0, 0, 0, 0.12)
  Blur radius:  8px
  Spread:       0px
  Offset:       0px, 4px

Box-shadow 2 (subtle detail):
  Color:        rgba(0, 0, 0, 0.06)
  Blur radius:  2px
  Spread:       0px
  Offset:       0px, 1px

Combined: Depth with sophistication

Level 4 - Elevated (Focused elements, hover)

Box-shadow 1 (ambient):
  Color:        rgba(0, 0, 0, 0.20)
  Blur radius:  12px
  Spread:       0px
  Offset:       0px, 8px

Box-shadow 2 (penumbra):
  Color:        rgba(0, 0, 0, 0.10)
  Blur radius:  4px
  Spread:       0px
  Offset:       0px, 2px

Box-shadow 3 (focus glow - when selected):
  Color:        rgba(0, 160, 210, 0.20)  [Teal primary]
  Blur radius:  16px
  Spread:       0px
  Offset:       0px, 0px

Combined: Floating effect, appears to float 16px off surface

Level 5 - Lifted (Modals, critical content)

Box-shadow 1 (ambient):
  Color:        rgba(0, 0, 0, 0.25)
  Blur radius:  16px
  Spread:       0px
  Offset:       0px, 12px

Box-shadow 2 (penumbra):
  Color:        rgba(0, 0, 0, 0.15)
  Blur radius:  6px
  Spread:       0px
  Offset:       0px, 4px

Box-shadow 3 (umbra):
  Color:        rgba(0, 0, 0, 0.08)
  Blur radius:  2px
  Spread:       0px
  Offset:       0px, 1px

Combined: Extreme depth for modals, overlays

Focus State Shadow (for interactive elements)

When element receives focus (remote/keyboard):

Box-shadow 1 (glow effect):
  Color:        rgba(0, 160, 210, 0.30)    [Teal primary, 30% opacity]
  Blur radius:  20px
  Spread:       2px
  Offset:       0px, 0px

Creates: Glowing, "floating" effect that appears to hover above surface
Animation: Fade in over 150ms easeOut, fade out over 200ms easeInOut

Summary Table

Level Usage Primary Shadow Accent Shadow Glow
1 Background, Disabled None None None
2 Base surfaces 0.08 @ 6px blur - -
3 Cards, Containers 0.12 @ 8px + 0.06 @ 2px Yes Optional
4 Hover/Focus 0.20 @ 12px + 0.10 @ 4px Yes #00A0D2 20px
5 Modals, Overlays 0.25 @ 16px + 0.15 @ 6px + detail Yes Optional

3.6 Animation System (Cinematic Timing)

Core Duration (Orchestration)

Entrance timing:    300-400ms
Interaction:        150-200ms
Navigation:         600-800ms
Transition:         1000-1200ms

Device/Input Correlation:
- Touch: instant (0ms) → 150ms feedback
- Remote: 300ms input lag → 150ms animation = 450ms felt
- Keyboard: 0ms → 150ms minimum animation

Duration Scale (Complete)

50ms:   MICRO   - Icon rotation, minimal state change
100ms:  XS      - Accessibility required minimum
150ms:  SM      - Button tap, quick response
200ms:  BASE    - Standard UI change, focus movement
300ms:  MD      - Card hover, scroll deceleration
400ms:  LG      - Page focus change, moderate navigation
600ms:  XL      - Full page transition, entrance animation
800ms:  XXL     - Modal entrance, major layout shift

Curve Specifications (Apple TV Patterns)

Entrance (Deceleration - starts fast, ends slow):

Name:       easeOutQuad (or fastOutSlowIn)
Bezier:     cubic-bezier(0.25, 0.46, 0.45, 0.94)
Timing:     300-600ms
Usage:      Page load, item entrance, scroll arrival
Feel:       Objects smoothly arrive, natural deceleration
Example:    Hero image fades and scales in

Interaction (Quick response - symmetrical):

Name:       easeInOutQuad (or easeInOutCubic)
Bezier:     cubic-bezier(0.42, 0, 0.58, 1)
Timing:     150-200ms
Usage:      Button press, item tap, quick transitions
Feel:       Responsive, snappy, purposeful
Example:    Card scales 1.02x on focus

Navigation (Deceleration with precision):

Name:       easeOutCubic
Bezier:     cubic-bezier(0.215, 0.61, 0.355, 1)
Timing:     400-600ms
Usage:      Focus movement, carousel slide, page change
Feel:       Smooth travel, confident landing
Example:    Focus ring travels to next item

Spring Micro-interactions (Bounce):

Name:       cubicBezier w/ spring
Bezier:     cubic-bezier(0.175, 0.885, 0.32, 1.275)
Timing:     250-350ms
Damping:    0.75
Usage:      Like/favorite button, achievement unlock
Feel:       Celebratory, satisfying feedback
Example:    Heart icon springs up on favorite tap

Loading (Smooth loop):

Name:       linear
Timing:     1000ms (one full rotation)
Usage:      Loading spinner, buffering indicator
Feel:       Consistent, predictable
Note:       Never use easeInOut for rotating loaders - jittery

Animation Composition (Sequences)

Focus Arrival (Remote Control):

Timeline:
0ms:        Item becomes focused (input event)
0-50ms:     Border color changes (fast)
0-150ms:    Scale 1.0 → 1.05 (easeInOutQuad)
0-200ms: Scale 1.05 → 1.04 (easeOutQuad - settle)
100-200ms:  Shadow color changes to accent (easeOut)
150-300ms:  Shadow blur increases (easeOut)

Result: Smooth, confident arrival with no overshoot

Tap Feedback (Button):

Timeline:
0ms:        Tap detected
0-50ms:     Scale 1.0 → 0.98 (instant)
50-100ms:   Scale 0.98 → 1.0 (easeOutQuad)
0-80ms:     Opacity 1.0 → 0.9 → 1.0 (easeOut)

Result: Tactile feedback without spring bounce

Page Transition:

Timeline:
0-200ms:    Fade out current page (easeInQuad)
200-600ms:  Scale current → 0.95 (easeOutQuad)
200-600ms:  Fade in new page + scale 1.0 (easeOutQuad)
400-800ms:  Focus moves to target item (nested animation)

Result: Cinematic flow, parallax effect

3.7 Component Specifications

Buttons (Complete)

Primary Button (Main CTA)

Size:
  Height:       56px (TV comfortable)
  Padding:      24px horizontal, 12px vertical
  Target size:  min 56px × 56px (touch target)

Normal state:
  Background:   #00A0D2 (teal primary)
  Foreground:   #FFFFFF (white)
  Border:       none
  Shadow:       Level 2 (subtle)
  Radius:       12px

Hover state (mouse):
  Background:   #0092BC (darker teal, -15% lightness)
  Scale:        1.02x
  Shadow:       Level 3 (elevated)
  Duration:     200ms easeOut

Focus state (remote/keyboard):
  Background:   #00A0D2 (unchanged)
  Foreground:   #FFFFFF
  Border:       2px solid #FFFFFF
  Shadow:       Level 4 + glow (teal)
  Scale:        1.05x
  Duration:     150ms easeOut

Pressed state:
  Scale:        0.98x
  Duration:     100ms easeOut
  Duration:     100ms easeOut

Disabled state:
  Background:   #4A4A4A (neutral grey)
  Foreground:   #888888 (dimmed text)
  Opacity:      0.6
  Cursor:       not-allowed

Secondary Button (Alternative CTA)

Size:       Same as primary (56px min)
Normal:
  Background:   #2A2A2A (surface variant)
  Foreground:   #FFFFFF
  Border:       1px solid #3A3A3A
  
Hover:
  Background:   #3A3A3A
  Border:       1px solid #4A4A4A

Focus:
  Foreground:   #FFFFFF
  Border:       2px solid #00A0D2 (accent)
  Glow:         Teal (#00A0D2) 16px

Text Button (Tertiary)

Normal:
  Foreground:   #00A0D2 (accent)
  Background:   transparent

Hover:
  Foreground:   #0092BC (darker teal)
  Background:   rgba(0, 160, 210, 0.08)
  
Focus:
  Foreground:   #00A0D2
  Background:   rgba(0, 160, 210, 0.12)
  Border:       2px solid #FFFFFF underneath text

Cards (Complete)

Content Card (Movie, Show, Live)

Container:
  Size:         Width varies, 2:3 aspect ratio (poster)
  Background:   #1A1A1A (deep grey)
  Border:       none (image-only clean look)
  Radius:       12px
  Shadow:       Level 2 (subtle)

Normal state:
  Scale:        1.0x
  Overlay:      none
  
Hover state:
  Scale:        1.04x
  Shadow:       Level 3 (elevated)
  Overlay:      rgba(0, 0, 0, 0.15) fade in 200ms
  
Focus state:
  Scale:        1.06x
  Shadow:       Level 4 + glow
  Overlay:      rgba(0, 0, 0, 0.25)
  Border:       2px solid #00A0D2
  
Active/Selected:
  Badge:        "PLAYING" or checkmark
  Border:       3px solid #00A0D2
  Glow:         #00A0D2, 20px blur

Info Card (Channel, Provider)

Container:
  Background:   #1A1A1A with 1px border #3A3A3A
  Padding:      16px
  Radius:       12px
  Shadow:       Level 2

Content:
  Title:        18px, w600, white
  Subtitle:     14px, w400, grey
  Badge:        Optional (12px, accent color)

Hover:
  Background:   #2A2A2A
  Scale:        1.02x
  Shadow:       Level 3

Focus:
  Border:       2px solid #00A0D2
  Glow:         20px teal

Active:
  Backend:      #00A0D2 10% opacity
  Border:       2px solid #00A0D2

Input Fields (Forms, Search)

Normal state:
  Background:   #1A1A1A
  Border:       1px solid #3A3A3A
  Text color:   #FFFFFF
  Placeholder:  #666666
  Height:       48px (comfortable for remote)
  Padding:      12px horizontal, 12px vertical
  Radius:       12px

Hover state (mouse):
  Background:   #2A2A2A
  Border:       1px solid #4A4A4A

Focus state (keyboard/remote):
  Background:   #1A1A1A
  Border:       2px solid #00A0D2
  Shadow:       glow, teal, 12px
  Cursor:       (visible text input cursor)

Error state:
  Border:       2px solid #FF3B30
  Shadow:       glow, red, 12px
  Helper text:  red, 12px

Success state:
  Border:       1px solid #34C759
  Helper text:  green, 12px

Disabled state:
  Background:   #2A2A2A
  Opacity:      0.5
  Cursor:       not-allowed

Navigation (Focus-Driven)

Top Navigation Bar

Height:       64px (including padding)
Background:   rgba(26, 26, 26, 0.95) with glass blur
Padding:      16px horizontal, 8px vertical
Items:        Spaced 48px apart (TV comfortable)

Logo/Title:   32px, w700, white, SF Pro Display
Actions:      Icon + text labels (20px icons, 14px labels)

Focus state:  
  Icon:       Glow with accent color
  Border:     2px solid white underneath text
  Scale:      1.1x
  Duration:   150ms easeOut

Side Navigation (if needed)

Width:        280px (4K TV comfortable)
Background:   #0A0A0A deep grey
Padding:      24px

Items:
  Height:     56px (large touch targets)
  Margin:     12px vertical
  Text:       18px, w600
  Icon:       24px, aligned left
  
Normal:
  Color:      #999999 (secondary text)
  Background: transparent

Focus:
  Color:      #FFFFFF
  Background: #00A0D2 10% opacity
  Border left: 3px solid #00A0D2
  Scale:      1.02x

Grid Cards (Channel List, Content Grid)

Per Row (responsive):
  4K TV (55"+):   5-6 items per row
  Full HD TV:     4 items per row
  Tablet:         3 items per row
  Mobile:         2 items per row

Spacing:
  Horizontal:     24px gap
  Vertical:       24px gap
  Page padding:   48px all sides (TV)

Card size (TV):
  Width:          aspect ratio 1:1 or 16:9
  Height:         auto or fixed
  Min size:       200×200px

Focus behavior:
  Focus cycle:    Horizontal first, wrap to next row
  Auto-scroll:    Keep focused item centered
  Focus zone:     Don't scale > 1.08x (prevent overlap)

3.8 Glass Morphism Specifications

Premium Glass Effect (Advanced)

Usage Rules:

  • Max 5-10% of screen use glass
  • Never on primary content
  • Only on: Navigation, overlays, modals
  • Avoid nested glass (glass inside glass)

Glass Container Definition:

Base:
  Backdrop Filter:   Blur(15px)
  Opacity:           6% white overlay
  Border:            1px solid white @ 12% opacity
  
Gradient overlay:
  Start:             rgba(255, 255, 255, 0.08) top-left
  End:               rgba(255, 255, 255, 0.04) bottom-right
  
Shadow:
  Shadow 1 (ambient):
    Color:           rgba(0, 0, 0, 0.15)
    Blur:            12px
    Spread:          -4px
    Offset:          0, 4px
    
  Shadow 2 (edge):
    Color:           rgba(0, 0, 0, 0.08)
    Blur:            2px
    Spread:          0px
    Offset:          0, 1px

Focused Glass:

When glass element receives focus:
  Blur:              20px (increase from 15)
  Opacity:           10% (increase from 6%)
  Border:            2px solid white @ 15%
  Shadow 3 (glow):   rgba(0, 160, 210, 0.2), blur 20
  Duration:          150ms easeOut

3.9 Theming Strategy (Systematic Approach)

Dark Mode (Primary - for TV)

Background:   #000000 pure black
Surfaces:
  Level 0:    #000000 (base)
  Level 1:    #0A0A0A (subtle lift)
  Level 2:    #1A1A1A (card surface)
  Level 3:    #2A2A2A (hover lift)
  Level 4:    #3A3A3A (disabled/secondary)

Text colors (4-tier system):
  Primary:    #FFFFFF (100% opacity)
  Secondary:  #999999 (60% opacity) = #FFFFFF @ 60%
  Tertiary:   #666666 (40% opacity) = #FFFFFF @ 40%
  Quaternary: #404040 (25% opacity) = #FFFFFF @ 25%

Accent colors:
  Primary:    #00A0D2 (teal, focus states)
  Secondary:  #FF3B30 (red, alerts)
  Tertiary:   #34C759 (green, success)

PART 4: IMPLEMENTATION ROADMAP

Phase 1: Color System Update (4-6 hours)

Files to update:

  1. lib/core/theme/app_colors.dart

    • Update primary from #00D4FF → #00A0D2
    • Refine secondary #FF6B6B → #FF3B30
    • Update tertiary #00E5BB → #00D4AA
    • Add grey surface levels (19 new colors)
    • Remove excessive category colors
    • Update glass opacity values (8% → 6%)
    • Add new focus glow color

  2. Update all theme-referencing files

    • lib/core/theme/app_theme.dart (color references)
    • lib/mobile/theme/mobile_theme.dart (color references)
    • All widget files using AppColors.primary etc.

Estimated changes:

  • app_colors.dart: ~50 lines modified/added
  • 15+ widget files: 1-5 line color reference updates each

Phase 2: Typography System (6-8 hours)

Files to update:

  1. lib/core/theme/app_theme.dart

    • Update all text styles with new sizes
    • Adjust line heights (add minimum 1.4)
    • Reduce letter-spacing on large text
    • Add new MICRO style (10px)
    • Increase Display Large from 56 → 64px

  2. Create lib/core/theme/typography_scale.dart

    • Document all type sizes with usage examples
    • Provide mixin for easy application

Estimated changes:

  • Text scale definitions: ~80 lines
  • Widget usage updates: Scattered, find via grep

Phase 3: Spacing & Layout (4-5 hours)

Files to update:

  1. lib/core/theme/app_theme.dart

    • Review spacing constants (already good - minimal changes)
    • Add TV-specific spacing (80px, 96px)
    • Create responsive spacing mixin

  2. Layout files - Targeted updates:

    • lib/features/iptv/screens/home_screen.dart
    • lib/core/widgets/tv_channel_grid.dart
    • lib/features/iptv/screens/player_screen.dart

Key change: Increase minimum padding from 16px → 32px for TV layouts

Phase 4: Shadow & Elevation System (3-4 hours)

Files to update:

  1. lib/core/theme/app_theme.dart - _AppThemeExtension

    • Redefine 5 elevation levels with multi-layer shadows
    • Create focus glow definitions
    • Add elevation utility functions

  2. Create lib/core/theme/elevation_system.dart

    • Predefined shadow presets (Level 1-5)
    • Usage examples

  3. Update all components using shadows:

    • Cards (15+ files)
    • Buttons (5+ files)
    • Navigation (3+ files)

Phase 5: Animation System (5-6 hours)

Files to update:

  1. lib/core/theme/app_theme.dart

    • Update animation curves
    • Add new durations (250ms)
    • Add spring curve definitions

  2. Create lib/core/animation/tv_animations.dart

    • Predefined animation sequences
    • Focus arrival animation
    • Tap feedback animation
    • Page transitions

  3. Update high-use animation files:

    • lib/core/widgets/tv_focusable_card.dart
    • lib/core/widgets/hero_carousel.dart
    • lib/core/widgets/glass_container.dart (scale animations)
    • Navigation widgets (focus transitions)

Phase 6: Component Styling (8-10 hours)

Primary Button Update:

  • File: lib/core/theme/app_theme.dart (filledButtonTheme)
  • Changes:
    • Height: 44px → 56px
    • Padding: 24×12 → 28×12
    • Radius: 12px → keep
    • Focus border: Add 2px white border
    • Glow: Add on focus

Secondary Button Update:

  • File: lib/core/theme/app_theme.dart (outlinedButtonTheme)
  • Changes: Similar to primary
  • Border styling on focus

Card Styling:

  • File: lib/core/theme/app_theme.dart (cardTheme)
  • Remove default border (use in component instead)
  • Add default shadow (Level 2)
  • Radius: 16px → 12px

Navigation:

  • lib/core/widgets/tv_nav_widgets.dart
  • Increase button height: 44px → 56px
  • Update icon sizing
  • Add focus glow

Phase 7: Glass Effect Refinement (3-4 hours)

Files to update:

  1. lib/core/widgets/glass_container.dart

    • Opacity: 8% → 6% (default)
    • Blur: 15px (good, keep)
    • Shadow redefinition (Level 3)
    • Add focused state with glow

  2. lib/core/widgets/glass_card.dart

    • Update animations to match new standards
    • Add press feedback

Phase 8: Verification & Testing (4-6 hours)

Checklist:

  • All colors match specification hex codes
  • Typography scales render correctly at 4K
  • Animations duration/curve matches spec
  • Focus states clearly visible
  • Shadows render with depth
  • Glass effects appear premium
  • Build passes without warnings
  • Visual regression testing (screenshots)

PART 5: Specific Hex Code Reference

Complete Color Palette

Primary System:

Primary Teal:        #00A0D2  (Focus, CTA, highlights)
Primary Teal Dark:   #0092BC  (Hover state)
Primary Teal Light:  #1BC4E5  (Disabled variant)

Secondary System:

Error Red:           #FF3B30  (Errors, alerts, live)
Error Dark:          #E62817  (Hover)
Error Light:         #FF6B6B  (Disabled variant)

Success System:

Success Green:       #34C759  (Success states)
Success Dark:        #2AA64D  (Hover)
Success Light:       #5AD361  (Disabled)

Warning System:

Warning Orange:      #FF9500  (Warnings)
Warning Dark:        #E68400  (Hover)
Warning Light:       #FFA325  (Disabled)

Neutral System:

Pure Black:          #000000  (Base background)
Deep Black:          #0A0A0A  (Lift 1)
Level 1 Grey:        #1A1A1A  (Card surface)
Level 2 Grey:        #2A2A2A  (Hover)
Level 3 Grey:        #3A3A3A  (Disabled)
Level 4 Grey:        #4A4A4A  (Divider)
Level 5 Grey:        #666666  (Secondary text)
Level 6 Grey:        #888888  (Tertiary text)
Level 7 White:       #FFFFFF  (Primary text)

Glass System:

Glass Base:          rgba(255, 255, 255, 0.06)
Glass Border:        rgba(255, 255, 255, 0.12)
Glass Premium:       rgba(255, 255, 255, 0.10)
Glass Dark:          rgba(0, 0, 0, 0.50)

Text Opacity System (from white #FFFFFF):

100% (Primary):      #FFFFFF  = 255, 255, 255, 1.0
80% (Emphasized):    #CCCCCC  = white @ 80%
60% (Secondary):     #999999  = white @ 60%
40% (Tertiary):      #666666  = white @ 40%
25% (Quaternary):    #404040  = white @ 25%

PART 6: Implementation Checklist

Pre-Implementation

  • Export this specification to team
  • Schedule design review (2-3 hours)
  • Identify high-impact screens (home, player, channels)
  • Create test plan for visual regression

Color System (Phase 1)

  • Update app_colors.dart
  • Verify all color references compile
  • Screenshot side-by-side comparison
  • Check contrast ratios (WCAG)

Typography (Phase 2)

  • Update app_theme.dart text styles
  • Test rendering at 4K resolution
  • Verify line-height spacing
  • Check readability at TV distance

Layout (Phase 3)

  • Update spacing usage
  • Review TV layout files
  • Test responsive behavior
  • Verify padding on all containers

Shadows (Phase 4)

  • Define elevation system
  • Update component shadows
  • Test shadow depth perception
  • Verify focus glow visibility

Animations (Phase 5)

  • Update animation curves
  • Test animation fluidity
  • Review animation timing
  • Test on target device

Components (Phase 6)

  • Update button styling
  • Update card styling
  • Update form elements
  • Update navigation

Glass (Phase 7)

  • Refine glass effects
  • Test on dark backgrounds
  • Verify premium appearance
  • Test focus states

Testing (Phase 8)

  • Full app build
  • Visual regression screenshots
  • Accessibility audit
  • Performance profiling
  • Cross-screen testing (mobile→TV)

SUMMARY

This specification provides:

  1. Current State Analysis - Identifies what works and what doesn't
  2. Apple TV Standards - Detailed design principles and specifications
  3. Complete Specifications - Exact hex codes, measurements, timings
  4. Implementation Path - Phased approach across 8 phases
  5. Reference Material - For developers implementing changes

Key Takeaways:

  • Current design has good foundation but needs refinement
  • Primary issue: Colors too vibrant (not Apple TV sophisticated)
  • Solution: Muted palette, reserved accent colors, grey-dominant UI
  • Focus states must be unmissable for TV remote control
  • Multi-layer shadow system creates cinematic depth
  • Animation curves should be easeOut-based (deceleration)
  • Spacing needs TV-aware expansion (48px minimum comfortable)
  • Glass effects should be subtle (6% opacity, not 8%)

Estimated Timeline: 4-6 weeks for full implementation Team Size: 2-3 developers (designer + 2 devs in parallel) Risk Level: Low (all changes contained, fallback to current if needed)

Reference in new issue View Git Blame Copy Permalink