> ## 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

> Введение в UI8Kit Core - минималистичную библиотеку React UI-компонентов, построенную на Tailwind CSS с семантическим HTML5

# Обзор

Этот документ представляет `@ui8kit/core` — минималистичную библиотеку React UI-компонентов, построенную на utility-first Tailwind CSS и семантическом HTML5. Он охватывает философию дизайна, архитектурные слои, инвентарь компонентов, систему вариантов и методы интеграции.

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

**Источники:** [.devin/wiki.json24-33](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L24-L33) [README.md1-10](https://github.com/ui8kit/core/blob/2afe2195/README.md#L1-L10)

***

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

`@ui8kit/core` — это готовая к production React-библиотека компонентов, разработанная для обеспечения быстрой разработки интерфейсов с минимальным количеством кода. Библиотека предоставляет 23 компонента, организованных в три архитектурных слоя, стилизованных через 12 композируемых CVA-вариантов, которые устраняют необходимость в ручном управлении className примерно в 80% случаев использования.

**Целевая аудитория:** React-разработчики, создающие приложения с Tailwind CSS, которые отдают приоритет:

* Минимальному размеру бандла и объему кода
* Типобезопасным API компонентов с TypeScript
* Семантическому HTML5 для доступности и SEO
* Гибким паттернам композиции без жестких дизайн-ограничений

**Что предоставляет эта библиотека:**

* 5 базовых примитивных компонентов (Слой 1) для фундаментальных макетов
* 15 композитных UI-компонентов (Слой 2) для общих интерфейсных паттернов
* 3 шаблонных компонента макетов (Слой 3) для структур приложений
* 12 повторно используемых категорий вариантов, охватывающих отступы, цвета, макет, типографику и эффекты
* Несколько методов интеграции: NPM-пакет, установка по компонентам, git submodule, прямой исходный код

**Что эта библиотека НЕ предоставляет:**

* Opinionated дизайн-систему с фиксированным визуальным стилем
* Валидацию форм или управление состоянием
* Фреймворк для анимации
* Библиотеку иконок (зависит от `lucide-react` для иконок в определенных компонентах)

**Источники:** [package.json1-20](https://github.com/ui8kit/core/blob/2afe2195/package.json#L1-L20) [README.md3-19](https://github.com/ui8kit/core/blob/2afe2195/README.md#L3-L19) [.devin/wiki.json2-10](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L2-L10)

***

## Философия дизайна

Библиотека построена на принципе **минимального кода с максимальной гибкостью**. Сложные интерфейсы возникают из композиции небольшого набора примитивов, а не из сборки десятков специализированных компонентов.

### Основные принципы

| Принцип | Реализация | Преимущество |
| - | - | - |
| **Минимализм** | 15 UI-компонентов против 50+ в типичных библиотеках | Уменьшенный размер бандла, более быстрая кривая обучения |
| **Покрытие 80/20** | 12 вариантов покрывают \~80% потребностей в стилизации | Устраняет большинство ручного использования className |
| **Композируемость** | Примитивы комбинируются для создания неограниченных дизайнов | Никаких жестких дизайн-ограничений |
| **Типобезопасность** | Полная поддержка TypeScript с интерфейсами props | Предотвращает ошибки props во время выполнения |
| **Семантический HTML** | Компоненты рендерятся как `<section>`, `<article>`, `<nav>` и т.д. | Лучшая доступность и SEO |
| **Нулевые накладные расходы во время выполнения** | CVA генерирует статические классы Tailwind на этапе сборки | Нет вычисления стилей во время выполнения |

### Минимализм на практике

Библиотека достигает сложности интерфейса через композицию, а не через разрастание компонентов:

```
// Традиционный подход: специализированные компоненты форм
<Form>
  <FormField>
    <FormLabel>Email</FormLabel>
    <FormInput type="email" />
    <FormError>Invalid email</FormError>
  </FormField>
</Form>

// Подход @ui8kit/core: композиция примитивов
<Block component="form" p="lg" rounded="md" bg="card">
  <Stack gap="md">
    <Box>
      <Text weight="medium" mb="xs">Email</Text>
      <Box component="input" type="email" w="full" border="1px solid border" />
      <Text size="sm" c="destructive">Invalid email</Text>
    </Box>
  </Stack>
</Block>
```

Оба достигают одного и того же результата, но примитивный подход:

* Исключает 4 специализированных компонента из бандла
* Предоставляет полный контроль стилизации через варианты
* Сохраняет семантический HTML с `component="form"` и `component="input"`
* Не требует дополнительной кривой обучения компонентов

**Источники:** [README.md388-403](https://github.com/ui8kit/core/blob/2afe2195/README.md#L388-L403) [.devin/wiki.json7-10](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L7-L10) [src/components/GUIDE\_CREATE\_FORM.md1-100](https://github.com/ui8kit/core/blob/2afe2195/src/components/GUIDE_CREATE_FORM.md#L1-L100)

***

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

```
Система вариантов (src/core/variants/)

Слой 1: Базовые примитивы (src/core/ui/)

Слой 2: UI-компоненты (src/components/ui/)

Слой 3: Шаблоны макетов (src/layouts/)

использует

использует

использует

расширяет

расширяет

использует

применяет

применяет

применяет

проброс props

проброс props

DashLayout.tsx
Дашборд с боковой панелью/хедером

LayoutBlock.tsx
Секции контента

SplitBlock.tsx
Двухколоночные макеты

button.tsx
Кнопки действий

card.tsx
+ Card.Header/Content/Footer

text.tsx
Семантический текст

title.tsx
Заголовки h1-h6

badge.tsx
Метки

icon.tsx
Обертка SVG

image.tsx
Оптимизированные изображения

container.tsx
Контейнер с max-width

group.tsx
Группировка элементов

sheet.tsx
Компонент drawer

accordion.tsx
Раскрывающиеся секции

Block.tsx
Семантический контейнер

Box.tsx
Гибкий примитив

Grid.tsx
CSS Grid макет

Flex.tsx
Flexbox макет

Stack.tsx
Вертикальная/горизонтальная укладка

spacing-variants.ts
p, m, px, py, mx, my, и т.д.

color-variants.ts
bg, c, borderColor

layout-variants.ts
w, h, position

typography-variants.ts
size, weight, align

effect-variants.ts
shadow, rounded, border
```

**Архитектура: Трехслойная иерархия компонентов**

Библиотека реализует строгую трехслойную иерархию, выровненную с принципами atomic design:

### Слой 1: Базовые примитивы (`src/core/ui/`)

Пять фундаментальных компонентов, которые напрямую применяют систему вариантов:

| Компонент | Файл | Назначение | Применяемые варианты |
| - | - | - | - |
| `Block` | `Block.tsx` | Семантический контейнер (`section`, `article`, `nav` и т.д.) | Все 12 вариантов |
| `Box` | `Box.tsx` | Универсальный гибкий примитив (любой HTML-элемент) | Все 12 вариантов |
| `Grid` | `Grid.tsx` | CSS Grid макет с props `cols` и `rows` | Варианты отступов, макета |
| `Flex` | `Flex.tsx` | Flexbox макет с props `direction` и `justify` | Варианты отступов, макета |
| `Stack` | `Stack.tsx` | Вертикальная/горизонтальная укладка с prop `gap` | Варианты отступов |

Эти примитивы обеспечивают основу для всех компонентов более высокого уровня. Они рендерят семантические HTML5-элементы и принимают props вариантов напрямую.

### Слой 2: UI-компоненты (`src/components/ui/`)

Пятнадцать композитных компонентов, которые расширяют примитивы через проброс props:

| Компонент | Файл | Базовый примитив | Специальные возможности |
| - | - | - | - |
| `Button` | `button.tsx` | `Box` | `variant`, `size`, `leftSection`, `rightSection` |
| `Card` | `card.tsx` | `Block` | Композитный: `Card.Header`, `Card.Content`, `Card.Footer` |
| `Text` | `text.tsx` | `Box` | Семантические теги: `p`, `span`, `em`, `strong` |
| `Title` | `title.tsx` | `Box` | Иерархия заголовков: `h1`-`h6` через prop `order` |
| `Badge` | `badge.tsx` | `Box` | Маленькая метка с `variant` |
| `Icon` | `icon.tsx` | `Box` | Обертка SVG с контролем размера |
| `Image` | `image.tsx` | `Box` | Оптимизировано с props `alt` и `loading` |
| `Container` | `container.tsx` | `Block` | Адаптивная max-width: `sm`, `md`, `lg`, `xl`, `2xl` |
| `Group` | `group.tsx` | `Flex` | Группировка элементов с `gap` |
| `Sheet` | `sheet.tsx` | N/A | Drawer с prop `side` (использует `lucide-react`) |
| `Accordion` | `accordion.tsx` | N/A | Раскрывающиеся секции (использует `lucide-react`) |

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

### Слой 3: Шаблоны макетов (`src/layouts/`)

Три шаблонных компонента, которые оркеструют компоненты Слоя 2 в структуры приложений:

| Компонент | Файл | Назначение | Зависимости |
| - | - | - | - |
| `DashLayout` | `DashLayout.tsx` | Дашборд с изменяемой боковой панелью, хедером, контентом | `react-resizable-panels` |
| `LayoutBlock` | `LayoutBlock.tsx` | Секция контента с хуками `beforeContent`/`content`/`afterContent` | `Grid` |
| `SplitBlock` | `SplitBlock.tsx` | Двухколоночный макет (медиа + контент или контент + медиа) | `Container` |

**Источники:** [README.md62-168](https://github.com/ui8kit/core/blob/2afe2195/README.md#L62-L168) [src/core/ui/Block.tsx1-50](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/Block.tsx#L1-L50) [src/core/ui/Box.tsx1-40](https://github.com/ui8kit/core/blob/2afe2195/src/core/ui/Box.tsx#L1-L40) [src/components/ui/button.tsx1-100](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/button.tsx#L1-L100) [src/components/ui/card.tsx1-150](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/card.tsx#L1-L150) [src/layouts/DashLayout.tsx1-100](https://github.com/ui8kit/core/blob/2afe2195/src/layouts/DashLayout.tsx#L1-L100)

***

## Обзор системы вариантов

```
Вывод

Артефакт сборки

Движок CVA

Файлы вариантов (src/core/variants/)

API разработчика

генерирует

генерирует

safelist для

JSX компонента
p='lg' rounded='xl'
shadow='md' bg='card'

spacing-variants.ts
spacingVariants

color-variants.ts
colorVariants

layout-variants.ts
layoutVariants

typography-variants.ts
typographyVariants

effect-variants.ts
effectVariants

class-variance-authority
функция cva()

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

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

HTML-элемент
с классами Tailwind

Очистка Tailwind CSS
```

**Система вариантов: Конвейер стилизации на основе CVA**

Система вариантов централизует всю логику стилизации через 12 композируемых категорий вариантов, устраняя необходимость ручного управления `className` в большинстве сценариев.

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

| Категория | Props | Значения | Файл |
| - | - | - | - |
| **Отступы** | `p`, `m`, `px`, `py`, `pt`, `pb`, `pl`, `pr`, `mx`, `my`, `mt`, `mb`, `ml`, `mr` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `auto` | `spacing-variants.ts` |
| **Цвета** | `bg`, `c`, `borderColor` | Цвета дизайн-системы: `primary`, `secondary`, `destructive`, `card`, `foreground` и т.д. | `color-variants.ts` |
| **Макет** | `w`, `h`, `minH`, `maxW`, `position` | `auto`, `full`, `screen`, `fit`, `min`, `max` | `layout-variants.ts` |
| **Типографика** | `size`, `weight`, `align`, `leading` | Размеры шрифта: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`; вес: `normal`, `medium`, `bold` | `typography-variants.ts` |
| **Эффекты** | `rounded`, `shadow`, `border` | Радиус углов, глубина тени, стили границ | `effect-variants.ts` |
| **Flexbox** | `direction`, `justify`, `items`, `wrap`, `gap` | Свойства Flexbox | Интегрировано в варианты макета |
| **Grid** | `cols`, `rows`, `gap` | Свойства CSS Grid | Интегрировано в варианты макета |

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

1. **Разработчик пишет props вариантов** в JSX: `<Card p="lg" rounded="xl" shadow="md" bg="card" />`
2. **Движок CVA разрешает props** в классы Tailwind через функцию `cva()` из `class-variance-authority`
3. **Сгенерированные классы** выводятся: `p-8 rounded-xl shadow-md bg-card`
4. **Валидация по белому списку** обеспечивает, что очистка Tailwind не удаляет необходимые классы (618 классов в `core-classes.json`)
5. **DOM рендерится** с применённой финальной строкой классов

### Извлечение классов на этапе сборки

Скрипт `scripts/cva-extractor.ts` сканирует все файлы вариантов и генерирует `src/lib/core-classes.json`:

```
{
  "classes": [
    "p-0", "p-1", "p-2", "p-4", "p-6", "p-8", "p-12", "p-16",
    "m-0", "m-1", "m-2", "m-4", "m-6", "m-8", "m-12", "m-16",
    "bg-primary", "bg-secondary", "bg-card", "bg-background",
    "rounded-none", "rounded-sm", "rounded-md", "rounded-lg", "rounded-xl",
    // ... всего 618 классов
  ]
}
```

Этот белый список служит двум целям:

* **Safelist для Tailwind** - предотвращает удаление классов вариантов при очистке CSS
* **Безопасность tw-merge** - обеспечивает корректное слияние классов

**Источники:** [README.md170-217](https://github.com/ui8kit/core/blob/2afe2195/README.md#L170-L217) [src/core/variants/spacing-variants.ts1-100](https://github.com/ui8kit/core/blob/2afe2195/src/core/variants/spacing-variants.ts#L1-L100) [src/core/variants/color-variants.ts1-80](https://github.com/ui8kit/core/blob/2afe2195/src/core/variants/color-variants.ts#L1-L80) [scripts/cva-extractor.ts1-260](https://github.com/ui8kit/core/blob/2afe2195/scripts/cva-extractor.ts#L1-L260) [src/lib/core-classes.json1-619](https://github.com/ui8kit/core/blob/2afe2195/src/lib/core-classes.json#L1-L619)

***

## Технологический стек

### Основные зависимости

| Пакет | Версия | Назначение | Использование |
| - | - | - | - |
| `react` | `^18.0.0` или `^19.0.0` | UI-фреймворк | Peer-зависимость (предоставляется потребителем) |
| `react-dom` | `^18.0.0` или `^19.0.0` | Рендеринг React | Peer-зависимость (предоставляется потребителем) |
| `class-variance-authority` | `^0.7.1` | Движок вариантов | Обеспечивает работу 12 категорий вариантов |
| `clsx` | `^2.1.1` | Конкатенация классов | Утилита для слияния строк классов |
| `tailwind-merge` | `^3.3.1` | Дедупликация классов | Предотвращает дублирование классов Tailwind |
| `lucide-react` | `^0.525.0` | Библиотека иконок | Используется в компонентах `Sheet` и `Accordion` |
| `react-resizable-panels` | `^3.0.6` | Изменяемые макеты | Используется в `DashLayout` для изменения размера боковой панели |

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

| Инструмент | Назначение | Конфигурация |
| - | - | - |
| TypeScript | Проверка типов и компиляция | `tsconfig.json` с таргетом `ES2022` |
| ESLint | Качество кода | `.eslintrc` с правилами TypeScript |
| Bun | Менеджер пакетов и среда выполнения | `bun-types` для поддержки TypeScript |
| `cva-extractor.ts` | Извлечение классов на этапе сборки | Генерирует белый список `core-classes.json` |
| `buildy-ui` CLI | Сканер реестра компонентов | Генерирует метаданные `registry.json` |

### Формат распространения

Библиотека распространяется как ES2022-модули с TypeScript-объявлениями:

| Артефакт | Путь | Назначение |
| - | - | - |
| Основная точка входа | `dist/index.js` | Экспорты ES2022-модулей |
| Определения типов | `dist/index.d.ts` | Объявления TypeScript-интерфейсов |
| Белый список классов | `src/lib/core-classes.json` | Safelist для Tailwind (618 классов) |
| Реестр компонентов | `src/registry.json` | Метаданные для установки по компонентам |

**Конфигурация экспорта** в [package.json33-37](https://github.com/ui8kit/core/blob/2afe2195/package.json#L33-L37):

```
{
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}
```

**Источники:** [package.json48-69](https://github.com/ui8kit/core/blob/2afe2195/package.json#L48-L69) [package.json30-37](https://github.com/ui8kit/core/blob/2afe2195/package.json#L30-L37) [README.md422-440](https://github.com/ui8kit/core/blob/2afe2195/README.md#L422-L440)

***

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

```
Метод интеграции 5: Программный

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

Метод интеграции 3: Git Submodule

Метод интеграции 2: По компонентам

Метод интеграции 1: Полная библиотека

Каналы распространения

Исходный репозиторий

github.com/ui8kit/core

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

NPM Registry
@ui8kit/Unsupported markdown: link

Git Repository
ветка main

npm install @ui8kit/core

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

npx buildy-ui add button card

components/ui/button.tsx
components/ui/card.tsx

git submodule add
Unsupported markdown: link
packages/@ui8kit/core

import { Button } from '@ui8kit/core'

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

Кастомный процесс сборки

import registry from
'@ui8kit/core/registry.json'

Автоматизация инструментов
```

**Методы интеграции: Пять подходов**

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

### Метод 1: Установка полной библиотеки (NPM)

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

```
npm install @ui8kit/core react react-dom
```

**Импорты:**

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

**Размер бандла:** Полная библиотека (\~15 UI-компонентов + 3 макета + 5 примитивов)

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

* Одна зависимость в объявлении
* Все компоненты немедленно доступны
* Автоматические обновления через `npm update`

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

***

### Метод 2: Установка по компонентам (buildy-ui CLI)

**Случай использования:** Оптимизация бандла, постепенное внедрение, микросервисы

```
npx buildy-ui add button card text
```

**Результат:** Копирует файлы компонентов в директорию `components/ui/`

```
components/
└── ui/
    ├── button.tsx
    ├── card.tsx
    └── text.tsx
```

**Импорты:**

```
import { Button } from '@/components/ui/button';
import { Card } from '@/components/ui/card';
```

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

* Минимальный размер бандла (только установленные компоненты)
* Нет зависимости от полной библиотеки
* Полный контроль исходного кода

**Метаданные реестра** в [src/registry.json1-244](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L1-L244):

```
{
  "name": "button",
  "type": "registry:ui",
  "dependencies": ["class-variance-authority"],
  "files": [
    {
      "path": "components/ui/button.tsx",
      "type": "registry:ui"
    }
  ]
}
```

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

***

### Метод 3: Git Submodule (Монорепозиторий)

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

```
git submodule add https://github.com/ui8kit/core.git packages/@ui8kit/core
```

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

```
{
  "compilerOptions": {
    "paths": {
      "@ui8kit/core": ["./packages/@ui8kit/core/src"]
    }
  }
}
```

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

* Прямой доступ к исходному коду
* Закрепление версий через git-коммиты
* Разделение между пакетами монорепозитория
* Возможность локальных модификаций

**Источники:** [SUBMODULE\_GUIDE.md1-300](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L1-L300) (упомянуто в диаграммах)

***

### Метод 4: Интеграция прямого исходного кода

**Случай использования:** Кастомные сборки, сильно модифицированные компоненты, встраиваемые системы

**Процесс:**

1. Скопировать директорию `src/` в проект
2. Скорректировать пути импортов
3. Настроить компоненты по необходимости
4. Собрать с TypeScript-компилятором проекта

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

* Полный контроль над исходным кодом
* Нет внешних зависимостей
* Кастомные таргеты компиляции
* Удаление неиспользуемых компонентов

***

### Метод 5: Программный доступ к реестру

**Случай использования:** Инструменты сборки, генераторы документации компонентов, автоматизированное тестирование

```
import registry from '@ui8kit/core/registry.json';

// Итерация по всем компонентам
registry.items.forEach(component => {
  console.log(`${component.name}: ${component.description}`);
  console.log(`Тип: ${component.type}`);
  console.log(`Зависимости:`, component.dependencies);
});
```

**Структура реестра:**

```
{
  "name": "@ui8kit/core",
  "version": "1.0.0",
  "items": [
    {
      "name": "button",
      "type": "registry:ui",
      "description": "Action button component",
      "dependencies": ["class-variance-authority"],
      "files": [...]
    }
  ]
}
```

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

* Автоматизация обнаружения компонентов
* Генерация документации
* Построение кастомных CLI-инструментов
* Валидация метаданных компонентов

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

***

## Инвентарь компонентов

### Полный список компонентов

| Слой | Количество компонентов | Компоненты |
| - | - | - |
| **Слой 1: Базовые примитивы** | 5 | `Block`, `Box`, `Grid`, `Flex`, `Stack` |
| **Слой 2: UI-компоненты** | 15 | `Button`, `Card`, `Text`, `Title`, `Container`, `Icon`, `Image`, `Badge`, `Group`, `Sheet`, `Accordion` |
| **Слой 3: Макеты** | 3 | `DashLayout`, `LayoutBlock`, `SplitBlock` |
| **Всего** | **23** | - |

### Распределение компонентов по типам

| Категория | Количество | Назначение |
| - | - | - |
| **Примитивы** | 5 | Основа для всех макетов и компонентов |
| **Контент** | 5 | Текст, заголовки, изображения, иконки, метки |
| **Контейнеры** | 3 | Карточки, группы, контейнеры |
| **Интерактивные** | 2 | Кнопки, sheets |
| **Раскрывающиеся** | 1 | Accordion |
| **Макеты** | 7 | Grid, Flex, Stack, DashLayout, LayoutBlock, SplitBlock, Container |

### Статистика покрытия вариантами

| Область покрытия | Процент | Задействованные варианты |
| - | - | - |
| **Отступы** | 30% | 16 props (p, m, px, py и т.д.) |
| **Цвета** | 20% | 3 props (bg, c, borderColor) |
| **Макет** | 20% | 5 props (w, h, minH, maxW, position) |
| **Типографика** | 15% | 4 props (size, weight, align, leading) |
| **Эффекты** | 15% | 3 props (rounded, shadow, border) |
| **Общее покрытие** | **\~80%** | **12 категорий вариантов** |

**Источники:** [README.md361-387](https://github.com/ui8kit/core/blob/2afe2195/README.md#L361-L387) [README.md388-403](https://github.com/ui8kit/core/blob/2afe2195/README.md#L388-L403)

***

## Сводка ключевых возможностей

### Типобезопасность и опыт разработчика

| Возможность | Реализация | Преимущество |
| - | - | - |
| **Полная поддержка TypeScript** | Все компоненты с точными интерфейсами props | Предотвращает ошибки во время выполнения, автодополнение IDE |
| **Проброс props** | Расширенные компоненты наследуют базовые props | Согласованный API, уменьшенная кривая обучения |
| **Семантический HTML** | Компоненты рендерятся как `section`, `article`, `nav` и т.д. | Лучшая доступность (WCAG), улучшенное SEO |
| **Data-атрибуты** | Все компоненты включают атрибут `data-class` | Согласованное таргетирование DOM для тестирования/стилизации |
| **Паттерн ForwardRef** | Все компоненты поддерживают проброс `ref` | Прямой доступ к DOM при необходимости |

### Производительность и размер бандла

| Оптимизация | Реализация | Преимущество |
| - | - | - |
| **Нулевые накладные расходы во время выполнения** | CVA генерирует статические классы на этапе сборки | Нет вычисления стилей во время выполнения |
| **Tree Shaking** | ES2022-модули с `sideEffects: false` | Неиспользуемые компоненты удаляются бандлерами |
| **Минимальные зависимости** | Только 5 основных зависимостей | Меньший размер бандла |
| **Белый список классов** | 618 классов в `core-classes.json` | Безопасность очистки Tailwind |
| **Установка по компонентам** | Через команду `buildy-ui add` | Устанавливайте только то, что нужно |

### Гибкость дизайна

| Возможность | Реализация | Преимущество |
| - | - | - |
| **Композируемая архитектура** | Примитивы комбинируются в неограниченные дизайны | Нет жестких дизайн-ограничений |
| **Система вариантов** | 12 повторно используемых категорий | \~80% стилизации без className |
| **Композитные компоненты** | `Card.Header`, `Card.Content`, `Card.Footer` | Гибкие паттерны композиции |
| **Темная тема** | `ThemeProvider` с персистентностью | Встроенная поддержка тем |
| **Адаптивный дизайн** | Адаптивные префиксы Tailwind работают на всех вариантах | Mobile-first макеты |

**Источники:** [README.md9-19](https://github.com/ui8kit/core/blob/2afe2195/README.md#L9-L19) [package.json30](https://github.com/ui8kit/core/blob/2afe2195/package.json#L30-L30) [src/themes/providers/ThemeProvider.tsx1-109](https://github.com/ui8kit/core/blob/2afe2195/src/themes/providers/ThemeProvider.tsx#L1-L109)

***

## Начало работы

Чтобы начать использовать `@ui8kit/core`, перейдите к [Начало работы](#2) для инструкций по установке и примеров базовой конфигурации.

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

**Источники:** [.devin/wiki.json35-43](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L35-L43) [README.md21-60](https://github.com/ui8kit/core/blob/2afe2195/README.md#L21-L60)


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