/vkui-tokens

Primary LanguageTypeScriptMIT LicenseMIT

vkui logo

vkui logo

Использование

  1. Устанавливаем npm-пакет @vkontakte/vkui-tokens:
npm i --save @vkontakte/vkui-tokens@latest

Используем css variables темы напрямую из пакета

  1. В любом css (или процессоре) импортируем css файл с объявлением переменных:
@import "@vkontakte/vkui-tokens/themes/vkBase/cssVars/declarations/index.css";
  1. далее используем эти переменные
  • напрямую в css (процессорах)
.myAwesomeClass:hover {
	background-color: var(--vkui--color_background--hover);
}
  • или через объект в js(ts)
import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase/cssVars/theme';

console.log(baseTheme.colorBackground.hover.name) // --vkui--color_background--hover;
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--size_field_height--compact), они все также попадают в :root)

Используем root темы напрямую из пакета

js/ts/json

  1. Импортируем необходимую тему в файле и используем:
import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase';

// do whatever you want with baseTheme

Используем в scss/styl/less root темы из пакета

  1. Импортируем файл с необходимой темой и используем переменные от туда (снизу синтаксис SCSS)
@import "~@vkontakte/vkui-tokens/themes/vkBase/index";

.myAwesomeClass {
	background-color: $color-bg;
}

.myAwesomeClass:hover {
	background-color: $color-bg--hover;
}

Используем pcss формат темы из пакета

  1. Заходим в файл, где хотим использовать тему, и импортируем её:

     @import "@vkontakte/vkui-tokens/themes/vkBase";

  2. Заходим в файл темы, смотрим какие там есть переменные и юзаем их, например:

     width: var(--size-content-block-width);

  3. Просто так ничего не заработает, нужно поставить postcss:

     npm i --save-dev postcss

    Для запуска у postcss есть командная строка, которую тоже надо установить:

     npm i --save-dev postcss-cli

  4. Создаем конфиг 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 и др.), чтобы понять, что вам необходимо.

  5. Устанавливаем все необходимые плагины, которые написали в конфиге, например:

     npm i --save-dev postcss-import

  6. Настраиваем сборку postcss.

    Сборка производится командой postcss через командную строку с необходимым параметрами. Про них подробнее тут https://github.com/postcss/postcss-cli

    Пример команды:

     postcss src/main.css -c ./ --dir public

    Такая команда прогонит файл src/main.css с помощью конфига из текущей папки и положит результат в папку public.

Локальная сборка своих тем инструментами библиотеки

Наследуемся от базовой темы

  1. Из библиотеки можно импортировать интерфейсы и темы от которых насследоваться всячески доопределять. Также из библиотеки можно заимпортить функции позволяющие собрать тему (сгенировать состояния цветов, пикселизировать значения и т.д.) в нужном формате: css, js, scss и т.д. Пример:
import type {ThemeDescription} from '@vkontakte/vkui-tokens/interfaces/general';
import type {Adaptive} from '@vkontakte/vkui-tokens/interfaces/general/tools';
import {lightTheme as baseTheme} from '@vkontakte/vkui-tokens/themeDescriptions/base/vk';
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,
	myNewAwesomeToken: {
		regular: 20,
		compact: 12,
	},
};

// получаем разные типы тем на основе описания
const {theme, pixelifyTheme, cssVarsTheme} = expandAll(myNewAwesomeTheme);

// получаем CSS-строку со всеми переменными темы,
// которую можно вставить в DOM или сохранить в файл
const cssString = compileStyles('css', pixelifyTheme);

Собираем локально свою тему (набор своих локальных переменных проекта)

  1. На самом деле никакой необходимости наследоваться (см. предыдущий пункт) нет, соберём свою тему из произвольного количества уникальных переменных. Пример:
import type {Adaptive} from '@vkontakte/vkui-tokens/interfaces/general/tools';
import {expandAll} from '@vkontakte/vkui-tokens/build/expandTheme';
import {compileStyles} from '@vkontakte/vkui-tokens/build/compilers/styles/compileStyles';

interface MyNewAwesomeThemeDescription {
	myNewAwesomeToken: Adaptive<number>;
}

const myNewAwesomeTheme: MyNewAwesomeThemeDescription = {
	myNewAwesomeToken: {
		regular: 20,
		compact: 12,
	},
};

// получаем разные типы тем на основе описания
const {theme, pixelifyTheme, cssVarsTheme} = expandAll(myNewAwesomeTheme);

// получаем CSS-строку со всеми переменными темы,
// которую можно вставить в DOM или сохранить в файл
// буквально тут содержится:
/* 
:root {
	--vkui--my_new_awesome_token--regular: 20px;
	--vkui--my_new_awesome_token--compact: 12px;
}
 */
const cssString = compileStyles('css', pixelifyTheme);

ROAD MAP библиотеки

  • Добавляем более умную генерацию active, hover состояний цвета. Будем учитывать тёмный и светлый вариант тем. Будем учитывать сам цвет, для которого генерим затемнение. (решаем проблему, что наведение на кнопки в синей шапке абсолютно не видны).

Полезные ссылки

  1. Доклад про дизайн-системы на фронтенде: там рассказывается зачем нужны дизайн-токены, причём тут UI-kit и как делать темизацию.
  2. Серия видеороликов на youtube, где показано использование этой библиотеки (но со старым названием, не пугайтесь), как ядра дизайн-системы, на практике: первый, второй, третий
  3. Opensource библиотека компонентов (UI-kit) VKUI, которая использует токены.
  4. Сайт дизайн системы Paradigm из которой выросла эта библиотека. Там можно найти дизайнерские принципы и идеи, которые стали основой кода находящемся в этом репозитории.