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

Дизайн-системыВебМобильные приложенияСветлыйТёмныйМинимализмБесплатно

VKUI — дизайн-система для мини-приложений ВКонтакте на React

Конспект открытой библиотеки VKUI: цвета и размеры из vkui-tokens, темы iOS и Android, готовые компоненты для VK Mini Apps.

VKUI — дизайн-система для мини-приложений ВКонтакте на React
Промпт
Подключи к моему проекту (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 с кириллицей.
  • Типографика библиотеки: Title1 24 px, Title2 20 px, Text 16 px, Headline 16 px, Subhead 14 px, Caption 12 px.
  • Скругления 4 / 8 / 12 px и круглые элементы, шкала отступов 4, 8, 12, 16, 24 px.
  • Темы платформ: vkBase (Android), vkIOS, vkCom (десктопный VK).
  • Компоненты: AppRoot, SplitLayout, Panel, Group, Cell, Button, FormItem, Input, Tabbar, Snackbar, ModalPage.
  • Правила для мини-приложений: безопасные зоны, нижняя навигация, адаптивность, русский текст.

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

  1. Скопируйте промпт: файл DESIGN.md скопируется вместе с ним.
  2. Вставьте его в Claude Code или Cursor в папке React-проекта. Агент сохранит файл, поставит @vkontakte/vkui и соберёт экран-витрину.
  3. Дальше просите экраны («каталог услуг», «профиль», «форма заявки»). Агент берёт только компоненты 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 в корне проекта

Похожие