Conclusion: Telegram ThemeParams as tai's theme-role reference

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	tui-framework-design
Document type	Conclusion
Tier	N/A
Date decided	2026-10-11
Decided by	retoor, advised by tai (agent, Muse Spark)
Status	Active
Confidence	Medium

Question / problem statement

How should Telegram's official ThemeParams vocabulary relate to tai's already-decided 12-role palette — which keys map to which roles, what default values ship, and what switching discipline applies — given that Telegram's values are user-themeable samples rather than constants, and that the working tree resolves roles at draw time but leaves borders hardcoded and several roles unused (established by the same-session internal inventory of tai.py, internal code, no source documents)?

Conclusion

Treat Telegram's 15 ThemeParams keys as the reference vocabulary mapped onto tai's 12 roles: canvas keys (bg_color, secondary_bg_color, section_bg_color, header_bg_color, bottom_bar_bg_color) onto bg/surface; text keys (text_color, subtitle_text_color, section_header_text_color, accent_text_color) onto fg/muted/accent; hint_color onto muted; link_color onto accent; button_color/button_text_color onto accent/on_accent; section_separator_color onto border; destructive_text_color onto error — with representative light/dark defaults taken from the Desktop theme files and the dark samples (#17212b canvas, #f5f5f5 text, #708499 hint, #6ab3f3 link, #5288c1 button, #6ab2f2 accent text, #ec3942 destructive), accent-blue #2B86FD outgoing convention, and the 17/14/11pt emphasis scale (third-party, flagged as such). Adopt Telegram's switching discipline as law: never hardcode colors, re-read the theme on every switch (tai's set_theme plus full repaint is the themeChanged equivalent), and never cache resolved colors across a switch. Defer exact light defaults for section_*/subtitle/destructive until officially published.

Supporting sources

../telegram-webapps-docs.md — the 15-key contract, light/dark scheme plus themeChanged, design rules, chrome inventory.
../mini-apps-docs-theming.md — dark sample values and the never-hardcode/re-read rule.
../mini-apps-docs-main-button.md — bottom primary-action grammar with active/progress states; back control with no implicit behavior.
../mini-apps-docs-settings-button.md — settings-in-overflow-menu placement rule (v6.10+).
../mini-apps-docs-viewport.md — chrome-padding discipline and stable-height rule for bottom-pinned UI.
../axhub-telegram-mobile-design.md — accent-blue outgoing convention and the only type/spacing scale found (third-party, unverified).
../tdesktop-day-blue-theme.md — light-side default values for the mapped roles.
../tdesktop-night-theme.md — dark-side default values for the mapped roles.

Alternatives considered and rejected

Tai-only role names with no Telegram mapping: rejected — mapping to the industry's most-deployed chat theme vocabulary keeps defaults recognizable and reviewable.
Hardcoding Telegram hexes as constants: rejected — Telegram's own docs forbid it (values are user-themeable); samples are defaults, resolved at draw through roles.
Copying pixel geometry (10pt radii, 50pt CTA, 44px targets): rejected — pixel units have no terminal meaning; only relative emphasis and placement discipline transfer.
Light defaults for section_*/subtitle/destructive invented by symmetry: rejected — unpublished values stay explicitly deferred rather than guessed.

Risks / open questions

Exact default light-theme hexes for section_*, subtitle, and destructive are not published officially; only dark samples were observed.
The type/spacing scale rests entirely on a third-party iOS teardown, unverified against Android/Desktop, because no official spec exists.
The WebViewColors diagram (image-only, no alt data) was never inspected and may hold additional guidance.
The sibling back-button SDK page was listed as consulted but yielded no captured evidence; its details remain unarchived.

Action taken

Nothing built yet: role resolution exists but chat uses only 6 of 12 roles, borders are hardcoded white, and no Telegram-derived defaults or section roles exist. This conclusion records the mapping and discipline to implement, not what shipped.

Amendment (2026-10-11): dedicated bubble roles added

Bubble rendering needed roles the 12-role mapping could not carry without collisions: bubble_in, bubble_out, bubble_fg, meta_in, meta_out, tick_read, service_bg, service_fg, unread, unread_muted (dark/light from the tdesktop day/night files, nord/gruvbox mapped by tone, ansi in plain names; register_theme now requires all 22 roles). The 12-role mapping above still holds for everything else.

Changelog

Date	Change
2026-10-11	Initial conclusion recorded.
2026-10-11	Amendment: 10 dedicated bubble/service/unread roles added (22 total).

5.1 KiB Raw Blame History