> ## 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`, включая трехуровневую иерархию компонентов, систему вариантов, конвейер сборки и организацию модулей. Он объясняет структурные взаимосвязи между примитивами, композитными компонентами и макетами, а также лежащие в основе механизмы стилизации, типобезопасности и распространения.

Для подробной документации API отдельных компонентов и их свойств см. [Справочник API](#4). Для инструкций по установке и настройке см. [Начало работы](#2). Для рабочих процессов разработки и примеров использования см. [Руководство разработчика](#5).

***

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

Библиотека реализует трехуровневую архитектуру, соответствующую принципам атомарного дизайна: **атомы** (базовые примитивы), **молекулы** (UI-компоненты) и **организмы** (шаблоны макетов). Каждый уровень строится на предыдущем через композицию и проброс свойств.

### Иерархия и зависимости уровней

```
Основа: Система вариантов

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

Уровень 2: UI-компоненты (Молекулы)

Уровень 3: Макеты (Организмы)

использует

использует

использует

использует

расширяет

расширяет

использует

расширяет

применяет

применяет

применяет

применяет

DashLayout

LayoutBlock

SplitBlock

Card + Card.Header/Content/Footer

Button

Badge

Title

Text

Image

Icon

Accordion

Sheet

Group

Container

Block

Box

Grid

Flex

Stack

class-variance-authority

spacingVariants

colorVariants

layoutVariants

typographyVariants

effectsVariants
```

**Источники:** [README.md62-89](https://github.com/ui8kit/core/blob/2afe2195/README.md#L62-L89) [README.md105-168](https://github.com/ui8kit/core/blob/2afe2195/README.md#L105-L168) [src/components/README.md9-19](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L9-L19)

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

Пять фундаментальных строительных блоков, расположенных в [src/core/ui/](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/) обеспечивают прямой доступ к системе вариантов CVA. Эти примитивы отрисовываются как семантические HTML-элементы и служат основой для всех компонентов более высокого уровня.

| Примитив | Базовый элемент | Основное применение | Ключевые свойства |
| - | - | - | - |
| `Box` | `div` | Универсальный контейнер | `component`, все варианты |
| `Block` | `section` | Семантические блоки | `component`, все варианты |
| `Grid` | `div` | Макеты CSS Grid | `cols`, `gap`, варианты grid |
| `Flex` | `div` | Макеты Flexbox | `direction`, `align`, `justify` |
| `Stack` | `div` | Вертикальное/горизонтальное размещение | `gap`, `align`, расширяет Flex |

**Детали реализации:**

* Все примитивы поддерживают `forwardRef` для доступа к 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)
* Полиморфное свойство `component` позволяет использовать семантические HTML-теги: [src/core/ui/Block.tsx10-15](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/Block.tsx#L10-L15)
* Прямое применение вариантов без промежуточной абстракции: [src/core/ui/Box.tsx20-30](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/Box.tsx#L20-L30)

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

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

Пятнадцать композитных компонентов в [src/components/ui/](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/) расширяют базовые примитивы через проброс свойств. Эти компоненты добавляют семантическую структуру, составные паттерны и специализированное поведение, наследуя при этом полную систему вариантов.

| Компонент | Расширяет | Составные части | Специальные возможности |
| - | - | - | - |
| `Card` | `Block` | Header, Content, Footer, Title, Description | Паттерн составного компонента |
| `Button` | `Box` | - | Состояние загрузки, секции (левая/правая) |
| `Badge` | `Box` | - | Индикатор точки, система вариантов |
| `Title` | `Box` | - | Иерархия заголовков (h1-h6) |
| `Text` | `Box` | - | Семантические текстовые элементы (p, span, em, strong) |
| `Container` | `Block` | - | Адаптивные предустановки max-width |
| `Group` | `Flex` | - | Помощник горизонтального макета |
| `Icon` | `Box` | - | Обертка SVG с контролем размера |
| `Image` | `Box` | - | Соотношение сторон, object-fit |
| `Sheet` | - | - | Панель/лист с переходами |
| `Accordion` | - | Item, Trigger, Content | Расширяемые секции |

**Паттерн проброса свойств:**

```
пробрасывает свойства

импортирует

JSX разработчика
Card p='lg' rounded='xl'

Компонент Card
src/components/ui/Card.tsx

Примитив Block
src/core/ui/Block.tsx

spacingVariants
roundedVariants
shadowVariants

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

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

**Источники:** [README.md105-145](https://github.com/ui8kit/core/blob/2afe2195/README.md#L105-L145) [src/components/ui/](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/) [src/components/README.md94-177](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L94-L177)

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

Три шаблона макетов в [src/layouts/](https://github.com/ui8kit/core/blob/2afe2195/src/layouts/) организуют UI-компоненты в структуры приложений. Эти шаблоны обрабатывают сложные паттерны композиции, такие как изменяемые панели, системы сеток и адаптивные точки останова.

| Макет | Основное применение | Ключевые возможности | Зависимости |
| - | - | - | - |
| `DashLayout` | Приложения-панели управления | Боковая панель, заголовок, изменяемые панели | `react-resizable-panels` |
| `LayoutBlock` | Секции контента | Макет Grid, хуки контента | Примитив `Grid` |
| `SplitBlock` | Двухколоночные макеты | Адаптивное разделение, изображение/контент | `Container`, `Grid` |

**Паттерн хуков контента:**

Компонент `LayoutBlock` демонстрирует паттерн хуков контента для динамической отрисовки:

```
// Из src/layouts/LayoutBlock.tsx
interface LayoutBlockProps {
  contentHooks?: {
    beforeContent?: () => React.ReactNode;
    content?: () => React.ReactNode;
    afterContent?: () => React.ReactNode;
  };
}
```

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

***

## Архитектурные принципы

### Соответствие атомарному дизайну

Трехуровневая структура напрямую соответствует методологии атомарного дизайна:

| Уровень | Уровень атомарного дизайна | Сложность | Композиция |
| - | - | - | - |
| Уровень 1 (Core) | Атомы | Минимальная | Прямое применение вариантов |
| Уровень 2 (UI) | Молекулы | Умеренная | Расширяет атомы, проброс свойств |
| Уровень 3 (Layouts) | Организмы | Сложная | Компонует молекулы в шаблоны |

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

**Источники:** [README.md62-79](https://github.com/ui8kit/core/blob/2afe2195/README.md#L62-L79) [.devin/wiki.json4](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L4-L4)

### Философия минимализма

Библиотека достигает своей минималистичной цели через три ключевых ограничения:

1. **15 композитных компонентов** обеспечивают 95% покрытие потребностей UI: [README.md370-386](https://github.com/ui8kit/core/blob/2afe2195/README.md#L370-L386)
2. **12 многократно используемых вариантов** устраняют 80% пользовательских классов: [README.md170-217](https://github.com/ui8kit/core/blob/2afe2195/README.md#L170-L217)
3. **5 базовых примитивов** служат универсальными строительными блоками: [README.md81-103](https://github.com/ui8kit/core/blob/2afe2195/README.md#L81-L103)

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

**Источники:** [README.md388-403](https://github.com/ui8kit/core/blob/2afe2195/README.md#L388-L403) [.devin/wiki.json8-9](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L8-L9)

### Паттерн проброса свойств

Все компоненты уровня 2 наследуют свойства вариантов от своих базовых примитивов через явный проброс свойств:

```
свойства

собственные варианты

пробрасывает в

применяет

объединяется с

Код пользователя
Button p='md' rounded='lg' shadow='sm'

Компонент Button
src/components/ui/Button.tsx

Примитив Box
src/core/ui/Box.tsx

buttonStyleVariants
buttonSizeVariants

spacingVariants
roundedVariants
shadowVariants
```

Этот паттерн обеспечивает:

* **Типобезопасность:** TypeScript валидирует все проброшенные свойства
* **Наследование вариантов:** Компоненты автоматически получают новые варианты, добавленные в примитивы
* **Гибкость композиции:** Несколько источников вариантов объединяются без конфликтов

**Источники:** [src/components/README.md9-19](https://github.com/ui8kit/core/blob/2afe2195/src/components/README.md#L9-L19) [.devin/wiki.json12-13](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L12-L13)

### Семантический HTML и data-атрибуты

Каждый компонент отрисовывает семантические элементы HTML5 и включает атрибуты `data-class` для идентификации:

| Паттерн | Назначение | Пример |
| - | - | - |
| Семантические элементы | Доступность, SEO | `<Block component="section">`, `<Block component="nav">` |
| Атрибуты `data-class` | Таргетирование DOM, тестирование | `<div data-class="card">`, `<div data-class="card-header">` |
| Полиморфные компоненты | Гибкие типы элементов | Свойство `component` принимает любой валидный HTML-тег |

**Пример из компонента Card:**

```
// src/components/ui/Card.tsx
<Block data-class="card" {...props}>
  {children}
</Block>

// Составные части также используют data-class
<Box data-class="card-header">{children}</Box>
<Box data-class="card-content">{children}</Box>
<Box data-class="card-footer">{children}</Box>
```

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

***

## Взаимосвязи компонентов и структура файлов

### Организация директорий

```
@ui8kit/core/
├── src/
│   ├── core/
│   │   ├── ui/              # Уровень 1: 5 примитивов
│   │   │   ├── Box.tsx
│   │   │   ├── Block.tsx
│   │   │   ├── Grid.tsx
│   │   │   ├── Flex.tsx
│   │   │   └── Stack.tsx
│   │   └── variants/        # Определения вариантов CVA
│   │       ├── spacing.ts
│   │       ├── colors.ts
│   │       ├── layout.ts
│   │       ├── typography.ts
│   │       └── effects.ts
│   ├── components/
│   │   └── ui/              # Уровень 2: 15 UI-компонентов
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       ├── badge.tsx
│   │       └── ...
│   ├── layouts/             # Уровень 3: 3 шаблона макетов
│   │   ├── DashLayout.tsx
│   │   ├── LayoutBlock.tsx
│   │   └── SplitBlock.tsx
│   ├── themes/
│   │   └── providers/       # Система тем
│   │       └── ThemeProvider.tsx
│   ├── lib/
│   │   ├── core-classes.json  # Сгенерированный whitelist классов (618 классов)
│   │   └── utils.ts
│   └── registry.json        # Метаданные компонентов
├── dist/                    # Результат сборки (модули ES2022)
│   ├── index.js
│   └── index.d.ts
└── scripts/
    └── cva-extractor.ts     # Извлечение классов на этапе сборки
```

**Источники:** [README.md1-453](https://github.com/ui8kit/core/blob/2afe2195/README.md#L1-L453) [package.json1-50](https://github.com/ui8kit/core/blob/2afe2195/package.json#L1-L50)

### Поток импорта и экспорта компонентов

```
компиляция tsc

npm publish

импортирует

импортирует

импортирует

src/core/ui/
Box, Block, Grid, Flex, Stack

src/core/variants/
12 определений вариантов

src/components/ui/
15 композитных компонентов

src/layouts/
3 шаблона макетов

src/themes/providers/
ThemeProvider

src/index.ts
Центральный файл экспорта

dist/
index.js + index.d.ts

Реестр NPM
@ui8kit/core
```

**Точки входа:**

Основная точка входа [src/index.ts](https://github.com/ui8kit/core/blob/2afe2195/src/index.ts) реэкспортирует все публичные API:

```
// Базовые примитивы
export * from './core/ui/Box';
export * from './core/ui/Block';
export * from './core/ui/Grid';
export * from './core/ui/Flex';
export * from './core/ui/Stack';

// UI-компоненты
export * from './components/ui/button';
export * from './components/ui/card';
// ... еще 13

// Макеты
export * from './layouts/DashLayout';
export * from './layouts/LayoutBlock';
export * from './layouts/SplitBlock';

// Система тем
export * from './themes/providers/ThemeProvider';

// Варианты (опциональный экспорт для расширения)
export * from './core/variants';
```

**Источники:** [src/index.ts](https://github.com/ui8kit/core/blob/2afe2195/src/index.ts) [package.json30-36](https://github.com/ui8kit/core/blob/2afe2195/package.json#L30-L36)

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

Библиотека поддерживает пять различных паттернов композиции для разных архитектурных потребностей:

```
Паттерн 5: Хуки контента

LayoutBlock
функции contentHooks

beforeContent, content, afterContent

Динамическая отрисовка секций

Паттерн 4: Композиция макета

DashLayout
sidebar, header, children

Container + Card + Stack

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

Паттерн 3: Проброс свойств

Button p='md' rounded='lg'
+ специфичные свойства button

Объединяет варианты button + базовые варианты

Стилизованный элемент button

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

Card
Card.Header
Card.Content
Card.Footer

Структурированная карточка с частями

Паттерн 1: Прямой примитив

Block component='form' p='lg'

элемент form с отступами
```

**Детали паттернов:**

1. **Прямой примитив:** Используйте `Box` или `Block` со свойством `component` для семантического HTML
2. **Составные компоненты:** Используйте структурированные компоненты как `Card.Header`, обеспечивает гибкую композицию
3. **Проброс свойств:** Композитные компоненты объединяют свои собственные варианты с унаследованными базовыми вариантами
4. **Композиция макета:** Шаблоны организуют несколько компонентов в структуры приложений
5. **Хуки контента:** Макеты принимают функции рендеринга для динамической инъекции контента

**Источники:** [src/components/GUIDE\_CREATE\_FORM.md10-13](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L10-L13) [src/layouts/LayoutBlock.tsx15-22](https://github.com/ui8kit/core/blob/2afe2195/src/layouts/LayoutBlock.tsx#L15-L22) [src/layouts/DashLayout.tsx72-99](https://github.com/ui8kit/core/blob/2afe2195/src/layouts/DashLayout.tsx#L72-L99)

***

## Архитектура системы вариантов

### Интеграция CVA

Система вариантов работает на `class-variance-authority`, предоставляя типобезопасные, композируемые утилиты стилизации. Все варианты определены в [src/core/variants/](https://github.com/ui8kit/core/blob/2afe2195/src/core/variants/) и применяются через базовые примитивы.

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

| Категория | Варианты | Значения | Назначение |
| - | - | - | - |
| Spacing | `p`, `m`, `px`, `py`, `pt`, `pb`, `pl`, `pr`, `mx`, `my`, `mt`, `mb`, `ml`, `mr` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `auto` | Отступы и поля |
| Colors | `bg`, `c`, `borderColor` | Цвета дизайн-системы | Цвета фона, текста, границ |
| Layout | `w`, `h`, `minH`, `maxW`, `position` | `auto`, `full`, `screen`, `fit`, `min`, `max` | Ширина, высота, позиционирование |
| Typography | `size`, `weight`, `align`, `leading` | Размеры и начертания шрифтов | Стилизация текста |
| Effects | `rounded`, `shadow`, `border` | `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full` | Визуальные улучшения |
| Display | `display` | `block`, `inline`, `flex`, `grid`, `none` | Режимы отображения |
| Flexbox | `direction`, `align`, `justify`, `wrap` | Свойства flex | Макеты Flexbox |
| Grid | `cols`, `rows`, `gap` | Свойства grid | Макеты Grid |
| Overflow | `overflow`, `overflowX`, `overflowY` | `auto`, `hidden`, `scroll`, `visible` | Контроль переполнения |
| Cursor | `cursor` | `pointer`, `default`, `move`, и т.д. | Стили курсора |
| Opacity | `opacity` | от `0` до `100` | Прозрачность |
| Z-Index | `z` | `0`, `10`, `20`, `30`, `40`, `50` | Порядок наложения |

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

### Конвейер применения вариантов

```
Свойства компонента
p='lg' rounded='xl' shadow='md'

Импортированные варианты
spacingVariants
roundedVariants
shadowVariants

Движок CVA
class-variance-authority

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

core-classes.json
whitelist из 618 классов

Очистка Tailwind CSS
Валидация safelist

Вывод в DOM
атрибут className
```

**Этапы конвейера:**

1. **Ввод свойств:** Разработчик предоставляет свойства вариантов (например, `p='lg'`)
2. **Разрешение вариантов:** Движок CVA разрешает свойства в классы Tailwind, используя определения вариантов
3. **Генерация классов:** Производит строку className (например, `'p-8 rounded-xl shadow-md'`)
4. **Валидация whitelist:** Сгенерированные классы валидируются против [src/lib/core-classes.json](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json) (618 классов)
5. **Обработка Tailwind:** Tailwind CSS применяет утилитарные классы, используя whitelist как safelist для предотвращения удаления
6. **Вывод в DOM:** Финальный className применяется к отрисованному элементу

**Источники:** [README.md98-124](https://github.com/ui8kit/core/blob/2afe2195/README.md#L98-L124) [src/lib/core-classes.json1-619](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L1-L619) [scripts/cva-extractor.ts223-260](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L223-L260)

### Генерация whitelist классов

Скрипт времени сборки `cva-extractor.ts` сканирует все определения вариантов для генерации whitelist классов:

**Рабочий процесс экстрактора:**

```
сканирование

генерирует

записывает

импортируется в

src/core/variants/
определения вариантов *.ts

scripts/cva-extractor.ts
Статический анализ

Извлеченные классы
всего 618 классов

src/lib/core-classes.json
Зафиксированный артефакт

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

**Категории сгенерированных классов:**

* Spacing: `p-0`, `p-1`, `p-2`, ..., `p-96`, `m-0`, `m-1`, ..., `m-96`, `mx-auto`, `my-auto`
* Rounded: `rounded-none`, `rounded-sm`, `rounded-md`, ..., `rounded-full`
* Shadow: `shadow-none`, `shadow-sm`, `shadow-md`, ..., `shadow-2xl`
* Colors: Все утилиты цветов дизайн-системы
* Layout: `w-full`, `w-screen`, `h-full`, `h-screen`, и т.д.

**Источники:** [scripts/cva-extractor.ts1-260](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L1-L260) [src/lib/core-classes.json617-619](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L617-L619)

***

## Архитектура времени сборки vs времени выполнения

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

### Системы времени сборки

```
Артефакты сборки (Зафиксированные)

Инструменты времени сборки

Исходный код
src/

cva-extractor.ts
Извлечение CSS-классов

Компилятор TypeScript
tsc -p tsconfig.json

ESLint
Проверка качества кода

buildy-ui scan
Метаданные компонентов

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

dist/index.js
dist/index.d.ts

src/registry.json
Метаданные компонентов
```

**Команды сборки:**

| Команда | Инструмент | Вывод | Назначение |
| - | - | - | - |
| `bun scripts/cva-extractor.ts` | Пользовательский скрипт | `core-classes.json` | Извлечение классов вариантов |
| `tsc -p tsconfig.json` | TypeScript | директория `dist/` | Компиляция в модули ES2022 |
| `eslint src --ext .ts,.tsx` | ESLint | Вывод в консоль | Валидация качества кода |
| `buildy-ui scan` | CLI buildy-ui | `registry.json` | Метаданные компонентов |

**Источники:** [scripts/cva-extractor.ts1-260](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L1-L260) [package.json19-25](https://github.com/ui8kit/core/blob/2afe2195/package.json#L19-L25)

### Системы времени выполнения

```
Приложение потребителя

Внешние зависимости времени выполнения

Системы времени выполнения

dist/index.js
Скомпилированные модули

Базовые примитивы
Block, Box, Grid, Flex, Stack

Система вариантов
class-variance-authority

UI-компоненты
15 композитных компонентов

Шаблоны макетов
3 компонента макетов

Система тем
ThemeProvider + useTheme

react ^18 | ^19

lucide-react
Иконки

react-resizable-panels
Макеты

class-variance-authority
Движок вариантов

Код приложения
импорт из @ui8kit/core

Tailwind CSS
Утилитарная стилизация
```

**Зависимости времени выполнения:**

| Зависимость | Тип | Использование | Компоненты |
| - | - | - | - |
| `react` | Peer | Фреймворк компонентов | Все компоненты |
| `react-dom` | Peer | Отрисовка DOM | Все компоненты |
| `class-variance-authority` | Прямая | Движок вариантов | Базовые примитивы |
| `lucide-react` | Прямая | Иконки | Sheet, Accordion |
| `react-resizable-panels` | Прямая | Изменяемые панели | DashLayout |

**Источники:** [package.json42-56](https://github.com/ui8kit/core/blob/2afe2195/package.json#L42-L56) [src/themes/providers/ThemeProvider.tsx1-109](https://github.com/ui8kit/core/blob/2afe2195/src/themes/providers/ThemeProvider.tsx#L1-L109)

***

## Система распространения и модулей

### Конфигурация пакета

Файл [package.json](https://github.com/ui8kit/core/blob/2afe2195/package.json) определяет множественные точки входа и паттерны экспорта:

**Основные точки входа:**

```
{
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.js"
    },
    "./registry.json": "./src/registry.json",
    "./core-classes.json": "./src/lib/core-classes.json"
  }
}
```

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

* **Основной экспорт (`.`):** Все компоненты, варианты и утилиты тем
* **Экспорт реестра (`./registry.json`):** Метаданные компонентов для инструментов
* **Экспорт классов (`./core-classes.json`):** Whitelist CSS-классов для конфигурации Tailwind

**Источники:** [package.json30-42](https://github.com/ui8kit/core/blob/2afe2195/package.json#L30-L42)

### Методы интеграции

```
Проект потребителя

Методы интеграции

npm publish

@ui8kit/core
Репозиторий GitHub

Реестр NPM
@ui8kit/Unsupported markdown: link

src/registry.json
Метаданные компонентов

npm install @ui8kit/core
Все 18 компонентов

npx buildy-ui add button
Выборочная установка

git submodule add
Интеграция монорепо

Копирование директории src/
Пользовательская сборка

node_modules/@ui8kit/core

src/components/ui/

packages/@ui8kit/core

src/lib/ui8kit/
```

**Сравнение интеграции:**

| Метод | Установка | Обновления | Бандл | Случай использования |
| - | - | - | - | - |
| Полная установка NPM | `npm install @ui8kit/core` | `npm update` | Полная библиотека | Требуется полная библиотека |
| Покомпонентно | `npx buildy-ui add button card` | Ручное повторное добавление | Минимальный | Оптимизация бандла |
| Git submodule | `git submodule add` | `git submodule update` | Полный исходник | Архитектура монорепо |
| Прямой исходник | Ручное копирование файлов | Ручная синхронизация | Пользовательский | Пользовательские модификации |

**Источники:** [README.md252-277](https://github.com/ui8kit/core/blob/2afe2195/README.md#L252-L277) [src/registry.json2-244](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L2-L244)

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

Файл [src/registry.json](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json) предоставляет метаданные для автоматизации инструментов:

**Схема реестра:**

```
interface Registry {
  version: string;
  items: ComponentItem[];
}

interface ComponentItem {
  name: string;              // Идентификатор компонента
  type: "registry:ui" | "registry:layout";
  description: string;       // Человекочитаемое описание
  dependencies?: string[];   // Зависимости внешних пакетов
  registryDependencies?: string[]; // Внутренние зависимости компонентов
  files: string[];          // Пути к исходным файлам
  target?: string;          // Целевая директория установки
}
```

**Пример записи:**

```
{
  "name": "card",
  "type": "registry:ui",
  "description": "Flexible card component with compound parts",
  "dependencies": [],
  "registryDependencies": ["block", "box"],
  "files": ["src/components/ui/card.tsx"],
  "target": "components/ui"
}
```

Эти метаданные обеспечивают:

* Покомпонентную установку через CLI `buildy-ui`
* Автоматическое разрешение зависимостей
* Программное обнаружение компонентов
* Интеграцию инструментов сборки

**Источники:** [src/registry.json1-244](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L1-L244) [README.md251-276](https://github.com/ui8kit/core/blob/2afe2195/README.md#L251-L276)

***

## Сквозные задачи

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

Настройка TypeScript балансирует строгую типобезопасность с эргономикой разработчика:

**Ключевые настройки из [tsconfig.json](https://github.com/ui8kit/core/blob/2afe2195/tsconfig.json):**

| Настройка | Значение | Назначение |
| - | - | - |
| `target` | `ES2022` | Современные возможности JavaScript |
| `module` | `ESNext` | Поддержка ES-модулей |
| `jsx` | `react-jsx` | Трансформация JSX React 17+ |
| `strict` | `true` | Максимальная типобезопасность |
| `skipLibCheck` | `true` | Более быстрая компиляция |
| `declaration` | `true` | Генерация файлов `.d.ts` |
| `declarationMap` | `true` | Source map для типов |
| `outDir` | `./dist` | Директория вывода сборки |

**Алиасы путей:**

```
{
  "paths": {
    "@/*": ["./src/*"],
    "@/components/*": ["./src/components/*"],
    "@/core/*": ["./src/core/*"],
    "@/layouts/*": ["./src/layouts/*"]
  }
}
```

Для подробной конфигурации TypeScript см. [Конфигурация TypeScript](#3.8).

**Источники:** [tsconfig.json1-30](https://github.com/ui8kit/core/blob/2afe2195/tsconfig.json#L1-L30) [package.json19-25](https://github.com/ui8kit/core/blob/2afe2195/package.json#L19-L25)

### Система тем

Система тем обеспечивает поддержку темной темы с автоматическим сохранением:

**Архитектура ThemeProvider:**

```
Компоненты-потребители

Сохранение

Состояние темы

isDarkMode: boolean

setDarkMode: function

toggleDarkMode: function

Компонент ThemeProvider
src/themes/providers/ThemeProvider.tsx

localStorage
'ui8kit-theme'

prefers-color-scheme
медиа-запрос

хук useTheme()

ThemeContext
```

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

```
// Оборачивание приложения
import { ThemeProvider, modernUITheme } from '@ui8kit/core';

<ThemeProvider theme={modernUITheme}>
  <App />
</ThemeProvider>

// Доступ к теме в компонентах
import { useTheme } from '@ui8kit/core';

const { isDarkMode, toggleDarkMode } = useTheme();
```

Для подробной реализации темы см. [Темная тема](#5.4).

**Источники:** [src/themes/providers/ThemeProvider.tsx1-109](https://github.com/ui8kit/core/blob/2afe2195/src/themes/providers/ThemeProvider.tsx#L1-L109) [README.md219-249](https://github.com/ui8kit/core/blob/2afe2195/README.md#L219-L249)

### Возможности доступности

Библиотека реализует доступность через семантический HTML и паттерны ARIA:

**Стратегии доступности:**

1. **Семантические элементы HTML5:** `<Block component="section">`, `<Block component="nav">`
2. **Иерархия заголовков:** `<Title order={1}>` отрисовывает `<h1>`, обеспечивая правильную структуру документа
3. **Навигация с клавиатуры:** Интерактивные компоненты поддерживают Tab, Enter, Space
4. **Атрибуты ARIA:** Компоненты Accordion и Sheet включают правильные метки ARIA
5. **Управление фокусом:** Видимые состояния фокуса и логический порядок табуляции
6. **Контраст цветов:** Цвета дизайн-системы соответствуют стандартам WCAG AA

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

***

## Ссылки на подразделы

Этот обзор архитектуры обеспечивает основу для понимания структуры библиотеки. Для подробной информации о конкретных подсистемах см. следующие страницы:

* [Базовые компоненты](#3.1) - Подробная документация 5 базовых примитивов
* [Система вариантов](#3.2) - Полные определения вариантов и паттерны использования
* [UI-компоненты](#3.3) - Реализации расширенных компонентов и проброс свойств
* [Макеты](#3.4) - Паттерны шаблонов макетов и стратегии композиции
* [Структура пакета](#3.5) - Экспорты модулей, точки входа и настройка распространения
* [Система сборки](#3.6) - Компиляция TypeScript, скрипты сборки и генерация артефактов
* [Реестр компонентов](#3.7) - Система реестра, формат метаданных и интеграция инструментов
* [Конфигурация TypeScript](#3.8) - Настройка системы типов, алиасы путей и опции компилятора

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

Для рабочих процессов разработки и примеров использования см. [Руководство разработчика](#5).

**Источники:** [.devin/wiki.json45-133](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L45-L133) [README.md1-453](https://github.com/ui8kit/core/blob/2afe2195/README.md#L1-L453)


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