Ультимативный гайд по дизайн-токенам

На небе только и разговоров, что о дизайн-системах и дизайн-токенах. Но информация представленная здесь строится исключительно на собственном опыте.

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

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

Меня зовут Женя, я руководитель UX-направления в компании Usetech. На досуге веду телеграм-канал «Мамкин Дизайнер», где рассказываю о вот таких штуках.

Я сам — дизайнер, но мне важно было понять что такое дизайн-токены, как они работают, как компилируются из JSON и как помогают в работе.

Дисклеймер

Друзья из frontend – я не разработчик и не претендую на единственно верный процесс. Буду очень рад, если вы дополните мою статью своими комментариями.

Я не призываю использовать токены везде и в каждом проекте. Вводить токены или нет — решать вам.

Для кого статья

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

Для разработчиков: которые шарят за код, но к которым пристают дизайнеры, чтобы ввели токены.

Забегая вперед: вариантов и процессов, через которые токены можно компилировать – множество. Это можно делать не только на фронте, но и на бэке. Я расскажу лишь о нескольких вариантах.

В качестве примера у нас:

• два плагина Figma;
• препроцессор SCSS (Sass);
• сервис zeroheight;
• библиотека Amazon Style Dictionary.

Что такое дизайн-токены?

Концепцию дизайн-токенов представили ребята из Salesforce: Джина Болтон и Джон Левин. Они использовали их в своей дизайн-системе Lightning и рассказывали о ней на презентации. На самом деле их использовали гораздо раньше, просто эти ребята стали первыми людьми, кто о них заговорил.

Они рассказали о своем подходе к проектированию, как токены переносят дизайн и как поддерживать кросс-платформенность. Даже разработали свой собственный продукт Theo, который компилирует JSON/XML в нужный формат.

Миссия дизайн токенов — сократить время на разработку и помочь держать несколько приложений в едином виде, оптимизируя стоимость и время на правки. А ещё они помогают дизайнеру и разработчику общаться на одном языке.

Если мы говорим про большие приложения, их массовость по количеству и платформам, то наверняка эти приложения стоят на каком-то фундаменте. Этот фундамент — дизайн-система.

Если вы занимаетесь лендингами или небольшими веб-сайтами, то дизайн-система и уж тем более дизайн-токены вам ни к чему.

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

Атомарный дизайн

Если следовать концепции атомарного дизайна Бреда Фроста, то самой маленькой частицей он представляет атом, но у этих атомов есть ещё и свойства: цвет заливки, цвет текста, шрифт, размер и т.д.

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

Дизайн-токены должны стать переносчиком данных со стилями

Получается, что самыми мелкими частицами в атомарном дизайне являются дизайн-токены.

С чего начать?

Прежде чем заниматься токенизацией, необходимо провести инвентаризацию интерфейса в Figma, иначе велик шанс навести бардак.

В качестве примера — цветовые стили.

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

Ещё я замечаю, что некоторые стили названы по их значению. Так, например, значение зелёного цвета в hex #44BE84 равняется названию самого стиля green.

Здесь я вижу несколько проблем.

Проблема 1. Как объяснить новому дизайнеру, который возьмётся за этот проект, какой стиль и для какого элемента должен быть использован?

Проблема 2. Если нет возможности / времени / ресурса отрисовать макет, то разработчик собирает его из готовых элементов прямо в коде — как ему понять какой цвет где использовать, если вдруг появляется новый, но возможно похожий элемент?

Проблема 3. Глобальные стили. Мы используем один primary-стиль для всего: кнопки, фоны, иконки. Как быть, если иконки нужно перекрасить?

И тут вариантов несколько: или перекрашивать primary, что незамедлительно приведет к перекрашиванию других элементов или разлинковывать стиль и придумывать что-то новое. И это касается не только ваших макетов в Figma, но и кода разработчика — перелинковывать переменные придется и там.

Хуже, когда стили называются не просто primary, а названием конкретного цвета: green, orange, red. А еще иногда red-1, red-2, light-red. Как понять, какой стиль где использовать?

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

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

Цвет можно разделить на несколько групп. Это решение не 100% универсальное, отталкивайтесь от своих целей и задач.

Расскажу на одном из примеров, как можно сгруппировать цвета.

• Фоны. Здесь я указываю общий фон, фон для подложек или островков, фон для подложек у островков (если требуется), границы (разделители, таблицы, обводки элементов), акцентный фон, фон для модальных окон с прозрачностью.
• Текст. Отдельный стиль для текста — темный для белых фонов, светлый для ярких фонов. Если надо, то добавляю стили с прозрачностью, для различных подписей и отдельно цвет под ссылку.
• Иконки. Цвет иконок для обычного фона и инвертный, если иконки используются на ярких фонах.
• Кнопки. Кнопки я разделяю на подгруппы и назначаю стили на различные состояния. Иногда я зашиваю в стиль еще и цвет текста и подписываю стили по их назначению.
• Статусы. Если есть индикация статусов – назначаю отдельные стили для них.

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

Конструкция токенов

Это обычная конструкция, которая помогает унифицировать ваши токены-переменные. Такая конструкция легко ложится на стили в Figma.

[Category]-[Type]-[Item]-[SubItem]-[State]

• Category – категория токена (color, font);
• Type – тип токена (text, background, border);
• Item – элемент (button, table, input);
• SubItem – тип элемента (primary, secondary);
• State – состояние элемента (default, hover, active).

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

Семантическое название токенов

На видео пример: разработчику не нужно вспоминать, а какая тень при наведении на карточку. Ему просто нужно ввести первые строчки переменной и выбрать переменную в состоянии *-hover.

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

Дизайн токен = переменная

В мире frontend-разработки (да и backend) токены явление также не новое. К элементам в коде “прокидываются” переменные, которые содержат в себе значение и переиспользуются в компонентах.

Беря за основу опыт frontend — дизайн-токен и есть переменная в коде.

Цвет в коде:

.button {
   background-color: #00BFFF;
}

Глобальная переменная цвета в коде:

$frost-sky: #00BFFF;

.button {
   background-color: $frost-sky;
}

Дизайн-токен с цветом, как переменная:

$color-button-primary-default: #00BFFF;

.button {
   background-color: $color-button-primary-default;
}

Таким образом, дизайн-токены дают больше гибкости, которые позволяют контролировать стили отдельных компонентов, а не влиять на них глобально.

Это полезно не только с точки зрения кода, но и с точки зрения компонентов в вашей дизайн-библиотеке Figma, где вы гибко используете палитру для разных элементов, а не назначаете одно глобальное свойство на всё.

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

JSON

JSON или JavaScript Object Notation — текстовый формат обмена данными, основанный на JavaScript. Но при этом он может использоваться в любом языке программирования.

Дизайн-токены хранятся в JSON-файле, в котором нет ничего хитрого: обычный текстовый файл, с расширением *.json и специальной древовидной разметкой.

Такой файл генерируется с помощью плагинов в инструментах (Figma, Adobe XD, Sketch), любыми сторонними сервисами (zeroheigh, Specify) или просто пишется ручками.

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

Если вы разрабатываете приложение для web и оно одно, то, возможно, завязываться на токенах не стоит. Синхронизировать дизайнера и пару разработчиков вполне можно.

Но что, если у вас есть веб-приложение, iOS приложение и android-приложение? А что, если у вас несколько приложений, которые выполняют разные функции, но выходят под одним брендом? 

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

Даже если вы сегодня делаете одно приложение — подстелите соломку, рынок может измениться, а приложений вашей компании может стать больше.

Семантика JSON

JSON-объект — это неупорядоченное множество пар «ключ:значение», заключённых в фигурные скобки { }  и взаимодействие с ним проходит, как со словарем.

Ключ — это название параметра (свойства), который мы передаём серверу. Он служит для того, чтобы сервер понял, какой параметр мы передаем.

Например:

Мы передаем значение "#ffffff" (белый цвет) с ключом "color" (цвет) и значение "16px" с ключом "font-size" (размер шрифта):

{
 "color": "#ffffff",
 "font-size": "16px"
}

Семантика дизайн-токена немного усложняется вложенностью и ключом является “value”.

{
  "category": {
    "type": {
      "item": {
        "state": {
           "value": {}
        }
      }
    }
  }
}

Пример токена с цветом кнопки в разных состояниях:

"buttons": {
      "primary": {
        "fill-border-default": {
          "value": "rgb(87,89,206)"
        },
        "fill-border-hover": {
          "value": "rgb(107,110,243)"
        },
        "fill-border-active": {
          "value": "rgb(69,71,168)"
        },
        "fill-border-disabled": {
          "value": "rgba(111,112,195,0.5)"
        },
        "text": {
          "value": "rgb(255,255,255)"
        }
}

После того, как мы подвергнем этот JSON компиляции для веб-платформы и пре-процессора SCSS, мы получим следующие переменные:

$color-button-primary-fill-border-default: rgb(87,89,206);
$color-button-primary-fill-border-hover: rgb(107,110,243);
$color-button-primary-fill-border-active: rgb(69,71,168);
$color-button-primary-fill-border-disabled: rgba(111,112,195,0.5);
$color-button-primary-text: rgb(255,255,255);

И далее, в коде можно назначать эти переменные нашим элементам и управлять стилями одним изменением.

Примечательно, что некоторые изменения можно делать напрямую от дизайна к продакшену, минуя этап разработки.

Если все правильно настроить, то дизайнеру достаточно будет изменить цвет стиля в Figma и нажать на кнопку, которая отправит JSON на сервер. Проект пересоберется и изменения выкатятся без боли.

Компоненты из переменных

Переменные сами по себе могут существовать и быть назначены на любой элемент html-страницы. Но я рекомендую некоторые стили оборачивать в так называемые миксины (примеси).

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

Sass документация

За пример возьмем текстовый стиль заголовка, который мы создали в Figma. В нем содержатся:

• семейство шрифтов (font-family);
• размер шрифта (font-size);
• толщина шрифта (font-weight);
• межбуквенное расстояние (letter-spacing);
• высота строки (line-height).

Как это выглядит в JSON:

{
  "font": {
    "header1": {
      "fontFamily": {
        "value": "Gilroy",
      },
      "fontSize": {
        "value": "48px"
      },
      "fontWeight": {
        "value": 500
      }
      "letterSpacing": {
        "value": "1%"
      },
      "lineHeight": {
        "value": "72px"
      }
    }
  }
}

Как это выглядит в переменных:

$font-header1-fontFamily: "Gilroy";
$font-header1-fontSize: 48px;
$font-header1-fontWeight: 500;
$font-header1-letterSpacing: 1%;
$font-header1-lineHeight: 72px;

Как это выглядит в миксине:

@mixin header-1 {
    font-family: $font-header1-fontFamily;
    font-size: $font-header1-fontSize;
    font-weight: $font-header1-fontWeight;
    letter-spacing: $font-header1-letterSpacing;
    line-height: $font-header1-lineHeight;
}

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

h1 {
    @include header-1();
}

.banner {
    @include header-1();
}

.widget {
    @include header-1();
}

Что получается в итоговом CSS:

h1 {
  font-family: "Gilroy";
  font-size: 48px;
  font-weight: 500;
  letter-spacing: 1%;
  line-height: 72px;
}

.banner {
  font-family: "Gilroy";
  font-size: 48px;
  font-weight: 500;
  letter-spacing: 1%;
  line-height: 72px;
}

.widget {
  font-family: "Gilroy";
  font-size: 48px;
  font-weight: 500;
  letter-spacing: 1%;
  line-height: 72px;
}

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

Если мы применили эту конструкцию условно 200 раз, то при изменении размера шрифта (или всего стиля текста) и пары кликов на выгрузку из Figma мы безболезненно заменим все 200 стилей.

Но можно и использовать директиву %extend, чтобы наследовать свойства и не нагружать браузер для считывания одних и тех же свойств. Но об этом в другой раз.

Токены и дизайнер

Давайте теперь вернемся и посмотрим, как выглядит процесс выгрузки токенов со стороны дизайнера.

Все что дизайнер видит в инструменте (Figma, Sketch, Adobe XD) это графическая составляющая: квадратики и кружочки, заливку цвета через удобный UI, и настройку стилей типографики.

Но если копнуть глубже, то все это так же состоит из кода, под капотом у той же Figma есть определенные свойства.

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

В качестве примера, сегодня рассмотрим два самых популярных плагина:

• Design Tokens
• Figma Tokens

Design Tokens

Плагин Design Tokens позволяет выгружать:

• стили: цвет, текст, тени;
• физические значения: размеры, отступы, сетки, скругления.

В работе со стилями все проще – плагин забирает значения из заготовленных стилей документа, а вот физические значения это танцы с бубнами. Если кратко: нужно готовить фреймы со специальными названиями, чтобы плагин понял, что это токен.

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

Название файла

Тут общее название, как будет на выходе и расширение. Я советую выбирать *.json

• *.tokens.json
• *.tokens
• *.json

Формат JSON

Здесь необходимо выбрать нужный формат нотации (что это?). Тут выбираете как вам удобнее считывать названия:

• kebab-case (мой выбор);
• camelCase.

Формат токена советую выбирать Original (deprecated). Второй формат W3C удобен для группировки свойств, но может стать проблемой при преобразовании токенов в переменные из-за настроек компилятора.

Настройка префиксов

• игнорирование токенов начинающихся с символов #, ., @
• идентификация названия токенов

Это раздел советую не трогать и оставить поля, которые заполнены по умолчанию

Префиксы для типа токенов

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

Если фрейм назван как size/sizes, то он автоматически подставит нужные числа, указанные в размерах этого элемента, а токен будет начинаться с size-*.

Работа с токенами плагина Design Tokens. Примеры

Теперь, когда все настройки сделаны, перейдем к обозначению токенов в самой Figma. С цветом и типографикой, как я говорил выше — все просто. Достаточно создать эти стили и при экспорте json поставить нужные чекбоксы.

А далее, чтобы выгрузить значения размеров / скругления / брейкпоинтов магическим движением рук, нам надо создать фрейм с названием “_token/***” и положить в него то, что хотим получить в токене. Ниже рассмотрим на примере размеров.

Размеры

Чтобы выгрузить в токен размерную сетку, нам необходимо создать фрейм с названием “_token/sizes”, а внутрь положить фреймы со всеми необходимыми размерами. Сами фреймы необходимо назвать “sizes/значение”.

При выгрузке токена он получит следующее название: [size-**], значение которого возьмется из размерных свойств.

После выгрузки мы получим следующий код JSON:

{
  "size": {
    "80": {
      "value": 80
    },
    "120": {
      "value": 120
    },
    "160": {
      "value": 160
    }
  }
}

Переменные в SCSS будут выглядеть так:

$size-80: 80px;
$size-120: 120px;
$size-160: 160px;

Все примеры выгрузки вы сможете посмотреть в документации к плагину и в Playground-файле.

Выгрузка токенов

Выгрузка JSON-файла может происходить в двух вариантах:

• ручная выгрузка на компьютер;
• выгрузка в репозиторий Github.

В случае с Github так же можно пойти двумя путями:

• просто выгружать файл и ответственный человек пересоберет проект и отправит изменения на продакшн;
• настроить автоматическую сборку проекта по изменению файла с токенами.

Figma Tokens

Плагин Figma Tokens хорош всем. Не требует дополнительных настроек и дизайн-токены можно как выгружать из него, так и загружать, если вы изменили что-то вручную.

Большим плюсом является линковка и поддержка документации. Если что-то поменялось в токене: цвет заливки, бордера или описание этого токена, то он автоматически поменяет значение и в вашей документации в Figma.

Стили можно как импортировать из документа Figma, так и создать прямо в плагине.

Плагин имеет два вида работы с токенами: в виде UI интерфейса и размеченным JSON-файлом. Значения для цвета могут быть в hex, rgb, hsl.

Название и ссылки

Название токена именуется через точку и обозначает вложенность. Так например если нам нужно получить переменную $color-button-primary-default нам необходимо в имени переменной написать: button.primary.default. Категория токена подтянется из родительской группы при выгрузке.

В параметр токена мы можем передавать не только прямое значение, но и ссылаться на ранее созданный токен. Это называется alias. Ссылаться на токен нужно через {alias}.

Например. Мы хотим считать цвет через HSL, меняя только параметры saturation и lightness, а hue оставить отдельной переменной.

Создаем токен с наименованием button.base и присваиваем значение 313. Просто число.

Далее создаем токен button.primary.default и вместо прямого значения HSL делаем его гибридным, ссылаемся на базовый токен и крутим saturation и lightness.

Alias в плагине пишется как {alias}, а значит запись для button.primary.default будет выглядеть как:

hsl({button.base},71,55)

А после обработки, вот так:

hsl(313,71,55)

Создаем такие же токены для hover, active. Только не забываем покрутить saturation и lightness.

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

Обновление документации

Плагин позволяет линковать к слоям Figma параметры стилей. Например для цвета можно линковать: заливку, границы, имя токена, значение токена и его описание.

Достаточно открыть плагин, выбрать нужные фреймы и слои и в контекстном меню токена выбрать, к какому типу линкуется слой.

Загрузка токенов

И как уже упоминалось выше, JSON можно не только выгружать, но и загружать. Если по какой-то причине разработчик изменил значения в JSON файле и сменил несколько параметров, то достаточно скопировать содержимое всего JSON-файла и просто вставить в плагин.

Выгрузка

У плагина есть несколько способов выгрузки JSON-файла, которые прячутся на вкладке Settings:

• локальный файл;
• на сервер по URL;
• в GitHub или GitLab

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

Преобразование из JSON

Мы разобрались, что дизайн-токены хранятся в JSON, что их можно или выгрузить через плагин или написать ручками, но как получить из JSON преобразованные переменные в SCSS-файле?

Преобразователей несколько:

• сервис для документации zeroheight (только цвет и текст);
• продукт Specify, для хранения документации проекта и токенов;
• библиотека Theo от Salesforce;
• библиотека из npm “JSON to SCSS” (только SCSS);
• библиотека Amazon Style Dictionary.

Сегодня посмотрим на сервис zeroheight и библиотеку Style Dictionary.

Zeroheight

Этот сервис очень похож на популярный у разработчиков storybook – программное обеспечение для документации кода.

Но zeroheight более дружественный по отношению к дизайнеру и обладает приятным бонусом: все стили и компоненты можно грузить непосредственно из Figma в пару кликов.

Zeroheight так же поддерживает дизайн-токены, но в ограниченном виде: только типографика и цвет. Никаких танцев с кодом и установкой дополнительных библиотек. Если вам этого хватает, то смело используйте его.

С чего начать?

Необходимо зарегистрироваться в сервисе, подключить свой Figma-файл и добавить стили на страницу. Я подробно рассказывал о сервисе zeroheight в своем обзоре.

Загрузка дизайна

Далее, необходимо выбрать нужную страницу в документации и подгрузить туда необходимые стили. Например цвет.

Дизайн-токены

У сервиса есть блоки форматирования и вставки. Вы можете добавлять текст, элементы из Figma, сниппеты, живой код, таблицы и дизайн-токены. Разметка токенов делится на 2 версии.

Первая версия сразу собирает необходимые форматы:

• Sass
• CSS
• JSON
• iOS
• Android

Необходимо только добавить префиксы к токенам, если это необходимо. Файл с преобразованными переменными можно или скачать или подключить в свой проект по адресу, который предлагает zeroheight.

Вторая версия отдает JSON файл и предлагает подключить его в свой проект, где компилятором выступает библиотека Amazon Style Dictionary.

Таким образом возникает процесс изменения стилей для приложения минуя разработчика. Дизайнер меняет что-то в Figma, загружает по кнопке в zeroheight и на проекте в реальном времени применяются изменения.

Будьте осторожны. Данный способ на бесплатных тарифах не подразумевает какую-то историю изменений или версионность. Если дизайнер что-то поменял в макете и обновил это в сервисе – изменения применятся в проекте.

Amazon Style Dictionary

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

Команда Amazon в 2017 году представила собственную библиотеку, которая помогает преобразовать JSON-файл в переменные для web (css, scss, less), iOS и Android-форматы.

У сервиса есть “песочница“, в которой можно поиграться и посмотреть на изменения в демо-карточке.

Сейчас постараюсь простыми словами объяснить, как установить и настроить данный компилятор.

Установка

Дальше мы будем действовать в интерфейсе CLI (command line interface), проще говоря из командной строки.

Для MacOS это встроенное приложение “Терминал”, для Windows это “Командная строка” (cmd). Но можно и в любом редакторе кода, который поддерживает данный интерфейс.

Шаг 1. Установка программной платформы npm

Нам необходимо установить глобальную программную платформу npm (Node Package Manager) (что это?) и node.js Это репозиторий для различных пакетов с приложениями. Если говорить на обывательском языке — магазин, где можно скачать приложение.

Установить node.js можно скачав с сайта, выбрав нужную операционную систему

Чтобы проверить, установлены ли у вас node.js и npm можно воспользоваться следующими командами в CLI:

node -v

и

npm -v

Когда мы убедились, что платформа установлена, переходим к установке Style Dictionary.

Шаг 2. Установка Style Dictionary

Введите в командной строке:

npm install -g style-dictionary

После этого дождитесь завершения установки

Шаг 3. Создание проекта

Нам необходимо перейти в нужную папку, где у вас лежит проект и где будет дополнительно развернут Style Dictionary (как указать путь к папке в CLI?).

cd путь к папке

Теперь инициируем базовый проект, он создаст все необходимые директории и файлы:

style-dictionary init basic

После этой команды вы должны увидеть такое:

Copying starter files...

Source style dictionary starter files created!

Running `style-dictionary build` for the first time to generate build artifacts.


scss
✔︎  build/scss/_variables.scss

android
✔︎  build/android/font_dimens.xml
✔︎  build/android/colors.xml

compose
✔︎ build/compose/StyleDictionaryColor.kt
✔︎ build/compose/StyleDictionarySize.kt

ios
✔︎  build/ios/StyleDictionaryColor.h
✔︎  build/ios/StyleDictionaryColor.m
✔︎  build/ios/StyleDictionarySize.h
✔︎  build/ios/StyleDictionarySize.m

ios-swift
✔︎  build/ios-swift/StyleDictionary.swift

ios-swift-separate-enums
✔︎  build/ios-swift/StyleDictionaryColor.swift
✔︎  build/ios-swift/StyleDictionarySize.swift

Это сообщение говорит о том, что созданы файлы для scss, android, compose, ios, ios-swift.

В структуре вы обнаружите папки и файлы:

• tokens — в ней содержатся json с демо-токенами;
• build — все артефакты, скомпилированные из json
• config.json — файл с настройками.

Шаг 4. Проверка

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

После того как измените, необходимо пересобрать проект командой:

style-dictionary build

Это главная команда, которую необходимо вызывать после того, как вносите изменения в JSON.

Шаг 5. Настройка

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

• source — отвечает за то, из каких папок и какие файлы необходимо конвертировать;
• platforms — массив настроек, который отвечает за платформу, в которую компилируем;
• scss (ios, android, css) — название платформы и внутри нее локальные настройки этой платформы;
• transforms — дополнительные настройки преобразования величин и значений;
• transformGroup — в какой формат файла преобразовываем;
• buildPath — папка, куда будут складываться преобразованные файлы;
• destinations — название файла;
• format — формат, в который будет преобразован JSON

const StyleDictionary = require('style-dictionary').extend({
  source: ['tokens/**/*.json'],
  platforms: {
    scss: {
      transforms: ["attribute/cti", "name/cti/kebab", "color/hex", "size/rem"],
      transformGroup: 'scss',
      buildPath: 'build/',
      files: [{
        destination: 'variables.scss',
        format: 'scss/variables'
      }]
    }
    // ...
  }
});

StyleDictionary.buildAllPlatforms();

В этом файле настройки объединяются по платформам и гибко настраиваются форматы и пути. Так же есть ряд дополнительных настроек.

Из дополнительных настроек, на которые стоит обратить внимание это transforms. В этой строчке можно задать конвертацию значений из px в sp/dp/pt/rem, из hex в rgb/hsl, и форматы названия переменных kebab-case и camelCase.

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

Токены для компонентов

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

Но токены имеют гибкую конструкцию и их можно использовать в описании конкретных компонентов. Подробную историю рассказал Кристиано Растелли, который делал дизайн-систему Cosmos для Badoo.

При таком подходе мы можем гибко управлять не только глобальными стилями, но и конкретными компонентами.

Но запомните, что чем больше переменных — тем сложнее их поддерживать. Будьте аккуратнее и разумны.

Если вы уже проделывали такое или собираетесь — напишите мне пожалуйста, поделитесь опытом.

Немного советов

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

Делюсь несколькими советами, надеюсь они будут ценны.

Размеры

Я видел несколько неймингов по размерной сетке и в градации сотых чисел и в так называемых “майках”.

$size-100: 4px;
$size-200: 8px;
...
$size-s: 4px;
$size-m: 8px;

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

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

$size-base: 4px;
$size-x1: $size-base;
$size-x2: $size-base*2;
...
$size-x10: $size-base*10;

Таким образом участникам команды не придется держать в голове всю размерную сетку, а всего лишь ее базовое значение в 4px, а глядя на название переменной можно понять, какое значение будет на выходе. Если мы захотим поставить отступы в 16px, то необходимо использовать переменную $size-x4.

К тому же, если вы захотите изменить базовый шаг, скажем на 2px, то размерная сетка автоматически пересчитается.

Цвет

Цвет можно считать автоматически, подставляя необходимые переменные и используя усилители цвета в SCSS.

Цвет можно считать в HEX, забивая в переменную базовый цвет, осветлять (lighten) или затемнять (darken) его. Как только базовый цвет изменится — палитра автоматически пересчитается. Важно то, что непрозрачность остается 100%, меняется само цветовое значение.

$color-base: #ffcc00;
$color-base-primary: $color-base;
$color-base-hover: darken($color-base,10%);
$color-base-active: lighten($color-base,10%);

Или можно посчитать в HSL, взяв за основу оттенок (hue), изменяя только насыщение (saturation) и яркость (lightness):

$color-accent: 72;
$color-accent-default: hsla($color-accent, 100%, 36%, 1);
$color-accent-hover: hsla($color-accent, 100%, 29%, 1);
$color-accent-active: hsla($color-accent, 53%, 44%, 1);

“A” — в модели hsla это альфа-канал непрозрачности.

Итоги

Как я уже говорил, если вы делаете сайтики и лендинги – вам не нужны дизайн токены.

Но они нужны, если

1. вы делаете несколько приложений и сервисов, которые должны быть консистентны, иметь единый вид
2. Если вы планируете темезацию, будь то светлая и темная тема одного приложения
3. Проектируете какое-то white label решение, которое кастомизируется под каждого заказчика.

Подстелить себе соломку – лишним уж точно не будет.

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

Но если все же вы понимаете, что вам это необходимо сделать и это точно закроет ваши проблемы, то следуйте простым правилам:

• заручитесь поддержкой разработки и узнайте, насколько они готовы вкладываться в это;
• проведите инвентаризацию текущих макетов в фигма;
• определитесь с категориями, что вы будете подвергать токенизации;
• разложите по смысловым группам стили и приведите в порядок семантические названия. И здесь важно договориться с разработкой о том, как будет понятнее всем;
• выберите необходимый инструмент – простой сервис zeroheight или выгрузка через плагины;
• если через плагины, то определитесь, какая библиотека будет компилировать ваши файлы;
• выстройте максимально прозрачный путь с разработкой, чтобы вы говорили на одном языке;
• и последний, немаловажный путь – наслаждайтесь!

Полезные материалы

Подкаст

Видео

Статьи

• Что такое дизайн-токены?Давайте разбираться вместе
• Дизайн-токены способны на большее: создаем единый источник информации о компонентах UI
• Как использовать дизайн-токены в React — опыт команды Bit
• Что такое Design токены?