@vkontakte/vkui-tokens 4.0.0 → 4.2.0

package/README.md

@@ -1,42 +1,86 @@
 <img src="assets/vkui_logo.png" alt="vkui logo" height="52"/>
 <img src="assets/logo.svg" alt="vkui logo" height="52"/>
 
+[![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)
+[![Npm](https://img.shields.io/npm/v/@vkontakte/vkui-tokens)](https://www.npmjs.com/package/@vkontakte/vkui-tokens)
+[![GitHub Repo stars](https://img.shields.io/github/stars/VKCOM/vkui-tokens?label=GitHub%20Repo%20Stars&style=social)](https://github.com/VKCOM/vkui-tokens)
+
+Этот репозиторий содержит токены единой дизайн-системы VKUI и
+их значения для тем оформления различных проектов.
+
+Темы собираются в следующие форматы: `css`, `scss`, `less`, `pcss`, `styl`, `js`, `json`.
+
+Для описания интерфейсов тем и значений переменных используется TypeScript.
+
+# Содержание
+
+* [Использование](#использование)
+  * [Использование CSS-переменных темы напрямую из пакета](#использование-css-переменных-темы-напрямую-из-пакета)
+    * [Подключение темы на страницу](#подключение-темы-на-страницу)
+    * [Использование переменных в вёрстке](#использование-переменных-в-вёрстке)
+  * [Использование базовой темы напрямую из пакета](#использование-базовой-темы-напрямую-из-пакета)
+* [Инструменты](#инструменты)
+  * [Локальная сборка своих тем инструментами библиотеки](#локальная-сборка-своих-тем-инструментами-библиотеки)
+    * [Наследование от существующей темы](#наследование-от-существующей-темы)
+    * [Создание собственной темы "с нуля"](#создание-собственной-темы-с-нуля)
+* [Roadmap](#roadmap)
+* [Полезные ссылки](#полезные-ссылки)
+* [Информация для внесения изменений](CONTRIBUTING.md)
+* [Changelog (архивная версия)](CHANGELOG.OLD.md)
+
+Актуальный changelog находится на странице
+[релизов в GitHub](https://github.com/VKCOM/vkui-tokens/releases)!
+
 # Использование
 
-1. Устанавливаем npm-пакет `@vkontakte/vkui-tokens`:
+Устанавливаем npm-пакет `@vkontakte/vkui-tokens`:
 ```bash
 npm i --save @vkontakte/vkui-tokens@latest
 ```
-## Используем css variables темы напрямую из пакета
-2. В любом css (или процессоре) импортируем css файл с объявлением переменных:
+## Использование CSS-переменных темы напрямую из пакета
+### Подключение темы на страницу
+
+В любом CSS-файле подключаем файл темы со значениями переменных:
 ```css
 @import "@vkontakte/vkui-tokens/themes/vkBase/cssVars/declarations/index.css";
 ```
 
-3. далее используем эти переменные
-* напрямую в css (процессорах)
+### Использование переменных в вёрстке
+#### Использование в CSS
 ```postcss
 .myAwesomeClass:hover {
 	background-color: var(--vkui--color_background--hover);
 }
 ```
-* или через объект в js(ts)
+
+#### Использование CSS-переменных через объект в JavaScript (TypeScript)
 ```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:
+// Динамически (с учётом возможных переопределений)
+// узнаём, чему равно значение переменной внутри myElement:
 getComputedStyle(myElement).getPropertyValue(baseTheme.colorBackground.hover.name)
 ```
-* для того, чтобы принудительно включать тот или иной вид темы у конкретного поддерева элементов, пользуемся классами `.vkui--force-${auto | regular | compact | large | largeX ...}`. Смотри [демо](demo/example-adaptive-css-vars-theme.html) работы адаптивных переменных и спец. классов. (Также можно просто использовать переменную конкретного брейкпоинта (ex. --vkui--size_field_height--**_compact_**), они все также попадают в `:root`)
 
+#### Принудительное использование токенов определённого размера
+Чтобы принудительно включить тот или иной вид темы у конкретного 
+поддерева элементов, нужно воспользоваться классами 
+`.vkui--force-${auto | regular | compact | large | largeX ...}`.
+Смотри [демо](demo/example-adaptive-css-vars-theme.html) работы 
+адаптивных переменных и спец. классов.
 
-## Используем root темы напрямую из пакета
+Также можно просто использовать переменную конкретного брейкпоинта 
+(ex. --vkui--size_field_height--**_compact_**), они все тоже
+попадают в `:root`)
+
+## Использование базовой темы напрямую из пакета
 ### js/ts/json
-2. Импортируем необходимую тему в файле и используем:
+Импортируем необходимую тему в файле и используем:
 ```ts
 import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase';
 
@@ -44,7 +88,7 @@ import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase';
 ```
 
 ### Используем в scss/styl/less root темы из пакета
-2. Импортируем файл с необходимой темой и используем переменные от туда (снизу синтаксис SCSS)
+Импортируем файл с необходимой темой и используем переменные от туда (снизу синтаксис SCSS)
 ```scss
 @import "~@vkontakte/vkui-tokens/themes/vkBase/index";
 
@@ -57,18 +101,17 @@ import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase';
 }
 ```
 
-
 ###  Используем pcss формат темы из пакета
 
-2. Заходим в файл, где хотим использовать тему, и импортируем её:
+1Заходим в файл, где хотим использовать тему, и импортируем её:
 
         @import "@vkontakte/vkui-tokens/themes/vkBase";
 
-3. Заходим в файл темы, смотрим какие там есть переменные и юзаем их, например:
+2. Заходим в файл темы, смотрим какие там есть переменные и юзаем их, например:
 
         width: var(--size-content-block-width);
 
-4. Просто так ничего не заработает, нужно поставить postcss:
+3. Просто так ничего не заработает, нужно поставить postcss:
 
         npm i --save-dev postcss
 
@@ -76,35 +119,35 @@ import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase';
 
         npm i --save-dev postcss-cli
 
-5. Создаем конфиг postcss. Для этого создаем файл postcss.config.js (можно в любом месте проекта, но лучше в корне) и пишем в него необходимые плагины:
+4. Создаем конфиг postcss. Для этого создаем файл postcss.config.js (можно в любом месте проекта, но лучше в корне) и пишем в него необходимые плагины:
 
      ```javascript
         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')
-         	],
+             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 и др.), чтобы понять, что вам необходимо.
 
-6. Устанавливаем все необходимые плагины, которые написали в конфиге, например:
+5. Устанавливаем все необходимые плагины, которые написали в конфиге, например:
 
         npm i --save-dev postcss-import
 
-7. Настраиваем сборку postcss.
+6. Настраиваем сборку postcss.
 
    Сборка производится командой postcss через командную строку с необходимым параметрами.
    Про них подробнее тут https://github.com/postcss/postcss-cli
@@ -115,11 +158,21 @@ import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase';
 
    Такая команда прогонит файл src/main.css с помощью конфига из текущей папки и положит результат в папку public.
 
+# Инструменты
 ## Локальная сборка своих тем инструментами библиотеки
 
-### Наследуемся от базовой темы
-2. Из библиотеки можно импортировать интерфейсы и темы от которых насследоваться всячески доопределять.
-   Также из библиотеки можно заимпортить функции позволяющие собрать тему (сгенировать состояния цветов, пикселизировать значения и т.д.) в нужном формате: css, js, scss и т.д. Пример:
+Библиотека предоставляет интерфейсы и темы, от которых можно 
+наследоваться.
+
+Помимо этого, библиотека предоставляет набор функций, которые позволяют
+собрать собственную тему в нужном формате.
+
+Сборка темы подразумевает раскрытие наследования, генерацию цветов
+состояний (hover, active), округление и "пикселизация" значений и т.д.
+
+### Наследование от существующей темы
+Пример:
+
 ```typescript
 import type {ThemeDescription} from '@vkontakte/vkui-tokens/interfaces/general';
 import type {Adaptive} from '@vkontakte/vkui-tokens/interfaces/general/tools';
@@ -147,8 +200,13 @@ const {theme, pixelifyTheme, cssVarsTheme} = expandAll(myNewAwesomeTheme);
 const cssString = compileStyles('css', pixelifyTheme);
 ```
 
-### Собираем локально свою тему (набор своих локальных переменных проекта)
-2. На самом деле никакой необходимости наследоваться (см. предыдущий пункт) нет, соберём свою тему из произвольного количества уникальных переменных. Пример:
+### Создание собственной темы "с нуля"
+В некоторых случаях нет необходимости наследоваться от одной из
+базовых тем. Библиотека позволяет сгенерировать свою тему из 
+произвольного количества уникальных переменных.
+
+Пример:
+
 ```typescript
 import type {Adaptive} from '@vkontakte/vkui-tokens/interfaces/general/tools';
 import {expandAll} from '@vkontakte/vkui-tokens/build/expandTheme';
@@ -180,11 +238,19 @@ const {theme, pixelifyTheme, cssVarsTheme} = expandAll(myNewAwesomeTheme);
 const cssString = compileStyles('css', pixelifyTheme);
 ```
 
-# ROAD MAP библиотеки
-* [ ] Добавляем более умную генерацию active, hover состояний цвета. Будем учитывать тёмный и светлый вариант тем. Будем учитывать сам цвет, для которого генерим затемнение. (решаем проблему, что наведение на кнопки в синей шапке абсолютно не видны).
+# Roadmap
+* [ ] Добавить более умную генерацию active, hover состояний цвета.
+  При генерации нужно учитывать тёмный и светлый вариант тем, а также
+  сам цвет, для которого генерируется состояние.
+  (решаем проблему, что цвет наведения, сгенерированный от синего,
+  плохо виден на большинстве мониторов).
+* [ ] Генерация цветов по заранее определённой палитре.
+* [ ] Текстовое описание семантики каждого токена.
+* [ ] Более подробная документация.
+* [ ] Сайт с примерами и описанием.
 
 # Полезные ссылки
-1. [Доклад](https://youtu.be/0rHgqQvl0NQ?t=1858) про дизайн-системы на фронтенде: там рассказывается зачем нужны дизайн-токены, причём тут UI-kit и как делать темизацию.
-2. Серия видеороликов на youtube, где показано использование этой библиотеки (но со старым названием, не пугайтесь), как ядра дизайн-системы, на практике: [первый](https://www.youtube.com/watch?v=RKCsrPOxYWE), [второй](https://www.youtube.com/watch?v=ZhiH4jFL-kU), [третий](https://www.youtube.com/watch?v=ZXOmmkyxrwk)
+1. [Доклад](https://youtu.be/0rHgqQvl0NQ?t=1858) про дизайн-системы на фронтенде: там рассказывается, зачем нужны дизайн-токены, причём тут UI-kit и как делать темизацию.
+2. Серия видеороликов на youtube, где показано использование этой библиотеки (но со старым названием, не пугайтесь), как ядра дизайн-системы на практике: [первый](https://www.youtube.com/watch?v=RKCsrPOxYWE), [второй](https://www.youtube.com/watch?v=ZhiH4jFL-kU), [третий](https://www.youtube.com/watch?v=ZXOmmkyxrwk)
 3. Opensource библиотека компонентов (UI-kit) [VKUI](https://github.com/VKCOM/VKUI), которая использует токены.
-4. [Сайт](https://paradigm.mail.ru/) дизайн системы Paradigm из которой выросла эта библиотека. Там можно найти дизайнерские принципы и идеи, которые стали основой кода находящемся в этом репозитории.
+4. [Сайт](https://paradigm.mail.ru/) дизайн-система Paradigm, из которой выросла эта библиотека. Там можно найти дизайнерские принципы и идеи, которые стали основой этого репозитория.

package/build/compilers/index.d.ts

@@ -2,8 +2,8 @@ import { PixelifyTheme, SpecialTokens, Theme, ThemeCssVarsWide } from '../../int
 declare type ThemeBuildType = 'root' | 'subtheme' | 'flat' | 'cssVars' | 'cssVarsPseudoRoot';
 declare function writeJsonFile<T = Theme>(themePath: string, theme: T, _?: ThemeBuildType): void;
 declare function writeTsFile<T extends SpecialTokens = Theme>(themePath: string, theme: T, type: ThemeBuildType, themeName?: string): void;
-declare function writeStyleFiles<PT = PixelifyTheme>(themePath: string, theme: PT): void;
-declare function writeCssVarsSourceFile<PT = PixelifyTheme>(themePath: string, theme: PT, cssWarsTheme: any): void;
+declare function writeStyleFiles<PT extends PixelifyTheme = PixelifyTheme>(themePath: string, theme: PT): void;
+declare function writeCssVarsSourceFile<PT extends PixelifyTheme = PixelifyTheme>(themePath: string, theme: PT, cssWarsTheme: any): void;
 declare function writeCssVarsSourceMediaFile<T = ThemeCssVarsWide>(themePath: string, theme: T): void;
 declare function writeCssVarsJsUtils<T = Theme>(themePath: string, theme: ThemeCssVarsWide<T>): void;
 export { writeCssVarsJsUtils, writeCssVarsSourceFile, writeCssVarsSourceMediaFile, writeJsonFile, writeStyleFiles, writeTsFile, };

package/build/compilers/index.js

@@ -70,9 +70,11 @@ function writeCssVarsSourceFile(themePath, theme, cssWarsTheme) {
     [
         { mode: 'default', fileName: 'index.css' },
         { mode: 'onlyVariables', fileName: 'onlyVariables.css' },
+        { mode: 'onlyVariablesLocal', fileName: 'onlyVariablesLocal.css' },
         { mode: 'onlyColors', fileName: 'onlyColors.css' },
         { mode: 'onlyAdaptiveGroups', fileName: 'onlyAdaptiveGroups.css' },
         { mode: 'noSizes', fileName: 'noSizes.css' },
+        { mode: 'noColors', fileName: 'noColors.css' },
     ].forEach(function (_a) {
         var _b;
         var mode = _a.mode, fileName = _a.fileName;

package/build/compilers/styles/compileStyles.d.ts

@@ -2,8 +2,10 @@ import 'css.escape';
 import { PixelifyTheme } from '../../../interfaces/general';
 import { Formats } from './helpers/tokenProcessors';
 export declare const serviceKeys: string[];
-export declare type CompileStylesMode = 'default' | 'onlyVariables' | 'onlyColors' | 'withAdaptiveGroups' | 'onlyAdaptiveGroups' | 'noSizes';
+export declare type CompileStylesMode = 'default' | 'onlyVariables' | 'onlyVariablesLocal' | 'onlyColors' | 'withAdaptiveGroups' | 'onlyAdaptiveGroups' | 'noSizes' | 'noColors';
+export declare function getPrefix<PT extends PixelifyTheme>(format: Formats, theme: PT): string;
+export declare function getRootSelector<PT extends PixelifyTheme>(theme: PT, mode: CompileStylesMode): string;
 /**
  * Компиллирует строку со стилями (в разных форматах), на основе темы
  */
-export declare const compileStyles: <PT = PixelifyTheme<import("../../../interfaces/general").Theme>>(format: Formats, theme: PT, mode?: CompileStylesMode) => string;
+export declare const compileStyles: <PT extends PixelifyTheme<import("../../../interfaces/general").Theme> = PixelifyTheme<import("../../../interfaces/general").Theme>>(format: Formats, theme: PT, mode?: CompileStylesMode) => string;

package/build/compilers/styles/compileStyles.js

@@ -4,28 +4,46 @@ var __makeTemplateObject = (this && this.__makeTemplateObject) || function (cook
     return cooked;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.compileStyles = exports.serviceKeys = void 0;
+exports.compileStyles = exports.getRootSelector = exports.getPrefix = exports.serviceKeys = void 0;
 require("css.escape");
 var common_tags_1 = require("common-tags");
+var getAllButColors_1 = require("../../helpers/getAllButColors");
 var getAllButSizes_1 = require("../../helpers/getAllButSizes");
 var getOnlyColors_1 = require("../../helpers/getOnlyColors");
 var unCamelcasify_1 = require("../../helpers/unCamelcasify");
 var tokenProcessors_1 = require("./helpers/tokenProcessors");
 var tokenRecognition_1 = require("./helpers/tokenRecognition");
 exports.serviceKeys = ['breakpoints', 'prefix', 'themeType'];
-/**
- * Компиллирует строку со стилями (в разных форматах), на основе темы
- */
-var compileStyles = function (format, theme, mode) {
-    if (mode === void 0) { mode = 'default'; }
-    var classicCssType = format === tokenProcessors_1.EStyleTypes.CSS || format === tokenProcessors_1.EStyleTypes.PCSS;
+function isClassicCssType(format) {
+    return format === tokenProcessors_1.EStyleTypes.CSS || format === tokenProcessors_1.EStyleTypes.PCSS;
+}
+function getPrefix(format, theme) {
     var prefix = theme.prefix ? theme.prefix + "-" : '';
-    if (classicCssType && prefix) {
+    if (isClassicCssType(format) && prefix) {
         prefix += '-';
     }
     if (format === tokenProcessors_1.EStyleTypes.CSS && !prefix) {
         prefix = 'vkui--';
     }
+    return prefix;
+}
+exports.getPrefix = getPrefix;
+function getRootSelector(theme, mode) {
+    var _a;
+    if (!mode.endsWith('Local')) {
+        return ':root';
+    }
+    return "." + getPrefix(tokenProcessors_1.EStyleTypes.CSS, theme) + ((_a = theme.themeNameBase) !== null && _a !== void 0 ? _a : theme.themeName) + "--" + theme.colorsScheme;
+}
+exports.getRootSelector = getRootSelector;
+/**
+ * Компиллирует строку со стилями (в разных форматах), на основе темы
+ */
+var compileStyles = function (format, theme, mode) {
+    if (mode === void 0) { mode = 'default'; }
+    var classicCssType = isClassicCssType(format);
+    var prefix = getPrefix(format, theme);
+    var rootSelector = getRootSelector(theme, mode);
     var getDeclaration = tokenProcessors_1.varDeclarations[format];
     var getVariableStatement = tokenProcessors_1.variablesStatementDeclaration[format];
     var getCustomMediaDeclaration = tokenProcessors_1.customMediaDeclaration[format];
@@ -39,6 +57,9 @@ var compileStyles = function (format, theme, mode) {
         case 'noSizes':
             theme = getAllButSizes_1.getAllButSizes(theme, theme.themeNameBase);
             break;
+        case 'noColors':
+            theme = getAllButColors_1.getAllButColors(theme, theme.themeNameBase);
+            break;
     }
     Object.keys(theme).forEach(function (key) {
         // пропускаем служебные ключи
@@ -91,9 +112,9 @@ var compileStyles = function (format, theme, mode) {
     });
     result = variables;
     if (classicCssType && variables) {
-        result = common_tags_1.stripIndent(templateObject_1 || (templateObject_1 = __makeTemplateObject(["\n\t\t:root {\n\t\t", "}\n\t\t"], ["\n\t\t:root {\n\t\t", "}\n\t\t"])), variables.split('\n').join('\n\t\t'));
+        result = common_tags_1.stripIndent(templateObject_1 || (templateObject_1 = __makeTemplateObject(["\n\t\t", " {\n\t\t", "}\n\t\t"], ["\n\t\t", " {\n\t\t", "}\n\t\t"])), rootSelector, variables.split('\n').join('\n\t\t'));
     }
-    if (mode === 'onlyVariables') {
+    if (mode === 'onlyVariables' || mode === 'onlyVariablesLocal') {
         return common_tags_1.stripIndent(result);
     }
     if (mode === 'onlyAdaptiveGroups') {