tai/research/tui-framework-design/textual-design-guide.md

Textual design guide — live theming and command palette

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	tui-framework-design
Document type	Source Dossier
Tier	1
Source title	Textual design guide — themes and variable system
Source URL	https://textual.textualize.io/guide/design/
Source publisher / author	Textualize (Textual project)
Source type	vendor docs
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 official design documentation: theme bases generate $-variables and shade ramps, assigning self.theme applies a theme live, and the Ctrl+P command palette offers theme switching. Documents the runtime-switch behavior tai wants in miniature.

Key findings

• Theme base colors generate $-variables plus shade ramps consumed throughout the widget system.
• Setting self.theme applies a theme live at runtime; the Ctrl+P command palette exposes theme switching to the user.

Pros / strengths

• Official docs confirming the live-switch contract: swapping the theme pointer plus a redraw is the whole mechanism.
• Shows user-facing switching (palette UI) as a first-class feature, not an afterthought.

Cons / limitations / caveats

• The variable/shade generation pipeline is Textual-scale machinery; tai adopts the switch contract, not the generator.

Relevance to tai

• Backs the palette-role conclusion's switch design (set_theme swaps the pointer and triggers a full redraw) and the single-cycle-key user switcher as tai's miniature of the command palette entry.

Changelog

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