feat(tma): add theming, viewport, and UI components pages

docs.json

@@ -228,6 +228,9 @@
             "group": "TMA: Telegram Mini Apps",
             "pages": [
               "ecosystem/tma/overview",
+              "ecosystem/tma/theming",
+              "ecosystem/tma/viewport",
+              "ecosystem/tma/ui-components",
               "ecosystem/tma/create-mini-app",
               {
                 "group": "Telegram UI",

ecosystem/tma/theming.mdx

@@ -0,0 +1,63 @@
+---
+title: "Theming"
+---
+
+Mini Apps are designed to look native inside Telegram. To achieve this, the Telegram client provides a set of theme colors that the app can apply to its UI.
+
+## Retrieving theme colors
+
+Theme colors are available in two ways.
+
+**Launch parameter.** The [`tgWebAppThemeParams`](/ecosystem/tma/launch-parameters) launch parameter contains a JSON-encoded object with color values. Parse it at startup to apply the initial theme.
+
+**Runtime updates.** The Telegram client can change the theme while the app is running (for example, when the user switches between light and dark mode). Call the [`web_app_request_theme`](https://docs.telegram-mini-apps.com/platform/methods#web-app-request-theme) method and listen for the [`theme_changed`](https://docs.telegram-mini-apps.com/platform/events#theme-changed) event to receive the updated colors.
+
+## Color reference
+
+The theme object contains the following optional properties:
+
+| Property                    | Description                                      |
+| --------------------------- | ------------------------------------------------ |
+| `bg_color`                  | Main background color.                           |
+| `secondary_bg_color`        | Secondary background color.                      |
+| `text_color`                | Primary text color.                              |
+| `hint_color`                | Hint and placeholder text color.                 |
+| `link_color`                | Link color.                                      |
+| `button_color`              | Default button background color.                 |
+| `button_text_color`         | Default button text color.                       |
+| `accent_text_color`         | Accent text color (highlights, active elements). |
+| `destructive_text_color`    | Destructive action text color (delete, remove).  |
+| `header_bg_color`           | Header background color.                         |
+| `bottom_bar_bg_color`       | Bottom bar background color.                     |
+| `section_bg_color`          | Section background color.                        |
+| `section_header_text_color` | Section header text color.                       |
+| `section_separator_color`   | Section separator line color.                    |
+| `subtitle_text_color`       | Subtitle text color.                             |
+
+Example value:
+
+```json
+{
+  "accent_text_color": "#6ab2f2",
+  "bg_color": "#17212b",
+  "button_color": "#5288c1",
+  "button_text_color": "#ffffff",
+  "bottom_bar_bg_color": "#ffffff",
+  "destructive_text_color": "#ec3942",
+  "header_bg_color": "#17212b",
+  "hint_color": "#708499",
+  "link_color": "#6ab3f3",
+  "secondary_bg_color": "#232e3c",
+  "section_bg_color": "#17212b",
+  "section_header_text_color": "#6ab3f3",
+  "subtitle_text_color": "#708499",
+  "text_color": "#f5f5f5"
+}
+```
+
+## Background and header colors
+
+A Mini App is displayed inside a native container that has a header bar and a body area. Telegram provides methods to change the colors of both:
+
+- [`web_app_set_header_color`](https://docs.telegram-mini-apps.com/platform/methods#web-app-set-header-color) — set the header color using a theme key or a custom RGB string.
+- [`web_app_set_background_color`](https://docs.telegram-mini-apps.com/platform/methods#web-app-set-background-color) — set the body background color.

ecosystem/tma/ui-components.mdx

@@ -0,0 +1,67 @@
+---
+title: "UI components"
+---
+
+import { Aside } from '/snippets/aside.jsx';
+
+Telegram provides a set of native UI components that Mini Apps can show and configure. These components are rendered by the Telegram client outside the WebView, so they match the platform look and feel.
+
+<Aside type="note">
+  Native components do not trigger any built-in actions when clicked. The Mini App must listen for the corresponding events and handle them.
+</Aside>
+
+## Back Button
+
+The Back Button appears in the top-left corner of the Mini App header. It is typically used for navigation — for example, returning to a previous screen.
+
+- Show or hide: [`web_app_setup_back_button`](https://docs.telegram-mini-apps.com/platform/methods#web-app-setup-back-button)
+- Click event: [`back_button_pressed`](https://docs.telegram-mini-apps.com/platform/events#back-button-pressed)
+
+## Main Button
+
+The Main Button is a large button at the bottom of the Mini App. It is used for primary actions — for example, confirming an order or submitting a form.
+
+Available customizations: text, text color, background color, active/disabled state, loader visibility.
+
+- Configure: [`web_app_setup_main_button`](https://docs.telegram-mini-apps.com/platform/methods#web-app-setup-main-button)
+- Click event: [`main_button_pressed`](https://docs.telegram-mini-apps.com/platform/events#main-button-pressed)
+
+<Aside type="tip">
+  If the action triggered by the Main Button takes time to complete, show the built-in loader. This signals to the user that the app is processing the request.
+</Aside>
+
+## Settings Button
+
+The Settings Button appears in the top-right menu of the Mini App. It has no built-in behavior — the Mini App decides what happens when the user taps it.
+
+Available since Mini Apps API version `6.10`.
+
+- Show or hide: [`web_app_setup_settings_button`](https://docs.telegram-mini-apps.com/platform/methods#web-app-setup-settings-button)
+- Click event: [`settings_button_pressed`](https://docs.telegram-mini-apps.com/platform/events#settings-button-pressed)
+
+## Popup
+
+A popup is a modal dialog displayed on top of the Mini App. Use it to request user confirmation before performing an action.
+
+A popup supports a title, a message, and up to 3 configurable buttons. When the user presses a button, the Telegram client returns the identifier of the pressed button.
+
+- Open: [`web_app_open_popup`](https://docs.telegram-mini-apps.com/platform/methods#web-app-open-popup)
+- Close event: [`popup_closed`](https://docs.telegram-mini-apps.com/platform/events#popup-closed)
+
+## Haptic feedback
+
+Haptic feedback produces short vibrations on mobile devices in response to user interactions (button taps, selection changes, completed actions). Three feedback types are available:
+
+| Type               | When to use                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `impact`           | Collision between UI elements (for example, snapping into place). |
+| `selection_change` | User changes a selection (for example, scrolling a picker).       |
+| `notification`     | Action completed (success, error, or warning).                    |
+
+Each type supports subtypes for different intensity levels. Trigger haptic feedback with the [`web_app_trigger_haptic_feedback`](https://docs.telegram-mini-apps.com/platform/methods#web-app-trigger-haptic-feedback) method.
+
+<Aside
+  type="caution"
+>
+  Frequent haptic events drain the device battery. Use haptic feedback sparingly — only for meaningful interactions.
+</Aside>

ecosystem/tma/viewport.mdx

@@ -0,0 +1,50 @@
+---
+title: "Viewport"
+---
+
+import { Aside } from '/snippets/aside.jsx';
+
+The viewport is the visible area of a Mini App. Its dimensions and behavior depend on the platform and the current state of the Telegram client.
+
+## Viewport properties
+
+| Property     | Type      | Description                                                         |
+| ------------ | --------- | ------------------------------------------------------------------- |
+| `width`      | `number`  | Width of the visible area in pixels.                                |
+| `height`     | `number`  | Height of the visible area in pixels.                               |
+| `stability`  | `boolean` | `true` when the viewport size is not expected to change imminently. |
+| `expansion`  | `boolean` | `true` when the Mini App has reached its maximum height.            |
+| `fullscreen` | `boolean` | `true` when the Mini App is displayed in fullscreen mode.           |
+
+To receive viewport updates, listen for the [`viewport_changed`](https://docs.telegram-mini-apps.com/platform/events#viewport-changed) event.
+
+## Expanding
+
+On mobile Telegram (Android and iOS), Mini Apps open inside a **BottomSheet** — a draggable panel at the bottom of the screen. By default, the app opens in a minimized state with the minimum allowed height. The user can drag it to the top to expand it, or the app can expand programmatically by calling the [`web_app_expand`](https://docs.telegram-mini-apps.com/platform/methods#web-app-expand) method.
+
+While the BottomSheet is being dragged, the viewport is considered unstable (`stability` is `false`). Avoid resizing or layout recalculations during this time.
+
+On desktop and web platforms, Mini Apps open maximized by default. Calling `web_app_expand` has no effect.
+
+## Fullscreen mode
+
+Fullscreen mode expands the Mini App to cover the entire device screen, hiding the Telegram header and bottom bar. This mode is suitable for games and media applications.
+
+Control fullscreen mode with:
+
+- [`web_app_request_fullscreen`](https://docs.telegram-mini-apps.com/platform/methods#web-app-request-fullscreen) — enter fullscreen.
+- [`web_app_exit_fullscreen`](https://docs.telegram-mini-apps.com/platform/methods#web-app-exit-fullscreen) — exit fullscreen.
+
+Listen for the [`fullscreen_changed`](https://docs.telegram-mini-apps.com/platform/events#fullscreen-changed) event to react to state changes.
+
+## Closing behavior
+
+When a user accidentally closes a Mini App during a multi-step workflow (for example, filling a form or completing a purchase), unsaved progress is lost. To prevent this, enable a confirmation dialog before closing with the [`web_app_setup_closing_behavior`](https://docs.telegram-mini-apps.com/platform/methods#web-app-setup-closing-behavior) method.
+
+## Swipe behavior
+
+On mobile, vertical swipe gestures inside the app can conflict with the system gesture for minimizing or closing the Mini App. To prevent accidental dismissal, disable vertical page swipes with the [`web_app_setup_swipe_behavior`](https://docs.telegram-mini-apps.com/platform/methods#web-app-setup-swipe-behavior) method.
+
+<Aside type="note">
+  Even with swipe behavior disabled, the user can still minimize or close the Mini App by swiping its header.
+</Aside>