@webitel/ui

Appearance

Генерація дизайн-токенів з Figma ​

Що це і навіщо ​

Дизайнери описують кольори, розміри та інші константи як variables у Figma й експортують їх у JSON-файли (Light.tokens.json / Dark.tokens.json). Скрипт генерації перетворює ці файли на дерево CSS-файлів з :root-змінними, якими вже користується код аплікейшенів.

Скрипт лежить у @webitel/styleguide: packages/styleguide/src/lib/styleguide/token-generation/script/.

Звідки беруться токени і куди вони кладуться ​

Вхідні файли лежать поряд зі скриптом, у теці token-generation:

  • apps/<app-name>/Light.tokens.json + Dark.tokens.json – токени конкретного аплікейшену.
  • lib/Light.tokens.json + Dark.tokens.json – спільні токени, якими користуються всі аплікейшени (наразі ця тека порожня – див. нижче).

Кожне джерело (кожен apps/<app-name> і lib/) генерується окремо, і результат лежить поряд із вхідними файлами – у власній теці dist/:

token-generation/
├── apps/
│   ├── agent-workspace-app/
│   │   ├── Light.tokens.json
│   │   ├── Dark.tokens.json
│   │   └── dist/              ← згенеровані CSS-файли саме для цього аплікейшену
│   └── crm/
│       ├── Light.tokens.json
│       ├── Dark.tokens.json
│       └── dist/
└── lib/
    ├── Light.tokens.json
    ├── Dark.tokens.json
    └── dist/                  ← згенеровані CSS-файли для спільних токенів

Всередині dist/ структура тек повторює структуру груп токенів у Figma. Групи, що називаються (або лежать всередині групи, що називається) Colors, вважаються залежними від теми – для них генеруються окремі light/index.css і dark/index.css. Усі інші групи – незалежні від теми, для них пишеться один index.css.

Запустити генерацію можна командою з кореня репозиторію:

bash
npm run design-tokens:generate

Як підключити токени в аплікейшені ​

Згенеровані CSS-змінні не входять до основного . експорту пакета – кожен аплікейшен, якому вони потрібні, підключає свій apps/<app-name>/dist/index.css окремим саб-шляхом @webitel/styleguide/<app-name>:

js
import '@webitel/styleguide/agent-workspace-app';

Саб-шлях описаний у exports у package.json пакета @webitel/styleguide і вказує напряму на token-generation/apps/<app-name>/dist/index.css. Якщо генерація запрацює для нового аплікейшену (див. нижче) – для нього так само треба додати відповідний запис в exports.

Хто генерує токени ​

Генерація – це відповідальність дизайн-команди. Саме дизайнери запускають скрипт після того, як оновили змінні у Figma та зробили новий експорт.

Якщо під час верстки чи розробки вам бракує потрібного CSS-токена (немає відповідної змінної, або токен ще не потрапив у dist/) – не додавайте його вручну і не "хардкодьте" значення в коді. Натомість зверніться до дизайнера, який робив макет: токена, найімовірніше, ще немає у Figma, і його потрібно спершу завести там, а вже потім – перегенерувати.

Для яких аплікейшенів працює генерація ​

На поточному етапі генерація токенів налаштована й реально використовується для agent-workspace-app та crm. Тека lib/ (спільні токени для всіх аплікейшенів) поки що порожня – скрипт коректно пропускає джерела без файлів токенів, не завершуючи роботу помилкою.

Це тимчасовий стан: після завершення міграції інших аплікейшенів на дизайн-токени з Figma, генерація запрацює для кожного з них так само, як зараз для agent-workspace-app і crm – достатньо буде додати відповідну теку apps/<app-name> з файлами Light.tokens.json / Dark.tokens.json.

Як формується назва CSS-змінної ​

Назва CSS custom property будується з шляху токена в дереві Figma: кожен сегмент шляху перетворюється у kebab-case і з'єднується через дефіс з префіксом --wt-.

Наприклад, токен кольору за шляхом:

Avatar → Colors → Unknown user → background

перетвориться на:

css
--wt-avatar-colors-unknown-user-background: #F0F1F5;

А токен розміру (число завжди форматується в px) за шляхом:

WS → App header → Sizes → Root → paddingX

перетвориться на:

css
--wt-ws-app-header-sizes-root-padding-x: 16px;

Тобто принцип простий: назва змінної = --wt- + весь шлях групи/токена у Figma, переведений у kebab-case. Це означає, що:

  • Назва змінної завжди однозначно показує, де саме в Figma шукати відповідний токен.
  • Перейменування групи або токена в Figma змінює назву CSS-змінної – відповідно, такі перейменування варто узгоджувати з розробниками, які цю змінну вже використовують.
  • Якщо в межах одного дерева два різні шляхи токенів дають однакову назву змінної (наприклад, через різницю лише в регістрі), скрипт зупиниться з помилкою колізії назв ще до запису файлів.