import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/styles/color/# Использование палитр'/>

# Использование палитр

Миксины палитр — это основной инструмент для работы с семантическими и системными цветами в DxtUI. Их главное назначение заключается в том, чтобы **автоматически поддерживать маршрутизацию CSS-переменных**, позволяя динамически менять темы и цветовые палитры компонентов "на лету", не нарушая изначальную контрастность дизайна.

Вместо базового свойства `backgroundColor()`, при работе с дизайн-системой вы используете специальный миксин:

```scss
@use '@dxtmisha/styles';

.my-button {
  // Применяем системный цвет 'primary'
  @include styles.paletteBackgroundColor('--d1-sys-palette-primary');
}
```

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

## Доступные миксины палитр

Ниже представлены ключевые миксины, работающие по идентичному принципу. В качестве единственного аргумента они принимают **строковое название системной CSS-переменной**.

- `paletteColor()` — Устанавливает цвет текста (`color`).
- `paletteBackgroundColor()` — Устанавливает цвет фона (`background-color`).
- `paletteBorderColor()` — Устанавливает цвет рамки (`border-color`).
- `paletteOutlineColor()` — Устанавливает цвет внешнего контура (`outline-color`).
- `paletteFill()` — Заливает векторные SVG-элементы (`fill`).
- `paletteStroke()` — Устанавливает цвет обводки SVG-элементов (`stroke`).

### Пример использования нескольких миксинов:

```scss
.card-alert {
  // Текст принимает системный цвет ошибки (красный)
  @include styles.paletteColor('--d1-sys-palette-error');
  
  // Фон принимает цвет поверхности
  @include styles.paletteBackgroundColor('--d1-sys-palette-surface');
  
  // Рамка принимает цвет рамки
  @include styles.paletteBorderColor('--d1-sys-palette-outline');
}
```

---

## Как это работает? (Архитектура маршрутизации)

Чтобы понять всю мощь миксинов `palette`, нужно взглянуть на то, как обрабатываются SCSS-строки во время сборки кода. Архитектура построена так, чтобы вам больше никогда не приходилось писать дополнительный CSS для переопределения цветов.

### Шаг 1: Системные переменные и базовые веса
Для начала, в файле конфигурации(`properties.scss`) задан реестр, который сопоставляет семантическое имя (например, `primary`) с конкретным "базовым весом" контрастности для светлой и темной тем.

Например, системный цвет `primary` в светлой теме всегда соответствует уровню плотности **`600`**. По умолчанию этот уровень привязан к синему цвету (`--d1-ref-palette-blue-600`).

### Шаг 2: Компиляция миксина
Когда вы вызываете миксин `paletteBackgroundColor('--d1-sys-palette-primary')`, препроцессор SCSS пропускает вашу строку через этот реестр. 

Вместо того чтобы просто вернуть синий цвет, он генерирует **умную каскадную CSS-переменную**, которая жестко привязывает цвет фона к "базовому" уровню `600`:

```css
/* Упрощенный пример сгенерированного CSS: */
background-color: var(--d1-palette-basic600, var(--d1-sys-palette-primary));
```

### Шаг 3: Смена палитры через HTML (DOM)
Представим, что мы оборачиваем наш компонент в HTML-контейнер и добавляем класс другой палитры:

```html
<div class="d1-palette--yellow">
  <button class="my-button">Нажми меня</button>
</div>
```

Класс `.d1-palette--yellow` переопределяет переменную `--d1-palette-basic600` на локальном уровне: теперь она ссылается на желтый цвет плотности `600` (`--d1-ref-palette-yellow-600`).

Так как наша кнопка через миксин `paletteBackgroundColor` сгенерировала и привязала себя напрямую к `basic600`, её фон моментально перекрасится в желтый.

**Главное преимущество:** 
Плотность цвета осталась ровно `600`. Это означает, что контрастность между белым текстом кнопки и её желтым фоном останется математически идеальной и выверенной. Разработчику не нужно писать ни строчки CSS (`.d1-palette--yellow .my-button { ... }`), чтобы перекрасить компонент вручную — всё происходит автоматически с помощью маршрутизации SCSS-переменных.

## Различие между базовыми миксинами и палитрами

Важно понимать принципиальную разницу в их логике:

- **Базовые миксины (`backgroundColor`, `color` и др.)**
  Они принимают **конкретное значение** (HEX, RGB или результат функции `getColor`). Эти миксины устанавливают цвет "как есть". Да, они поддерживают системную прозрачность, но сам цвет остается статичным. Если вы передали синий цвет через `getColor('primary')`, он останется синим, даже если вы добавите класс желтой палитры на родителя.

- **Миксины палитр (`paletteBackgroundColor`, `paletteColor` и др.)**
  Они принимают **строку-ключ** (название системной переменной, например `'--d1-sys-palette-primary'`). Эти миксины не устанавливают цвет напрямую, а создают **динамический маршрут** к переменным палитры (уровень `basic`). Именно это позволяет компоненту мгновенно "перекрашиваться" при смене класса палитры в DOM, сохраняя при этом нужный уровень контрастности.
