@ws-serenity/radix-design-tokens

About

@ws-serenity/radix-design-tokens пакет токенов дизайн-системы.

Токены организованы в 3 слоя:

1. primitives сырые значения
2. semantics роли и смыслы интерфейса
3. components токены конкретных компонентов

Базовый принцип использования:

• primitives содержат исходные значения: цвета, размеры, opacity, shadow, z-index, font и т.д.
• semantics ссылаются на primitives и отвечают на вопрос: зачем используется значение
• components ссылаются на semantics и primitives и отвечают на вопрос: где именно в компоненте используется значение
• стили компонентов должны использовать только component tokens

Структура

Primitives

Файлы слоя primitives:

• breakpoints.scss
• colors.scss
• durations.scss
• fonts.scss
• opacities.scss
• radiuses.scss
• shadows.scss
• sizes.scss
• zIndexes.scss

Это lowest-level токены. Они не описывают роль интерфейса, только значение.

Примеры:

--color-white
--color-blue-base-light-1
--font-size-16
--font-weight-bold
--duration-500
--opacity-30
--size-24
--z-index-100

Semantics

Файлы слоя semantics:

• background.scss
• border.scss
• duration.scss
• icon.scss
• radius.scss
• space.scss
• text.scss

Это слой ролей интерфейса. Он не привязан к конкретному компоненту.

Примеры:

--background-primary-color
--background-secondary-color
--duration-md-time
--text-primary-color
--text-error-color
--icon-accent-color
--radius-pill-size
--space-sm-size

Components

Файлы слоя components:

• accordion.scss
• button.scss
• calendar.scss
• card.scss
• checkbox.scss
• chip.scss
• dateInput.scss
• modal.scss
• radioGroup.scss
• scrollbar.scss
• selectInput.scss
• selectInputDropdown.scss
• skeleton.scss
• switch.scss
• textInput.scss
• textareaInput.scss
• tooltip.scss
• typography.scss

Это слой токенов конкретных компонентов.

Примеры:

--button-primary-text-color
--button-sm-icon-width-size
--accordion-content-text-color
--textInput-primary-border-color
--scrollbar-thumb-background-color

Правила слоёв

1. Primitives

Используются для хранения raw values.

Допустимо:

--size-16: 16px;
--color-white: #ffffff;

Не должны описывать роль интерфейса:

• нельзя использовать названия компонентов
• нельзя использовать смысловые роли вроде primary button или input error

2. Semantics

Используются для описания роли токена в интерфейсе.

Допустимо:

--text-primary-color: var(--color-dark);
--background-secondary-color: var(--color-blue-base-light-1);

Как правило:

• semantic token должен ссылаться на primitive
• raw value допустим только в редком случае, когда для него нет подходящего primitive token

Пример:

--radius-circle-size: 50%;
--radius-pill-size: 9999px;

3. Components

Используются только для конкретного компонента.

Допустимо:

--button-primary-text-color: var(--text-inverse-color);
--checkbox-border-color: var(--border-primary-color);
--textInput-primary-border-color: var(--border-primary-color);

Как правило:

• component token должен ссылаться на semantic или primitive
• raw value нежелателен
• в стилях компонентов должен использоваться только component token

Нейминг токенов

Используется модель:

1. Component (для компонентных) / Context (для семантических)
2. Variant / Role
3. Element
4. Sub-element / Detail
5. Property
6. Category
7. State

Component tokens

Для component tokens первый сегмент это имя компонента.

Формат:

--{component}-{variant/role}-{element}-{sub-element/detail}-{property}-{category}-{state}

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

Базовый принцип:

• Component это имя компонента, которому принадлежит токен: button, textInput, accordion, radioGroup
• Variant / Role это вариант компонента или роль внутри компонента: primary, secondary, tertiary, sm, lg, desktop
• Element это конкретная часть компонента: item, trigger, content, thumb, overlay, icon, headline1
• Sub-element / Detail это деталь внутри элемента или отступ, если ему присваивается значение: text, background, border, icon, font, paddingTop, paddingRight, paddingBottom, paddingLeft, rowGap, columnGap
• Property это свойство выбранного элемента или подэлемента: width, height, minHeight, lineHeight, positionLeft, animation, transition
• Category это категория значения из примитивов: color, duration, opacity, radius, size, zIndex
• State это состояние компонента или элемента: hover, active, disabled, focus, selected, checked

Разбор component tokens по частям:

| Token | Component | Variant / Role | Element | Sub-element / Detail | Property | Category | State | | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | | --typography-desktop-headline1-font-lineHeight | typography | desktop | headline1 | font | lineHeight | - | - | | --textInput-primary-border-color | textInput | primary | border | - | - | color | - | | --dateInput-border-width-size | dateInput | - | border | - | width | size | - | | --checkbox-paddingBottom-size | checkbox | - | - | paddingBottom | - | size | - | | --modal-overlay-animation-duration | modal | - | overlay | - | animation | duration | - | | --calendar-sm-icon-width-size | calendar | sm | icon | - | width | size | - | | --accordion-chevron-transition-duration | accordion | - | chevron | - | transition | duration | - | | --button-tertiary-border-width-size | button | tertiary | border | - | width | size | - | | --button-secondary-background-color-active | button | secondary | background | - | - | color | active | | --radioGroup-indicatorWrapper-border-width-size | radioGroup | - | indicatorWrapper | border | width | size | - |

Правило разделения сегментов:

• если значение относится к самостоятельной части компонента, она идёт в Element: item, trigger, content, thumb, overlay, description, errorMessage
• если внутри этой части нужно выделить отдельную видимую деталь, она идёт в Sub-element: text, background, border, icon, padding, gap
• если токен описывает не сам элемент, а его конкретное свойство, после него добавляется Property

Semantic tokens

Для semantic tokens первый сегмент это Context, а не Components.

Формат:

--{context}-{variant/role}-{property}-{category}-{state}

Разбор semantic tokens по частям:

| Token | Context | Variant / Role | Property | Category | State | | ------ | ------ | ------ | ------ | ------ | ------ | | --background-primary-color | background | primary | - | color | - | | --background-error-color | background | error | - | color | - | | --text-placeholder-color | text | placeholder | - | color | - | | --icon-md-width-size | icon | md | width | size | - | | --icon-lg-height-size | icon | lg | height | size | - | | --border-inverse-color-hover | border | inverse | - | color | hover | | --border-sm-size | border | sm | - | size | - | | --duration-md-time | duration | md | - | time | - | | --space-3xl-size | space | 3xl | - | size | - | | --radius-circle-size | radius | circle | - | size | - |

Primitive tokens

Primitive tokens именуются по категории и raw value / raw family.

Разбор primitive tokens по частям:

| Token | Category | Family / Group | Variant / Scale | Value / Index | | ------ | ------ | ------ | ------ | ------ | | --color-white | color | white | - | - | | --color-blue-base-light-1 | color | blue | base-light | 1 | | --font-family-primary | font | family | primary | - | | --font-size-16 | font | size | - | 16 | | --font-weight-bold | font | weight | bold | - | | --font-lineHeight-120 | font | lineHeight | - | 120 | | --duration-500 | duration | - | - | 500 | | --opacity-30 | opacity | - | - | 30 | | --radius-4 | radius | - | - | 4 | | --shadow-sm | shadow | - | sm | - | | --size-24 | size | - | - | 24 | | --z-index-100 | z-index | - | - | 100 |

Breakpoints

breakpoints особый случай.

Они лежат в lib/primitives/breakpoints.scss как scss переменные, а не как CSS custom properties, потому что CSS custom properties нельзя использовать в @media так же, как обычные токены.

Доступные breakpoint variables:

• $breakpoint-laptop-lg
• $breakpoint-laptop-sm
• $breakpoint-tablet-lg
• $breakpoint-tablet-sm
• $breakpoint-mobile-lg
• $breakpoint-mobile-sm

Практическое правило использования

Если нужен новый токен:

1. Сначала проверить, существует ли подходящий component token
2. Если нет проверить, существует ли подходящий semantic token
3. Если нет проверить, существует ли подходящий primitive token
4. Только после этого добавлять новый токен на нужный слой

Правило выбора слоя:

• если токен отвечает на вопрос «какое это значение?» это primitive
• если токен отвечает на вопрос «зачем это значение?» это semantic
• если токен отвечает на вопрос «где это значение используется?» это component