tai/research/tui-framework-design/telegram-webapps-docs.md

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.