Соглашения об именовании токенов

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

Распространённая схема: [category]-[property]-[variant]. Примеры: color-text-primary, color-text-secondary, spacing-inset-sm. Каждый сегмент последовательно уточняет значение.

Избегайте имён палитры, таких как blue-500, в компонентах. Используйте семантические имена: color-action-default, color-feedback-error. Семантические имена сохраняются при изменении фирменных цветов, не требуя обновления компонентов.

Добавляйте состояние в конец: color-button-bg-default, color-button-bg-hover, color-button-bg-disabled. Последовательные суффиксы состояний делают наборы токенов предсказуемыми и полными.

Последовательно используйте обозначения размеров (xs, sm, md, lg, xl) или числовые шкалы (100, 200...900). Числовые шкалы позволяют добавлять промежуточные значения, а обозначения размеров понятнее для небольших наборов.

Для систем с несколькими брендами или продуктами добавляйте к токенам префикс пространства имён: brand-a-color-primary и brand-b-color-primary. Пространства имён предотвращают конфликты при объединении наборов токенов.

Имена в стиле kebab-case напрямую преобразуются в пользовательские свойства CSS: color-text-primary становится --color-text-primary. Имена токенов в camelCase требуют преобразования, а имена в kebab-case — нет.

Хорошие имена сами служат документацией: spacing-stack-md (вертикальный интервал между расположенными друг над другом элементами, средний) передаёт назначение без комментария. Для понимания плохих имён, таких как s3, нужна внешняя документация.

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

Проверяйте имена токенов с помощью собственных правил в Style Dictionary или скрипта CI. Отклоняйте токены, не соответствующие схеме именования. Автоматический контроль предотвращает постепенное расхождение имён по мере роста системы.

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

Почему для токенов компонентов следует использовать семантические имена, а не имена палитры вроде «blue-500»?

Согласованное соглашение об именовании токенов, основанное на шаблонах «категория-свойство-вариант», семантических именах, суффиксах состояния и префиксах пространства имён, делает систему токенов предсказуемой, самодокументируемой и устойчивой к изменениям бренда, не нарушая код компонентов.