Библиотека дизайна / Дизайн-системы

Дизайн-системыTelegram Mini AppsСветлыйТёмныйМинимализмБесплатно

Telegram UI — дизайн-система для Telegram Mini Apps на React

Конспект открытой библиотеки Telegram UI: цвета из themeParams, системный шрифт, секции и ячейки как в Telegram.

Telegram UI — дизайн-система для Telegram Mini Apps на React
Промпт
Подключи к моему проекту (React, Vite) официальную библиотеку Telegram UI: пакет @telegram-apps/telegram-ui (автор XeleneStudio при поддержке TON Foundation, лицензия MIT, документация: github.com/Telegram-Mini-Apps/TelegramUI, Storybook: tgui.xelene.me). Ниже мой конспект DESIGN.md в открытом формате Google: токены и правила для интерфейса Mini App.

Что сделать:
1. Сохрани файл как DESIGN.md в корне проекта без изменений. Перед каждым новым экраном перечитывай его.
2. Установи пакет: `npm i @telegram-apps/telegram-ui`. Он требует React 18 (`react` и `react-dom` ^18.2), а свежий шаблон Vite ставит React 19, и установка падает с ERESOLVE. Поэтому для нового проекта сразу поставь `npm i react@18 react-dom@18 @types/react@18 @types/react-dom@18`, а в существующем проекте на React 19 не переходи на `--legacy-peer-deps` молча: сначала предупреди меня.
3. В точке входа импортируй стили: import '@telegram-apps/telegram-ui/dist/styles.css'. Оберни приложение в AppRoot из пакета. Платформу (iOS или Android) и тему AppRoot определяет сам, пропсы platform и appearance передавай только для проверки в обычном браузере. Для интеграции с Telegram используй официальный SDK @telegram-apps/sdk-react или скрипт telegram-web-app.js, не придумывай свой.
4. Собери экран-витрину: список из Section и Cell с подписями, поле Input, кнопки Button трёх видов, Chip, SegmentedControl, Placeholder для пустого состояния и Tabbar внизу. Проверь экран в светлой и тёмной теме.
5. Дальше собирай экраны только из компонентов Telegram UI и токенов из DESIGN.md. Не добавляй новые цвета: цвета берутся из CSS-переменных --tgui--* и из темы Telegram. Если нужного компонента нет, сначала предложи вариант, потом используй.

Тексты интерфейса на русском, на «вы», без восклицательных знаков.

Файл DESIGN.md скопируется вместе с промптом

Конспект открытой библиотеки Telegram UI для ИИ-агента. Библиотека повторяет интерфейс самого Telegram: списки из секций и ячеек, серый фон страницы, белые карточки, синяя основная кнопка. Мини-приложение, собранное из неё, выглядит как родная часть мессенджера и подхватывает тему пользователя.

Это не официальный продукт Telegram и не замена документации. Токены и правила ниже выписаны из исходников пакета и README, чтобы агент собирал экраны из готовых компонентов, а не рисовал свои. Сам пакет @telegram-apps/telegram-ui распространяется по лицензии MIT, поэтому вы ставите его из npm, а не копируете из этого файла.

Весь конспект лежит в одном файле DESIGN.md (открытый формат Google): вверху токены, ниже правила словами. В Telegram цвета приходят от клиента (themeParams), поэтому токены здесь это запасные значения библиотеки, а не палитра, которую нужно навязывать.

Что внутри

  • Цвета по умолчанию для светлой и тёмной темы: белый фон и серый #EFEFF4 у страницы, тёмный #212121 и #0F0F0F. Акцент #007AFF (светлая) и #2990FF (тёмная).
  • Шрифт: в приложении будет системный (system-ui, SF Pro на iOS, Roboto на Android). В конспекте и превью стоит Roboto как ближайший шрифт Google Fonts с кириллицей.
  • Шкала текста библиотеки: от large_title 34 px до caption2 11 px, вес 400, 600 и 700.
  • Скругления 8 / 12 / 16 px: секции и поля 12 px, нижняя шторка 16 px.
  • Компоненты: Section, Cell, List, Button, Input, Chip, SegmentedControl, Tabbar, Placeholder, Modal.
  • Правила для Mini Apps: безопасные зоны, нижняя навигация, главная кнопка Telegram, тема из themeParams, текст на русском.

Как пользоваться

  1. Скопируйте промпт: файл DESIGN.md скопируется вместе с ним.
  2. Вставьте его в Claude Code или Cursor в папке React-проекта (подойдёт шаблон Vite). Агент сохранит файл, поставит пакет и соберёт экран-витрину из официальных компонентов.
  3. Дальше просите экраны («каталог», «профиль», «оформление заказа»). Агент берёт только компоненты Telegram UI.

Для проверки откройте приложение внутри Telegram (через бота и кнопку Mini App) или хотя бы в браузере: библиотека сама определит платформу и тему.

Откуда токены

  • outline светлой темы (#D9D9D9) взят из разделителя --tgui--divider (чёрный 15% на белом). Обводка --tgui--outline в библиотеке намного бледнее (чёрный 5%, около #F2F2F2), её используйте для рамок полей и карточек.

Значения сверены с пакетом @telegram-apps/telegram-ui версии 2.1.13 (файл dist/styles.css) и документацией:

Что не удалось сверить точно: радиус и размер шрифта подписи основной кнопки. В styles.css у кнопок встречаются радиусы 10 и 12 px, в конспекте принято 12 px. Размер подписи 15 px взят как subheadline2, при расхождении с Storybook верьте Storybook. Роль secondary не существует в самой библиотеке, под неё взят цвет подсказок hint_color. Светлая и тёмная палитры соответствуют базовым блокам стилей; значения iOS и Android отличаются только высотой строк и толщиной границы.

DESIGN.md
---
version: alpha
name: Telegram UI
description: Конспект открытой библиотеки Telegram UI для Mini Apps. Секции и ячейки как в Telegram, синий акцент, цвета из темы клиента, системный шрифт.
colors:
  primary: "#007AFF"
  on-primary: "#FFFFFF"
  secondary: "#707579"
  success: "#31D158"
  error: "#E53935"
  light:
    surface: "#FFFFFF"
    surface-container: "#EFEFF4"
    on-surface: "#000000"
    on-surface-variant: "#707579"
    outline: "#D9D9D9"
    tertiary-container: "#F4F4F7"
  dark:
    surface: "#212121"
    surface-container: "#0F0F0F"
    on-surface: "#FFFFFF"
    on-surface-variant: "#AAAAAA"
    outline: "#373737"
    primary: "#2990FF"
    on-primary: "#FFFFFF"
    card: "#242424"
    tertiary-container: "#2A2A2A"
typography:
  headline-lg:
    fontFamily: Roboto
    fontSize: 28px
    fontWeight: 700
    lineHeight: 1.25
  headline-md:
    fontFamily: Roboto
    fontSize: 20px
    fontWeight: 600
    lineHeight: 1.2
  title-lg:
    fontFamily: Roboto
    fontSize: 24px
    fontWeight: 600
    lineHeight: 1.3
  headline:
    fontFamily: Roboto
    fontSize: 19px
    fontWeight: 600
    lineHeight: 1.45
  body-md:
    fontFamily: Roboto
    fontSize: 17px
    fontWeight: 400
    lineHeight: 1.5
  subheadline:
    fontFamily: Roboto
    fontSize: 15px
    fontWeight: 400
    lineHeight: 1.45
  label-md:
    fontFamily: Roboto
    fontSize: 15px
    fontWeight: 600
    lineHeight: 1.3
  caption:
    fontFamily: Roboto
    fontSize: 13px
    fontWeight: 400
    lineHeight: 1.5
  caption-sm:
    fontFamily: Roboto
    fontSize: 11px
    fontWeight: 400
    lineHeight: 1.45
rounded:
  sm: 8px
  md: 12px
  lg: 16px
  full: 9999px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 20px
  xl: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    height: 50px
  section:
    backgroundColor: "{colors.light.surface}"
    rounded: "{rounded.md}"
    padding: 0 20px
  input:
    backgroundColor: "{colors.light.surface}"
    textColor: "{colors.light.on-surface}"
    rounded: "{rounded.md}"
    height: 44px
  bottom-sheet:
    backgroundColor: "{colors.light.surface}"
    rounded: "{rounded.lg}"
---

## Overview

Telegram UI делает Mini App похожим на сам Telegram. Экран это серый фон страницы и белые (в тёмной теме графитовые) секции со скруглёнными углами, внутри ячейки с подписью, значением и иконкой. Один синий акцент для ссылок и главного действия, остальное нейтральное. Ощущение: знакомый, спокойный, без собственного «бренда» приложения. Платформа определяется автоматически: на iOS строки плотнее, граница 0.5 px, на Android строки выше, граница 1 px.

## Colors

В Telegram цвета задаёт клиент пользователя через `themeParams` (`bg_color`, `text_color`, `hint_color`, `link_color`, `button_color`, `button_text_color`, `secondary_bg_color` и другие). Telegram UI превращает их в CSS-переменные `--tgui--*`. Значения в токенах выше это запасные цвета самой библиотеки, они применяются, когда клиент ничего не передал. Поэтому не фиксируйте цвета в коде: используйте переменные и компоненты.

- **Primary (#007AFF), синий:** главная кнопка, ссылки, активная вкладка, переключатели. В тёмной теме запасное значение `#2990FF` (`dark.primary`). Белый текст на `#007AFF` даёт контраст около 4:1, это значение библиотеки, оно сохранено без изменений.
- **Secondary (#707579):** подсказки, подписи, вторичный текст и иконки (`hint_color`). В самой библиотеке такой роли нет, это наше сопоставление.
- **Success (#31D158) и Error (#E53935):** статусы и ошибки. Деструктивные действия («Удалить») красным текстом `destructive_text_color`.
- **Светлая тема:** фон страницы `surface-container` (#EFEFF4), секции и карточки `surface` (#FFFFFF), текст `on-surface`, подписи `on-surface-variant`, разделитель `outline` (в библиотеке чёрный с прозрачностью 15%).
- **Тёмная тема:** секции `surface` (#212121), страница `surface-container` (#0F0F0F), карточки `dark.card` (#242424), текст белый, подписи `#AAAAAA`, разделитель белый с прозрачностью 10%.
- Градиентов и теней почти нет: единственная лёгкая тень у секций `0 1px 2px rgba(0,0,0,0.1)`.

## Typography

В приложении будет системный шрифт платформы: `system-ui`, на iOS SF Pro, на Android Roboto (в библиотеке стек `system-ui, -apple-system, BlinkMacSystemFont, "Roboto", "Apple Color Emoji", "Helvetica Neue", sans-serif`). В этом конспекте и превью указан Roboto: это ближайший шрифт Google Fonts с кириллицей. Не подключайте свои шрифты.

Шкала библиотеки: `large_title` 34 px, `title1` 28 px, `title2` 24 px, `title3` 20 px, `headline` 19 px, `text` 17 px, `subheadline1` 16 px, `subheadline2` 15 px, `caption1` 13 px, `caption2` 11 px. Веса: 400 для текста, 600 для заголовков и кнопок, 700 для крупных заголовков. Основной текст 17 px. Заголовок экрана `headline-lg`, заголовок секции `headline-md`.

## Layout

Экран это вертикальный список секций. Поля у секций 20 px по бокам, внутри ячейки по вертикали 12 или 16 px. Между секциями 16–20 px. Контент не выходит за безопасные зоны: снизу учитывайте `env(safe-area-inset-bottom)` (в библиотеке `--tgui--safe_area_inset_bottom`), особенно у нижней навигации и фиксированных кнопок. Ширина адаптивная, Mini App открывается на телефоне и в окне десктопа, поэтому ограничьте ширину контента примерно 480–600 px и центрируйте.

## Elevation & Depth

Глубина через цвет: серый фон, белая секция. Тени минимальные. Всплывающие слои (выпадающий список, модальное окно) получают мягкую тень `0 32px 64px rgba(0,0,0,0.04)`. Нижняя шторка поднимается над затемнением с радиусом 16 px сверху. Размытие фона (`backdrop-filter: blur(28px)`) только у тостов.

## Shapes

8 px для мелких элементов, 12 px для секций, полей, выпадающих списков и кнопок, 16 px для верхних углов нижней шторки. Чипсы и бейджи круглые. Аватары круглые (`50%`).

## Motion

Короткие переходы: смена состояния 125–150 мс, плавное появление шторки и модальных окон. Анимация только прозрачности и положения. Нажатие на ячейку показывает лёгкую подсветку (`--tgui--plain_background`). Не добавляйте свои эффекты и пружины.

## Voice & Content Strategy

- Тон: дружелюбный и короткий, на «вы». Без восклицательных знаков и сленга.
- Заголовки секций короткие и в нижнем регистре Telegram-стиля: «Настройки», «Уведомления».
- Кнопки это глагол: «Оформить заказ», «Сохранить», «Отправить». Не «ОК».
- Пустое состояние: заголовок, одно предложение и одна кнопка (компонент `Placeholder`).
- Ошибки: что случилось и что сделать: «Не удалось загрузить. Проверьте интернет и повторите».
- Цены «1 990 ₽», время «14:30», даты «24 ноября».

## Components

- **AppRoot:** корневая обёртка. Определяет платформу и тему, задаёт шрифт и цвета. Всё приложение внутри него.
- **List и Section:** основной способ собрать экран. Section с заголовком (`header`) и белым фоном, внутри Cell. Отступы между секциями задаёт List.
- **Cell:** строка с `before` (иконка или аватар), заголовком, `description`, `after` (значение или переключатель). Нажимаемая ячейка ведёт на следующий экран.
- **Button:** виды `filled` (основной, синий фон, белый текст), `tinted` (светло-синий фон), `plain` (только текст), размеры `s`, `m`, `l`. На экране одна основная кнопка. Для закрепления у нижнего края используйте `FixedLayout` с учётом безопасной зоны.
- **Input, Textarea, Select, Switch, Checkbox, Radio:** поля внутри Section, подпись в `header`, ошибка в `status="error"`.
- **Chip и SegmentedControl:** фильтры и переключение вида. Выбранный чип с фоном акцента.
- **Tabbar:** нижняя навигация из 3–5 пунктов с иконкой и подписью, активный пункт цвета акцента.
- **Placeholder:** пустые состояния и экраны ошибок: иконка или картинка, заголовок, описание, кнопка.
- **Modal и Snackbar:** шторка снизу для выбора и подтверждения, всплывающее сообщение для результата действия.

## Do's and Don'ts

- Собирайте экран из List, Section и Cell. Это узнаваемый облик Telegram.
- Берите цвета из CSS-переменных и темы клиента, не из жёстких hex в коде.
- Проверяйте экран в светлой и тёмной теме и на iOS и Android (пропс `platform` у `AppRoot`).
- Закрепляйте нижние кнопки с отступом на безопасную зону.
- Не рисуйте свои кнопки, поля и вкладки, если есть компонент.
- Не ставьте больше одной основной кнопки на экран.
- Не задавайте фиксированный белый фон: в тёмной теме текст станет нечитаемым.
- Не используйте логотип и фирменные названия Telegram в интерфейсе своего приложения.

Только файл: сохраните его как DESIGN.md в корне проекта

Похожие