{"id":15107879,"url":"https://github.com/vkcom/vkui-tokens","last_synced_at":"2026-02-01T10:04:55.416Z","repository":{"id":37461369,"uuid":"375370631","full_name":"VKCOM/vkui-tokens","owner":"VKCOM","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-12T15:03:23.000Z","size":36992,"stargazers_count":40,"open_issues_count":30,"forks_count":67,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-14T04:41:27.782Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VKCOM.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.OLD.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-06-09T13:45:56.000Z","updated_at":"2025-04-16T13:07:28.000Z","dependencies_parsed_at":"2023-12-18T15:08:32.146Z","dependency_job_id":"5da5fa6d-760a-4d21-918c-b03d44002eda","html_url":"https://github.com/VKCOM/vkui-tokens","commit_stats":null,"previous_names":[],"tags_count":117,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VKCOM%2Fvkui-tokens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VKCOM%2Fvkui-tokens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VKCOM%2Fvkui-tokens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VKCOM%2Fvkui-tokens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VKCOM","download_url":"https://codeload.github.com/VKCOM/vkui-tokens/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535826,"owners_count":22087398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-25T21:42:22.281Z","updated_at":"2026-01-28T14:05:18.675Z","avatar_url":"https://github.com/VKCOM.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"assets/vkui_logo.png\" alt=\"vkui logo\" height=\"52\"/\u003e\n\u003cimg src=\"assets/logo.svg\" alt=\"vkui logo\" height=\"52\"/\u003e\n\n[![Tests](https://github.com/VKCOM/vkui-tokens/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/VKCOM/vkui-tokens/actions/workflows/test.yml)\n[![Npm](https://img.shields.io/npm/v/@vkontakte/vkui-tokens)](https://www.npmjs.com/package/@vkontakte/vkui-tokens)\n[![GitHub Repo stars](https://img.shields.io/github/stars/VKCOM/vkui-tokens?label=GitHub%20Repo%20Stars\u0026style=social)](https://github.com/VKCOM/vkui-tokens)\n\n**[Интерактивная документация](https://vkcom.github.io/vkui-tokens/)**\n\nЭтот репозиторий содержит токены единой дизайн-системы VKUI и их значения для тем оформления различных проектов.\n\nТемы собираются в следующие форматы: `css`, `scss`, `less`, `pcss`, `styl`, `js`, `json`.\n\nДля описания интерфейсов тем и значений переменных используется TypeScript.\n\n# Содержание\n\n- [Использование](#использование)\n  - [Использование CSS-переменных темы напрямую из пакета](#использование-css-переменных-темы-напрямую-из-пакета)\n    - [Подключение темы на страницу](#подключение-темы-на-страницу)\n    - [Использование переменных в вёрстке](#использование-переменных-в-вёрстке)\n  - [Использование базовой темы напрямую из пакета](#использование-базовой-темы-напрямую-из-пакета)\n  - [Создание новой темы для вашего проекта](docs/articles/new-theme/INDEX.md)\n- [Инструменты](#инструменты)\n  - [Локальная сборка своих тем инструментами библиотеки](#локальная-сборка-своих-тем-инструментами-библиотеки)\n    - [Наследование от существующей темы](#наследование-от-существующей-темы)\n- [Roadmap](#roadmap)\n- [Полезные ссылки](#полезные-ссылки)\n- [Информация для внесения изменений](CONTRIBUTING.md)\n- [Changelog (архивная версия)](CHANGELOG.OLD.md)\n\nАктуальный changelog находится на странице\n[релизов в GitHub](https://github.com/VKCOM/vkui-tokens/releases)!\n\n# Использование\n\nУстанавливаем npm-пакет `@vkontakte/vkui-tokens`:\n\n```bash\nnpm i --save @vkontakte/vkui-tokens@latest\n```\n\n## Использование CSS-переменных темы напрямую из пакета\n\n### Подключение темы на страницу\n\nВ любом CSS-файле подключаем файл темы со значениями переменных:\n\n```css\n@import '@vkontakte/vkui-tokens/themes/vkBase/cssVars/declarations/index.css';\n```\n\n### Использование переменных в вёрстке\n\n#### Использование в CSS\n\n```postcss\n.class:hover {\n  background-color: var(--vkui--color_background--hover);\n}\n```\n\n#### Использование CSS-переменных через объект в JavaScript (TypeScript)\n\n```typescript\nimport baseTheme from '@vkontakte/vkui-tokens/themes/vkBase/cssVars/theme';\n\n// Собствено имя CSS-переменной (название токена)\nconsole.log(baseTheme.colorBackground.hover.name); // --vkui--color_background--hover;\n// Сниппет для использования CSS-переменной\nconsole.log(baseTheme.colorBackground.hover.value); // var(--vkui--color_background--hover, #F5F5F7)\n\n// Динамически (с учётом возможных переопределений)\n// узнаём, чему равно значение переменной внутри myElement:\ngetComputedStyle(myElement).getPropertyValue(baseTheme.colorBackground.hover.name);\n```\n\n#### Принудительное использование токенов определённого размера\n\nЧтобы принудительно включить тот или иной вид темы у конкретного\nподдерева элементов, нужно воспользоваться классами\n`.vkui--force-${auto | regular | compact | large | largeX ...}`.\nСмотри [демо](demo/example-adaptive-css-vars-theme.html) работы\nадаптивных переменных и спец. классов.\n\nТакже можно просто использовать переменную конкретного брейкпоинта\n(ex. --vkui--size*field_height--\\*\\*\\_compact*\\*\\*), они все тоже\nпопадают в `:root`)\n\n## Использование базовой темы напрямую из пакета\n\n### js/ts/json\n\nИмпортируем необходимую тему в файле и используем:\n\n```ts\nimport baseTheme from '@vkontakte/vkui-tokens/themes/vkBase';\n\n// do whatever you want with baseTheme\n```\n\n### Используем в scss/styl/less root темы из пакета\n\nИмпортируем файл с необходимой темой и используем переменные от туда (снизу синтаксис SCSS)\n\n```scss\n@import '~@vkontakte/vkui-tokens/themes/vkBase/index';\n\n.myAwesomeClass {\n  background-color: $color-bg;\n}\n\n.myAwesomeClass:hover {\n  background-color: $color-bg--hover;\n}\n```\n\n### Используем pcss формат темы из пакета\n\n1. Заходим в файл, где хотим использовать тему, и импортируем её:\n\n   ```css\n   @import '@vkontakte/vkui-tokens/themes/vkBase';\n   ```\n\n2. Заходим в файл темы, смотрим какие там есть переменные и используем их, например:\n\n   ```css\n   width: var(--size-content-block-width);\n   ```\n\n3. Просто так ничего не заработает, нужно поставить postcss:\n\n   ```bash\n   npm i --save-dev postcss\n   ```\n\n   Для запуска у postcss есть командная строка, которую тоже надо установить:\n\n   ```bash\n   npm i --save-dev postcss-cli\n   ```\n\n4. Создаем конфиг postcss. Для этого создаем файл postcss.config.js (можно в любом месте проекта, но лучше в корне) и пишем в него необходимые плагины:\n\n   ```javascript\n   const postcssPresetEnv = require('postcss-preset-env');\n\n   module.exports = {\n     plugins: [\n       require('postcss-import'),\n       require('precss'),\n       require('postcss-css-variables'),\n       require('postcss-custom-media'),\n       require('postcss-media-minmax'),\n       require('postcss-extend-rule'),\n       postcssPresetEnv({\n         stage: 0,\n       }),\n       require('postcss-color-mix'),\n       require('cssnano'),\n     ],\n   };\n   ```\n\n   Возможно, вам не понадобятся все эти плагины, поэтому лучше почитать, что делает каждый из них (https://www.postcss.parts/).\n   Нужно посмотреть файл вашей темы и ваш css (scss и др.), чтобы понять, что вам необходимо.\n\n5. Устанавливаем все необходимые плагины, которые написали в конфиге, например:\n\n   ```bash\n   npm i --save-dev postcss-import\n   ```\n\n6. Настраиваем сборку postcss.\n\n   Сборка производится командой postcss через командную строку с необходимым параметрами.\n   Про них подробнее тут https://github.com/postcss/postcss-cli\n\n   Пример команды:\n\n   ```bash\n   postcss src/main.css -c ./ --dir public\n   ```\n\n   Такая команда прогонит файл src/main.css с помощью конфига из текущей папки и положит результат в папку public.\n\n# Инструменты\n\n## Локальная сборка своих тем инструментами библиотеки\n\nБиблиотека предоставляет интерфейсы и темы, от которых можно наследоваться, и набор функций, которые позволяют собрать собственную тему в нужном формате.\n\nСборка темы подразумевает раскрытие наследования, генерацию цветов состояний (hover, active), округление и \"пикселизация\" значений и т.д.\n\n## Предварительная настройка\n\nИнструменты адаптированы для запуска в `Node`-среде, и не подходят для генерации темы в рантайме (в браузерной среде).\nВам необходимо установить следующие пакеты для корректной работы скриптов генерации:\n\n```bash\nnpm i --save-dev color common-tags css.escape\n```\n\n### Наследование от существующей темы\n\nНапример, возьмем базовые темы (светлую и темную) и добавим к ним новый токен и переопределим один существующий.\nДля этого нам нужно исполнить следующий скрипт:\n\n```typescript\nimport type { ThemeDescription } from '@vkontakte/vkui-tokens/interfaces/general';\nimport type { Adaptive } from '@vkontakte/vkui-tokens/interfaces/general/tools';\nimport {\n  lightTheme as baseTheme,\n  darkTheme,\n} from '@vkontakte/vkui-tokens/themeDescriptions/base/vk.js';\nimport { expandAll } from '@vkontakte/vkui-tokens/build/expandTheme';\nimport { compileStyles } from '@vkontakte/vkui-tokens/build/compilers/styles/compileStyles';\n\ninterface MyNewAwesomeThemeDescription extends ThemeDescription {\n  myNewAwesomeToken: Adaptive\u003cnumber\u003e;\n}\n\nconst myNewAwesomeTheme: MyNewAwesomeThemeDescription = {\n  ...baseTheme,\n  // Название темы\n  themeName: 'myAwesomeTheme',\n  // Базовая часть названия темы (используется для генерации локального селектора, например: .vkui--myAwesomeTheme--light)\n  themeNameBase: 'myAwesomeTheme',\n  // Тема, от которой наследуются переменные, носит информационный характер\n  themeInheritsFrom: 'vkBase',\n  // Новый адаптивный токен\n  myNewAwesomeToken: {\n    regular: 20,\n    compact: 12,\n  },\n  colors: {\n    // Сохраняем остальные значения из темы\n    ...baseTheme.colors,\n    // Переопределяем необходимую переменную\n    colorTextAccentThemed: '#ff0000',\n  },\n};\n\nconst myNewAwesomeThemeDark: MyNewAwesomeThemeDescription = {\n  ...myNewAwesomeTheme,\n  ...darkTheme,\n  themeName: 'myAwesomeThemeDark',\n  themeNameBase: 'myAwesomeTheme',\n  themeInheritsFrom: 'vkBaseDark',\n  colors: {\n    ...darkTheme.colors,\n    colorTextAccentThemed: '#00ff00',\n  },\n};\n\n// Получаем разные типы тем на основе описания\nconst { theme, pixelifyTheme, cssVarsTheme } = expandAll(myNewAwesomeTheme);\nconst { pixelifyTheme: pixelifyThemeDark } = expandAll(myNewAwesomeThemeDark);\n\n// Для использования, например, в вебе вам подойдет компиляция \"пикселяризованной\" темы в формате '.css':\nconst cssString = compileStyles('css', pixelifyTheme);\nconst cssStringDark = compileStyles('css', pixelifyThemeDark);\n\n// Полученные CSS-строки со всеми переменными тем можно вставить в DOM или сохранить в файл\n```\n\n# Roadmap\n\n- [ ] Добавить более умную генерацию active, hover состояний цвета.\n      При генерации нужно учитывать тёмный и светлый вариант тем, а также\n      сам цвет, для которого генерируется состояние.\n      (решаем проблему, что цвет наведения, сгенерированный от синего,\n      плохо виден на большинстве мониторов).\n- [ ] Генерация цветов по заранее определённой палитре.\n- [ ] Текстовое описание семантики каждого токена.\n- [ ] Более подробная документация.\n- [ ] Сайт с примерами и описанием.\n\n# Полезные ссылки\n\n1. [Доклад](https://youtu.be/0rHgqQvl0NQ?t=1858) про дизайн-системы на фронтенде: там рассказывается, зачем нужны дизайн-токены, причём тут UI-kit и как делать темизацию.\n2. Серия видеороликов на youtube, где показано использование этой библиотеки (но со старым названием, не пугайтесь), как ядра дизайн-системы на практике: [первый](https://www.youtube.com/watch?v=RKCsrPOxYWE), [второй](https://www.youtube.com/watch?v=ZhiH4jFL-kU), [третий](https://www.youtube.com/watch?v=ZXOmmkyxrwk)\n3. Opensource библиотека компонентов (UI-kit) [VKUI](https://github.com/VKCOM/VKUI), которая использует токены.\n4. [Сайт](https://paradigm.mail.ru/) дизайн-система Paradigm, из которой выросла эта библиотека. Там можно найти дизайнерские принципы и идеи, которые стали основой этого репозитория.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvkcom%2Fvkui-tokens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvkcom%2Fvkui-tokens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvkcom%2Fvkui-tokens/lists"}