53 lines
2.8 KiB
Markdown
53 lines
2.8 KiB
Markdown
|
# Telegram Web Apps (Mini Apps) documentation — ThemeParams, events, design rules
|
||
|
|
|
||
|
|
## Metadata
|
||
|
|
|
||
|
|
| Field | Value |
|
||
|
|
|---|---|
|
||
|
|
| Institute | Molodetz Institute — Research & Retrieval Division |
|
||
|
|
| Subject | tui-framework-design |
|
||
|
|
| Document type | Source Dossier |
|
||
|
|
| Tier | 1 |
|
||
|
|
| Source title | Telegram Web Apps (Mini Apps) documentation |
|
||
|
|
| Source URL | https://core.telegram.org/bots/webapps |
|
||
|
|
| Source publisher / author | Telegram |
|
||
|
|
| 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 | High |
|
||
|
|
| Status | Active |
|
||
|
|
|
||
|
|
## Summary
|
||
|
|
|
||
|
|
The official Mini Apps reference: the 15-key `ThemeParams` contract theming every Mini App, the `light`/`dark` color scheme with its change event, the native button inventory (Back, Main/Secondary, Settings), and Telegram's own design rules for apps living inside its chrome.
|
||
|
|
|
||
|
|
## Key findings
|
||
|
|
|
||
|
|
- `ThemeParams` carries 15 optional keys: `bg_color`, `text_color`, `hint_color`, `link_color`, `button_color`, `button_text_color`, `secondary_bg_color`, `header_bg_color`, `bottom_bar_bg_color`, `accent_text_color`, `section_bg_color`, `section_header_text_color`, `section_separator_color`, `subtitle_text_color`, `destructive_text_color`.
|
||
|
|
- `colorScheme` is `light` or `dark` (mirrored in the `--tg-color-scheme` CSS variable); a `themeChanged` event fires on theme or night-mode switches and clients must re-read theme parameters then.
|
||
|
|
- Official design rules: mobile-first, mimic native components, sustain 60fps, use dynamic theme colors (never hardcode), and respect both the safe area and the content safe area.
|
||
|
|
- Native chrome inventory: the BackButton lives in the Mini App header, Main and Secondary buttons sit at the bottom, and Settings is a context-menu item.
|
||
|
|
|
||
|
|
## Pros / strengths
|
||
|
|
|
||
|
|
- The authoritative theming contract: exact key names, scheme values, and event semantics in one place.
|
||
|
|
- The design rules read as Telegram's own look-and-feel policy, directly reusable as tai theming principles.
|
||
|
|
|
||
|
|
## Cons / limitations / caveats
|
||
|
|
|
||
|
|
- The `WebViewColors` diagram is image-only with no alt data and its contents were not inspected (open gap).
|
||
|
|
- No official typography or spacing specification exists anywhere in Telegram's docs (open gap).
|
||
|
|
- Exact default light-theme hexes for the `section_*`, `subtitle`, and `destructive` keys are not published officially; only dark samples were observed elsewhere (open gap).
|
||
|
|
|
||
|
|
## Relevance to tai
|
||
|
|
|
||
|
|
The role vocabulary tai's theming should map onto: 15 Telegram keys against tai's 12 roles, the light/dark scheme contract behind theme switching, and the never-hardcode/re-read-on-change discipline behind `set_theme` plus repaint.
|
||
|
|
|
||
|
|
## Changelog
|
||
|
|
|
||
|
|
| Date | Change |
|
||
|
|
|---|---|
|
||
|
|
| 2026-10-11 | Initial dossier created. |
|