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

# Базовый рабочий процесс

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

Этот документ описывает типичные рабочие процессы и паттерны разработки, используемые при создании пользовательских интерфейсов с помощью `@ui8kit/core`. Он охватывает распространенные сценарии, с которыми сталкиваются разработчики при компоновке компонентов, применении стилизации через систему вариантов и построении стандартных паттернов UI, таких как карточки, формы и макеты.

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

**Источники:** [.devin/wiki.json181-188](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L181-L188) [src/components/README.md1-259](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L1-L259)

***

## Рабочий процесс выбора компонента

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

```
Да

Нет

Да

Нет

Да

Нет

Начало: Нужно отрисовать UI

Нужна структура
макета?

Нужен семантический
контейнер?

Нужен готовый
стилизованный компонент?

Уровень 1: Базовые примитивы

Уровень 2: UI-компоненты

Уровень 3: Макеты

Box
(универсальный контейнер)

Block
(семантический элемент)

Grid
(CSS Grid)

Flex
(Flexbox)

Stack
(вертикальный/горизонтальный)

Button

Card + подкомпоненты

Text

Title

Container

Badge

Group

Icon

Image

DashLayout

LayoutBlock

SplitBlock
```

**Матрица принятия решений:**

| Сценарий | Выбор компонента | Причина |
| - | - | - |
| Универсальный контейнер со стилями | `Box` | Гибкий примитив с полной поддержкой вариантов |
| Семантический HTML-элемент (section, article, nav) | `Block` | Рендерит семантические теги через проп `component` |
| Сеточный макет | `Grid` | CSS Grid с адаптивными пресетами |
| Flexbox-макет | `Flex` или `Stack` | Flex для общих случаев, Stack для вертикального/горизонтального |
| Интерактивная кнопка | `Button` | Готовый стиль с вариантами и состояниями |
| Контентная карточка | `Card` | Составной компонент с Header/Content/Footer |
| Шаблон дашборда | `DashLayout` | Полный макет с боковой панелью и шапкой |

**Источники:** [README.md62-103](https://github.com/ui8kit/core/blob/2afe2195/README.md#L62-L103) [src/components/README.md9-19](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L9-L19) [README.md363-387](https://github.com/ui8kit/core/blob/2afe2195/README.md#L363-L387)

***

## Рабочий процесс базовой стилизации

Все компоненты принимают пропы вариантов вместо строк className. Этот рабочий процесс показывает, как применять стилизацию через систему вариантов.

```
Вывод

Обработка CVA

Категории вариантов

Экземпляр компонента

Пропы отступов
p, m, px, py, и т.д.

Пропы цветов
bg, c, borderColor

Визуальные пропы
rounded, shadow, border

Пропы макета
w, h, position

Типографические пропы
size, weight, align

spacingVariants

colorVariants

roundedVariants

shadowVariants

layoutVariants

typographyVariants

Классы Tailwind
p-8 rounded-xl shadow-md
```

### Пошагово: Стилизация компонента

**Шаг 1: Применение вариантов отступов**

```
// Импорт компонента
import { Box } from '@ui8kit/core';

// Применение внутренних и внешних отступов
<Box p="lg" m="md" mx="auto">
  Контент
</Box>
```

Доступные значения отступов: `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `auto`

**Шаг 2: Применение вариантов цветов**

```
<Box p="lg" bg="card" c="foreground">
  Контент с семантическими цветами
</Box>
```

**Шаг 3: Применение визуальных эффектов**

```
<Box p="lg" bg="card" rounded="xl" shadow="md" border="default">
  Стилизованный контейнер
</Box>
```

**Шаг 4: Применение вариантов макета**

```
<Box p="lg" w="full" h="screen" position="relative">
  Макет на всю ширину
</Box>
```

### Справочник пропов вариантов

| Категория | Пропы | Значения |
| - | - | - |
| **Отступы** | `p`, `px`, `py`, `pt`, `pb`, `pl`, `pr` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl` |
| **Отступы** | `m`, `mx`, `my`, `mt`, `mb`, `ml`, `mr` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `auto` |
| **Цвета** | `bg`, `c`, `borderColor` | Токены цветов дизайн-системы |
| **Скругление** | `rounded` | `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full` |
| **Тень** | `shadow` | `none`, `sm`, `md`, `lg`, `xl`, `2xl` |
| **Макет** | `w`, `h`, `minH`, `maxW` | `auto`, `full`, `screen`, `fit`, `min`, `max` |
| **Позиция** | `position` | `static`, `relative`, `absolute`, `fixed`, `sticky` |

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

***

## Рабочие процессы паттернов макетов

### Вертикальная укладка с `Stack`

Наиболее распространенный паттерн макета — это вертикальная укладка элементов.

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

<Stack gap="lg" align="center" p="md">
  <Title order={1}>Заголовок</Title>
  <Text>Описательный текст</Text>
  <Button variant="primary">Действие</Button>
</Stack>
```

**Ключевые пропы `Stack`:**

* `gap`: Пространство между дочерними элементами (`xs`, `sm`, `md`, `lg`, `xl`, `2xl`)
* `align`: Выравнивание по поперечной оси (`start`, `center`, `end`, `stretch`)
* `justify`: Выравнивание по главной оси (`start`, `center`, `end`, `between`, `around`)

**Источники:** [src/components/README.md52-64](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L52-L64)

### Горизонтальный макет с `Group`

Для горизонтальных расположений используйте `Group`.

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

<Group gap="md" align="center" justify="between">
  <Button variant="secondary">Отмена</Button>
  <Button variant="primary">Подтвердить</Button>
</Group>
```

**Источники:** [src/components/README.md66-78](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L66-L78)

### Сеточный макет с `Grid`

Для многоколоночных макетов используйте `Grid` с адаптивными пресетами.

```
import { Grid, GridCol, Card } from '@ui8kit/core';

<Grid cols="1-2-3" gap="lg" p="md">
  <GridCol span={2}>
    <Card p="lg">Широкая колонка</Card>
  </GridCol>
  <GridCol>
    <Card p="lg">Обычная колонка</Card>
  </GridCol>
</Grid>
```

**Значения пресета `cols`:**

* `"1-2-3"`: 1 колонка на мобильных, 2 на планшетах, 3 на десктопе
* `"2"`: 2 колонки на всех разрешениях
* Кастомные: Используйте стандартные пропы Grid

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

### Адаптивный контейнер

Используйте `Container` для центрированных макетов с максимальной шириной.

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

<Container size="lg" px="md" centered>
  <Card p="lg">
    Центрированный контент с адаптивной максимальной шириной
  </Card>
</Container>
```

**Размеры контейнера:**

* `xs`: 448px
* `sm`: 640px
* `md`: 768px
* `lg`: 1024px
* `xl`: 1280px

**Источники:** [src/components/README.md39-50](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L39-L50)

***

## Паттерны UI-компонентов

### Работа с карточками

`Card` — это составной компонент с семантическими подкомпонентами.

```
Card (корневой контейнер)

Card.Header

Card.Title

Card.Description

Card.Content

Card.Footer

data-class='card'

data-class='card-header'

data-class='card-title'

data-class='card-content'

data-class='card-footer'
```

**Пошагово: Построение карточки**

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

<Card p="lg" rounded="xl" shadow="md" bg="card">
  <Card.Header>
    <Card.Title>Заголовок</Card.Title>
    <Card.Description>Необязательное описание</Card.Description>
  </Card.Header>
  
  <Card.Content>
    <Stack gap="md">
      <Text>Основной контент размещается здесь</Text>
      <Text c="muted-foreground">Дополнительные детали</Text>
    </Stack>
  </Card.Content>
  
  <Card.Footer>
    <Button variant="primary">Действие</Button>
  </Card.Footer>
</Card>
```

**Источники:** [src/components/README.md96-117](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L96-L117) [README.md121-145](https://github.com/ui8kit/core/blob/2afe2195/README.md#L121-L145)

### Работа с кнопками

`Button` поддерживает варианты, размеры, состояния загрузки и секции с иконками.

```
import { Button } from '@ui8kit/core';
import { Heart } from 'lucide-react';

// Базовая кнопка
<Button variant="primary" size="md">
  Нажми меня
</Button>

// Кнопка с иконкой
<Button 
  variant="default" 
  leftSection={<Heart size={16} />}
  rounded="md"
  shadow="sm"
>
  Избранное
</Button>

// Состояние загрузки
<Button variant="primary" loading={isLoading}>
  Отправить
</Button>
```

**Варианты кнопки:**

* `default`: Стандартная кнопка
* `primary`: Основное действие
* `secondary`: Второстепенное действие
* `destructive`: Опасные действия
* `outline`: Стиль с обводкой
* `ghost`: Минималистичный стиль
* `link`: Стиль ссылки

**Источники:** [src/components/README.md119-133](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L119-L133)

### Работа с типографикой

Используйте `Title` для заголовков и `Text` для основного контента.

```
import { Title, Text, Stack } from '@ui8kit/core';

<Stack gap="md">
  <Title order={1} size="3xl" weight="bold" c="primary">
    Главный заголовок
  </Title>
  
  <Title order={2} size="2xl" weight="semibold">
    Подзаголовок
  </Title>
  
  <Text size="lg" c="muted-foreground" align="left">
    Основной текст с семантической стилизацией
  </Text>
  
  <Text size="sm" weight="medium" truncate>
    Усеченный текст для сценариев переполнения
  </Text>
</Stack>
```

**Сопоставление `Title` order:**

* `order={1}`: тег `<h1>`
* `order={2}`: тег `<h2>`
* `order={3}`: тег `<h3>`
* (продолжается до `order={6}`)

**Источники:** [src/components/README.md150-177](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L150-L177)

### Работа с бейджами

Используйте `Badge` для индикаторов статуса и меток.

```
import { Badge, Group } from '@ui8kit/core';
import { CheckCircle } from 'lucide-react';

<Group gap="sm">
  <Badge variant="success" size="sm" rounded="full">
    Активен
  </Badge>
  
  <Badge 
    variant="default" 
    dot
    rightSection={<CheckCircle size={14} />}
  >
    Проверен
  </Badge>
</Group>
```

**Варианты бейджа:**

* `default`: Стандартный бейдж
* `success`: Зеленый/позитивный
* `warning`: Желтый/предупреждение
* `error`: Красный/негативный
* `outline`: Стиль с обводкой

**Источники:** [src/components/README.md135-148](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L135-L148)

***

## Рабочий процесс семантического HTML

Используйте `Block` с пропом `component` для рендера семантических HTML5-элементов.

```
import { Block, Title, Text } from '@ui8kit/core';

<Block component="section" py="xl" bg="background">
  <Block component="article" p="lg" rounded="lg">
    <Title order={2}>Заголовок статьи</Title>
    <Text>Контент статьи</Text>
  </Block>
</Block>

<Block component="nav" p="md" bg="card">
  <Block component="ul">
    <Block component="li">Элемент навигации</Block>
  </Block>
</Block>

<Block component="header" py="md" border="bottom">
  <Title>Заголовок страницы</Title>
</Block>

<Block component="footer" py="lg" bg="muted">
  <Text size="sm">Контент подвала</Text>
</Block>
```

**Распространенные семантические элементы:**

* `section`: Тематическая группировка
* `article`: Самодостаточный контент
* `nav`: Навигационные ссылки
* `header`: Вводный контент
* `footer`: Контент подвала
* `aside`: Контент боковой панели
* `main`: Основная область контента

**Источники:** [src/components/README.md23-37](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L23-L37) [README.md14](https://github.com/ui8kit/core/blob/2afe2195/README.md#L14-L14)

***

## Распространенные сценарии разработки

### Сценарий 1: Построение карточки функции

```
import { Card, Title, Text, Button, Stack, Badge } from '@ui8kit/core';
import { CheckCircle } from 'lucide-react';

export function FeatureCard() {
  return (
    <Card variant="outlined" p="xl" rounded="xl" shadow="lg">
      <Card.Header>
        <Stack gap="sm">
          <Badge variant="success" size="sm">
            Новое
          </Badge>
          <Title order={3} size="xl" weight="bold">
            Премиум-функция
          </Title>
        </Stack>
      </Card.Header>
      
      <Card.Content>
        <Stack gap="md">
          <Text size="md" c="muted-foreground">
            Разблокируйте расширенные возможности с нашим премиум-планом.
          </Text>
          <Stack gap="xs">
            <Text size="sm">
              ✓ Расширенная аналитика
            </Text>
            <Text size="sm">
              ✓ Приоритетная поддержка
            </Text>
            <Text size="sm">
              ✓ Пользовательские интеграции
            </Text>
          </Stack>
        </Stack>
      </Card.Content>
      
      <Card.Footer>
        <Button 
          variant="primary" 
          w="full"
          leftSection={<CheckCircle size={16} />}
        >
          Обновить сейчас
        </Button>
      </Card.Footer>
    </Card>
  );
}
```

**Источники:** [README.md310-339](https://github.com/ui8kit/core/blob/2afe2195/README.md#L310-L339) [src/components/README.md96-117](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L96-L117)

### Сценарий 2: Построение макета формы

Когда специфичные для форм компоненты недоступны, компонуйте макеты, используя `Block` и `Box`.

```
import { Card, Block, Box, Title, Text, Button, Stack } from '@ui8kit/core';

export function FormCard() {
  return (
    <Card variant="outlined" p="xl" rounded="xl">
      <Card.Header>
        <Title order={2} size="2xl">
          Регистрация
        </Title>
      </Card.Header>
      
      <Card.Content>
        <Stack gap="md">
          <Box>
            <Text weight="medium" mb="xs">
              Email
            </Text>
            <Box 
              component="input"
              type="email"
              p="sm"
              rounded="md"
              border="default"
              w="full"
            />
          </Box>
          
          <Box>
            <Text weight="medium" mb="xs">
              Пароль
            </Text>
            <Box 
              component="input"
              type="password"
              p="sm"
              rounded="md"
              border="default"
              w="full"
            />
          </Box>
        </Stack>
      </Card.Content>
      
      <Card.Footer>
        <Stack gap="md" direction="row">
          <Button variant="secondary" w="full">
            Отмена
          </Button>
          <Button variant="primary" w="full">
            Зарегистрироваться
          </Button>
        </Stack>
      </Card.Footer>
    </Card>
  );
}
```

**Примечание:** Для продвинутых рабочих процессов с пользовательскими компонентами форм см. [Продвинутый рабочий процесс](#5.2).

**Источники:** [README.md310-339](https://github.com/ui8kit/core/blob/2afe2195/README.md#L310-L339) [src/components/README.md315-328](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L315-L328)

### Сценарий 3: Построение секции дашборда

```
import { Block, Container, Grid, Card, Title, Text, Badge } from '@ui8kit/core';

export function DashboardSection() {
  return (
    <Block component="section" py="xl" bg="background">
      <Container size="lg">
        <Stack gap="lg">
          <Title order={1} size="3xl">
            Обзор дашборда
          </Title>
          
          <Grid cols="1-2-3" gap="lg">
            <Card p="lg" shadow="md">
              <Stack gap="sm">
                <Badge variant="success">Активно</Badge>
                <Title order={3}>Всего пользователей</Title>
                <Text size="2xl" weight="bold">1,234</Text>
              </Stack>
            </Card>
            
            <Card p="lg" shadow="md">
              <Stack gap="sm">
                <Badge variant="default">В ожидании</Badge>
                <Title order={3}>Новые заказы</Title>
                <Text size="2xl" weight="bold">56</Text>
              </Stack>
            </Card>
            
            <Card p="lg" shadow="md">
              <Stack gap="sm">
                <Badge variant="warning">Предупреждение</Badge>
                <Title order={3}>Проблемы</Title>
                <Text size="2xl" weight="bold">3</Text>
              </Stack>
            </Card>
          </Grid>
        </Stack>
      </Container>
    </Block>
  );
}
```

**Источники:** [README.md155-168](https://github.com/ui8kit/core/blob/2afe2195/README.md#L155-L168) [src/components/README.md80-92](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L80-L92)

### Сценарий 4: Адаптивная навигация

```
import { Block, Container, Group, Button, Image } from '@ui8kit/core';

export function Navbar() {
  return (
    <Block component="nav" py="md" bg="card" border="bottom">
      <Container size="xl">
        <Group justify="between" align="center">
          <Image 
            src="/logo.svg" 
            alt="Логотип" 
            w="auto" 
            h="8"
          />
          
          <Group gap="md">
            <Button variant="ghost" size="sm">
              Главная
            </Button>
            <Button variant="ghost" size="sm">
              О нас
            </Button>
            <Button variant="ghost" size="sm">
              Контакты
            </Button>
          </Group>
          
          <Group gap="sm">
            <Button variant="outline" size="sm">
              Войти
            </Button>
            <Button variant="primary" size="sm">
              Регистрация
            </Button>
          </Group>
        </Group>
      </Container>
    </Block>
  );
}
```

**Источники:** [src/components/README.md66-78](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L66-L78) [src/components/README.md39-50](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L39-L50)

***

## Таргетирование атрибутов данных

Все UI-компоненты включают атрибуты `data-class` для семантического таргетирования в CSS и тестах.

```
<Card data-class="card">
  <Card.Header data-class="card-header">
    <Card.Title data-class="card-title">Заголовок</Card.Title>
  </Card.Header>
  <Card.Content data-class="card-content">
    Контент
  </Card.Content>
</Card>
```

**Пример таргетирования в CSS:**

```
[data-class="card"] {
  /* Пользовательские стили карточки */
}

[data-class="card-header"] {
  /* Пользовательские стили шапки */
}
```

**Пример селектора в тестах:**

```
// В тестах
const card = screen.getByTestId('card');
const header = within(card).getByTestId('card-header');
```

**Источники:** [src/components/README.md223-236](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L223-L236)

***

## Итоговая таблица рабочих процессов

| Задача | Используемые компоненты | Ключевые пропы | Паттерн |
| - | - | - | - |
| Вертикальный макет | `Stack` | `gap`, `align` | Вертикальная укладка элементов |
| Горизонтальный макет | `Group` | `gap`, `justify` | Горизонтальное расположение элементов |
| Сеточный макет | `Grid`, `GridCol` | `cols`, `gap`, `span` | Многоколоночные адаптивные макеты |
| Контентная карточка | `Card` + подкомпоненты | `p`, `rounded`, `shadow` | Card.Header → Content → Footer |
| Семантический контейнер | `Block` | `component`, варианты | Section, article, nav и т.д. |
| Интерактивная кнопка | `Button` | `variant`, `size`, состояния загрузки | Триггеры действий |
| Типографика | `Title`, `Text` | `order`, `size`, `weight` | Заголовки и основной текст |
| Индикатор статуса | `Badge` | `variant`, `size`, `dot` | Метки и статусы |
| Центрированный контент | `Container` | `size`, `centered` | Адаптивные макеты с максимальной шириной |
| Макет формы | `Block`, `Box` | Варианты отступов и границ | Пользовательские композиции форм |

**Источники:** [src/components/README.md1-259](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L1-L259) [README.md36-217](https://github.com/ui8kit/core/blob/2afe2195/README.md#L36-L217)


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