# Textual theme.py — Theme model and builtin registry

## Metadata

| Field | Value |
|---|---|
| Institute | Molodetz Institute — Research & Retrieval Division |
| Subject | tui-framework-design |
| Document type | Source Dossier |
| Tier | 1 |
| Source title | Textual src/textual/theme.py — Theme class and BUILTIN_THEMES |
| Source URL | https://raw.githubusercontent.com/Textualize/textual/main/src/textual/theme.py |
| Source publisher / author | Textualize (Textual project) |
| Source type | repository |
| Source date (published) | Unknown — not stated |
| Date researched | 2026-10-11 |
| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
| Research method | direct page fetch |
| Confidence | Medium |
| Status | Active |

## Summary

Textual's theme model: a `Theme` built from 11 base colors of which only `primary` is required, with the bases generating the full variable/shade/text system, plus a `BUILTIN_THEMES` dict holding 21 named presets. The richest theme model surveyed, and the explicit template for tai's role names and kebab-case registry.

## Key findings

- A `Theme` is defined by 11 base colors; only `primary` is required, the rest fall back to defaults.
- The base colors generate the full design system: `$`-variables, shade ramps, and text variants.
- `BUILTIN_THEMES` is a dict registry holding 21 named preset themes.

## Pros / strengths

- One-required-color authoring makes custom themes cheap while the generated system keeps them complete.
- A plain-dict named registry with kebab-case names is the simplest registry shape that scales to 21 presets.

## Cons / limitations / caveats

- The generated shade/text machinery is far heavier than tai needs; copying the model whole would violate tai's scope discipline.
- App-level `get_css_variables` override behavior was seen in snippet only, not fetched — not claimed here.

## Relevance to tai

- Template for the palette-role conclusion: tai copies the role names and the kebab-case dict registry, but not the generated-shade machinery.

## Changelog

| Date | Change |
|---|---|
| 2026-10-11 | Initial dossier created from 2026-10-11 research-pass evidence (body opened via web_fetch by researching agent). |