Этот репозиторий содержит токены единой дизайн-системы VKUI и их значения для тем оформления различных проектов.
Темы собираются в следующие форматы: css, scss, less, pcss, styl, js, json.
Для описания интерфейсов тем и значений переменных используется TypeScript.
- Использование
- Инструменты
- Roadmap
- Полезные ссылки
- Информация для внесения изменений
- Changelog (архивная версия)
Актуальный changelog находится на странице релизов в GitHub!
Устанавливаем npm-пакет @vkontakte/vkui-tokens:
npm i --save @vkontakte/vkui-tokens@latestВ любом CSS-файле подключаем файл темы со значениями переменных:
@import '@vkontakte/vkui-tokens/themes/vkBase/cssVars/declarations/index.css';.class:hover {
background-color: var(--vkui--color_background--hover);
}import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase/cssVars/theme';
// Собствено имя CSS-переменной (название токена)
console.log(baseTheme.colorBackground.hover.name); // --vkui--color_background--hover;
// Сниппет для использования CSS-переменной
console.log(baseTheme.colorBackground.hover.value); // var(--vkui--color_background--hover, #F5F5F7)
// Динамически (с учётом возможных переопределений)
// узнаём, чему равно значение переменной внутри myElement:
getComputedStyle(myElement).getPropertyValue(baseTheme.colorBackground.hover.name);Чтобы принудительно включить тот или иной вид темы у конкретного
поддерева элементов, нужно воспользоваться классами
.vkui--force-${auto | regular | compact | large | largeX ...}.
Смотри демо работы
адаптивных переменных и спец. классов.
Также можно просто использовать переменную конкретного брейкпоинта
(ex. --vkui--sizefield_height--**_compact**), они все тоже
попадают в :root)
Импортируем необходимую тему в файле и используем:
import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase';
// do whatever you want with baseThemeИмпортируем файл с необходимой темой и используем переменные от туда (снизу синтаксис SCSS)
@import '~@vkontakte/vkui-tokens/themes/vkBase/index';
.myAwesomeClass {
background-color: $color-bg;
}
.myAwesomeClass:hover {
background-color: $color-bg--hover;
}-
Заходим в файл, где хотим использовать тему, и импортируем её:
@import '@vkontakte/vkui-tokens/themes/vkBase';
-
Заходим в файл темы, смотрим какие там есть переменные и используем их, например:
width: var(--size-content-block-width);
-
Просто так ничего не заработает, нужно поставить postcss:
npm i --save-dev postcss
Для запуска у postcss есть командная строка, которую тоже надо установить:
npm i --save-dev postcss-cli
-
Создаем конфиг postcss. Для этого создаем файл postcss.config.js (можно в любом месте проекта, но лучше в корне) и пишем в него необходимые плагины:
const postcssPresetEnv = require('postcss-preset-env'); module.exports = { plugins: [ require('postcss-import'), require('precss'), require('postcss-css-variables'), require('postcss-custom-media'), require('postcss-media-minmax'), require('postcss-extend-rule'), postcssPresetEnv({ stage: 0, }), require('postcss-color-mix'), require('cssnano'), ], };
Возможно, вам не понадобятся все эти плагины, поэтому лучше почитать, что делает каждый из них (https://www.postcss.parts/). Нужно посмотреть файл вашей темы и ваш css (scss и др.), чтобы понять, что вам необходимо.
-
Устанавливаем все необходимые плагины, которые написали в конфиге, например:
npm i --save-dev postcss-import
-
Настраиваем сборку postcss.
Сборка производится командой postcss через командную строку с необходимым параметрами. Про них подробнее тут https://github.com/postcss/postcss-cli
Пример команды:
postcss src/main.css -c ./ --dir public
Такая команда прогонит файл src/main.css с помощью конфига из текущей папки и положит результат в папку public.
Библиотека предоставляет интерфейсы и темы, от которых можно наследоваться, и набор функций, которые позволяют собрать собственную тему в нужном формате.
Сборка темы подразумевает раскрытие наследования, генерацию цветов состояний (hover, active), округление и "пикселизация" значений и т.д.
Инструменты адаптированы для запуска в Node-среде, и не подходят для генерации темы в рантайме (в браузерной среде).
Вам необходимо установить следующие пакеты для корректной работы скриптов генерации:
npm i --save-dev color common-tags css.escapeНапример, возьмем базовые темы (светлую и темную) и добавим к ним новый токен и переопределим один существующий. Для этого нам нужно исполнить следующий скрипт:
import type { ThemeDescription } from '@vkontakte/vkui-tokens/interfaces/general';
import type { Adaptive } from '@vkontakte/vkui-tokens/interfaces/general/tools';
import {
lightTheme as baseTheme,
darkTheme,
} from '@vkontakte/vkui-tokens/themeDescriptions/base/vk.js';
import { expandAll } from '@vkontakte/vkui-tokens/build/expandTheme';
import { compileStyles } from '@vkontakte/vkui-tokens/build/compilers/styles/compileStyles';
interface MyNewAwesomeThemeDescription extends ThemeDescription {
myNewAwesomeToken: Adaptive<number>;
}
const myNewAwesomeTheme: MyNewAwesomeThemeDescription = {
...baseTheme,
// Название темы
themeName: 'myAwesomeTheme',
// Базовая часть названия темы (используется для генерации локального селектора, например: .vkui--myAwesomeTheme--light)
themeNameBase: 'myAwesomeTheme',
// Тема, от которой наследуются переменные, носит информационный характер
themeInheritsFrom: 'vkBase',
// Новый адаптивный токен
myNewAwesomeToken: {
regular: 20,
compact: 12,
},
colors: {
// Сохраняем остальные значения из темы
...baseTheme.colors,
// Переопределяем необходимую переменную
colorTextAccentThemed: '#ff0000',
},
};
const myNewAwesomeThemeDark: MyNewAwesomeThemeDescription = {
...myNewAwesomeTheme,
...darkTheme,
themeName: 'myAwesomeThemeDark',
themeNameBase: 'myAwesomeTheme',
themeInheritsFrom: 'vkBaseDark',
colors: {
...darkTheme.colors,
colorTextAccentThemed: '#00ff00',
},
};
// Получаем разные типы тем на основе описания
const { theme, pixelifyTheme, cssVarsTheme } = expandAll(myNewAwesomeTheme);
const { pixelifyTheme: pixelifyThemeDark } = expandAll(myNewAwesomeThemeDark);
// Для использования, например, в вебе вам подойдет компиляция "пикселяризованной" темы в формате '.css':
const cssString = compileStyles('css', pixelifyTheme);
const cssStringDark = compileStyles('css', pixelifyThemeDark);
// Полученные CSS-строки со всеми переменными тем можно вставить в DOM или сохранить в файл- Добавить более умную генерацию active, hover состояний цвета. При генерации нужно учитывать тёмный и светлый вариант тем, а также сам цвет, для которого генерируется состояние. (решаем проблему, что цвет наведения, сгенерированный от синего, плохо виден на большинстве мониторов).
- Генерация цветов по заранее определённой палитре.
- Текстовое описание семантики каждого токена.
- Более подробная документация.
- Сайт с примерами и описанием.
- Доклад про дизайн-системы на фронтенде: там рассказывается, зачем нужны дизайн-токены, причём тут UI-kit и как делать темизацию.
- Серия видеороликов на youtube, где показано использование этой библиотеки (но со старым названием, не пугайтесь), как ядра дизайн-системы на практике: первый, второй, третий
- Opensource библиотека компонентов (UI-kit) VKUI, которая использует токены.
- Сайт дизайн-система Paradigm, из которой выросла эта библиотека. Там можно найти дизайнерские принципы и идеи, которые стали основой этого репозитория.