SCSS-модули и токены (references/styling.md)

Источник: ds-skills/core-ui-development-skills/src/skills/build-core-ui-components/references/styling.md — справочник скилла build-core-ui-components

Использовать CSS Modules и kebab-case для классов.
Сначала искать дизайн-токены в теме и существующих компонентах. Не придумывать имена токенов.
Использовать токены для цветов, отступов, радиусов, типографики, теней и motion, когда токен существует.
Допускать вычисляемые inline-значения и необходимую геометрию, если они зависят от данных или токена нет; сверять исключение с аналогами.
Применять set-typography и scale-typography из src/typography/mixins.
Переиспользовать миксины из src/theme/mixins: square, circle, ellipsis-text, disable-text-selection и другие подходящие.
Не реализовывать переключение темы внутри компонента.
Добавлять disabled, active, focus-visible согласно семантике и похожим компонентам.
Не запрещать и не добавлять hover глобально — сверять с конкретным семейством.
Учитывать safe-area через --injected-safe-area-inset-*, когда компонент привязан к краю экрана.

Токены отступов и радиусов

Перед использованием токена отступа или радиуса обязательно проверить его точное имя в актуальной теме проекта:

отступы — src/theme/space.css;
радиусы — src/theme/radius.css;
способ применения — ближайшие актуальные компоненты и их Storybook-стили.

Не выводить имя токена из дизайнерского названия и не предполагать промежуточные значения. Например, наличие --space-m и --space-xl не означает, что существует --space-l.

Для CSS shorthand проверять каждый использованный токен. Если хотя бы одна переменная в выражении не определена, браузер отбросит всё свойство:

/* Некорректно, если --space-l отсутствует в src/theme/space.css. */
padding: var(--space-xl) var(--space-l);

Если точного токена нет:

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

При изменении Storybook использовать те же существующие theme-токены, что и в коде компонента. Storybook-пример не должен вводить несуществующие CSS-переменные.

Запрещённые legacy-токены

При создании и изменении компонентов не использовать токены из файлов:

src/theme/old-typography.css;
src/theme/chart-color.css.

Не считать импорт этих файлов в src/theme/index.scss разрешением для нового кода: они остаются подключёнными для обратной совместимости существующих компонентов.

Для типографики использовать актуальные текстовые компоненты core-ui, src/theme/typography-tokens.css и миксины из src/typography/mixins.scss. Для цветов выбирать существующие актуальные семантические или брендовые токены после проверки src/theme/brand-colors.css и ближайших компонентов.

Если макет требует значение, доступное только в old-typography.css или chart-color.css, не переносить legacy-токен автоматически. Зафиксировать расхождение и запросить решение по актуальной замене.