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

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

Мини — дизайн-система для Telegram Mini App

Токены повторяют темы Telegram и привязаны к --tg-theme-*. MainButton, safe area, haptic. Без библиотек, Roboto.

Мини — дизайн-система для Telegram Mini App
Промпт
Подключи к моему проекту дизайн-систему «Мини» для Telegram Mini App (автор Сергей Дургалян, MIT). Ниже файл DESIGN.md в открытом формате Google: вверху YAML-токены, ниже правила словами.

Что сделать:
1. Сохрани файл как DESIGN.md в корне проекта без изменений. Перед каждым новым экраном перечитывай его.
2. Подключи в index.html `<script src="https://telegram.org/js/telegram-web-app.js"></script>` до своего кода. В начале приложения вызови `Telegram.WebApp.ready()` и `Telegram.WebApp.expand()`.
3. Перенеси токены в CSS-переменные. Значения по умолчанию возьми из групп `light` и `dark` файла. Тема по умолчанию светлая: её значения лежат в `:root`, тёмные включаются атрибутом `data-theme="dark"`. Поверх них используй переменные Telegram: `--bg: var(--tg-theme-bg-color, <light.surface>)`, `--bg-secondary: var(--tg-theme-secondary-bg-color, <light.surface-container>)`, `--text: var(--tg-theme-text-color, <light.on-surface>)`, `--hint: var(--tg-theme-hint-color, <light.on-surface-variant>)`, `--subtitle: var(--tg-theme-subtitle-text-color, <light.on-surface-variant>)`, `--link: var(--tg-theme-link-color, <light.link>)`, `--button: var(--tg-theme-button-color, <primary>)`, `--button-text: var(--tg-theme-button-text-color, <on-primary>)`, `--section-bg: var(--tg-theme-section-bg-color, <light.surface>)`, `--section-separator: var(--tg-theme-section-separator-color, <light.outline>)`, `--header-bg: var(--tg-theme-header-bg-color, <light.surface>)`, `--bottom-bar-bg: var(--tg-theme-bottom-bar-bg-color, <light.surface>)`, `--danger: var(--tg-theme-destructive-text-color, <light.error-text>)`. Фон страницы `--bg-secondary`, секции и ячейки `--section-bg`, шапка `--header-bg` (запасное значение совпадает с `--bg`). Для тёмной темы запасные значения: `--bg` и `--section-bg` равны `dark.surface`, `--bg-secondary` равен `dark.surface-container`, `--hint` и `--subtitle` равны `dark.on-surface-variant`, `--link` равен `dark.link`, `--danger` равен `dark.error`, `--section-separator` равен `dark.outline`. Если нужных `--tg-theme-*` нет (старый клиент), работают значения по умолчанию. Если `Telegram.WebApp` нет или `initData` пуст (обычный браузер), нарисуй вместо MainButton фиксированную полосу-заглушку внизу экрана: цвет `--button`, текст `--button-text`, высота 50 px. Внутри Telegram эту полосу не показывай. Тёмные значения по умолчанию включай по `Telegram.WebApp.colorScheme === 'dark'`, ставя атрибут `data-theme` на html. Подпишись на событие `themeChanged` и обновляй атрибут.
4. Главное действие экрана делай через `Telegram.WebApp.MainButton` (setText, show, onClick), а не своей кнопкой внизу. Возврат назад — через `Telegram.WebApp.BackButton`. Свои кнопки используй только для второстепенных действий внутри экрана.
5. Учитывай безопасные зоны: внешние отступы `padding-top: max(var(--tg-safe-area-inset-top, 0px) + var(--tg-content-safe-area-inset-top, 0px), 12px)` и такие же для низа и боков. Для высоты используй `var(--tg-viewport-stable-height, 100vh)`, а не `100vh`.
6. Тактильный отклик: `Telegram.WebApp.HapticFeedback.impactOccurred('light')` при нажатии на карточки и чипсы, `notificationOccurred('success' | 'error')` после результата, `selectionChanged()` при смене сегмента. Всё в `try/catch`, в браузере объекта нет.
7. Собери страницу-витрину `/design-system`: палитра, шрифты, компоненты из раздела Components в обеих темах. Проверь, что ничего не ломается без Telegram.WebApp.

Тексты интерфейса на русском, на «вы», как в разделе Voice & Content Strategy. Новых цветов и размеров не придумывай: если чего-то не хватает, сначала предложи дополнение в DESIGN.md.

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

Дизайн-система для мини-приложения внутри Telegram: магазин, запись, трекер, кабинет бота. Она ничего не навязывает от себя. Токены по умолчанию повторяют стандартные светлую и тёмную темы Telegram, а в промпте описано, как привязать их к переменным --tg-theme-*, которые клиент выдаёт мини-приложению. Пользователь сменил тему в Telegram, и ваш экран перекрасился сам.

Всё лежит в одном файле DESIGN.md (открытый формат Google): вверху токены, ниже правила словами. Сторонние UI-библиотеки не нужны, хватает CSS и пары строк JavaScript. Если приложение выглядит чужеродно внутри чата, обычно причина в том, что цвета и кнопки нарисованы «по-своему». Эта система устроена наоборот.

Что внутри

  • Палитра: акцент #2481CC (синий Telegram), две темы по умолчанию совпадают со стандартными светлой и тёмной темами клиента (светлая лежит в :root, тёмная включается атрибутом data-theme="dark"). Вместо них подставляются реальные цвета пользователя из themeParams. Запасной белый текст на #2481CC даёт 4.1:1: в Telegram цвета берутся из клиента, а свои значения нужны для браузера и старых клиентов.
  • Шрифт Roboto. В самом Telegram используется системный шрифт платформы, поэтому в стек надо добавить system-ui запасным.
  • Соответствие токенов переменным --tg-theme-*: фон, вторичный фон, текст, подсказка, подзаголовок, ссылка, кнопка, текст кнопки, фон секции, разделитель секции, шапка, нижняя панель, цвет опасного действия.
  • Правила нативных элементов: MainButton и BackButton вместо своих кнопок, безопасные зоны, тактильный отклик, высота окна.
  • Компоненты: секции-списки в стиле настроек, ячейки, поля, чипсы, карточки, нижний лист, тост, пустое состояние.

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

  1. Скопируйте промпт: файл DESIGN.md копируется вместе с ним.
  2. Вставьте в Claude Code или Cursor в папке проекта. Агент сохранит файл, подключит telegram-web-app.js и свяжет токены с темой Telegram.
  3. Открывайте приложение через бота и проверяйте обе темы: в Telegram их переключают в настройках оформления.

Для быстрой проверки без телефона используйте веб-версию Telegram и настольный клиент. В обычном браузере объекта Telegram.WebApp нет, и агент должен оставить рабочие значения токенов по умолчанию.

Как поменять под себя

  • Свой акцент: в Telegram акцентом управляет пользователь через --tg-theme-button-color. Свой цвет задайте только если бренд важнее нативности, и тогда проверьте контраст белого текста на нём.
  • Свой шрифт: поменяйте fontFamily во всех уровнях. Для мини-приложения чаще лучше оставить системный.
  • Только светлая тема: попросите агента игнорировать colorScheme и всегда брать группу light. Так делать не рекомендуем, пользователи ночью это заметят.
DESIGN.md
---
version: alpha
name: Мини
description: Дизайн-система для Telegram Mini App. Токены повторяют темы Telegram и привязываются к переменным --tg-theme-*, без сторонних библиотек.
colors:
  primary: "#2481CC"
  on-primary: "#FFFFFF"
  secondary: "#5AA9E6"
  tertiary: "#F5A623"
  success: "#2E9E4F"
  error: "#D14E4E"
  light:
    surface: "#FFFFFF"
    surface-container: "#EFEFF3"
    on-surface: "#0B0B0F"
    on-surface-variant: "#707579"
    outline: "#DADCE0"
    link: "#1D6FB8"
    error-text: "#C23B3B"
  dark:
    error: "#FF7B7B"
    surface: "#17212B"
    surface-container: "#232E3C"
    on-surface: "#F5F5F5"
    on-surface-variant: "#8396AA"
    outline: "#2F3B4A"
    link: "#5AA9E6"
typography:
  headline-lg:
    fontFamily: Roboto
    fontSize: 28px
    fontWeight: 700
    lineHeight: 1.15
  headline-md:
    fontFamily: Roboto
    fontSize: 20px
    fontWeight: 600
    lineHeight: 1.25
  title-md:
    fontFamily: Roboto
    fontSize: 17px
    fontWeight: 500
    lineHeight: 1.35
  body-md:
    fontFamily: Roboto
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.45
  body-sm:
    fontFamily: Roboto
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.4
  label-md:
    fontFamily: Roboto
    fontSize: 14px
    fontWeight: 500
    lineHeight: 1.2
rounded:
  sm: 8px
  md: 10px
  lg: 14px
  full: 9999px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
components:
  main-button:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    height: 50px
  section:
    backgroundColor: "{colors.light.surface}"
    rounded: "{rounded.lg}"
    padding: 0 16px
  cell:
    backgroundColor: "{colors.light.surface}"
    height: 52px
    padding: 0 16px
  input:
    backgroundColor: "{colors.light.surface-container}"
    textColor: "{colors.light.on-surface}"
    rounded: "{rounded.md}"
    height: 44px
---

## Overview

Мини живёт внутри чужого интерфейса, и его главная задача не выделяться. Пользователь открыл мини-приложение из чата и должен чувствовать, что это часть Telegram: те же цвета, та же логика кнопок, та же тема. Поэтому система описывает не «свой стиль», а правила встраивания. Токены в файле это запасные значения. В работающем приложении цвета берутся из темы клиента, а токены нужны, чтобы экран выглядел прилично в обычном браузере и на старых клиентах.

Ощущение: спокойный список настроек, а не витрина. Мало декора, много воздуха, крупные зоны нажатия.

## Colors

Токены сопоставляются переменным Telegram. Везде, где в коде нужен цвет, пишите `var(--tg-theme-*, запасное значение из токена)`.

- **Фон страницы** (`surface-container`): `--tg-theme-secondary-bg-color`. **Фон шапки и нижней панели** (`surface`): `--tg-theme-bg-color`, `--tg-theme-header-bg-color`, `--tg-theme-bottom-bar-bg-color`.
- **Фон секции-списка и ячеек** (`surface`): `--tg-theme-section-bg-color`, подпись над секцией: `--tg-theme-section-header-text-color`, разделитель: `--tg-theme-section-separator-color`.
- **Текст** (`on-surface`): `--tg-theme-text-color`. **Подсказки и подписи** (`on-surface-variant`): `--tg-theme-hint-color`. Подзаголовок ячейки: `--tg-theme-subtitle-text-color`.
- **Primary (#2481CC):** главная кнопка и активные элементы. В работе берётся из `--tg-theme-button-color`, текст на ней из `--tg-theme-button-text-color`. Акцентный текст и ссылки: `--tg-theme-accent-text-color` и `--tg-theme-link-color`. Запасной белый на #2481CC даёт 4.1:1, как текст на белом тоже 4.1:1, поэтому запасной цвет ссылки отдельный: `light.link` (#1D6FB8, 5.23:1 к белому, 4.56:1 к подложке) и `dark.link` (#5AA9E6, 6.40:1 к `dark.surface`, 5.40:1 к `dark.surface-container`).
- **Error:** опасные действия и ошибки, `--tg-theme-destructive-text-color`. Запасные значения для текста: `light.error-text` (#C23B3B, 5.27:1 к белому) и `dark.error` (#FF7B7B, 6.50:1 к `dark.surface`).
- **Success и tertiary:** только статусы («оплачено», «осталось мало»). Своих брендовых цветов не вводите.
- **Шапка и нижняя панель:** `--tg-theme-header-bg-color`, `--tg-theme-bottom-bar-bg-color`. Цвет шапки приложения задавайте через `Telegram.WebApp.setHeaderColor`, чтобы он совпал с фоном экрана.
- Тёмную тему включайте по `Telegram.WebApp.colorScheme`, обновляйте по событию `themeChanged`.

## Typography

Roboto в токенах, но в самом Telegram используется системный шрифт платформы, поэтому стек такой: `Roboto, system-ui, -apple-system, 'Segoe UI', sans-serif`. Размеры задаются в пикселях и не зависят от масштаба. Основной текст 16 px, подписи 14 px, заголовок экрана 28 px. Не больше трёх размеров на экране, жирность 400, 500 и 700. Цифры в таблицах и ценах набирайте с `font-variant-numeric: tabular-nums`.

## Layout

Один столбец на всю ширину экрана, поля 16 px. Отступы кратны 4 px. Секции-группы отделяются 24 px по вертикали. Минимальная зона нажатия 44 на 44 px.

Безопасные зоны. В полноэкранном режиме и на телефонах с вырезом контент не должен прятаться под системными элементами. Отступы сверху считаются как `var(--tg-safe-area-inset-top, 0px) + var(--tg-content-safe-area-inset-top, 0px)`, то же для `bottom`, `left` и `right`. Высота окна: `var(--tg-viewport-stable-height, 100vh)`. Не используйте `100vh` напрямую, при выезде клавиатуры и нижнего листа он врёт. Вызывайте `Telegram.WebApp.expand()` при старте, чтобы окно открылось на всю высоту.

## Elevation & Depth

Глубина тоном, без теней: подложка `surface-container`, поверх неё секции цвета `surface`. Разделители 1 px `outline` (или `--tg-theme-section-separator-color`). Тень допустима только у нижнего листа: `0 -8px 32px rgba(0,0,0,0.18)`.

## Shapes

Секции и карточки скруглены на 14 px, поля и кнопки на 10 px, мелкие элементы на 8 px. Чипсы и аватары круглые. Внутри секции у ячеек скруглений нет, у первой и последней скругляются внешние углы секции.

## Motion

Переходы короткие, 150 мс, только `opacity` и `transform`. Экраны не выезжают сами: переходами между экранами управляет BackButton. При `prefers-reduced-motion` анимации отключаются. Тактильный отклик: `impactOccurred('light')` при нажатии на карточки и чипсы, `selectionChanged()` при смене сегмента, `notificationOccurred('success')` после сохранения и `'error'` при ошибке. Вызовы оборачивайте в `try/catch`.

## Voice & Content Strategy

- Тон: дружелюбный и короткий, как сообщение в чате. На «вы», без восклицательных знаков.
- Кнопки называют результат: «Оформить заказ», «Записаться», «Сохранить». Текст MainButton не длиннее 20 символов, поэтому с суммой: «Оплатить 1 240 ₽».
- Ошибки человеческие и с выходом: «Не удалось отправить. Проверьте соединение и нажмите ещё раз».
- Пустые состояния: одна строка о том, что здесь будет, и одно действие.
- Деньги: «1 990 ₽», даты «24 ноября», время «14:30».

## Components

- **MainButton:** главное действие экрана. Только `Telegram.WebApp.MainButton`: setText, show, hide, `showProgress` на время запроса, onClick. Своя залитая кнопка внизу не рисуется, кроме полосы-заглушки в обычном браузере без Telegram. Вторую кнопку делайте через SecondaryButton, если клиент её поддерживает.
- **BackButton:** показывается на всех экранах, кроме главного. Свой «крестик» или стрелку в шапке не рисуйте.
- **Секция-список:** фон section-bg, скругление lg, подпись над секцией цветом hint, ячейки высотой 52 px с разделителем outline.
- **Ячейка:** слева иконка 28 px, по центру название (title-md) и подзаголовок (body-sm, hint), справа значение или стрелка. Нажатая ячейка темнеет на 6%.
- **Поле ввода:** фон surface-container, высота 44 px, скругление md, подпись над полем. Фокус: граница 2 px цвета primary. При фокусе прокрутите поле в видимую область, клавиатура уменьшает окно.
- **Чипсы и сегменты:** высота 32 px, выбранный залит primary, остальные на surface-container. Смена сопровождается `selectionChanged()`.
- **Карточка товара или услуги:** фон section-bg, скругление lg, картинка сверху 4 к 3, название, цена tabular, под ней счётчик количества.
- **Нижний лист:** выезжает снизу, скругление 14 px сверху, поверх затемнение 40%. Закрывается свайпом вниз и по BackButton.
- **Тост:** сверху под системной зоной, 3 секунды, фон on-surface, текст surface.
- **Пустое состояние:** иконка, одна строка, одно действие.

## Do's and Don'ts

- Делайте главное действие через MainButton, возврат через BackButton.
- Берите цвета из `--tg-theme-*`, токены оставляйте запасными значениями.
- Закладывайте безопасные зоны и высоту через `--tg-viewport-stable-height`.
- Проверяйте обе темы и сценарий без Telegram.WebApp.
- Не рисуйте собственные кнопки «Назад» и «Закрыть».
- Не задавайте жёсткие цвета фона и текста: они ломают тёмную тему.
- Не используйте `100vh` и не прячьте поля ввода за клавиатурой.
- Не добавляйте тяжёлые анимации: мини-приложение открывается в чате и должно быть лёгким.

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

Похожие