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

Стилизация VegaUI построена как многослойная система 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. используйте прямые переопределения стилей, только когда ни токены, ни задокументированные переменные не покрывают случай

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

## Пример

```tsx
<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
- предпочитайте задокументированные семантические переменные сырым значениям палитры
- держите вопросы темы глобальными, а переопределения компонентов — локальными