Skip to main content

Обзор

Этот документ представляет @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 для иконок в определенных компонентах)
Источники: package.json1-20 README.md3-19 .devin/wiki.json2-10

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

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

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

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

Библиотека достигает сложности интерфейса через композицию, а не через разрастание компонентов:
Оба достигают одного и того же результата, но примитивный подход:
  • Исключает 4 специализированных компонента из бандла
  • Предоставляет полный контроль стилизации через варианты
  • Сохраняет семантический HTML с component="form" и component="input"
  • Не требует дополнительной кривой обучения компонентов
Источники: README.md388-403 .devin/wiki.json7-10 src/components/GUIDE_CREATE_FORM.md1-100

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

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

Слой 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

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

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

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

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

  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:
Этот белый список служит двум целям:
  • Safelist для Tailwind - предотвращает удаление классов вариантов при очистке CSS
  • Безопасность tw-merge - обеспечивает корректное слияние классов
Источники: README.md170-217 src/core/variants/spacing-variants.ts1-100 src/core/variants/color-variants.ts1-80 scripts/cva-extractor.ts1-260 src/lib/core-classes.json1-619

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

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

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

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

Библиотека распространяется как ES2022-модули с TypeScript-объявлениями: Конфигурация экспорта в package.json33-37:
Источники: package.json48-69 package.json30-37 README.md422-440

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

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

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

Случай использования: Стандартная разработка приложений со всеми доступными компонентами
Импорты:
Размер бандла: Полная библиотека (~15 UI-компонентов + 3 макета + 5 примитивов) Преимущества:
  • Одна зависимость в объявлении
  • Все компоненты немедленно доступны
  • Автоматические обновления через npm update
Источники: README.md21-34 package.json2-3

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

Случай использования: Оптимизация бандла, постепенное внедрение, микросервисы
Результат: Копирует файлы компонентов в директорию components/ui/
Импорты:
Преимущества:
  • Минимальный размер бандла (только установленные компоненты)
  • Нет зависимости от полной библиотеки
  • Полный контроль исходного кода
Метаданные реестра в src/registry.json1-244:
Источники: README.md252-276 src/registry.json1-244

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

Случай использования: Архитектуры монорепозиториев, разделяемые библиотеки компонентов между проектами
Конфигурация TypeScript:
Преимущества:
  • Прямой доступ к исходному коду
  • Закрепление версий через git-коммиты
  • Разделение между пакетами монорепозитория
  • Возможность локальных модификаций
Источники: SUBMODULE_GUIDE.md1-300 (упомянуто в диаграммах)

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

Случай использования: Кастомные сборки, сильно модифицированные компоненты, встраиваемые системы Процесс:
  1. Скопировать директорию src/ в проект
  2. Скорректировать пути импортов
  3. Настроить компоненты по необходимости
  4. Собрать с TypeScript-компилятором проекта
Преимущества:
  • Полный контроль над исходным кодом
  • Нет внешних зависимостей
  • Кастомные таргеты компиляции
  • Удаление неиспользуемых компонентов

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

Случай использования: Инструменты сборки, генераторы документации компонентов, автоматизированное тестирование
Структура реестра:
Преимущества:
  • Автоматизация обнаружения компонентов
  • Генерация документации
  • Построение кастомных CLI-инструментов
  • Валидация метаданных компонентов
Источники: README.md267-276 src/registry.json1-10

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

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

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

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

Источники: 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