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

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

# Использование базовых свойств

Миксины базовых свойств — это ваш основной инструмент для применения цветов к UI-компонентам. Вместо написания обычного CSS-свойства, например `color: black;`, вы вызываете:

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

.my-text {
  @include styles.color(#000000);
}
```

Этот подход гарантирует, что цвет будет корректно разложен на RGB-каналы, а для компонента будут созданы и применены необходимые системные переменные прозрачности.

## Доступные базовые миксины

Ключевые миксины, работающие по идентичному принципу. Все эти миксины принимают общие параметры (значение цвета и прозрачность), которые подробно описаны ниже:

- `color()` — для цвета текста (`color`). Системная переменная: `--sys-color`.
- `backgroundColor()` — для цвета фона (`background-color`). Системная переменная: `--sys-background`.
- `borderColor()` — для обводки границ (`border-color`). Системная переменная: `--sys-border`.
- `outlineColor()` — для цвета внешнего контура (`outline-color`). Системная переменная: `--sys-outline`.
- `fill()` — для заливки векторных элементов (`fill`). Системная переменная: `--sys-fill`.
- `stroke()` — для обводки векторных элементов (`stroke`). Системная переменная: `--sys-stroke`.
- `gradient()` — для сплошного цвета, применяемого к свойствам, ожидающим изображение (`background-image`). Системная переменная: `--sys-gradient`.

### Параметр `$color`

Все эти миксины принимают цвет в качестве первого параметра, который может быть одним из трех типов:

#### 1. Явный цвет (HEX, RGB или CSS переменная)

Чаще всего вы будете передавать цвет из нашей дизайн-системы, используя функцию `styles.getColor('название-цвета')`, базовые HEX-значения или пользовательскую CSS переменную `var(--my-color)`:

```scss
.card {
  @include styles.backgroundColor(styles.getColor('surface'));
  @include styles.color(#333333);
}
```

#### 2. Специальное значение `'as-color'`

Что делать, если вам нужно, чтобы цвет границы, контура или фона точно совпадал с текущим системным цветом текста (`--sys-color`)? Вы можете передать строку `'as-color'`:

```scss
.button-outline {
  // Текст становится синим
  @include styles.color(styles.getColor('primary'));
  
  // Рамка автоматически подхватит синий цвет из --sys-color
  @include styles.borderColor('as-color');
}
```
Это мощный инструмент для создания компонентов, меняющих свой цвет целиком (текст + рамка + иконки) с помощью изменения всего одной переменной `--sys-color`.

#### 3. Специальное значение `'init'`

Передача `'init'` применяется при необходимости **форсированного обновления** свойства без изменения базового цвета. Например, если прозрачность (`--sys-color-opacity`) была изменена напрямую через CSS, и вы хотите, чтобы браузер повторно применил свойство `color`:

```scss
.text-reset {
  @include styles.color('init');
}
```

### Управление прозрачностью (`$opacity`)

Второй параметр миксинов — `$opacity`. Он позволяет управлять начальной прозрачностью элемента.

```scss
.text-faded {
  // Текст с прозрачностью 50%
  @include styles.color(#000000, 0.5);
}
```

Если передать `null` (или ничего не передавать), прозрачность будет сброшена до стандартной из системной переменной.
Вы также можете передать CSS переменную, если прозрачность должна динамически меняться:

```scss
.dynamic-fade {
  @include styles.backgroundColor(#ff0000, var(--custom-opacity));
}
```

## Работа с локальными переменными: `colorSys`

Иногда вам нужно сохранить цвет в переменной, но не применять его сразу к свойству (например, для передачи цвета дочернему компоненту). Для этого используйте миксин `colorSys`:

```scss
.parent {
  // Устанавливает --sys-color и --sys-color-opacity: 0.8
  @include styles.colorSys('color', #ff0000, 0.8);
}
```
Первый параметр — это «имя свойства», которое станет суффиксом в переменной `--sys-[имя]`. Затем этот цвет может быть применен в дочерних узлах через `color('init')` или считан в CSS `rgba(var(--sys-color), 1)`.
