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

# Руководство разработчика

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

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

***

## Обзор рабочего процесса разработки

Библиотека поддерживает три основных подхода к разработке на основе архитектурных слоев:

### Модель разработки на основе слоев

```
Слой стилизации

Слой 1: Базовые примитивы

Слой 2: UI-компоненты

Слой 3: Макеты

Дерево решений

Да

Нет

Да

Нет

Да

Начало разработки

Нужна пользовательская структура макета?

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

Нужен базовый примитив?

Использование компонентов макетов

Использование составных компонентов

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

DashLayout
src/layouts/DashLayout.tsx

LayoutBlock
src/layouts/LayoutBlock.tsx

SplitBlock
src/layouts/SplitBlock.tsx

Button
src/components/ui/Button.tsx

Card + Card.Header/Content/Footer
src/components/ui/Card.tsx

Accordion
src/components/ui/Accordion.tsx

Sheet
src/components/ui/Sheet.tsx

Box
src/core/ui/Box.tsx

Block
src/core/ui/Block.tsx

Grid
src/core/ui/Grid.tsx

Flex
src/core/ui/Flex.tsx

Stack
src/core/ui/Stack.tsx

Применение вариантов CVA
src/core/variants/

spacingVariants

colorVariants

layoutVariants

typographyVariants

effectsVariants
```

**Источники**: [README.md64-169](https://github.com/ui8kit/core/blob/2afe2195/README.md#L64-L169) [.devin/wiki.json4-5](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L4-L5)

***

## Руководство по выбору компонентов

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

| Сценарий | Слой | Выбор компонента | Пример использования |
| - | - | - | - |
| **Приложение панели управления** | Слой 3 | `DashLayout` | Админ-панель с боковой панелью, заголовком, изменяемыми панелями |
| **Секция контента с сеткой** | Слой 3 | `LayoutBlock` | Секции целевой страницы с несколькими блоками контента |
| **Разделение на два столбца** | Слой 3 | `SplitBlock` | Сравнение функций, макеты изображение + текст |
| **Кнопка действия** | Слой 2 | `Button` | Отправка формы, навигация, призывы к действию |
| **Карточка контента** | Слой 2 | `Card` | Карточки товаров, статьи блога, профили пользователей |
| **Сворачиваемые секции** | Слой 2 | `Accordion` | FAQ, панели настроек |
| **Боковой выдвижной элемент** | Слой 2 | `Sheet` | Мобильное меню, фильтры, уведомления |
| **Пользовательская форма** | Слой 1 | `Block` + `Box` | Элементы формы, когда UI-компонентов недостаточно |
| **Универсальный контейнер** | Слой 1 | `Box` | Обертка с конкретными потребностями в стилизации |
| **Макет CSS Grid** | Слой 1 | `Grid` | Фотогалереи, сетки товаров |
| **Макет Flexbox** | Слой 1 | `Flex` | Панели навигации, панели инструментов |
| **Вертикальный/горизонтальный стек** | Слой 1 | `Stack` | Поля формы, группы кнопок |

**Источники**: [README.md80-169](https://github.com/ui8kit/core/blob/2afe2195/README.md#L80-L169) [.devin/wiki.json7-13](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L7-L13)

***

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

### Поток вариантов в разработке

```
Применение к компонентам

Обработка во время выполнения

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

Рабочий процесс разработчика

Написание JSX с пропсами вариантов

Выбор из 12 категорий вариантов

TypeScript валидирует пропсы

Отступы: p, m, px, py, mx, my и т.д.
src/core/variants/spacingVariants.ts

Цвета: bg, c, borderColor
src/core/variants/colorVariants.ts

Макет: w, h, minH, maxW, position
src/core/variants/layoutVariants.ts

Типография: size, weight, align, leading
src/core/variants/typographyVariants.ts

Эффекты: rounded, shadow, border
src/core/variants/effectsVariants.ts

class-variance-authority
разрешает варианты

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

core-classes.json
белый список из 618 классов
src/lib/core-classes.json

Базовые примитивы
Прямое применение вариантов

Составные компоненты
Проброс пропсов

Отрендеренный DOM
с атрибутами data-class
```

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

***

## Общие паттерны разработки

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

Для базовых потребностей в макете используйте базовые примитивы с вариантами:

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

// Простой контейнер с вариантами
<Box p="lg" bg="card" rounded="xl" shadow="md">
  <Stack gap="md">
    {/* контент */}
  </Stack>
</Box>
```

**Когда использовать**: Пользовательские макеты, простые обертки, структуры форм.

**Файлы компонентов**: [src/core/ui/Box.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/Box.tsx) [src/core/ui/Stack.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/Stack.tsx)

***

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

Для предварительно стилизованных UI-элементов используйте компоненты слоя 2:

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

// Составной компонент с составными частями
<Card p="lg" shadow="md">
  <Card.Header>
    <Card.Title>Заголовок</Card.Title>
  </Card.Header>
  <Card.Content>
    Контент
  </Card.Content>
  <Card.Footer>
    <Button variant="primary">Действие</Button>
  </Card.Footer>
</Card>
```

**Когда использовать**: Стандартные UI-паттерны, согласованная стилизация в приложении.

**Файлы компонентов**: [src/components/ui/Card.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Card.tsx) [src/components/ui/Button.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Button.tsx)

***

### Паттерн 3: Использование шаблонов макетов

Для структуры приложения используйте макеты слоя 3:

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

// Шаблон панели управления
<DashLayout 
  sidebar={<Sidebar />}
  header={<Header />}
>
  <Container>
    {/* основной контент */}
  </Container>
</DashLayout>
```

**Когда использовать**: Приложения панели управления, админ-панели, сложные многосекционные страницы.

**Файлы компонентов**: [src/layouts/DashLayout.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/layouts/DashLayout.tsx) [src/components/ui/Container.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Container.tsx)

***

### Паттерн 4: Проброс пропсов с вариантами

Составные компоненты наследуют пропсы вариантов от примитивов:

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

// Button расширяет Box, наследует все пропсы вариантов
<Button 
  variant="primary"
  size="md"
  p="lg"           // вариант отступов из Box
  rounded="xl"     // вариант эффектов из Box
  shadow="sm"      // вариант эффектов из Box
>
  Отправить
</Button>
```

**Когда использовать**: Требуется дополнительная стилизация помимо стандартных настроек компонента.

**Файлы компонентов**: [src/components/ui/Button.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Button.tsx) [src/core/ui/Box.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/Box.tsx)

***

### Паттерн 5: Хуки контента в макетах

Макеты поддерживают динамическую инъекцию контента:

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

<LayoutBlock
  layout="grid"
  contentHooks={{
    beforeContent: () => <Header />,
    content: () => <MainContent />,
    afterContent: () => <Footer />
  }}
/>
```

**Когда использовать**: Гибкие секции контента, динамические макеты.

**Файлы компонентов**: [src/layouts/LayoutBlock.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/layouts/LayoutBlock.tsx)

**Источники**: [README.md36-60](https://github.com/ui8kit/core/blob/2afe2195/README.md#L36-L60) [README.md278-338](https://github.com/ui8kit/core/blob/2afe2195/README.md#L278-L338)

***

## Подходы к интеграции

### Выбор метода установки

```
Метод 4: Прямой исходный код

Метод 3: Git Submodule

Метод 2: Установка по компонентам

Метод 1: Полная установка NPM

Факторы решения

Да

Нет

Да

Нет

Да

Нет

Да

Нет

Выбор метода интеграции

Нужна вся библиотека?

Критичен размер бандла?

Архитектура монорепозитория?

Требуется пользовательская сборка?

npm install @ui8kit/core

Импорт всех 18 компонентов

Использует dist/index.js
модули ES2022

npx buildy-ui add button card

Читает метаданные registry.json

Копирует конкретные файлы в
components/ui/ или layouts/

git submodule add
Unsupported markdown: link

packages/@ui8kit/core

Импорт из пути субмодуля

Копирование каталога src/

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

Полный контроль над компиляцией
```

**Источники**: [README.md252-276](https://github.com/ui8kit/core/blob/2afe2195/README.md#L252-L276) [.devin/wiki.json15-17](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L15-L17) [src/registry.json](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json)

***

## Настройка среды разработки

### Необходимые зависимости

| Зависимость | Тип | Назначение | Установка |
| - | - | - | - |
| `react` | Peer | Фреймворк React | `npm install react@^18` или `@^19` |
| `react-dom` | Peer | Рендеринг React DOM | `npm install react-dom@^18` или `@^19` |
| `tailwindcss` | Dev | Утилитарный CSS | `npm install -D tailwindcss` |
| `class-variance-authority` | Direct | Движок вариантов | Включен в `@ui8kit/core` |
| `lucide-react` | Direct | Иконки (Sheet, Accordion) | Включен в `@ui8kit/core` |
| `react-resizable-panels` | Direct | Изменяемые панели (DashLayout) | Включен в `@ui8kit/core` |

**Источники**: [package.json](https://github.com/ui8kit/core/blob/2afe2195/package.json) [README.md22-34](https://github.com/ui8kit/core/blob/2afe2195/README.md#L22-L34)

***

### Конфигурация Tailwind

Настройте Tailwind для обработки классов библиотеки:

```
// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@ui8kit/core/dist/**/*.js',
  ],
  darkMode: 'class',
  safelist: [
    // Включите core-classes.json при необходимости
  ],
};
```

Импортируйте белый список для конфигурации safelist:

```
const coreClasses = require('@ui8kit/core/src/lib/core-classes.json');

module.exports = {
  safelist: coreClasses,
};
```

**Файлы конфигурации**: [src/lib/core-classes.json](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json)

**Источники**: [README.md29-34](https://github.com/ui8kit/core/blob/2afe2195/README.md#L29-L34) [src/lib/core-classes.json](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json)

***

## Жизненный цикл компонента в разработке

### От выбора до рендеринга

```
Фаза выполнения

Фаза сборки

Фаза разработки

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

Безопасность типов

Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list
```

**Источники**: [README.md422-440](https://github.com/ui8kit/core/blob/2afe2195/README.md#L422-L440) [.devin/wiki.json4-5](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L4-L5)

***

## Работа с атрибутами Data-Class

Все компоненты используют атрибуты `data-class` для согласованного таргетинга DOM:

### Паттерн идентификации компонентов

```
// Компонент Card рендерится с data-class
<Card p="lg">
  {/* Рендерится как: */}
  {/* <div data-class="card" class="p-8">...</div> */}
</Card>

// Составные компоненты поддерживают иерархию
<Card.Header>
  {/* Рендерится как: */}
  {/* <div data-class="card-header">...</div> */}
</Card.Header>
```

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

```
// Запрос по data-class в тестах
const card = screen.getByTestId('[data-class="card"]');
const header = screen.getByTestId('[data-class="card-header"]');

// CSS-селекторы
[data-class="card"] { /* стили */ }
[data-class="button"][data-variant="primary"] { /* стили */ }
```

**Файлы компонентов**: [src/components/ui/Card.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Card.tsx) [src/components/ui/Button.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Button.tsx)

**Источники**: [.devin/wiki.json11-13](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L11-L13)

***

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

Компоненты используют `forwardRef` для доступа к ref базовых DOM-элементов:

### Доступ к Ref в разработке

```
import { Button, Box } from '@ui8kit/core';
import { useRef } from 'react';

function MyComponent() {
  const buttonRef = useRef<HTMLButtonElement>(null);
  const boxRef = useRef<HTMLDivElement>(null);
  
  const handleClick = () => {
    buttonRef.current?.focus();
    boxRef.current?.scrollIntoView();
  };
  
  return (
    <>
      <Button ref={buttonRef}>Фокус на мне</Button>
      <Box ref={boxRef}>Прокрутить ко мне</Box>
    </>
  );
}
```

**Когда использовать refs**: Управление полями формы, контроль прокрутки, управление фокусом, измерения DOM.

**Файлы компонентов**: [src/core/ui/Box.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/Box.tsx) [src/core/ui/Block.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/Block.tsx) [src/components/ui/Button.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Button.tsx)

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

***

## Безопасность типов в разработке

### Интеграция с TypeScript

Все компоненты предоставляют полные определения типов:

```
import type { ButtonProps, CardProps } from '@ui8kit/core';

// Типобезопасное определение пропсов
interface MyButtonProps extends ButtonProps {
  customProp?: string;
}

// Типы пропсов вариантов выводятся автоматически
<Button 
  variant="primary"  // ✓ Типобезопасно: 'primary' | 'secondary' | 'ghost' | 'destructive'
  size="md"          // ✓ Типобезопасно: 'sm' | 'md' | 'lg'
  p="lg"             // ✓ Типобезопасно: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
>
  Отправить
</Button>
```

**Файлы определений типов**: Генерируются в [dist/index.d.ts](https://github.com/ui8kit/core/blob/2afe2195/dist/index.d.ts) из компиляции TypeScript.

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

***

## Следующие шаги

Для подробных рабочих процессов разработки:

* **[Базовый рабочий процесс](#5.1)** - Пошаговые паттерны для распространенных сценариев
* **[Продвинутый рабочий процесс](#5.2)** - Пользовательские формы и обработка крайних случаев
* **[Лучшие практики](#5.3)** - Производительность, доступность и организация кода
* **[Темная тема](#5.4)** - Конфигурация и использование провайдера темы

Для архитектурных деталей см. [Архитектура](#3). Для полной документации API см. [Справочник API](#4).

**Источники**: [.devin/wiki.json170-219](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L170-L219)


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