Перейти к основному содержанию

Обзор

Этот документ представляет @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

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

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

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

ПринципРеализацияПреимущество
Минимализм15 UI-компонентов против 50+ в типичных библиотекахУменьшенный размер бандла, более быстрая кривая обучения
Покрытие 80/2012 вариантов покрывают ~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 .devin/wiki.json7-10 src/components/GUIDE_CREATE_FORM.md1-100

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

Система вариантов (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/)

Пять фундаментальных компонентов, которые напрямую применяют систему вариантов:
КомпонентФайлНазначениеПрименяемые варианты
BlockBlock.tsxСемантический контейнер (section, article, nav и т.д.)Все 12 вариантов
BoxBox.tsxУниверсальный гибкий примитив (любой HTML-элемент)Все 12 вариантов
GridGrid.tsxCSS Grid макет с props cols и rowsВарианты отступов, макета
FlexFlex.tsxFlexbox макет с props direction и justifyВарианты отступов, макета
StackStack.tsxВертикальная/горизонтальная укладка с prop gapВарианты отступов
Эти примитивы обеспечивают основу для всех компонентов более высокого уровня. Они рендерят семантические HTML5-элементы и принимают props вариантов напрямую.

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

Пятнадцать композитных компонентов, которые расширяют примитивы через проброс props:
КомпонентФайлБазовый примитивСпециальные возможности
Buttonbutton.tsxBoxvariant, size, leftSection, rightSection
Cardcard.tsxBlockКомпозитный: Card.Header, Card.Content, Card.Footer
Texttext.tsxBoxСемантические теги: p, span, em, strong
Titletitle.tsxBoxИерархия заголовков: h1-h6 через prop order
Badgebadge.tsxBoxМаленькая метка с variant
Iconicon.tsxBoxОбертка SVG с контролем размера
Imageimage.tsxBoxОптимизировано с props alt и loading
Containercontainer.tsxBlockАдаптивная max-width: sm, md, lg, xl, 2xl
Groupgroup.tsxFlexГруппировка элементов с gap
Sheetsheet.tsxN/ADrawer с prop side (использует lucide-react)
Accordionaccordion.tsxN/AРаскрывающиеся секции (использует lucide-react)
Эти компоненты наследуют все props вариантов от своих базовых примитивов, добавляя специфичные для компонента props.

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

Три шаблонных компонента, которые оркеструют компоненты Слоя 2 в структуры приложений:
КомпонентФайлНазначениеЗависимости
DashLayoutDashLayout.tsxДашборд с изменяемой боковой панелью, хедером, контентомreact-resizable-panels
LayoutBlockLayoutBlock.tsxСекция контента с хуками beforeContent/content/afterContentGrid
SplitBlockSplitBlock.tsxДвухколоночный макет (медиа + контент или контент + медиа)Container
Источники: 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

Файлы вариантов (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, mrnone, xs, sm, md, lg, xl, 2xl, autospacing-variants.ts
Цветаbg, c, borderColorЦвета дизайн-системы: primary, secondary, destructive, card, foreground и т.д.color-variants.ts
Макетw, h, minH, maxW, positionauto, full, screen, fit, min, maxlayout-variants.ts
Типографикаsize, weight, align, leadingРазмеры шрифта: xs, sm, md, lg, xl, 2xl, 3xl; вес: normal, medium, boldtypography-variants.ts
Эффектыrounded, shadow, borderРадиус углов, глубина тени, стили границeffect-variants.ts
Flexboxdirection, justify, items, wrap, gapСвойства FlexboxИнтегрировано в варианты макета
Gridcols, 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 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

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

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

ПакетВерсияНазначениеИспользование
react^18.0.0 или ^19.0.0UI-фреймворкPeer-зависимость (предоставляется потребителем)
react-dom^18.0.0 или ^19.0.0Рендеринг ReactPeer-зависимость (предоставляется потребителем)
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.jsonSafelist для Tailwind (618 классов)
Реестр компонентовsrc/registry.jsonМетаданные для установки по компонентам
Конфигурация экспорта в package.json33-37:
{
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}
Источники: package.json48-69 package.json30-37 README.md422-440

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

Метод интеграции 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 package.json2-3

Метод 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:
{
  "name": "button",
  "type": "registry:ui",
  "dependencies": ["class-variance-authority"],
  "files": [
    {
      "path": "components/ui/button.tsx",
      "type": "registry:ui"
    }
  ]
}
Источники: README.md252-276 src/registry.json1-244

Метод 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 (упомянуто в диаграммах)

Метод 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 src/registry.json1-10

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

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

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

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

КатегорияКоличествоНазначение
Примитивы5Основа для всех макетов и компонентов
Контент5Текст, заголовки, изображения, иконки, метки
Контейнеры3Карточки, группы, контейнеры
Интерактивные2Кнопки, sheets
Раскрывающиеся1Accordion
Макеты7Grid, 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 README.md388-403

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

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

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

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

ОптимизацияРеализацияПреимущество
Нулевые накладные расходы во время выполненияCVA генерирует статические классы на этапе сборкиНет вычисления стилей во время выполнения
Tree ShakingES2022-модули с 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 package.json30 src/themes/providers/ThemeProvider.tsx1-109

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

Чтобы начать использовать @ui8kit/core, перейдите к Начало работы для инструкций по установке и примеров базовой конфигурации. Для подробной документации по архитектуре см. Архитектура.
Для справочника по API компонентов см. Справочник API.
Для паттернов разработки и лучших практик см. Руководство разработчика.
Источники: .devin/wiki.json35-43 README.md21-60