Дизайн-системыTelegram Mini AppsСветлыйТёмныйМинимализмБесплатно
Telegram UI — дизайн-система для Telegram Mini Apps на React
Конспект открытой библиотеки Telegram UI: цвета из themeParams, системный шрифт, секции и ячейки как в Telegram.
Промпт
Подключи к моему проекту (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.
Правила для Mini Apps: безопасные зоны, нижняя навигация, главная кнопка Telegram, тема из themeParams, текст на русском.
Как пользоваться
Скопируйте промпт: файл DESIGN.md скопируется вместе с ним.
Вставьте его в Claude Code или Cursor в папке React-проекта (подойдёт шаблон Vite). Агент сохранит файл, поставит пакет и соберёт экран-витрину из официальных компонентов.
Дальше просите экраны («каталог», «профиль», «оформление заказа»). Агент берёт только компоненты 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 в корне проекта