Skip to content

VKCOM/vkui-tokens

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Folders and files

NameName
Last commit message
Last commit date
Dec 26, 2024
Aug 23, 2023
Jul 23, 2021
Jul 23, 2021
Dec 2, 2024
Feb 14, 2024
Dec 27, 2024
Apr 19, 2023
May 24, 2024
Feb 14, 2024
Jan 12, 2023
Dec 26, 2024
Jul 23, 2021
Mar 29, 2022
Dec 1, 2022
Jan 12, 2023
Apr 20, 2022
Jul 26, 2024
Jan 12, 2023
Jul 17, 2023
Jul 23, 2021
May 24, 2024
Dec 1, 2022
Jan 13, 2025
Jul 24, 2024
Jun 16, 2023
Jan 12, 2023
Jan 13, 2025

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), округление и "пикселизация" значений и т.д.

Предварительная настройка

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

Roadmap

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

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

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