Обзор
Этот документ представляет@ui8kit/core — минималистичную библиотеку React UI-компонентов, построенную на utility-first Tailwind CSS и семантическом HTML5. Он охватывает философию дизайна, архитектурные слои, инвентарь компонентов, систему вариантов и методы интеграции.
Для инструкций по установке и настройке см. Начало работы.Для подробного описания архитектуры см. Архитектура.
Для полной документации API см. Справочник API. Источники: .devin/wiki.json24-33 README.md1-10
Назначение и область применения
@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для иконок в определенных компонентах)
Философия дизайна
Библиотека построена на принципе минимального кода с максимальной гибкостью. Сложные интерфейсы возникают из композиции небольшого набора примитивов, а не из сборки десятков специализированных компонентов.Основные принципы
| Принцип | Реализация | Преимущество |
|---|---|---|
| Минимализм | 15 UI-компонентов против 50+ в типичных библиотеках | Уменьшенный размер бандла, более быстрая кривая обучения |
| Покрытие 80/20 | 12 вариантов покрывают ~80% потребностей в стилизации | Устраняет большинство ручного использования className |
| Композируемость | Примитивы комбинируются для создания неограниченных дизайнов | Никаких жестких дизайн-ограничений |
| Типобезопасность | Полная поддержка TypeScript с интерфейсами props | Предотвращает ошибки props во время выполнения |
| Семантический HTML | Компоненты рендерятся как <section>, <article>, <nav> и т.д. | Лучшая доступность и SEO |
| Нулевые накладные расходы во время выполнения | CVA генерирует статические классы Tailwind на этапе сборки | Нет вычисления стилей во время выполнения |
Минимализм на практике
Библиотека достигает сложности интерфейса через композицию, а не через разрастание компонентов:- Исключает 4 специализированных компонента из бандла
- Предоставляет полный контроль стилизации через варианты
- Сохраняет семантический HTML с
component="form"иcomponent="input" - Не требует дополнительной кривой обучения компонентов
Архитектура компонентов
Слой 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 | Варианты отступов |
Слой 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) |
Слой 3: Шаблоны макетов (src/layouts/)
Три шаблонных компонента, которые оркеструют компоненты Слоя 2 в структуры приложений:
| Компонент | Файл | Назначение | Зависимости |
|---|---|---|---|
DashLayout | DashLayout.tsx | Дашборд с изменяемой боковой панелью, хедером, контентом | react-resizable-panels |
LayoutBlock | LayoutBlock.tsx | Секция контента с хуками beforeContent/content/afterContent | Grid |
SplitBlock | SplitBlock.tsx | Двухколоночный макет (медиа + контент или контент + медиа) | Container |
Обзор системы вариантов
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 | Интегрировано в варианты макета |
Поток применения вариантов
- Разработчик пишет props вариантов в JSX:
<Card p="lg" rounded="xl" shadow="md" bg="card" /> - Движок CVA разрешает props в классы Tailwind через функцию
cva()изclass-variance-authority - Сгенерированные классы выводятся:
p-8 rounded-xl shadow-md bg-card - Валидация по белому списку обеспечивает, что очистка Tailwind не удаляет необходимые классы (618 классов в
core-classes.json) - DOM рендерится с применённой финальной строкой классов
Извлечение классов на этапе сборки
Скриптscripts/cva-extractor.ts сканирует все файлы вариантов и генерирует src/lib/core-classes.json:
- Safelist для Tailwind - предотвращает удаление классов вариантов при очистке CSS
- Безопасность tw-merge - обеспечивает корректное слияние классов
Технологический стек
Основные зависимости
| Пакет | Версия | Назначение | Использование |
|---|---|---|---|
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 | Метаданные для установки по компонентам |
Методы интеграции
Метод 1: Установка полной библиотеки (NPM)
Случай использования: Стандартная разработка приложений со всеми доступными компонентами- Одна зависимость в объявлении
- Все компоненты немедленно доступны
- Автоматические обновления через
npm update
Метод 2: Установка по компонентам (buildy-ui CLI)
Случай использования: Оптимизация бандла, постепенное внедрение, микросервисыcomponents/ui/
- Минимальный размер бандла (только установленные компоненты)
- Нет зависимости от полной библиотеки
- Полный контроль исходного кода
Метод 3: Git Submodule (Монорепозиторий)
Случай использования: Архитектуры монорепозиториев, разделяемые библиотеки компонентов между проектами- Прямой доступ к исходному коду
- Закрепление версий через git-коммиты
- Разделение между пакетами монорепозитория
- Возможность локальных модификаций
Метод 4: Интеграция прямого исходного кода
Случай использования: Кастомные сборки, сильно модифицированные компоненты, встраиваемые системы Процесс:- Скопировать директорию
src/в проект - Скорректировать пути импортов
- Настроить компоненты по необходимости
- Собрать с TypeScript-компилятором проекта
- Полный контроль над исходным кодом
- Нет внешних зависимостей
- Кастомные таргеты компиляции
- Удаление неиспользуемых компонентов
Метод 5: Программный доступ к реестру
Случай использования: Инструменты сборки, генераторы документации компонентов, автоматизированное тестирование- Автоматизация обнаружения компонентов
- Генерация документации
- Построение кастомных CLI-инструментов
- Валидация метаданных компонентов
Инвентарь компонентов
Полный список компонентов
| Слой | Количество компонентов | Компоненты |
|---|---|---|
| Слой 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 категорий вариантов |
Сводка ключевых возможностей
Типобезопасность и опыт разработчика
| Возможность | Реализация | Преимущество |
|---|---|---|
| Полная поддержка 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 макеты |
Начало работы
Чтобы начать использовать@ui8kit/core, перейдите к Начало работы для инструкций по установке и примеров базовой конфигурации.
Для подробной документации по архитектуре см. Архитектура.Для справочника по API компонентов см. Справочник API.
Для паттернов разработки и лучших практик см. Руководство разработчика. Источники: .devin/wiki.json35-43 README.md21-60