# Settings Screen Three-Column Architecture

Audited June 14, 2026. All 10 gaps fixed.

## Layout

The settings screen uses a three-column layout matching Netflix's Android TV settings:

```
┌──────┬──────────────┬─────────────────────────────────────┐
│ Icon │  Category    │  Content Panel                      │
│ Rail │  Rail        │  (gradient background, white-pill   │
│(72dp)│  (220dp)     │   rows on focus, red toggles)       │
├──────┼──────────────┼─────────────────────────────────────┤
│  🏠  │  Playback    │  Settings  (40sp header)            │
│  🔍  │  Subtitles   │  ┌──────────────────────────┐       │
│  ▶️  │  Debrid      │  │🎬 Default player: Exo... │       │
│  ⚙️  │  Trakt       │  │🔇 Auto-play  [🟥──● ]    │       │
│      │  Advanced    │  │⚡ Refresh-rate  [──● ]   │       │
│      │              │  └──────────────────────────┘       │
└──────┴──────────────┴─────────────────────────────────────┘
```

## Key Files

| File | Role |
|------|------|
| `screen/settings/SettingsScreen.kt` | Three-column layout, category routing, focus gating |
| `screen/settings/SettingsDesignSystem.kt` | All components: gradient bg, rail items, content rows, toggles, choice chips |
| `screen/settings/PlaybackSettingsScreen.kt` | Embedded sub-screen (fully migrated to new design) |
| `screen/settings/SubtitleStyleSettingsScreen.kt` | Embedded sub-screen (fully migrated) |
| `screen/settings/DebridServicesScreen.kt` | Embedded sub-screen (transparent bg only) |
| `screen/settings/TraktServicesScreen.kt` | Embedded sub-screen (transparent bg only) |
| `screen/settings/SourcePreferencesScreen.kt` | Embedded sub-screen (transparent bg only, shown under Playback) |
| `screen/addons/AddonsScreen.kt` | Embedded sub-screen (transparent bg only) |

## Components in SettingsDesignSystem.kt

### SettingsGradientBackground
Radial gradient (crimson burst -> navy -> deep blue, 1800f radius, cached in remember).
Applied as root Box modifier on the settings page.

### SettingsRailItem
Text-only category rail item:
- Default: White text at 70% opacity, FontWeight.Normal
- Selected: Red text (#E50914), FontWeight.SemiBold
- Focused: White text, FontWeight.SemiBold
- Card: Color.Transparent bg, no border, no scale
- 52dp min height, 17sp font

### SettingsContentToggleRow
Content row with toggle pill:
- Default: Transparent bg, white text, white-dimmed icon
- Focused: White bg, dark text (#1A1A2E), semi-bold weight
- Toggle: 44x26dp, red #E50914 when ON, white at 20% alpha when OFF

### SettingsContentActionRow
Content row with value + chevron:
- Same white-pill focus as toggle row
- Value text on right, ChevronRight icon at edge
- 64dp min height, 18sp title, 15sp value

### SettingsContentChoiceChip
Selection chip with selection indicator:
- White-pill focus same as other content rows
- Selected: red dot indicator + red checkmark
- 56dp min height, 17sp label

### SettingsTogglePill (private)
Toggle switch: 44x26dp, red bg ON, white pill thumb 22x22dp

## Focus Architecture

- Rail -> Content: RIGHT on LazyColumn onPreviewKeyEvent -> onMoveToDetail()
- Content -> Rail: LEFT on content Box onPreviewKeyEvent -> onMoveToRail()
- Scroll gating: animateScrollToItem completes -> pendingContentFocusRequestId -> content focuses
- focusGroup() on content Box isolates content focus
- FocusRequester persistence: railFocusRequesters + contentFocusRequesters via remember (stable for session)

## Embedded Sub-Screen Migration

When a sub-screen accepts embedded: Boolean = true:
1. Remove SettingsGroupCard wrappers
2. Remove SettingsDetailHeader
3. Gate .background() with if (!embedded)
4. Replace old SettingsActionRow -> SettingsContentActionRow with icon param
5. Replace old SettingsToggleRow -> SettingsContentToggleRow with icon param
6. Replace SettingsChoiceChip -> SettingsContentChoiceChip

### Full migration (new components): PlaybackSettingsScreen, SubtitleStyleSettingsScreen
### Transparent-only (complex custom layouts): DebridServicesScreen, TraktServicesScreen, AddonsScreen, SourcePreferencesScreen

## Known Remaining Issues

1. Dual SettingsDesignSystem files: screen/settings/ vs ui/components/. Toggle pill sizes/colors differ (44x26dp red vs 52x28dp accent). Defer until old consumers (FocusedSettingRow, FocusedToggleRow, AIOStreamsConfigScreen) are updated.
2. SourcePreferencesScreen still uses custom FocusCard/PresetCard with backgrounds.
3. DebridServicesScreen still uses old SettingsChoiceChip for auth action buttons.
4. TraktServicesScreen TraktCard has transparent bg but shows a border.
5. Gradient performance: radial gradient with 1800f radius on 1920x1080. Cached in remember - fine on modern GPUs, may add 1-3 frame startup on Mali-class.