# Onboarding UX Redesign — Session 2026-05-22

## Context

The onboarding had 4 UX problems:
1. **Double-skip bug**: DebridSetupCard showed two skip buttons side-by-side when not connected
2. **Selection states invisible on TV**: 1dp borders and subtle GlassHover backgrounds invisible from couch
3. **Uninformative copy**: No explanation of WHY debrid/Trakt/OTT matter
4. **No clear progress indicator**: 5 tiny dots, hard to read

## Files Changed

4 files rewritten: 419 insertions, 285 deletions. Commit `22d9991`.

| File | Before | After |
|------|--------|-------|
| `OnboardingScreen.kt` | 480 lines | ~460 lines |
| `DebridSetupCard.kt` | 477 lines | ~430 lines |
| `TraktSetupCard.kt` | 388 lines | ~340 lines |
| `OttRowPicker.kt` | 248 lines | ~260 lines |

## Key Fix: Double-Skip in DebridSetupCard

**Before (broken):**
```kotlin
// Two buttons side-by-side when not connected:
Button(onClick = onSkip)   { Text("Skip") }     // skip #1
Button(onClick = onContinue) { Text("Skip →") }  // skip #2 — WHY?!
```

**After (fixed):**
```kotlin
// Single Skip always present:
Button(onClick = onSkip) { Text("Skip") }

// Continue ONLY when connected:
if (state.debridStatus == "connected") {
    Button(onClick = onContinue) { Text("Continue →") }
}
```

## Key Fix: Strong Selection States

**Before (subtle — invisible on TV):**
```kotlin
ClickableSurfaceDefaults.colors(
    containerColor = GlassBg,           // 10% white — invisible shift
    focusedContainerColor = GlassHover, // 20% white — still invisible
)
border(focusedBorder = Border(BorderStroke(1.dp, Accent)))  // 1dp — invisible from couch
```

**After (visible from couch):**
```kotlin
ClickableSurfaceDefaults.colors(
    containerColor = SurfaceHigh,        // solid dark
    focusedContainerColor = AccentSoft,  // 15% RED tint — unmistakable
)
border(focusedBorder = Border(BorderStroke(2.dp, Accent)))  // 2dp RED border

// Selected chips additionally get:
border(2.dp, NexColors.Accent)    // persistent border
background(NexColors.AccentSoft)  // persistent red tint
checkmark badge in top-end corner
```

## Key Fix: Informative Copy

**Before:** "Get buffer-free 4K streams with cached debrid links."

**After:** "Debrid services give you access to premium, cached 4K streams through private servers. No buffering, no ISP throttling, no waiting. Works with any debrid-compatible source."

**Before:** "Sync your watchlist, history, and ratings across all your devices."

**After:** "Trakt tracks everything you watch — automatically syncing your watchlist, history, and ratings across every Trakt-compatible app and device. Start a movie on your TV, finish it on your phone — Trakt remembers."

**Before:** "Select the services you have — we'll show their trending content."

**After:** "Pick the services you subscribe to. We'll show their trending and popular content on your home screen. Change anytime in Settings → OTT Rows."

## Netflix-Style Progress Bar

**Before:** 5 tiny dots (`8dp` / `12dp`), no text label

**After:**
```kotlin
Box(Modifier.fillMaxWidth().height(3.dp).clip(RoundedCornerShape(2.dp)).background(TextDisabled)) {
    Box(Modifier.fillMaxWidth(progress).height(3.dp)
        .clip(RoundedCornerShape(2.dp)).background(Accent))
}
Text("${currentStep + 1} / $totalSteps")
```
Progress animates via `animateFloatAsState(tween(300))`.

## Build Verification

```bash
./gradlew compileDebugKotlin testDebugUnitTest assembleDebug assembleRelease
# BUILD SUCCESSFUL in 1m 31s
# 17 tests pass
```

## Design Principles (Future Reference)

1. **Single skip per step** — never two skip buttons. Continue only when step is complete.
2. **2dp border minimum** on TV — 1dp is invisible from 10 feet.
3. **Red tint (AccentSoft)** for focus — more visible than brightness shift on dark backgrounds.
4. **Checkmark badge** for selected/toggled state — unambiguous even without color.
5. **Why matters** — every feature needs one plain-language sentence explaining its value.
6. **Thin progress bar** over dots — more visible, scales to any step count.
7. **"Skip Setup" on step 0** — users who don't want onboarding can skip everything immediately.