Hexa UI Core

Пакет дизайн-системы Hexa UI. Разделен на три домена: шрифты, токены типографии, токены цветов.

• Установка
• Использование в проекте
  • Шрифты
  • Токены типографии
  • Токены цветов
• Обновление токенов
• Сборка пакета
• Ресурсы

Установка

npm install @kaspersky/hexa-ui-core

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

Шрифты

import '@kaspersky/hexa-ui-core/fonts'

На странице создается элемент <style class="hexa-ui-fonts"></style>, в котором определены источники шрифтов.

При SSR подключение шрифтов происходит следующим образом:

import '@kaspersky/hexa-ui-core/fonts/tokens.css'

Токены типографии

import '@kaspersky/hexa-ui-core/typography/css'

На странице создается элемент <style class="hexa-ui-typography"></style>, в котором определены css-variables для токенов типографии.

import { typography }  from '@kaspersky/hexa-ui-core/typography/js'

Экспортируемые объекты и типы:

• typography - объект с токенами типографии
• Typography - тип токенов типографии

При SSR подключение токенов типографии происходит следующим образом:

import '@kaspersky/hexa-ui-core/typography/tokens.css'

Токены цветов

import '@kaspersky/hexa-ui-core/colors/css'

На странице создается элемент <style class="hexa-ui-colors"></style>, в котором определены css-variables для токенов цветов.

import '@kaspersky/hexa-ui-core/colors/css/static'
import '@kaspersky/hexa-ui-core/colors/css/button'

На странице создается элемент <style class="hexa-ui-colors-static"></style>, в котором определены css-variables для токенов цветов из статической палитры, а также элемент <style class="hexa-ui-colors-button"></style>, в котором определены css-variables для токенов цветов конкретного компонента (в примере - button).

ВАЖНО

Возможность подключать токены цветов конкретного компонента уменьшает итоговый размер бандла, но при таком подходе важно всегда импортировать статические цвета, так как переменные для компонентов на них ссылаются.

import { colors }  from '@kaspersky/hexa-ui-core/colors/js'

Экспортируемые объекты:

• colors - цвета из статической базовой палитры (в том числе устаревшей)
• productColors - цвета, имеющие пару в темной теме, предназначены для продуктовых команд для раскраски некоторых компонентов (например, иконок) и всего, что не является компонентом
• componentColors - цвета, имеющие пару в темной теме, предназначены для раскраски компонентов библиотеки
• themeColors - устаревшие цвета, имеющие пару в темной теме
• allColors - colors + themeColors + productColors + componentColors
• shortcutsV6 (устаревшие), productColorsShortcuts, componentColorsShortcuts - цвета, имеющие пару в темной теме (другая структура объекта)
• shortcuts - productColorsShortcuts + componentColorsShortcuts + shortcutsV6

При SSR подключение токенов цветов происходит следующим образом:

import '@kaspersky/hexa-ui-core/colors/tokens.css'

Сборка пакета

npm run build

В корне пакета создается директория /dist со сборкой пакета в двух основных форматах: CommonJS и ESM.

Обновление токенов (for maintainers)

npm run update-colors
npm run update-typography

Команда update-colors обновляет токены цветов в пакете: создает новую палитру цветов по импортированным токенам из Figma в формате JSON, генерирует css-variables для токенов.

Команда update-typography обновляет токены типографии в пакете: генерирует JSON-файл с токенами типографии, генерирует css-variables для токенов.

Обновление токенов (for designers)

{base_path} = /full/path/to/repo/product/osmp/web/packages/packages

Перед первым обновлением токенов однократно выполнить следующее: создать .env файл по аналогии с .env.example.

1. Перейти в директорию с пакетом компонентов @kaspersky/hexa-ui ({base_path}/kaspersky-hexa-ui). Установить или обновить node_modules.

npm i

2. Установить или обновить node_modules в пакете @kaspersky/hexa-ui-core.

npm i

3. Копирование токенов

(Pixso) [NEW]

Экспортированные из Pixso JSON-файлы с необходимыми обновлениями скопировать в ./src/colors/tokens-pixso/_, заменив существующие. Для статических токенов название файла следующее - static-tokens.json, для токенов продукта - product-tokens.json, для семантических токенов - semantic-tokens.json, а для токенов виджетов - widget-tokens.json. Добавить только файлы, в которых есть изменения.

(Figma) [OLD]

Скопировать JSON-файлы (static-tokens.json, product-tokens.json, component-tokens.json, widget-tokens.json) из директории ./src/colors/tokens в директорию ./src/colors/tokens/_, заменив существующие.

Экспортированные из Figma JSON-файлы с необходимыми обновлениями скопировать в ./src/colors/tokens/_, заменив существующие. Для статических токенов название файла следующее - static-tokens.json, для токенов продукта - product-tokens.json, для токенов компонентов - component-tokens.json, а для токенов виджетов - widget-tokens.json. Добавить только файлы, в которых есть изменения.

4. Выполнить команду

npm run check-tokens-change:swapped

Команда check-tokens-change:swapped проверяет, изменилась ли структура токенов, и выводит об этом информацию.

ВАЖНО

Если были добавлены токены для нового компонента в component-tokens.json, его нужно добавить в список src/colors/constants.js (в алфавитном порядке) и экспортировать из индекса (src/index.ts) по аналогии с другими компонентами (в алфавитном порядке).

Если структура токенов не изменилась, необходимо выполнить команду.

npm run storybook-hexa-ui

Команда storybook-hexa-ui собирает пакет с новыми токенами, копирует обновленный пакет в директорию с компонентами и запускает сторибук.

Ресурсы

Hexa UI Core в Pixso

Product tokens
Semantic tokens
Static tokens
Widget tokens

How to create Pull Request