> For the complete documentation index, see [llms.txt](https://docs.kouch.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kouch.dev/docs/adr/0008-rich-data-themes.md). # ADR 0008: Rich data themes, and a Black/White built-in theme ## Status Accepted 2026-09-26 (owner decision, Plan v2 planning). Supersedes part of ADR 0003 and `docs/DESIGN.md` §10. ## Context The old rules (ADR 0003, DESIGN.md §1.7/§10): * Themes may recolor, not restyle. * A theme may set one accent, radii, durations, a background image and sounds. * `mode` must be `dark`. The owner now wants Kouch to be very customizable while keeping its design philosophy: * custom and Workshop themes * a Black/White toggle * an ambient animated background * a Big Picture-style shell ## Decision **The built-in theme stays strict and lint-enforced** (DESIGN.md, the §12 checklist, `design-lint`). It gains: * a light "White" token set alongside the OLED "Black" set * an ambient background of slow-drifting shapes, animated with transform and opacity only, and switchable off * more sound slots and optional background music **Custom themes (`kouch-theme/2`, `docs/THEME_FORMAT.md`) are data only.** They may set: * colors, including light themes * gradients and shadows * radii and durations * fonts (bundled `.woff2`) * the view per screen * tile shape * per-system backgrounds and video * the ambient background * sounds and music * silhouettes and system art (see ADR 0009) They may **not** contain raw CSS, selectors or scripts. **The Rust validator is the boundary.** It emits only CSS custom properties and asset URLs, through the existing `#k-theme` pipeline, and it enforces: * relative paths only * file types and sizes from an allowlist * no remote URLs ## Consequences * DESIGN.md §10 is replaced by `docs/THEME_FORMAT.md`. * `docs/theme-token-allowlist.json` grows. * Rust reads the allowlist with `include_str!`, so the TypeScript and Rust sides can't drift apart. * Player colors get darker variants wherever they fall below 3:1 on White. * Themes can no longer break navigation or run code. The price is losing some visual effects that raw CSS would allow. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kouch.dev/docs/adr/0008-rich-data-themes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.