> ## Documentation Index
> Fetch the complete documentation index at: https://ui8kit.buildy.tw/llms.txt
> Use this file to discover all available pages before exploring further.

# Система вариантов

> Система вариантов UI8Kit Core - CVA-основное styling с 12 композируемыми категориями, охватывающими spacing, colors, layout, typography и effects

# Система вариантов

## Назначение и область применения

Система вариантов — это базовый слой стилизации `@ui8kit/core`, предоставляющий подход к стилизации компонентов на основе CVA (class-variance-authority). Эта система группирует утилитарные классы Tailwind CSS в 12 композируемых, переиспользуемых категорий вариантов, которые покрывают приблизительно 80% сценариев дизайна, устраняя необходимость в ручном управлении `className` и сокращая дублирование стилей в компонентах.

Данный документ охватывает архитектуру вариантов, 12 категорий вариантов, генерацию классов CVA, механику извлечения и паттерны композиции. Для информации о том, как компоненты используют эти варианты, см. [Базовые компоненты](#3.1) и [UI-компоненты](#3.3). Для извлечения классов вариантов во время сборки см. [Система сборки](#3.6).

**Источники:** [README.md170-217](https://github.com/ui8kit/core/blob/2afe2195/README.md#L170-L217) [.devin/wiki.json19-22](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L19-L22)

***

## Обзор архитектуры

Система вариантов работает как конвейер из трех этапов: определения вариантов, разрешение CVA и применение классов.

### Конвейер системы вариантов

```
Извлечение во время сборки

Этап 3: Применение классов

Этап 2: Разрешение CVA

Этап 1: Определения вариантов

safelist для

whitelist для

src/core/variants/
Определения CVA на TypeScript

12 категорий вариантов
spacing, colors, layout,
typography, effects

class-variance-authority
вызовы функции cva()

Пропсы компонента
p='lg', rounded='xl'

Сгенерированные классы
p-8 rounded-xl

Примитивы
Block, Box, Grid, Flex, Stack

Композитные
Card, Button, Badge

Макеты
DashLayout, LayoutBlock

scripts/cva-extractor.ts
Извлечение на основе AST

src/lib/core-classes.json
618 классов

Очистка Tailwind CSS

утилита tw-merge
```

**Источники:** [README.md64-88](https://github.com/ui8kit/core/blob/2afe2195/README.md#L64-L88) [scripts/cva-extractor.ts282-291](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L282-L291) [src/lib/core-classes.json1-624](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L1-L624)

***

## 12 категорий вариантов

Система предоставляет 12 категорий вариантов, организованных по области дизайна. Каждая категория преобразует понятные разработчику имена пропсов в утилитарные классы Tailwind CSS.

### Обзор категорий вариантов

| Категория | Пропсы вариантов | Диапазон значений | Назначение |
| - | - | - | - |
| **Отступы** | `p`, `m`, `px`, `py`, `pt`, `pb`, `pl`, `pr`, `mx`, `my`, `mt`, `mb`, `ml`, `mr` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `auto` | Управление padding и margin |
| **Цвета** | `bg`, `c`, `borderColor` | Токены системы дизайна: `primary`, `secondary`, `accent`, `destructive`, `muted`, `card`, `background`, `foreground` и т.д. | Применение семантических цветов |
| **Макет - Размеры** | `w`, `h`, `minH`, `maxW` | `auto`, `full`, `screen`, `fit`, `min`, `max` | Управление шириной и высотой |
| **Макет - Позиция** | `position` | `static`, `relative`, `absolute`, `fixed`, `sticky` | Позиционирование элементов |
| **Типографика - Размер** | `size` | `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl` | Масштабирование размера шрифта |
| **Типографика - Вес** | `weight`, `fw` | `normal`, `medium`, `semibold`, `bold` | Управление весом шрифта |
| **Типографика - Выравнивание** | `align`, `ta` | `left`, `center`, `right`, `justify` | Выравнивание текста |
| **Типографика - Межстрочный интервал** | `leading` | `tight`, `normal`, `relaxed` | Управление высотой строки |
| **Эффекты - Скругление** | `rounded` | `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full` | Радиус границ |
| **Эффекты - Тень** | `shadow` | `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `inner` | Применение box shadow |
| **Эффекты - Граница** | `border` | `0`, `default`, `2`, `4` + направленные варианты | Толщина границы |
| **Flexbox/Grid** | `gap`, `justify`, `items`, `cols`, `rows` | Контекстные значения | Выравнивание и отступы в макете |

**Источники:** [README.md174-217](https://github.com/ui8kit/core/blob/2afe2195/README.md#L174-L217) [src/components/README.md206-221](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L206-L221)

***

### Варианты отступов

Варианты отступов управляют padding и margin с использованием последовательной шкалы. Каждый вариант поддерживает направленные модификаторы.

#### Структура вариантов отступов

```
Шкала значений

Варианты Margin

Варианты Padding

p (все стороны)

px (горизонтально)

py (вертикально)

pt (сверху)

pr (справа)

pb (снизу)

pl (слева)

m (все стороны)

mx (горизонтально)

my (вертикально)

mt (сверху)

mr (справа)

mb (снизу)

ml (слева)

none → 0

xs → 1 (0.25rem)

sm → 2 (0.5rem)

md → 4 (1rem)

lg → 8 (2rem)

xl → 12 (3rem)

2xl → 16+ (4rem+)

auto → auto
```

**Примеры использования:**

```
// Padding со всех сторон
<Box p="lg">              // → p-8
<Box p="xl">              // → p-12

// Направленный padding
<Box px="md" py="lg">     // → px-4 py-8
<Box pt="sm" pb="xl">     // → pt-2 pb-12

// Автоматические margin для центрирования
<Box mx="auto">           // → mx-auto
<Box ml="auto">           // → ml-auto

// Комбинированные отступы
<Card p="xl" mb="lg">     // → p-12 mb-8
```

**Извлеченные классы (образец):**

```
["p-0", "p-1", "p-2", "p-4", "p-6", "p-8", "p-12",
 "px-0", "px-1", "px-2", "px-4", "px-6", "px-8", "px-12",
 "py-0", "py-1", "py-2", "py-4", "py-8", "py-16", "py-32", "py-48",
 "m-0", "m-1", "m-2", "m-4", "m-6", "m-8", "m-12", "m-auto",
 "mx-auto", "my-auto", "mt-auto", "mb-auto", "ml-auto", "mr-auto"]
```

**Источники:** [README.md174-181](https://github.com/ui8kit/core/blob/2afe2195/README.md#L174-L181) [src/lib/core-classes.json261-463](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L261-L463) [src/components/README.md209-212](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L209-L212)

***

### Варианты цветов

Варианты цветов применяют семантические цветовые токены системы дизайна к фону, тексту и границам. Цвета автоматически поддерживают темную тему через переменные Tailwind CSS.

#### Отображение вариантов цветов

```
Сгенерированные классы

Семантические токены

Пропсы цветов

bg
(фон)

c
(цвет текста)

borderColor
(граница)

primary /
primary-foreground

secondary /
secondary-foreground

accent /
accent-foreground

destructive /
destructive-foreground

muted /
muted-foreground

card /
card-foreground

background /
foreground

border / input / ring

bg-primary
bg-secondary
bg-accent
bg-destructive
bg-muted
bg-card
bg-background

text-primary
text-secondary
text-foreground
text-muted-foreground

border-primary
border-border
border-input
```

**Примеры использования:**

```
// Цвета фона
<Card bg="card">                    // → bg-card
<Button bg="primary">               // → bg-primary
<Badge bg="destructive">            // → bg-destructive

// Цвета текста
<Text c="foreground">               // → text-foreground
<Text c="muted-foreground">         // → text-muted-foreground
<Title c="primary">                 // → text-primary

// Цвета границ
<Box borderColor="border">          // → border-border
<Box borderColor="input">           // → border-input

// Комбинация с состояниями hover
<Button 
  bg="primary" 
  className="hover:bg-primary/90"
>                                   // → bg-primary hover:bg-primary/90
```

**Извлеченные классы (образец):**

```
["bg-primary", "bg-primary-foreground", "bg-secondary", "bg-secondary-foreground",
 "bg-accent", "bg-accent-foreground", "bg-destructive", "bg-destructive-foreground",
 "bg-muted", "bg-muted-foreground", "bg-card", "bg-background", "bg-foreground",
 "bg-border", "bg-input", "bg-ring", "bg-transparent",
 "text-primary", "text-secondary", "text-foreground", "text-muted-foreground",
 "border-primary", "border-secondary", "border-border", "border-input"]
```

**Источники:** [README.md183-190](https://github.com/ui8kit/core/blob/2afe2195/README.md#L183-L190) [src/lib/core-classes.json26-576](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L26-L576)

***

### Варианты макета

Варианты макета управляют размерами и позиционированием элементов. Варианты ширины и высоты поддерживают адаптивное и внутреннее изменение размеров.

#### Значения размеров макета

| Пропс | Значения | Сгенерированные классы | Вариант использования |
| - | - | - | - |
| `w` | `auto`, `full`, `screen`, `fit`, `min`, `max`, `px`, числовые | `w-auto`, `w-full`, `w-screen`, `w-fit`, `w-3` до `w-12` | Управление шириной |
| `h` | `auto`, `full`, `screen`, `fit`, `min`, `max`, `px`, числовые | `h-auto`, `h-full`, `h-screen`, `h-fit`, `h-3` до `h-12` | Управление высотой |
| `minH` | `full`, `screen`, `200px`, `300px`, `400px`, `500px` | `min-h-full`, `min-h-screen`, `min-h-[200px]` | Минимальная высота |
| `maxW` | `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `4xl`, `6xl`, `full`, `screen-*` | `max-w-sm`, `max-w-md`, `max-w-screen-lg` | Ограничения максимальной ширины |
| `position` | `static`, `relative`, `absolute`, `fixed`, `sticky` | `static`, `relative`, `absolute`, `fixed`, `sticky` | Режим позиционирования |

**Примеры использования:**

```
// Полная ширина/высота
<Box w="full" h="screen">              // → w-full h-screen

// Внутреннее изменение размера
<Box w="fit" h="auto">                 // → w-fit h-auto

// Минимальная высота
<Box minH="screen">                    // → min-h-screen
<Box minH="400px">                     // → min-h-[400px]

// Максимальная ширина с центрированием
<Container maxW="4xl" mx="auto">       // → max-w-4xl mx-auto

// Позиционирование
<Box position="relative">              // → relative
<Box position="absolute">              // → absolute
```

**Извлеченные классы (образец):**

```
["w-auto", "w-full", "w-screen", "w-fit", "w-min", "w-max", "w-px", "w-3", "w-4", "w-5", "w-6", "w-8", "w-10", "w-12",
 "h-auto", "h-full", "h-screen", "h-fit", "h-min", "h-max", "h-px", "h-3", "h-4", "h-5", "h-6", "h-8", "h-9", "h-10", "h-11", "h-12",
 "min-h-full", "min-h-screen", "min-h-[200px]", "min-h-[300px]", "min-h-[400px]", "min-h-[500px]",
 "max-w-sm", "max-w-md", "max-w-lg", "max-w-xl", "max-w-2xl", "max-w-4xl", "max-w-6xl", "max-w-full", "max-w-screen-sm", "max-w-screen-md",
 "static", "relative", "absolute", "fixed", "sticky"]
```

**Источники:** [README.md192-199](https://github.com/ui8kit/core/blob/2afe2195/README.md#L192-L199) [src/lib/core-classes.json196-606](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L196-L606)

***

### Варианты типографики

Варианты типографики управляют внешним видом текста: размером, весом, выравниванием и межстрочным интервалом (line height).

#### Матрица вариантов типографики

```
Вариант межстрочного интервала

tight → leading-tight

normal → leading-normal

relaxed → leading-relaxed

Вариант выравнивания

left → text-left

center → text-center

right → text-right

justify → text-justify

Вариант веса

normal → font-normal

medium → font-medium

semibold → font-semibold

bold → font-bold

Вариант размера

xs → text-xs

sm → text-sm

base → text-base

lg → text-lg

xl → text-xl

2xl → text-2xl

3xl → text-3xl

4xl → text-4xl

5xl → text-5xl
```

**Примеры использования:**

```
// Варианты размера
<Text size="sm">                    // → text-sm
<Title size="3xl">                  // → text-3xl

// Варианты веса
<Text weight="medium">              // → font-medium
<Title fw="bold">                   // → font-bold (fw - это алиас)

// Варианты выравнивания
<Text align="center">               // → text-center
<Text ta="right">                   // → text-right (ta - это алиас)

// Варианты межстрочного интервала
<Text leading="tight">              // → leading-tight

// Комбинированная типографика
<Title 
  size="2xl" 
  weight="bold" 
  align="center"
  leading="tight"
>                                   // → text-2xl font-bold text-center leading-tight
```

**Извлеченные классы:**

```
["text-xs", "text-sm", "text-base", "text-lg", "text-xl", "text-2xl", "text-3xl", "text-4xl", "text-5xl",
 "font-normal", "font-medium", "font-semibold", "font-bold",
 "text-left", "text-center", "text-right", "text-justify",
 "leading-tight", "leading-normal", "leading-relaxed"]
```

**Источники:** [README.md201-208](https://github.com/ui8kit/core/blob/2afe2195/README.md#L201-L208) [src/lib/core-classes.json150-579](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L150-L579)

***

### Варианты эффектов

Варианты эффектов применяют визуальные улучшения: скругленные углы, тени и границы.

#### Категории вариантов эффектов

| Категория | Пропс | Значения | Сгенерированные классы |
| - | - | - | - |
| **Скругление** | `rounded` | `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full` | `rounded-none`, `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`, `rounded-full` |
| **Тень** | `shadow` | `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `inner` | `shadow-none`, `shadow-sm`, `shadow-md`, `shadow-lg`, `shadow-xl`, `shadow-2xl`, `shadow-inner` |
| **Граница** | `border` | `0`, `default`, `2`, `4` + направленные (`t`, `r`, `b`, `l`) | `border-0`, `border`, `border-2`, `border-4`, `border-t`, `border-r`, `border-b`, `border-l` |

**Примеры использования:**

```
// Скругленные углы
<Card rounded="xl">                 // → rounded-xl
<Button rounded="full">             // → rounded-full
<Badge rounded="md">                // → rounded-md

// Тени
<Card shadow="lg">                  // → shadow-lg
<Box shadow="md">                   // → shadow-md

// Границы
<Box border="default">              // → border
<Box border="2">                    // → border-2
<Box border="t">                    // → border-t (только сверху)

// Комбинированные эффекты
<Card 
  rounded="2xl" 
  shadow="xl" 
  border="default"
  borderColor="border"
>                                   // → rounded-2xl shadow-xl border border-border
```

**Направленные варианты границ:**

```
// Верхняя граница
<Box border="t" border="2">         // → border-t-2

// Нижняя граница
<Box border="b" border="4">         // → border-b-4

// Левая и правая
<Box border="l" border="r">         // → border-l border-r
```

**Извлеченные классы (образец):**

```
["rounded-none", "rounded-sm", "rounded-md", "rounded-lg", "rounded-xl", "rounded-2xl", "rounded-3xl", "rounded-full",
 "rounded-t-none", "rounded-t-sm", "rounded-t-md", "rounded-t-lg", "rounded-t-xl", "rounded-t-full",
 "rounded-b-none", "rounded-b-sm", "rounded-b-md", "rounded-b-lg", "rounded-b-xl", "rounded-b-full",
 "rounded-l-none", "rounded-l-sm", "rounded-l-md", "rounded-l-lg", "rounded-l-xl", "rounded-l-full",
 "rounded-r-none", "rounded-r-sm", "rounded-r-md", "rounded-r-lg", "rounded-r-xl", "rounded-r-full",
 "shadow-none", "shadow-sm", "shadow-md", "shadow-lg", "shadow-xl", "shadow-2xl", "shadow-inner",
 "border", "border-0", "border-2", "border-4", "border-t", "border-r", "border-b", "border-l",
 "border-t-0", "border-t-2", "border-t-4", "border-b-0", "border-b-2", "border-b-4"]
```

**Источники:** [README.md210-217](https://github.com/ui8kit/core/blob/2afe2195/README.md#L210-L217) [src/lib/core-classes.json48-540](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L48-L540)

***

## Движок CVA и генерация классов

Система вариантов использует `class-variance-authority` (CVA) для преобразования API на основе пропсов в классы Tailwind CSS.

### Поток обработки CVA

```
Выходные данные: Классы Tailwind

Движок CVA

Определение CVA

Входные данные: Пропсы компонента

JSX компонента

p='lg'
rounded='xl'
shadow='md'
bg='card'

функция cva()

base: 'transition-all'

variants: {
  p: { lg: 'p-8' },
  rounded: { xl: 'rounded-xl' },
  shadow: { md: 'shadow-md' },
  bg: { card: 'bg-card' }
}

Разрешение вариантов

Объединение классов

Сгенерированный className

'transition-all p-8 rounded-xl shadow-md bg-card'

Применено к DOM-элементу
```

**Паттерн определения CVA:**

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

```
import { cva } from 'class-variance-authority';

export const spacingVariants = cva('', {
  variants: {
    p: {
      none: 'p-0',
      xs: 'p-1',
      sm: 'p-2',
      md: 'p-4',
      lg: 'p-8',
      xl: 'p-12',
      '2xl': 'p-16'
    },
    px: {
      none: 'px-0',
      xs: 'px-1',
      sm: 'px-2',
      md: 'px-4',
      lg: 'px-8',
      xl: 'px-12'
    }
    // ... больше вариантов отступов
  }
});
```

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

Компоненты импортируют и применяют варианты:

```
import { spacingVariants } from '@/core/variants';

// Пропсы передаются в функцию CVA
const className = spacingVariants({ p: 'lg', px: 'xl' });
// Результат: 'p-8 px-12'
```

**Источники:** [scripts/cva-extractor.ts114-143](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L114-L143) [README.md283-304](https://github.com/ui8kit/core/blob/2afe2195/README.md#L283-L304)

***

## Система извлечения и белого списка

Система сборки извлекает все классы, определенные в CVA, чтобы сгенерировать белый список для очистки Tailwind CSS и утилит `tw-merge`.

### Конвейер извлечения

```
Потребители

Выходные данные

Процесс извлечения

Исходные файлы

src/core/variants/
Все файлы .ts/.tsx

Определения CVA
cva('base', { variants: {...} })

scripts/cva-extractor.ts

@babel/parser
Разбор в AST

@babel/traverse
Поиск вызовов cva()

Извлечение классов из:
• Базовых строк
• Объектов вариантов
• Вложенных объектов
• Массивов

618 уникальных классов

src/lib/core-classes.json

timestamp: 2025-10-29T12:17:54.882Z

tailwind.config.js
конфигурация safelist

утилита tw-merge
белый список классов
```

**Детали скрипта извлечения:**

Скрипт извлечения [scripts/cva-extractor.ts1-339](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L1-L339) реализует следующие шаги:

1. **Рекурсивное сканирование** `src/core/variants/` для файлов `.ts` и `.tsx` [scripts/cva-extractor.ts67-93](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L67-L93)

2. **Разбор TypeScript** с использованием парсера Babel с плагинами `['typescript', 'jsx']` [scripts/cva-extractor.ts103-106](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L103-L106)

3. **Обход AST** для поиска узлов `CallExpression`, где callee является `cva` [scripts/cva-extractor.ts114-125](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L114-L125)

4. **Извлечение классов** из:

   * Строковых литералов (базовые классы) [scripts/cva-extractor.ts129-137](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L129-L137)
   * Объектных выражений (определения вариантов) [scripts/cva-extractor.ts138-142](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L138-L142)
   * Вложенных объектов и массивов [scripts/cva-extractor.ts164-195](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L164-L195)

5. **Разделение по пробелам** для отделения отдельных имен классов [scripts/cva-extractor.ts200-203](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L200-L203)

6. **Дедупликация** в Set, затем сортировка по алфавиту [scripts/cva-extractor.ts46-51](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L46-L51)

**Структура сгенерированного белого списка:**

Выходной файл [src/lib/core-classes.json1-624](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L1-L624) содержит:

```
{
  "classes": [
    "absolute",
    "bg-primary",
    "border",
    "flex",
    "gap-4",
    "p-8",
    "rounded-xl",
    "shadow-md",
    // ... всего 618 классов
  ],
  "count": 618,
  "timestamp": "2025-10-29T12:17:54.882Z"
}
```

**Использование в конфигурации Tailwind:**

```
// tailwind.config.js
const coreClasses = require('./src/lib/core-classes.json');

module.exports = {
  safelist: coreClasses.classes,
  // ... остальная конфигурация
};
```

**Источники:** [scripts/cva-extractor.ts1-339](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L1-L339) [src/lib/core-classes.json1-624](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L1-L624)

***

## Композиция вариантов

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

### Паттерны композиции

```
Композиция типографики

  size='2xl'
  weight='bold'
  align='center'
  leading='tight'
  c='primary'
/>

text-2xl font-bold text-center leading-tight text-primary

Направленная композиция

  px='lg'
  py='md'
  mt='xl'
  mb='sm'
/>

px-8 py-4 mt-12 mb-2

Композиция нескольких вариантов

  p='xl'
  rounded='2xl'
  shadow='lg'
  bg='card'
/>

p-12 rounded-2xl shadow-lg bg-card

Применение одного варианта

p-8
```

### Приоритет композиции

Когда варианты конфликтуют, порядок приоритета следующий:

1. **Пропсы, специфичные для компонента** (более высокая специфичность)
2. **Направленные варианты** (`px`, `py`) переопределяют общие варианты (`p`)
3. **Последний пропс побеждает** в списке пропсов компонента
4. **Пропс `className`** переопределяет все варианты (аварийный люк)

**Пример: Переопределение направления**

```
// py переопределяет вертикальную часть p
<Box p="lg" py="xl">
// Результат: p-8 py-12
// Tailwind применяет: padding: 2rem (из p-8), затем padding-top/bottom: 3rem (из py-12)
```

**Пример: Аварийный люк className**

```
// className для пользовательских стилей, не покрываемых вариантами
<Card 
  p="lg" 
  rounded="xl" 
  className="hover:scale-105 transition-transform"
>
// Результат: p-8 rounded-xl hover:scale-105 transition-transform
```

**Источники:** [src/components/README.md238-257](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L238-L257)

***

## Типобезопасность и IntelliSense

Система вариантов обеспечивает полную поддержку TypeScript для типобезопасного использования пропсов и автодополнения IntelliSense.

### Структура определения типов

```
Финальный тип компонента

Интерфейс пропсов компонента

Определение варианта

cva('', { variants: {...} })

VariantProps

ComponentPropsWithoutRef<'div'>

SpacingVariantProps
ColorVariantProps
LayoutVariantProps
EffectsVariantProps

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

type CardProps = 
  BaseProps &
  VariantProps &
  CustomProps

IntelliSense показывает:
• Все варианты
• Допустимые значения
• Описания
```

**Пример определения типов:**

```
// Определение варианта с извлечением типа
import { cva, type VariantProps } from 'class-variance-authority';

const spacingVariants = cva('', {
  variants: {
    p: {
      none: 'p-0',
      xs: 'p-1',
      sm: 'p-2',
      md: 'p-4',
      lg: 'p-8',
      xl: 'p-12'
    }
  }
});

// Извлечение типов пропсов вариантов
export type SpacingVariantProps = VariantProps<typeof spacingVariants>;
// Результат: { p?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' }

// Интерфейс пропсов компонента
interface CardProps extends ComponentPropsWithoutRef<'div'>, SpacingVariantProps {
  variant?: 'default' | 'outlined';
}
```

**Преимущества IntelliSense:**

1. **Автодополнение**: Введите `<Card p=` и IntelliSense покажет `'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'`
2. **Проверка типов**: Использование `<Card p="invalid">` приводит к ошибке TypeScript
3. **Документация**: Наведите курсор на пропсы, чтобы увидеть доступные значения
4. **Рефакторинг**: Безопасное переименование значений вариантов во всей кодовой базе

**Источники:** [README.md11-12](https://github.com/ui8kit/core/blob/2afe2195/README.md#L11-L12)

***

## Структура файлов системы вариантов

Система вариантов организована по областям в `src/core/variants/`:

```
src/core/variants/
├── spacing.ts          # Варианты padding и margin
├── colors.ts           # Варианты цвета фона, текста и границ
├── layout.ts           # Варианты ширины, высоты, позиции
├── typography.ts       # Варианты размера, веса, выравнивания, межстрочного интервала
├── effects.ts          # Варианты скругления, теней, границ
├── flex.ts             # Варианты выравнивания flexbox и gap
├── grid.ts             # Варианты макета grid
└── index.ts            # Экспорт всех вариантов
```

**Паттерн экспорта:**

Все варианты экспортируются из [src/index.ts1-3](https://github.com/ui8kit/core/blob/2afe2195/src/index.ts#L1-L3):

```
// Экспорт вариантов и утилит из core
export * from './core/variants';
```

Это позволяет потребителям импортировать варианты:

```
import { 
  spacingVariants, 
  colorVariants, 
  roundedVariants 
} from '@ui8kit/core';
```

**Источники:** [src/index.ts1-3](https://github.com/ui8kit/core/blob/2afe2195/src/index.ts#L1-L3)

***

## Паттерны использования

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

Примитивы (`Block`, `Box`, `Grid`, `Flex`, `Stack`) непосредственно применяют варианты:

```
import { Block, Box, Stack } from '@ui8kit/core';

<Block 
  component="section" 
  p="xl" 
  bg="background" 
  rounded="lg"
>
  <Stack gap="md" align="center">
    <Box w="full" h="auto" border="default" rounded="md">
      Контент
    </Box>
  </Stack>
</Block>
```

**Источники:** [README.md82-103](https://github.com/ui8kit/core/blob/2afe2195/README.md#L82-L103) [src/components/README.md23-92](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L23-L92)

***

### Паттерн 2: Проброс пропсов композитных компонентов

Композитные компоненты (`Card`, `Button`, `Badge`) расширяют примитивы и пробрасывают пропсы вариантов:

```
import { Card, Button, Text } from '@ui8kit/core';

<Card 
  p="lg" 
  rounded="xl" 
  shadow="md" 
  bg="card"
>
  <Card.Header>
    <Text size="xl" weight="bold" c="foreground">
      Заголовок
    </Text>
  </Card.Header>
  <Card.Content>
    <Text size="base" c="muted-foreground">
      Описание
    </Text>
  </Card.Content>
  <Card.Footer>
    <Button 
      bg="primary" 
      rounded="md" 
      px="lg" 
      py="md"
    >
      Действие
    </Button>
  </Card.Footer>
</Card>
```

**Источники:** [README.md38-145](https://github.com/ui8kit/core/blob/2afe2195/README.md#L38-L145) [src/components/README.md94-149](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L94-L149)

***

### Паттерн 3: Композиция шаблонов макета

Макеты используют варианты для последовательных отступов и структуры:

```
import { DashLayout, Container, LayoutBlock } from '@ui8kit/core';

<DashLayout>
  <Container maxW="6xl" px="lg" py="xl">
    <LayoutBlock 
      layout="grid" 
      gap="lg" 
      p="xl"
      bg="background"
      rounded="lg"
    >
      {/* Контент grid */}
    </LayoutBlock>
  </Container>
</DashLayout>
```

**Источники:** [README.md147-168](https://github.com/ui8kit/core/blob/2afe2195/README.md#L147-L168)

***

## Резюме

Система вариантов обеспечивает базовый слой стилизации для `@ui8kit/core` через:

* **12 композируемых категорий**: Отступы, цвета, макет, типографика и эффекты, покрывающие \~80% сценариев дизайна
* **Движок на основе CVA**: Типобезопасное разрешение вариантов с использованием `class-variance-authority`
* **618 извлеченных классов**: Извлечение во время сборки генерирует белый список для очистки Tailwind
* **API на основе пропсов**: Чистый опыт разработчика с `p="lg"` вместо `className="p-8"`
* **Полная типобезопасность**: Типы TypeScript обеспечивают IntelliSense и валидацию во время компиляции
* **Паттерны композиции**: Варианты легко комбинируются в примитивах, композитах и макетах

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

**Источники:** [README.md1-453](https://github.com/ui8kit/core/blob/2afe2195/README.md#L1-L453) [.devin/wiki.json19-22](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L19-L22) [scripts/cva-extractor.ts1-339](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L1-L339) [src/lib/core-classes.json1-624](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L1-L624)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.