Add Theme

---
name: add-theme
version: 1.0.0
description: "Add a new color theme to pixtuoid (a full ~90-role palette across 9 groups, rendered into the office). Use when the user says 'add a <name> theme', 'new color scheme', or 'port <palette> to pixtuoid'. Orchestrates the Rust registration PLUS the two steps agents miss — the site manifest bridge test and the committed-media regen."
metadata:
  scope: "pixtuoid repo only"
---

# add-theme (v1)

A theme is a `pub static Theme` with ~90 color roles across **9** groups
(surface, office, lighting, furniture, effects, ui, tool_glow, `ApplianceColors`
for corridor appliances, and `SourceColors` for per-CLI dashboard badge hues).
Every field must be supplied — corridor appliances render wrong until each theme
provides its own set.

## When to use

- "Add a `<name>` theme" / "new color scheme" / "port `<palette>`".

## The checklist

Full current steps: **[`.github/prompts/add-theme.prompt.md`](../../../.github/prompts/add-theme.prompt.md)**
+ the theme notes in [`crates/pixtuoid/src/tui/CLAUDE.md`](../../../crates/pixtuoid/src/tui/CLAUDE.md).
Read an existing theme (e.g. `crates/pixtuoid-scene/src/theme/dracula.rs`) for the
full field set, then:

1. Create `crates/pixtuoid-scene/src/theme/<name>.rs` — fill EVERY field; never
   fall back to the normal palette.
2. Register: `mod` in `theme/mod.rs`, append `&<NAME>` to `ALL_THEMES`,
   `theme_by_name()` resolves the kebab-case name.
3. **Theme roles MAY share an RGB** (every bundled theme does) — the unique-RGB
   rule belongs to SPRITE PACKS (`RECOLOR_KEYS` B/H/S/P, enforced at pack load by
   `validate_recolor_palette`), not to themes. What binds a theme author are the
   per-theme legibility guards in `theme/mod.rs`:
   `appliance_palette_is_legible_for_every_theme`,
   `source_badges_legible_for_every_theme`,
   `token_paper_is_legible_on_the_desk_for_every_theme`, and
   `sun_and_moon_read_warm_and_cool_for_every_theme`.

## The two steps agents miss (both have teeth)

- **`site/src/themes.json` row** (`id` = the kebab-case name) —
  `theme_gallery_manifest_matches_all_themes` (`theme/mod.rs`) asserts the
  manifest ids == `ALL_THEMES` names, so the theme **fails `just test`** until the
  row exists. The site never runs the binary, so this bridge test is the only
  guard that the switcher stays in sync.
- **`just gen-media`** — `themes.json` drives the committed theme stills; a new
  theme drifts them, so regenerate and commit them or the smoke `gen-check` reds
  the PR (the same error the bridge test's message points at).

(Full step list + field details: `add-theme.prompt.md` + the tui `CLAUDE.md` theme
notes — this skill headlines the two teeth steps agents miss.)

## Finish

- `just test` — `appliance_palette_is_legible_for_every_theme` + the snapshot
  tests must pass; update insta snapshots if the theme list changed.
- **Visually verify** — render the `snapshot` example and eyeball the office (see
  the `beautify-decoration` skill); a palette that passes the legibility guard can
  still read badly.
- `just preflight`, then the **two-lens-review** skill (a theme is public-facing —
  add the editorial/film-critic lens for the rendered stills).