tai/research/tui-framework-design/textual-theme-module.md

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).