markdown-converter/docs/superpowers/specs/2026-09-14-theme-registry-design.md

# MarkdownConverter — Editor Theme Registry Design

**Date:** 2026-09-14
**Status:** Draft — pending review
**Author:** Amit Haridas

## Overview

Replace the hardcoded editor-theme menu array in `main.js` (25 inline items at `src/main.js:1137-1245`) and the scattered CSS (`body.theme-<id>` selector blocks across `styles.css`, `styles-modern.css`, `styles-concreteinfo.css`) with a single `ThemeRegistry` module and a per-theme CSS file convention. Add 12 new themes spanning popular-requested, high-contrast, and seasonal categories. Future theme additions become a one-line `register()` call plus one CSS file.

## Goals

1. New themes can be added by changing one JS file and adding one CSS file — no menu edits.
2. Add 12 new themes spanning popular-requested (Catppuccin palette), high-contrast (Solarized Dark HC), and seasonal categories.
3. Theme application stays sub-100ms on theme switch (current behaviour).
4. Existing 25 themes keep working — pure refactor for them, additive for the 12 new ones.
5. Theme persistence model unchanged — `electron-store` `theme` key, default `atomonelight`.

## Non-Goals (v1)

- No user-defined custom themes (theme editor) — only shipped themes.
- No per-syntax-token color customization beyond the per-theme palette.
- No theme auto-switching based on system light/dark mode.
- No export-theme changes — `ExportThemes.js` is a separate system with its own registry (already exists).

## Decisions Locked

| Decision | Choice | Reason |
|---|---|---|
| Module location | `src/main/ThemeRegistry.js` (pure, no Electron) | Matches the established `DocQA`/`DailyNotes`/`WorkspaceSearch` pattern |
| Persistence | Existing `electron-store` `theme` key | Already wired; no migration needed |
| CSS organisation | One file per theme at `src/styles/themes/<id>.css` | Convention beats scattered selector blocks |
| CSS loading | Preload ALL theme `<link>` tags in `index.html`; toggle `disabled` on theme switch | Avoids link-swap network roundtrip; < 5 KB per theme × 37 = ~185 KB total CSS overhead |
| Menu generation | `main.js` calls `ThemeRegistry.list()` + `categories()` to build menu items | Removes the 109-line hardcoded block |
| Theme id format | kebab-case, lowercase, no spaces (`catppuccin-mocha`, `winter-is-coming-light`) | Stable contract for storage + CSS file naming |
| New themes | 12 new: 4× Catppuccin, 1× One Light, 1× Tokyo Night Storm, 2× Synthwave/Outrun, 2× Winter is Coming, 1× Solarized Dark HC, 1× Solarized Light (seasonal Spring variant) | Highest demand per GitHub issues + aesthetic completeness |

## Architecture

```
                       ┌─────────────────────────┐
   electron-store ───► │  src/main/ThemeRegistry │ ◄── register() at startup
   (theme = "x")       │   .js (pure module)     │
                       │   list()                │
                       │   get(id)               │
                       │   categories()          │
                       └──────────┬──────────────┘
                                  │ list()
                                  ▼
                       main.js menu builder
                                  │
                       ┌──────────┴───────────┐
                       │                      │
                       ▼                      ▼
              "Light Themes"         "Dark Themes"
              "High-Contrast"        "Seasonal"
                       │                      │
                       └──────────┬───────────┘
                                  │ IPC: theme-changed
                                  ▼
                  renderer.js applyTheme(id)
                                  │
                                  ▼
                  index.html has 37 <link rel="stylesheet"
                  href="styles/themes/<id>.css" disabled
                  (all themes preloaded)
                                  │
                                  ▼
                  applyTheme() flips `disabled` on the
                  matching <link>, removes from others
```

## New Modules

| File | Role |
|---|---|
| `src/main/ThemeRegistry.js` | Pure module: `register(theme)`, `unregister(id)`, `list()`, `get(id)`, `categories()`, `lightThemes()`, `darkThemes()`. A theme is `{ id, label, category: 'light'\|'dark'\|'high-contrast'\|'seasonal', isDark: boolean }`. No Electron imports. |
| `src/main/ThemeRegistry.bootstrap.js` | Calls `register()` for all 37 themes (25 existing + 12 new). Imported by `main.js` at startup. |
| `src/styles/themes/<id>.css` × 37 | Per-theme CSS rules previously scattered. Each file's body selector is `body.theme-<id>`. Naming convention: `<id>.css`. |
| `tests/theme-registry.test.js` | Register / unregister / list / get / categories; lightThemes/darkThemes filtering; throws on duplicate id. |
| `tests/theme-menu-builder.test.js` | Generates MenuItem[] from `list()` + `categories()`: each item has `{ id, label, type: 'radio', checked, click: () => setTheme(id) }`. |

## Modified Modules

| File | Change |
|---|---|
| `src/main.js:1137-1245` | Delete the 109-line hardcoded theme menu array. Replace with: `const themeMenu = buildThemeMenu(store, mainWindow)` (new helper, ~25 lines, lives next to the menu builder). |
| `src/main.js:3952-3955` | `setTheme(id)` already validates against a hardcoded set — replace hardcoded list with `ThemeRegistry.get(id) ? id : 'atomonelight'`. |
| `src/main.js` startup | Add `require('./main/ThemeRegistry.bootstrap')` once. |
| `src/index.html` | Replace the bare `<link rel="stylesheet" href="styles.css">` block with: preload ALL theme CSS as `<link id="theme-<id>" rel="stylesheet" href="styles/themes/<id>.css" disabled>` (one per theme). The base `styles.css` link stays as the structural (non-themed) layer. |
| `src/renderer.js:2900` (`get-theme` IPC) | No change — handler already returns stored theme. |
| `src/renderer.js:3005-3007` (apply theme) | Replace `document.body.className = 'theme-<id>'` with: find the matching `<link id="theme-<id>">`, set `disabled = false`; find the previously active `<link>`, set `disabled = true`. Keep the `theme-<id>` body className for any rule that depends on it (we keep the convention). |
| `src/styles.css` + `styles-modern.css` + `styles-concreteinfo.css` | Remove the inlined `body.theme-<id> { … }` blocks (one per existing 25 themes). Move them to `src/styles/themes/<id>.css`. Pure code-motion — no rules change. |
| `README.md:129-159` (Themes section) | Update list to 37 themes, mention new categories. |

## New Themes (12)

| id | label | category | notes |
|---|---|---|---|
| `catppuccin-latte` | Catppuccin Latte | light | Warm pastel |
| `catppuccin-frappe` | Catppuccin Frappé | dark | Muted pastels |
| `catppuccin-macchiato` | Catppuccin Macchiato | dark | Medium contrast |
| `catppuccin-mocha` | Catppuccin Mocha | dark | High contrast pastels |
| `one-light` | One Light | light | Atom One Light sibling |
| `tokyo-night-storm` | Tokyo Night Storm | dark | Variant of existing Tokyo Night |
| `synthwave-84` | Synthwave '84 | dark | Neon-on-dark |
| `outrun` | Outrun | dark | Magenta/cyan |
| `winter-is-coming-light` | Winter is Coming (Light) | light | Light variant of existing dark |
| `winter-is-coming-dark` | Winter is Coming (Dark) | dark | New dark variant |
| `solarized-dark-hc` | Solarized Dark (High Contrast) | high-contrast | Accessibility-focused |
| `spring-light` | Spring Light | seasonal | First seasonal theme; same palette as Solarized Light but with green accents |

Categories are independent from `isDark`; e.g. `winter-is-coming-light` has `isDark: false` and `category: 'light'` but conceptually belongs to the "winter is coming" family. Future seasonal themes can share a `family: 'winter-is-coming'` field without changing the public API.

## Data Flow

1. App starts → `main.js` requires `ThemeRegistry.bootstrap.js` → calls `register()` for each of the 37 themes.
2. `main.js` menu builder reads `ThemeRegistry.list()` + `categories()`, generates the View → Theme submenu programmatically.
3. Renderer on init sends `get-theme` IPC → `main.js` replies with stored theme id.
4. `renderer.js:3005-3007` `applyTheme(id)` toggles `disabled` on the matching `<link id="theme-<id>">`; sets `body.className = 'theme-<id>'` for legacy rule compatibility.
5. User picks a new theme in menu → main process `setTheme(id)` → persists via `electron-store` → broadcasts `theme-changed` IPC → renderer `applyTheme(id)` re-toggles.

## Error Handling

| Scenario | Handling |
|---|---|
| Stored theme id no longer exists (e.g. after downgrade) | `setTheme()` falls back to `atomonelight`; logs a warning. Renderer also re-applies defensively. |
| Missing theme CSS file (e.g. partial install) | `<link disabled>` simply doesn't activate; no JS error. App continues with previous active theme. |
| `register()` called with duplicate id | Throws synchronously — startup fails loudly rather than silently shadowing an existing theme. |
| Theme CSS file fails to parse (syntax error) | Browser logs error to console; the disabled `<link>` is never activated so no visual breakage. |

## Testing

1. **Unit (`tests/theme-registry.test.js`)** — `register` adds to list, `unregister` removes, `get` returns the theme, `categories()` returns unique categories in registration order, `lightThemes()`/`darkThemes()` filter correctly. Throws on duplicate id. Throws on missing id in `get()`.
2. **Unit (`tests/theme-menu-builder.test.js`)** — Given a list of 5 sample themes (2 light, 2 dark, 1 hc), `buildThemeMenu` returns a `MenuItem[]` with the correct structure: submenu labels, accelerators, `type: 'radio'`, `checked` matching current selection, `click` handlers wired.
3. **Snapshot (`tests/theme-registry-bootstrap.test.js`)** — At startup, `ThemeRegistry.list()` returns exactly 37 themes with the expected ids in the expected order.
4. **Existing tests** — `tests/project-meta.test.js` already checks `v${version}` in README (now 4.8.0); unchanged.

## Risks

| Risk | Likelihood | Mitigation |
|---|---|---|
| Per-theme CSS files duplicate common rules across 37 files | Medium | Factor the shared editor-surface rules (caret, selection, scrollbar) into a `styles/themes/_base.css`; per-theme files only carry palette tokens. |
| Preloading 37 `<link>` tags delays first paint | Low | Total CSS ≈ 185 KB; gzip ≈ 30 KB; below the 100 ms first-paint budget on Electron's bundled Chromium. Measure with `webContents.getPrintersAsync`-style timing if needed. |
| Body className + disabled-link double-state could drift | Low | Single function `applyTheme(id)` is the only mutation path; unit-tested with both states asserted. |
| README Themes list grows unwieldy at 37 | Low | Group by category in the README; collapse to one-liners per theme with a table. |

## Acceptance Criteria

- [ ] `src/main/ThemeRegistry.js` exists with the public API documented.
- [ ] 37 themes registered at startup; `list().length === 37`.
- [ ] `main.js` menu builder produces the View → Theme submenu from the registry (no hardcoded theme names).
- [ ] Renderer switches themes by toggling `<link disabled>`; no full page reload.
- [ ] Theme persists across restarts via `electron-store`.
- [ ] All existing 25 themes look identical to v4.8.0 (visual regression by inspection — themes are CSS, no logic change).
- [ ] `npm test` passes with the new theme-registry + menu-builder test files added.
- [ ] `npm run lint` clean, `npm run format:check` clean.
- [ ] README updated to list all 37 themes by category.