fix(themes): add dark-theme toggle overrides for network cache settings

The network cache and persistent cache toggles were unreadable in
metro-teal and neon-love because bg-primary/bg-muted resolve to
near-identical colors. Add explicit background-color overrides
matching the existing lastfm-toggle pattern.

- Add docs/theming.md documenting the toggle override pattern
- Reference theming guide from AGENTS.md quick reference table
- Create TASK-299 to port remaining legacy themes and remove themes.json

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pythoninthegrass

AGENTS.md

@@ -47,6 +47,7 @@ Always use Context7 MCP when I need library/API documentation, code generation,
 | MCP bridge tools | [MCP Tool Reference](docs/mcp-reference.md) |
 | Remote debugging, crash analysis | [Debugging Guide](docs/debugging.md) |
 | Last.fm scrobbling | [Last.fm Integration](docs/lastfm.md) |
+| Themes, dark mode toggle fixes | [Theming Guide](docs/theming.md) |
 | Cross-platform builds, CI/CD | [Build Configuration](docs/builds.md) |
 
 ## Architecture Overview

app/frontend/styles.css

@@ -339,12 +339,16 @@ aside button:hover svg {
   color: #00C4CC !important;
 }
 
-/* Metro-teal scrobbling toggle needs explicit colors (Tailwind bg-primary/bg-muted resolve transparent) */
-[data-theme-preset='metro-teal'] [data-testid='lastfm-toggle'].bg-muted {
+/* Metro-teal toggle overrides (Tailwind bg-primary/bg-muted resolve transparent) */
+[data-theme-preset='metro-teal'] [data-testid='lastfm-toggle'].bg-muted,
+[data-theme-preset='metro-teal'] [data-testid='network-cache-toggle'].bg-muted,
+[data-theme-preset='metro-teal'] [data-testid='network-cache-persistent-toggle'].bg-muted {
   background-color: hsl(0 0% 25%) !important;
 }
 
-[data-theme-preset='metro-teal'] [data-testid='lastfm-toggle'].bg-primary {
+[data-theme-preset='metro-teal'] [data-testid='lastfm-toggle'].bg-primary,
+[data-theme-preset='metro-teal'] [data-testid='network-cache-toggle'].bg-primary,
+[data-theme-preset='metro-teal'] [data-testid='network-cache-persistent-toggle'].bg-primary {
   background-color: hsl(184 100% 38%) !important;
 }
 
@@ -497,11 +501,15 @@ aside button:hover svg {
   color: #41C8E5 !important;
 }
 
-[data-theme-preset='neon-love'] [data-testid='lastfm-toggle'].bg-muted {
+[data-theme-preset='neon-love'] [data-testid='lastfm-toggle'].bg-muted,
+[data-theme-preset='neon-love'] [data-testid='network-cache-toggle'].bg-muted,
+[data-theme-preset='neon-love'] [data-testid='network-cache-persistent-toggle'].bg-muted {
   background-color: hsl(268 30% 25%) !important;
 }
 
-[data-theme-preset='neon-love'] [data-testid='lastfm-toggle'].bg-primary {
+[data-theme-preset='neon-love'] [data-testid='lastfm-toggle'].bg-primary,
+[data-theme-preset='neon-love'] [data-testid='network-cache-toggle'].bg-primary,
+[data-theme-preset='neon-love'] [data-testid='network-cache-persistent-toggle'].bg-primary {
   background-color: hsl(191 76% 58%) !important;
 }
 

backlog/tasks/task-299 - Implement-remaining-themes-from-themes.json-and-remove-legacy-file.md

@@ -0,0 +1,46 @@
+---
+id: TASK-299
+title: Implement remaining themes from themes.json and remove legacy file
+status: To Do
+assignee: []
+created_date: '2026-03-19 03:56'
+labels:
+  - frontend
+  - themes
+  - cleanup
+dependencies: []
+references:
+  - themes.json
+  - app/frontend/styles.css
+  - docs/theming.md
+documentation:
+  - docs/theming.md
+priority: low
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+`themes.json` is a legacy file from the tkinter-era backend containing theme definitions that were never ported to the Tauri/Tailwind CSS frontend. Three themes are defined but not implemented as CSS presets:
+
+- **midnight** — dark theme with blue primary (#0a21f5)
+- **nightout** — dark theme with blue primary (#164fe2)
+- **spotify** — dark theme with green primary (#1DB954)
+
+`metro-teal` is already implemented in `styles.css`. After porting the remaining three, delete `themes.json`.
+
+Each new theme needs:
+1. CSS custom properties under `[data-theme-preset='<name>']` in `styles.css`
+2. Toggle overrides for `bg-primary`/`bg-muted` (see `docs/theming.md`)
+3. Entry in the theme picker UI
+4. Visual regression test snapshots
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 midnight, nightout, and spotify themes implemented as CSS presets in styles.css
+- [ ] #2 Each theme has dark-mode toggle overrides for bg-primary/bg-muted (per docs/theming.md)
+- [ ] #3 Each theme selectable from the Appearance settings theme picker
+- [ ] #4 Visual regression snapshots added for each new theme
+- [ ] #5 themes.json deleted from repo root
+<!-- AC:END -->

docs/theming.md

@@ -0,0 +1,44 @@
+# Theming
+
+## Theme Presets
+
+MT ships with three themes defined in `app/frontend/styles.css`:
+
+| Preset | Type | CSS vars defined under |
+|--------|------|----------------------|
+| (default) | Light | `:root` |
+| `metro-teal` | Dark | `[data-theme-preset='metro-teal']` |
+| `neon-love` | Dark | `[data-theme-preset='neon-love']` |
+
+## Dark Theme Toggle Overrides
+
+Tailwind's `bg-primary` and `bg-muted` utilities resolve to near-identical colors in the dark themes, making toggle switches unreadable. Any toggle button that uses `bg-primary`/`bg-muted` for its enabled/disabled state **must** have explicit `background-color` overrides for both `metro-teal` and `neon-love`.
+
+Existing pattern in `styles.css`:
+
+```css
+/* metro-teal */
+[data-theme-preset='metro-teal'] [data-testid='my-toggle'].bg-muted {
+  background-color: hsl(0 0% 25%) !important;
+}
+[data-theme-preset='metro-teal'] [data-testid='my-toggle'].bg-primary {
+  background-color: hsl(184 100% 38%) !important;
+}
+
+/* neon-love */
+[data-theme-preset='neon-love'] [data-testid='my-toggle'].bg-muted {
+  background-color: hsl(268 30% 25%) !important;
+}
+[data-theme-preset='neon-love'] [data-testid='my-toggle'].bg-primary {
+  background-color: hsl(191 76% 58%) !important;
+}
+```
+
+When adding a new toggle to settings, add its `data-testid` selector to the existing grouped rules (search for `toggle overrides` in `styles.css`).
+
+## Adding a New Theme
+
+1. Define CSS custom properties under a new `[data-theme-preset='name']` selector
+2. Add the preset to `themes.json`
+3. Check all toggles are readable in the new theme — add overrides if `bg-primary`/`bg-muted` lack contrast
+4. Run visual regression tests: `cd app/frontend && npx playwright test tests/visual-regression.spec.js`