63 lines
5.1 KiB
Markdown
63 lines
5.1 KiB
Markdown
# 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). |
|