Skip to content

Zaycevq/vkui-tokens

 
 

Repository files navigation

vkui logo

vkui logo

Tests Npm GitHub Repo stars

Интерактивная документация

Этот репозиторий содержит токены единой дизайн-системы VKUI и их значения для тем оформления различных проектов.

Темы собираются в следующие форматы: css, scss, less, pcss, styl, js, json.

Для описания интерфейсов тем и значений переменных используется TypeScript.

Содержание

Актуальный changelog находится на странице релизов в GitHub!

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

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

npm i --save @vkontakte/vkui-tokens@latest

Использование CSS-переменных темы напрямую из пакета

Подключение темы на страницу

В любом CSS-файле подключаем файл темы со значениями переменных:

@import '@vkontakte/vkui-tokens/themes/vkBase/cssVars/declarations/index.css';

Использование переменных в вёрстке

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

.class:hover {
	background-color: var(--vkui--color_background--hover);
}

Использование CSS-переменных через объект в JavaScript (TypeScript)

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)

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

js/ts/json

Импортируем необходимую тему в файле и используем:

import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase';

// do whatever you want with baseTheme

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

Импортируем файл с необходимой темой и используем переменные от туда (снизу синтаксис 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.

Инструменты

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

Библиотека предоставляет интерфейсы и темы, от которых можно наследоваться.

Помимо этого, библиотека предоставляет набор функций, которые позволяют собрать собственную тему в нужном формате.

Сборка темы подразумевает раскрытие наследования, генерацию цветов состояний (hover, active), округление и "пикселизация" значений и т.д.

Наследование от существующей темы

Пример:

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);

Roadmap

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

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

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

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 97.0%
  • JavaScript 2.9%
  • Shell 0.1%