> ## 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 - композиция базовых примитивов для создания пользовательских интерфейсов при недостаточности композитных компонентов

# Продвинутый рабочий процесс

## Цель и область применения

Этот документ охватывает нестандартные сценарии, когда 15 составных UI-компонентов из [src/components/ui/](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/) недостаточны для вашей задачи. Вы узнаете, как компоновать пять базовых примитивов (`Block`, `Box`, `Grid`, `Flex`, `Stack`) из [src/core/ui/](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/) для создания пользовательских интерфейсов.

Для типичного использования компонентов с готовыми композитами см. [Базовый рабочий процесс](#5.1). Для общих рекомендаций по использованию и паттернов см. [Лучшие практики](#5.3).

**Источники:** [.devin/wiki.json191-198](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L191-L198) [src/components/GUIDE\_CREATE\_FORM.md1-10](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L1-L10)

***

## Когда использовать продвинутый рабочий процесс

Библиотека предоставляет 15 составных компонентов, которые покрывают \~80% обычных сценариев UI. Однако некоторые элементы намеренно отсутствуют в библиотеке:

| Отсутствующий тип компонента | Причина отсутствия | Продвинутое решение |
| - | - | - |
| Элементы форм (Form, Label, Input) | HTML-семантика сильно варьируется | Компоновать `Block` + `Box` с пропом `component` |
| Выпадающие списки Select | Требуется сложное управление состоянием | Использовать `Box component="select"` с вариантами |
| Пользовательские интерактивные виджеты | Специфическая для приложения логика | Строить с помощью примитивов + вариантов |
| Нестандартные макеты | Уникальные структурные требования | Компоновать `Grid`, `Flex`, `Stack` напрямую |

**Дерево решений: Базовый vs Продвинутый рабочий процесс**

```
Да

Нет

Да

Нет

Да

Нет

Нужен UI-элемент

Компонент существует в
src/components/ui/?

Использовать составной компонент
(Button, Card, Badge)

Стандартный HTML-элемент
со стилизацией?

Использовать Block/Box
с пропом component

Сложная структура
макета?

Компоновать Grid/Flex/Stack
с примитивами

Создать пользовательский компонент
из примитивов

Базовый рабочий процесс (5.1)

Продвинутый рабочий процесс (5.2)
```

**Источники:** [src/components/README.md1-8](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L1-L8) [src/components/GUIDE\_CREATE\_FORM.md5-10](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L5-L10)

***

## Построение форм с помощью Block и Box

Библиотека не включает специализированные компоненты Form, Label или Input. Вместо этого используйте полиморфный проп `component` на `Block` и `Box` для рендеринга семантических HTML-элементов с полной системой вариантов.

### Паттерн пропа component

Проп `component` преобразует примитивы в любой HTML-элемент, сохраняя типобезопасные пропы вариантов:

```
Пропы вариантов

Отрендеренные элементы

проп component

Примитивные компоненты

применяется к

применяется к

применяется к

применяется к

Block
(семантический контейнер)

Box
(гибкий примитив)

component='form'

component='label'

component='input'

component='textarea'

component='select'

<form>

<label>

<input>

<textarea>

<select>

p, m, px, py, и т.д.

w, h, maxW, minH

rounded, border, shadow

bg, c, borderColor
```

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md7-9](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L7-L9)

***

### Паттерн структуры формы

Используйте `Block` с `component="form"` как обёртку формы, применяя варианты макета и стилизации:

**Структура контейнера формы:**

| Элемент | Компонент | Пропы | Назначение |
| - | - | - | - |
| Обёртка формы | `<Block component="form">` | `w`, `maxW`, `p`, `rounded`, `shadow`, `bg` | Семантический контейнер формы с макетом |
| Группы полей | `<Block>` | `w="full"`, `className="space-y-2"` | Вертикальное расстояние между полями |
| Метки | `<Box component="label">` | `c`, `className="text-sm font-medium"` | Доступные метки полей |
| Поля ввода | `<Box component="input">` | `w="full"`, `p`, `rounded`, `border`, `borderColor` | Поля ввода формы |
| Текстовые области | `<Box component="textarea">` | `w="full"`, `p`, `rounded`, `border`, `minH` | Многострочный ввод текста |
| Кнопка отправки | `<Button>` | `w="full"`, `size`, `variant` | Отправка формы |

**Пример структуры формы** (см. [src/components/GUIDE\_CREATE\_FORM.md14-32](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L14-L32)):

```
<Block 
  component="form"
  w="full"
  maxW="md"
  p="lg"
  rounded="lg"
  shadow="md"
  bg="white"
>
  {/* Поля формы */}
</Block>
```

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md11-33](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L11-L33)

***

### Паттерны полей ввода

Все типы ввода используют `Box` с `component="input"` и стандартными HTML-атрибутами:

**Текстовое поле** ([src/components/GUIDE\_CREATE\_FORM.md37-50](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L37-L50)):

```
<Box 
  component="input"
  type="text"
  placeholder="Enter your name"
  w="full"
  p="md"
  rounded="md"
  border="default"
  borderColor="gray-300"
/>
```

**Поле с состояниями фокуса** ([src/components/GUIDE\_CREATE\_FORM.md54-67](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L54-L67)):

```
<Box 
  component="input"
  type="text"
  w="full"
  p="md"
  rounded="lg"
  border="default"
  bg="white"
  c="gray-900"
  className="focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
/>
```

**Поле пароля** ([src/components/GUIDE\_CREATE\_FORM.md70-82](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L70-L82)):

```
<Box 
  component="input"
  type="password"
  placeholder="Password"
  w="full"
  p="md"
  rounded="md"
  border="default"
  borderColor="gray-300"
/>
```

**Числовое поле с ограничениями** ([src/components/GUIDE\_CREATE\_FORM.md84-97](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L84-L97)):

```
<Box 
  component="input"
  type="number"
  placeholder="Age"
  w="full"
  p="md"
  rounded="md"
  border="default"
  min={0}
  max={120}
/>
```

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md35-97](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L35-L97)

***

### Поля Textarea

Используйте `Box` с `component="textarea"` для многострочного ввода текста:

**Базовая текстовая область** ([src/components/GUIDE\_CREATE\_FORM.md99-115](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L99-L115)):

```
<Box 
  component="textarea"
  rows={4}
  placeholder="Enter your message"
  w="full"
  p="md"
  rounded="md"
  border="default"
  borderColor="gray-300"
  className="resize-none"
/>
```

**Текстовая область с минимальной высотой** ([src/components/GUIDE\_CREATE\_FORM.md117-129](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L117-L129)):

```
<Box 
  component="textarea"
  placeholder="Description"
  w="full"
  p="md"
  rounded="lg"
  border="default"
  minH="32"
  className="resize-y"
/>
```

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md99-129](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L99-L129)

***

### Полный пример формы

**Архитектура контактной формы:**

```
Block component='form'
обработчик onSubmit
Макет: w='full' maxW='lg' p='lg'
Стиль: rounded='lg' shadow='lg' bg='white'

Block (группа поля имени)
w='full' space-y-2

Box component='label'
c='gray-700' text-sm font-medium

Box component='input'
type='text' name='name' required
w='full' p='md' rounded='md'
border='default' borderColor='gray-300'

Block (группа поля email)
w='full' space-y-2

Box component='label'
c='gray-700' text-sm font-medium

Box component='input'
type='email' name='email' required
w='full' p='md' rounded='md'

Block (группа поля сообщения)
w='full' space-y-2

Box component='label'
c='gray-700' text-sm font-medium

Box component='textarea'
rows=5 name='message' required
w='full' p='md' minH='32'
resize-none focus:ring-2

Button type='submit'
w='full' size='lg' variant='default'
```

Полная реализация в [src/components/GUIDE\_CREATE\_FORM.md134-226](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L134-L226) Ключевые паттерны:

1. **Обработка событий формы**: проп `onSubmit` на форме Block
2. **Структура полей**: обёртка Block → метка → поле ввода в каждой группе
3. **Расстояния**: `className="space-y-6"` на форме, `className="space-y-2"` на группах полей
4. **Валидация**: атрибут `required` на полях ввода
5. **Состояния фокуса**: комбинация вариантов с `className` для колец фокуса

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md131-226](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L131-L226)

***

### Многоколоночный макет формы

Для сложных форм используйте `Box` с grid-отображением ([src/components/GUIDE\_CREATE\_FORM.md228-277](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L228-L277)):

```
<Block 
  component="form"
  w="full"
  maxW="2xl"
  p="lg"
  rounded="lg"
  shadow="md"
  bg="white"
>
  <Box 
    display="grid" 
    className="grid-cols-1 md:grid-cols-2 gap-6"
  >
    {/* Поле имени */}
    <Block className="space-y-2">
      <Box component="label" className="text-sm font-medium">
        First Name
      </Box>
      <Box 
        component="input"
        type="text"
        w="full"
        p="md"
        rounded="md"
        border="default"
      />
    </Block>

    {/* Поле фамилии */}
    <Block className="space-y-2">
      <Box component="label" className="text-sm font-medium">
        Last Name
      </Box>
      <Box 
        component="input"
        type="text"
        w="full"
        p="md"
        rounded="md"
        border="default"
      />
    </Block>
  </Box>
</Block>
```

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md228-277](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L228-L277)

***

### Паттерн валидации формы

Создавайте переиспользуемые компоненты полей с валидацией ([src/components/GUIDE\_CREATE\_FORM.md311-339](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L311-L339)):

```
function ValidatedInput({ error, label, ...props }) {
  return (
    <Block w="full" className="space-y-2">
      <Box component="label" c="gray-700" className="text-sm font-medium">
        {label}
      </Box>
      <Box 
        component="input"
        w="full"
        p="md"
        rounded="md"
        border="default"
        borderColor={error ? "red-500" : "gray-300"}
        bg={error ? "red-50" : "white"}
        className={error ? "focus:ring-red-500" : "focus:ring-blue-500"}
        {...props}
      />
      {error && (
        <Box c="red-600" className="text-sm">
          {error}
        </Box>
      )}
    </Block>
  );
}
```

**Разбор паттерна:**

* Условные `borderColor` и `bg` на основе состояния ошибки
* Динамические цвета кольца фокуса через `className`
* Отображение сообщения об ошибке с `Box` для цвета текста
* Распространение пропов с `{...props}` для HTML-атрибутов

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md311-339](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L311-L339)

***

## Доступные пропы вариантов для примитивов

Все примитивы поддерживают 12 категорий вариантов CVA. Ключевые варианты для построения форм:

### Варианты расстояний

| Проп | Значения | Назначение |
| - | - | - |
| `p`, `px`, `py`, `pt`, `pb`, `pl`, `pr` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl` | Управление padding |
| `m`, `mx`, `my`, `mt`, `mb`, `ml`, `mr` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `auto` | Управление margin |

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

| Проп | Значения | Назначение |
| - | - | - |
| `w` | `auto`, `full`, `screen`, `fit`, `min`, `max`, `1/2`, `1/3`, и т.д. | Управление шириной |
| `h` | `auto`, `full`, `screen`, `fit`, `min`, `max` | Управление высотой |
| `minH` | Числовые значения типа `"32"`, `"64"` | Минимальная высота (полезно для textarea) |
| `maxW` | `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, и т.д. | Максимальная ширина (полезно для центрированных форм) |
| `display` | `block`, `flex`, `grid`, `inline`, `none` | Тип отображения |

### Варианты границ и стиля

| Проп | Значения | Назначение |
| - | - | - |
| `border` | `none`, `default`, `2`, `4`, `8` | Ширина границы |
| `borderColor` | Все цвета дизайн-системы | Цвет границы |
| `rounded` | `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full` | Радиус скругления |
| `shadow` | `none`, `sm`, `md`, `lg`, `xl`, `2xl` | Тень блока |

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

| Проп | Значения | Назначение |
| - | - | - |
| `bg` | Все цвета дизайн-системы (напр., `white`, `card`, `gray-50`) | Цвет фона |
| `c` | Все цвета дизайн-системы (напр., `gray-700`, `red-600`) | Цвет текста |

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md279-301](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L279-L301) [src/components/README.md205-222](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L205-L222)

***

## Лучшие практики для продвинутой компоновки

### Рекомендации для полей формы

1. **Всегда устанавливайте `w="full"`** на полях ввода для согласованной ширины ([src/components/GUIDE\_CREATE\_FORM.md304](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L304-L304))
2. **Используйте `Block` для структуры формы** (элемент формы, группы полей) ([src/components/GUIDE\_CREATE\_FORM.md305](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L305-L305))
3. **Используйте `Box` для фактических полей ввода** (input, textarea, select) ([src/components/GUIDE\_CREATE\_FORM.md306](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L306-L306))
4. **Комбинируйте пропы вариантов с Tailwind-классами** для состояний фокуса ([src/components/GUIDE\_CREATE\_FORM.md307](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L307-L307))
5. **Используйте `minH` для textarea** вместо фиксированной высоты ([src/components/GUIDE\_CREATE\_FORM.md308](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L308-L308))
6. **Применяйте `className="resize-none"`** для предотвращения изменения размера textarea при необходимости ([src/components/GUIDE\_CREATE\_FORM.md309](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L309-L309))

### Гибридный паттерн Вариант + className

Система вариантов покрывает \~80% потребностей в стилизации. Для оставшихся 20% комбинируйте варианты с `className`:

```
<Box 
  component="input"
  // Варианты покрывают структуру
  w="full"
  p="md"
  rounded="md"
  border="default"
  bg="white"
  // className покрывает интерактивные состояния
  className="focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
/>
```

**Когда использовать `className`:**

* Интерактивные состояния (`:hover`, `:focus`, `:active`)
* Псевдоэлементы (`:before`, `:after`)
* Сложные анимации
* Grid/flex утилиты, не покрытые вариантами
* Точки останова адаптивности за пределами системы вариантов

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md302-310](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L302-L310) [src/components/README.md237-244](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L237-L244)

***

## Пользовательская компоновка компонентов

### Создание переиспользуемых композитов

Когда вам нужен один и тот же паттерн многократно, извлеките его в пользовательский компонент:

**Паттерн: Поле ввода с меткой**

```
управляет

отображает

рендерит

Пользовательский компонент ValidatedInput

Обёртка Block
w='full' space-y-2

Box component='label'
c='gray-700'
text-sm font-medium

Box component='input'
w='full' p='md'
rounded='md' border='default'
Условно: borderColor, bg

Box (условный рендер)
c='red-600' text-sm
Отображает сообщение об ошибке

Пропы:
- error (string | undefined)
- label (string)
- ...props (HTML-атрибуты)
```

**Подход к реализации:**

1. Принимать пропы вариантов и HTML-атрибуты через распространение пропов
2. Обрабатывать условную логику (состояния ошибок, валидация)
3. Поддерживать доступность (ассоциации меток, ARIA-атрибуты)
4. Возвращать компоновку примитивов (Block + Box)

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md311-339](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L311-L339)

***

### Нестандартные пользовательские сценарии, не связанные с формами

**Пользовательские интерактивные виджеты:**

При создании специфичных для приложения виджетов (слайдеры, пикеры, пользовательские элементы управления):

1. **Начинайте с `Box` или `Block`** как контейнера
2. **Применяйте семантический проп `component`** (`<Box component="button">` для кликабельных элементов)
3. **Используйте пропы вариантов** для макета и стилизации
4. **Добавляйте обработчики событий** (`onClick`, `onChange`, и т.д.)
5. **Комбинируйте с `className`** для сложных взаимодействий

**Пользовательские структуры макета:**

Для уникальных требований к макету, не покрытых DashLayout, LayoutBlock или SplitBlock:

1. **Компонуйте `Grid`, `Flex` или `Stack`** из [src/core/ui/](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/)
2. **Применяйте варианты макета** (`cols`, `gap`, `align`, `justify`)
3. **Вкладывайте примитивы** для иерархической структуры
4. **Используйте `Block` с `component="section"`/`component="aside"`** для семантической разметки

**Источники:** [src/components/README.md237-244](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L237-L244) [.devin/wiki.json191-198](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L191-L198)

***

## Сравнение: Базовый vs Продвинутый рабочий процесс

**Когда использовать каждый подход:**

```
Продвинутый рабочий процесс (5.2)

Базовый рабочий процесс (5.1)

Да

Нет

Готовые компоненты существуют

Card, Button, Badge,
Title, Text, Image, Icon

Использовать составные компоненты
из src/components/ui/

Пример:
<Card p='lg' rounded='xl'>

Пользовательские требования

Элементы форм, пользовательские виджеты,
уникальные макеты

Компоновать примитивы
из src/core/ui/

Пример:
<Block component='form'>
<Box component='input'/>

Компонент существует
в библиотеке?
```

**Матрица возможностей:**

| Особенность | Базовый рабочий процесс | Продвинутый рабочий процесс |
| - | - | - |
| Скорость разработки | Быстрая (готовые компоненты) | Умеренная (ручная компоновка) |
| Гибкость | Ограничена пропами компонентов | Полный контроль через примитивы |
| Поддержка кода | Проще (меньше компонентов) | Более сложная (больше кода) |
| Типобезопасность | Полная (типы составных компонентов) | Полная (типы примитивных компонентов) |
| Поддержка вариантов | Через пробрасывание пропов | Прямое применение |
| Семантический HTML | Предопределённая структура | Полный контроль через проп `component` |
| Лучше всего для | Стандартных UI-паттернов | Пользовательских/уникальных требований |

**Источники:** [src/components/README.md1-19](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L1-L19) [src/components/GUIDE\_CREATE\_FORM.md1-10](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L1-L10)

***

## Резюме

Продвинутый рабочий процесс позволяет создавать пользовательские интерфейсы, когда 15 составных компонентов недостаточны:

1. **Формы**: Компонуйте `Block` + `Box` с пропом `component` для элементов форм, меток и полей ввода
2. **Пользовательские виджеты**: Используйте примитивы с семантическими пропами `component` и системой вариантов
3. **Уникальные макеты**: Компонуйте `Grid`, `Flex`, `Stack` для структурных требований
4. **Гибридный подход**: Комбинируйте пропы вариантов (\~80% покрытие) с `className` для граничных случаев

Для стандартных сценариев с существующими компонентами используйте [Базовый рабочий процесс](#5.1). Для общих рекомендаций см. [Лучшие практики](#5.3).

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md341-347](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L341-L347) [.devin/wiki.json191-198](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L191-L198)


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