# Themes — index

The single source of the dark UI theme. See [`schema.md`](../schema.md) for the
memory-map conventions.

| File | Purpose |
|------|---------|
| `Controls.xaml` | All custom control styles/templates: `YtButton`, `YtButtonSecondary`, `IconButton`, `YtTextBox`, `YtTextBoxCompact` (the dense variant the properties panel uses), `YtComboBox`/`YtComboBoxItem` and `YtQualityComboBoxItem` (paid tiers dim but remain clickable), `YtCheckBox`, scrollbar/slider/tooltip/context-menu/menu-item/separator/list-item (implicit where app-wide), `YtListBoxItem`, `YtLabel`, `SectionHeader` |

How it's wired:
- Merged once in [`App.xaml`](../App.xaml) — app-wide. New windows get the theme
  automatically; **do not re-merge per-window**.
- Palette: window `#1a1a2e`, fields `#0f3460`, borders `#2a3a5e`, popups
  `#16213e`, accent `#e94560`, hover `#26ffffff`, text `#e0e0e0`.

Gotchas learned the hard way:
- `MenuItemRole` has **no `Separator` value** — separators are standalone
  `Separator` controls with their own implicit style.
- A custom `ComboBox` template must put the `ContentPresenter` (`SelectionBoxItem`)
  **inside the ComboBox template, not the ToggleButton template** — the latter
  resolves against the wrong TemplatedParent and renders nothing.
- **A control with no style renders with the LIGHT WPF system template** — a
  hand-painted `Background`/`Foreground` colours the box but leaves the system
  border, the system arrow and the white popup list. That is why the Stream
  Alerts "Display" drop-down looked like it belonged to another app (TASK 58,
  2026-10-21). **Rule: every control carries a theme style** — `YtComboBox`,
  `YtCheckBox`, `YtTextBox`/`YtTextBoxCompact` — and paints no colour of its
  own. `ytLive.Tests/PropertiesStyleTests.cs` fails if that drifts back.
  ⚠️ **But that guard sees only those control TYPES** — a picker built as a
  `Button` + a code-built `ContextMenu` is invisible to it (the border-colour
  picker was exactly that, TASK 63). A picker that LOOKS like a drop-down must
  BE the app's drop-down.
- **The `YtComboBox` popup sizes to its CONTENT, not to the ComboBox** (measured
  2026-10-21: the border-colour popup came out 142.7px wide against a 100px
  ComboBox) — a long row is never clipped, and the popup may be wider than the
  closed box. Measure, don't guess.
- **The closed box and the rows of a ComboBox can only differ through an
  `ItemTemplateSelector`** — WPF copies `ItemTemplate` into the read-only
  `SelectionBoxItemTemplate`, so one template renders in both places. The
  selector is told them apart by the `ContentPresenter`'s templated parent
  (`ComboBox` = closed box, `ComboBoxItem` = a row) — see
  `Helpers/ClosedBoxTemplateSelector.cs`.

Related: [`Helpers/index.md`](../Helpers/index.md) (custom controls the theme
styles), the XAML files at repo root that consume these styles.