Обзор
Этот документ представляет@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для иконок в определенных компонентах)
Философия дизайна
Библиотека построена на принципе минимального кода с максимальной гибкостью. Сложные интерфейсы возникают из композиции небольшого набора примитивов, а не из сборки десятков специализированных компонентов.Основные принципы
Минимализм на практике
Библиотека достигает сложности интерфейса через композицию, а не через разрастание компонентов:- Исключает 4 специализированных компонента из бандла
- Предоставляет полный контроль стилизации через варианты
- Сохраняет семантический HTML с
component="form"иcomponent="input" - Не требует дополнительной кривой обучения компонентов
Архитектура компонентов
Слой 1: Базовые примитивы (src/core/ui/)
Пять фундаментальных компонентов, которые напрямую применяют систему вариантов:
Эти примитивы обеспечивают основу для всех компонентов более высокого уровня. Они рендерят семантические HTML5-элементы и принимают props вариантов напрямую.
Слой 2: UI-компоненты (src/components/ui/)
Пятнадцать композитных компонентов, которые расширяют примитивы через проброс props:
Эти компоненты наследуют все props вариантов от своих базовых примитивов, добавляя специфичные для компонента props.
Слой 3: Шаблоны макетов (src/layouts/)
Три шаблонных компонента, которые оркеструют компоненты Слоя 2 в структуры приложений:
Источники: README.md62-168 src/core/ui/Block.tsx1-50 src/core/ui/Box.tsx1-40 src/components/ui/button.tsx1-100 src/components/ui/card.tsx1-150 src/layouts/DashLayout.tsx1-100
Обзор системы вариантов
className в большинстве сценариев.
Категории вариантов
Поток применения вариантов
- Разработчик пишет 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 - обеспечивает корректное слияние классов
Технологический стек
Основные зависимости
Инструменты сборки
Формат распространения
Библиотека распространяется как ES2022-модули с TypeScript-объявлениями:
Конфигурация экспорта в package.json33-37:
Методы интеграции
Метод 1: Установка полной библиотеки (NPM)
Случай использования: Стандартная разработка приложений со всеми доступными компонентами- Одна зависимость в объявлении
- Все компоненты немедленно доступны
- Автоматические обновления через
npm update
Метод 2: Установка по компонентам (buildy-ui CLI)
Случай использования: Оптимизация бандла, постепенное внедрение, микросервисыcomponents/ui/
- Минимальный размер бандла (только установленные компоненты)
- Нет зависимости от полной библиотеки
- Полный контроль исходного кода
Метод 3: Git Submodule (Монорепозиторий)
Случай использования: Архитектуры монорепозиториев, разделяемые библиотеки компонентов между проектами- Прямой доступ к исходному коду
- Закрепление версий через git-коммиты
- Разделение между пакетами монорепозитория
- Возможность локальных модификаций
Метод 4: Интеграция прямого исходного кода
Случай использования: Кастомные сборки, сильно модифицированные компоненты, встраиваемые системы Процесс:- Скопировать директорию
src/в проект - Скорректировать пути импортов
- Настроить компоненты по необходимости
- Собрать с TypeScript-компилятором проекта
- Полный контроль над исходным кодом
- Нет внешних зависимостей
- Кастомные таргеты компиляции
- Удаление неиспользуемых компонентов
Метод 5: Программный доступ к реестру
Случай использования: Инструменты сборки, генераторы документации компонентов, автоматизированное тестирование- Автоматизация обнаружения компонентов
- Генерация документации
- Построение кастомных CLI-инструментов
- Валидация метаданных компонентов
Инвентарь компонентов
Полный список компонентов
Распределение компонентов по типам
Статистика покрытия вариантами
Источники: README.md361-387 README.md388-403
Сводка ключевых возможностей
Типобезопасность и опыт разработчика
Производительность и размер бандла
Гибкость дизайна
Источники: README.md9-19 package.json30 src/themes/providers/ThemeProvider.tsx1-109
Начало работы
Чтобы начать использовать@ui8kit/core, перейдите к Начало работы для инструкций по установке и примеров базовой конфигурации.
Для подробной документации по архитектуре см. Архитектура.Для справочника по API компонентов см. Справочник API.
Для паттернов разработки и лучших практик см. Руководство разработчика. Источники: .devin/wiki.json35-43 README.md21-60