VKUI — дизайн-система для мини-приложений ВКонтакте на React
Конспект открытой библиотеки VKUI: цвета и размеры из vkui-tokens, темы iOS и Android, готовые компоненты для VK Mini Apps.
Промпт
Подключи к моему проекту (React) официальную библиотеку VKUI: пакет @vkontakte/vkui (автор VK, лицензия MIT, документация: vkcom.github.io/VKUI, токены: @vkontakte/vkui-tokens). Ниже мой конспект DESIGN.md в открытом формате Google: токены и правила интерфейса.
Что сделать:
1. Сохрани файл как DESIGN.md в корне проекта без изменений. Перед каждым новым экраном перечитывай его.
2. Установи пакет: npm i @vkontakte/vkui. Он требует React 18 или 19. Версию уточни в документации.
3. В точке входа импортируй стили: import '@vkontakte/vkui/dist/vkui.css'. Оберни приложение в ConfigProvider, затем AdaptivityProvider, затем AppRoot (все из @vkontakte/vkui). Платформу (android, ios, vkcom) и цветовую схему определяют автоматически, для проверки передавай platform и colorScheme у ConfigProvider. Если приложение работает внутри VK, подключи @vkontakte/vk-bridge и @vkontakte/vk-mini-apps-router по документации VK Mini Apps.
4. Собери экран-витрину: SplitLayout, SplitCol, View, Panel с PanelHeader, Group с Header, список из SimpleCell, форма из FormItem и Input, кнопки Button трёх видов (primary, secondary, tertiary), Tabbar снизу, Snackbar. Проверь светлую и тёмную схему и платформы android и ios.
5. Дальше собирай экраны только из компонентов VKUI и токенов из DESIGN.md. Цвета бери из CSS-переменных --vkui--*, не пиши hex в коде. Если нужного компонента нет, сначала предложи вариант, потом используй.
Тексты интерфейса на русском, на «вы», без восклицательных знаков.
Файл DESIGN.md скопируется вместе с промптом
Конспект открытой библиотеки VKUI для ИИ-агента. VKUI это адаптивные React-компоненты, основанные на дизайн-системе VK: панели, группы, ячейки, кнопки, формы. Интерфейс выглядит как приложения ВКонтакте: серый фон страницы, белые группы, синий акцент #2688EB. Подходит для мини-приложений VK (VK Mini Apps) и просто для веб-приложений.
Это не официальный продукт VK и не замена документации. Токены и правила ниже выписаны из пакета @vkontakte/vkui-tokens и документации, чтобы агент собирал экраны из готовых компонентов. Пакет @vkontakte/vkui распространяется по лицензии MIT, вы ставите его из npm, а не копируете из конспекта.
Всё лежит в одном файле DESIGN.md (открытый формат Google): вверху токены, ниже правила словами. Агент читает файл и собирает каждый экран в одном стиле, не придумывая цвета заново.
Что внутри
Цвета тем: светлая (страница #EBEDF0, группы #FFFFFF) и тёмная (страница #0A0A0A, группы #19191A). Акцент #2688EB, ошибка #E64646, успех #4BB34B.
Шрифт: в приложении системный (-apple-system, system-ui, Roboto). В конспекте и превью Roboto как ближайший шрифт Google Fonts с кириллицей.
Правила для мини-приложений: безопасные зоны, нижняя навигация, адаптивность, русский текст.
Как пользоваться
Скопируйте промпт: файл DESIGN.md скопируется вместе с ним.
Вставьте его в Claude Code или Cursor в папке React-проекта. Агент сохранит файл, поставит @vkontakte/vkui и соберёт экран-витрину.
Дальше просите экраны («каталог услуг», «профиль», «форма заявки»). Агент берёт только компоненты VKUI.
Для проверки в самой сети VK подключите мини-приложение по документации VK Mini Apps. Для разработки хватит браузера: платформа определяется автоматически.
Откуда токены
Значения сверены с пакетом @vkontakte/vkui-tokens версии 4.102.0 (темы vkBase, vkBaseDark, vkIOS, vkIOSDark, vkCom) и пакетом @vkontakte/vkui версии 8.5.1:
Что не удалось сверить точно: цвета светлой и тёмной тем vkBase и vkIOS совпадают, различия платформ в основном в скруглениях (iOS 10 px вместо 8 px) и поведении компонентов; в конспекте принята база vkBase. Роли secondary в токенах нет, взят цвет вторичного текста colorTextSecondary. В тёмной теме библиотека использует белый «тематический» акцент для залитых кнопок: это описано в Colors.
DESIGN.md
---
version: alpha
name: VKUI
description: Конспект открытой библиотеки VKUI для React. Серый фон страницы, белые группы, синий акцент VK, системный шрифт, темы Android, iOS и десктоп.
colors:
primary: "#2688EB"
on-primary: "#FFFFFF"
secondary: "#818C99"
success: "#4BB34B"
error: "#E64646"
light:
surface: "#FFFFFF"
surface-container: "#F2F3F5"
on-surface: "#000000"
on-surface-variant: "#6D7885"
outline: "#D7D8D9"
background: "#EBEDF0"
accent: "#2688EB"
link: "#2D81E0"
dark:
surface: "#19191A"
surface-container: "#232324"
on-surface: "#E1E3E6"
on-surface-variant: "#969A9F"
outline: "#363738"
background: "#0A0A0A"
accent: "#529EF4"
primary: "#FFFFFF"
on-primary: "#000000"
error: "#FF5C5C"
typography:
headline-lg:
fontFamily: Roboto
fontSize: 24px
fontWeight: 600
lineHeight: 1.17
headline-md:
fontFamily: Roboto
fontSize: 20px
fontWeight: 500
lineHeight: 1.2
title-sm:
fontFamily: Roboto
fontSize: 17px
fontWeight: 600
lineHeight: 1.3
body-md:
fontFamily: Roboto
fontSize: 16px
fontWeight: 400
lineHeight: 1.25
label-md:
fontFamily: Roboto
fontSize: 16px
fontWeight: 500
lineHeight: 1.25
subhead:
fontFamily: Roboto
fontSize: 14px
fontWeight: 400
lineHeight: 1.3
footnote:
fontFamily: Roboto
fontSize: 13px
fontWeight: 400
lineHeight: 1.25
caption:
fontFamily: Roboto
fontSize: 12px
fontWeight: 400
lineHeight: 1.2
rounded:
sm: 4px
md: 8px
lg: 12px
full: 48px
promo: 20px
spacing:
xs: 4px
sm: 8px
md: 16px
lg: 24px
xl: 32px
xxl: 40px
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "{colors.on-primary}"
typography: "{typography.label-md}"
rounded: "{rounded.md}"
height: 44px
input:
backgroundColor: "{colors.light.surface-container}"
textColor: "{colors.light.on-surface}"
rounded: "{rounded.md}"
height: 44px
group:
backgroundColor: "{colors.light.surface}"
rounded: "{rounded.lg}"
padding: 12px 0
---
## Overview
VKUI это интерфейс в духе ВКонтакте: серый фон страницы, на нём белые блоки (группы), внутри списки ячеек, один синий акцент. Тон спокойный и рабочий, много воздуха, без декоративных эффектов. Библиотека адаптивная: на телефоне панель на весь экран и нижняя навигация, на широком экране колонки и боковое меню. Платформа задаёт детали: `ios` (чуть большие скругления, поведение как в iOS), `android` (базовая) и `vkcom` (десктопный VK с отдельным шрифтовым стеком).
## Colors
Цвета в VKUI это семантические токены (`colorBackground`, `colorTextPrimary`, `colorBackgroundAccent` и так далее), которые в CSS превращаются в переменные `--vkui--*` и переключаются вместе с темой. В коде используйте их, а не hex. Роли в нашем файле:
- **Primary (#2688EB), синий VK:** залитые кнопки, активные вкладки, переключатели. Белый текст на нём даёт контраст около 3.5:1. Это значение библиотеки, оно сохранено.
- **Dark primary:** в тёмной теме библиотека не заливает кнопки синим: токены `colorBackgroundAccentThemed` и `colorTextContrastThemed` дают белую кнопку с чёрным текстом. Поэтому `dark.primary` белый, `dark.on-primary` чёрный. Синий `#529EF4` (`dark.accent`) остаётся для ссылок и акцентного текста.
- **Secondary (#818C99):** вторичный текст и иконки (`colorTextSecondary`). Роль в библиотеке называется иначе, это наше сопоставление.
- **Success (#4BB34B) и Error (#E64646):** статусы и ошибки. В тёмной теме ошибка `#FF5C5C`.
- **Светлая тема:** страница `light.background` (#EBEDF0), группы и панели `surface` (#FFFFFF), поля ввода `surface-container` (#F2F3F5), основной текст `#000000`, подзаголовки `#6D7885`, разделители `#D7D8D9`, ссылки `#2D81E0`.
- **Тёмная тема:** страница `dark.background` (#0A0A0A), группы `surface` (#19191A), поля `#232324`, текст `#E1E3E6`, подзаголовки `#969A9F`, разделители `#363738`.
- Градиентов нет. Тени только у всплывающих слоёв.
## Typography
В приложении будет системный шрифт: `-apple-system, system-ui, "Helvetica Neue", Roboto, sans-serif` (на десктопном VK расширенный стек с Noto). В конспекте и превью Roboto: ближайший шрифт Google Fonts с кириллицей. Не подключайте свои шрифты.
Шкала библиотеки (пиксели и высота строки): `Title1` 24/28 вес 600, `Title2` 20/24 вес 500, `Title3` 17/22 вес 600, `Headline1` 16/20 вес 500, `Headline2` 15/20 вес 500, `Text` 16/20 вес 400, `Subhead` 14/18, `Footnote` 13/16, `Caption1` 12/14, `Caption2` 11/14. В компактном режиме (мышь, широкий экран) размеры на 1 px меньше. В коде используйте компоненты `Title`, `Headline`, `Text`, `Subhead`, `Footnote`, `Caption`.
## Layout
Структура: `AppRoot`, внутри `SplitLayout`, колонки `SplitCol`, внутри `View` и `Panel`. Панель с заголовком `PanelHeader`, содержимое делится на `Group` (белый блок с заголовком `Header`). Отступы по шкале библиотеки: 4, 8, 12, 16, 24, 32, 40 px. Внутренние поля группы 12–16 px, высота поля ввода 44 px (36 px в компактном режиме). На телефоне нижняя навигация `Tabbar` с учётом безопасной зоны `env(safe-area-inset-bottom)`, на широком экране боковая колонка и контент до 680–880 px (размеры всплывающих окон 430, 680, 880 px).
## Elevation & Depth
Глубина через цвет: серая страница, белые группы. Границы тонкие, 1 px или 0.5 px (разделитель `colorSeparatorPrimary`). Тени есть только у всплывающих слоёв: меню, модальных страниц и `Snackbar`. Затемнение под модальным окном: `rgba(0,0,0,0.4)`.
## Shapes
4 px у чекбоксов, 8 px у кнопок, полей и карточек (на iOS 10 px), 12 px у бумажных блоков (`Paper`, модальные страницы), 20 px у промо-блоков, 48 px у круглых элементов (токен `sizeBorderRadiusRounded`). Аватары круглые.
## Motion
Короткие стандартные переходы: наведение и нажатие меняют оттенок цвета (у каждого токена есть состояния `hover` и `active`), панели переключаются по горизонтали, модальные страницы выезжают снизу. Не добавляйте свои анимации. Уважайте настройку пользователя «уменьшить движение».
## Voice & Content Strategy
- Тон: ровный, дружелюбный, на «вы». Без восклицательных знаков.
- Заголовки групп короткие: «Заказы», «Настройки», «О сервисе».
- Кнопки это глагол: «Оформить», «Сохранить», «Отправить заявку». Не «ОК».
- Подпись ячейки одной строкой, пояснение в `subtitle` или `after`.
- Пустое состояние: заголовок, одно предложение и кнопка (компонент `Placeholder`).
- Ошибки по делу: «Не удалось сохранить. Проверьте соединение и повторите».
- Числа «1 990 ₽», время «14:30», даты «24 ноября».
## Components
- **ConfigProvider, AdaptivityProvider, AppRoot:** обязательная обёртка. ConfigProvider задаёт платформу и цветовую схему, AdaptivityProvider даёт адаптивность, AppRoot подключает базовые стили и порталы.
- **SplitLayout, SplitCol, View, Panel, PanelHeader:** каркас экрана и навигация. Один экран это одна `Panel`.
- **Group, Header, Div:** белый блок с заголовком и внутренними отступами.
- **SimpleCell, Cell, RichCell:** строки списков. `before` для иконки или аватара, `after` для значения, `subtitle` для пояснения.
- **Button:** режимы `primary`, `secondary`, `tertiary`, `outline`, размеры `s`, `m`, `l`. Одна primary-кнопка на экран.
- **FormItem, Input, Textarea, Select, Checkbox, Radio, Switch:** поля формы. Подпись в `top`, ошибка через `status="error"` и `bottom`.
- **Tabbar, TabbarItem:** нижняя навигация из 3–5 пунктов, активный пункт цвета акцента. На широком экране заменяется боковой колонкой.
- **ModalRoot и ModalPage, Snackbar, Alert:** диалоги, шторки и всплывающие сообщения.
- **Placeholder, Banner, Avatar, Counter, Badge:** пустые состояния, баннеры, аватары и счётчики.
## Do's and Don'ts
- Оборачивайте приложение в ConfigProvider, AdaptivityProvider и AppRoot, иначе стили и адаптивность не заработают.
- Собирайте экран из Panel, Group и Cell: это узнаваемый вид VK.
- Берите цвета из токенов и CSS-переменных, не из hex в коде.
- Проверяйте обе цветовые схемы и платформы android и ios.
- Не ставьте больше одной primary-кнопки на экран.
- Не рисуйте свои кнопки и поля, если есть компонент.
- Не задавайте белый фон вручную: в тёмной схеме текст станет нечитаемым.
- Не используйте логотип и фирменные названия VK в интерфейсе своего приложения.
Только файл: сохраните его как DESIGN.md в корне проекта