# Settings Screen Visual Design Pattern

**Date:** 2026-06-14  
**Context:** Full visual redesign of the Unspooled Settings screen to match reference screenshot (three-column layout, gradient background, white pill focus state).

## Layout Structure

```
┌──────────────┬──────────────┬───────────────────────────────┐
│  Icon Sidebar│ Category Rail│  Content Panel                │
│  (72dp)      │  (220dp)     │  (fills remaining width)     │
│              │              │                               │
│  [Search]    │  Addons      │  Settings (40sp header)       │
│  [Home]      │  Playback    │  Playback (17sp subtitle)     │
│  [Shuffle]   │  Subtitles   │                               │
│  [Settings]◄─│  Debrid      │  ┌─ icon  Auto-play    [ON] ─┐│
│              │  Trakt       │  │← 22dp spacing 18sp   toggle││
│              │  Profiles    │  └────────────────────────────┘│
│              │  Advanced    │  ┌─ icon  Casting  Normal  > ─┐│
│              │  About       │  │  white pill bg on focus     ││
│              │              │  └────────────────────────────┘│
└──────────────┴──────────────┴───────────────────────────────┘
```

## Files

| File | Purpose |
|---|---|
| `ui/screens/settings/SettingsScreen.kt` | Main screen: three-column layout, category/content wiring, D-pad routing |
| `ui/screens/settings/SettingsDesignSystem.kt` | All visual components (appended to bottom — preserves existing sub-screen components) |

## Components (in SettingsDesignSystem.kt)

### 1. `SettingsGradientBackground`
Radial gradient behind the settings content:
```
Brush.radialGradient(
    radius = 1800f,
    center = Offset(800f, -400f),  // top-center
    colors = listOf(
        0xFF8B1A1A,  // burgundy/crimson
        0xFF0A1628,  // dark navy
        0xFF0D1B2A,  // deeper navy
    ),
)
```

### 2. `SettingsRailItem` — Text-only category list
- No Card background — transparent with Text
- **Default:** White text @ 70% alpha
- **Selected (active category):** `#E50914` red, SemiBold
- **Focused (D-pad cursor):** White, SemiBold
- Height: 52dp minimum
- Uses `Card` wrapper only for D-pad click handling (transparent colors)

### 3. `SettingsContentToggleRow` — Toggle row
- **Default state:** Transparent bg, white text, dimmed icon
- **Focused state:** White bg, `#1A1A2E` dark text, bold
- Icon + 16dp spacing + label on left, toggle pill on right
- 64dp height, 32dp pill radius

### 4. `SettingsContentActionRow` — Value + chevron row
- Same focus behavior as toggle row
- Adds value text + right chevron
- Value text: `1A1A2E @ 60%` when focused, `White @ 50%` when default

### 5. `SettingsTogglePill` — Toggle switch
- **ON:** `#E50914` red background, white thumb aligned right
- **OFF:** `White @ 20%` background, white thumb aligned left
- 44×26dp, 13dp corner radius, 22dp thumb

## Focus/Color States (Matrix)

| State | Category Rail Text | Content Row BG | Content Row Text | Content Row Icon | Toggle |
|---|---|---|---|---|---|
| Default | White @ 70% alpha | Transparent | White | White @ 70% | Off: dim / On: red |
| Selected | Red `#E50914` | — | — | — | — |
| Focused | White | White | `#1A1A2E` | `#1A1A2E` | — |
| Selected+Focused | Red `#E50914` | White | `#1A1A2E` | `#1A1A2E` | — |

## D-pad Navigation

```
Sidebar icon rail → Category list → Content panel
                    LEFT=rail ←→ RIGHT=detail (via onPreviewKeyEvent)
```

- **LEFT** from content panel: moves focus back to category rail (via `onPreviewKeyEvent`)
- **RIGHT** from category list: moves focus to content panel detail
- **UP/DOWN** within category list: natural LazyColumn
- **UP/DOWN** within content panel: natural Column scroll

## Key Design Decisions

1. **Components appended to existing file, not rewritten.** The old `SettingsDesignSystem.kt` has `SettingsGroupCard`, `SettingsActionRow`, `SettingsToggleRow`, `SettingsSingleChoiceDialog` used by sub-screens (PlaybackSettingsScreen, SubtitleStyleSettingsScreen, etc.). New components have distinct names (`SettingsContent*Row`, `SettingsRailItem`) to avoid naming conflicts.

2. **`SettingsGradientBackground` wraps content only.** The gradient is inside the scaffold's content area, not behind the sidebar. The sidebar retains its existing glass blur background.

3. **`ComposeColor` alias** — The file uses `import androidx.compose.ui.graphics.Color as ComposeColor`. New components must follow this convention. Do NOT add a second `Color` import.