CSS-переменные

Слои

1. исходные переменные токенов из @vega-ui/tokens-core
2. семантические переменные приложения из @vega-ui/theme-core
3. локальные переменные компонентов из packages/ui/src/**/style.module.css

Как слои работают вместе

Пример цепочки:

1. --color-blue-500 определяется в слое токенов
2. активная тема сопоставляет эту шкалу с семантическими переменными, такими как --color-blue-accent-500, --text-color или --fills-primary
3. компонент затем может предоставлять локальные переменные, такие как --select-value-color или --select-size

Поэтому документация компонентов должна различать три уровня переопределения:

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

Предпочтительный порядок переопределения

Начинайте с самого широкого безопасного уровня:

1. меняйте семантику темы, когда изменение должно затронуть много компонентов
2. меняйте локальные переменные компонента --component-*, когда должно измениться только одно семейство компонентов
3. используйте прямые переопределения стилей, только когда ни токены, ни задокументированные переменные не покрывают случай

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

Пример

<Select
  style={{
    '--select-size': '44px',
    '--select-value-color': 'var(--color-primary-700)',
  } as React.CSSProperties}
>
  {/* parts */}
</Select>

В этом примере:

• --color-primary-700 берётся из семантического слоя темы
• --select-size и --select-value-color — локальные переменные компонента

Рекомендации

• не считайте каждое пользовательское CSS-свойство в исходниках стабильным публичным API
• предпочитайте задокументированные семантические переменные сырым значениям палитры
• держите вопросы темы глобальными, а переопределения компонентов — локальными