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

Этот документ охватывает установку, конфигурацию и начальную настройку @ui8kit/core в вашем React-приложении. Он предоставляет пошаговые инструкции по интеграции библиотеки в различные типы проектов (Next.js, Vite, Create React App) и демонстрирует базовые паттерны использования компонентов. Для получения подробной информации об архитектуре см. Архитектура. Для полной документации по API компонентов см. Справочник API. Для продвинутых паттернов интеграции, включая настройку монорепозитория, обратитесь к SUBMODULE_GUIDE.md

Предварительные требования

Перед установкой @ui8kit/core убедитесь, что ваша среда разработки соответствует следующим требованиям:

Требование	Версия	Назначение
Node.js	18.0.0+	JavaScript runtime
React	18.0.0 или 19.0.0+	Peer dependency
React DOM	18.0.0 или 19.0.0+	Peer dependency
Tailwind CSS	3.4.0+	Utility-first стилизация
TypeScript	5.0.0+ (опционально)	Типобезопасность

Источники: package.json55-58 package.json59-66

Методы установки

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

Процесс установки

Выбор метода установки

Установка полной библиотеки
npm install @ui8kit/core

Установка отдельных компонентов
npx buildy-ui add button

Submodule для монорепозитория
git submodule add

Прямая интеграция исходников
Копирование директории src/

NPM Registry
@ui8kit/Unsupported markdown: link

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

GitHub Repository
ui8kit/core

Настройка приложения

Настройка Tailwind
tailwind.config.js

Импорт CSS
index.css или globals.css

Настройка ThemeProvider
App.tsx или _app.tsx

Источники: README.md21-34 README.md252-276 package.json1-70

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

Установите полную библиотеку со всеми 15 UI-компонентами и 3 шаблонами макетов:

npm install @ui8kit/core react react-dom

Это устанавливает:

Базовые примитивы: Block, Box, Grid, Flex, Stack
UI-компоненты: Button, Card, Text, Title, Container, Icon, Image, Badge, Group, Sheet, Accordion
Компоненты макетов: DashLayout, LayoutBlock, SplitBlock
Систему вариантов CVA и утилиты для тем

Источники: README.md25-27 package.json31-37

Метод 2: Установка отдельных компонентов

Установите отдельные компоненты для оптимального размера бандла:

npx buildy-ui add button card text

Этот метод использует src/registry.json для установки только запрошенных компонентов и их зависимостей. Каждый компонент развертывается в свою целевую директорию:

UI-компоненты → components/ui/
Компоненты макетов → layouts/

Источники: README.md260-265 src/registry.json

Метод 3: Submodule для монорепозитория

Для архитектур монорепозиториев интегрируйте как Git submodule:

git submodule add https://github.com/ui8kit/core.git packages/@ui8kit/core
git submodule update --init --recursive

Этот подход обеспечивает:

Прямой доступ к исходникам для кастомизации
Интеграцию с Turbo/workspace
Разрешение зависимостей без копирования

Полные инструкции по настройке монорепозитория доступны в SUBMODULE_GUIDE.md1-713 Источники: SUBMODULE_GUIDE.md136-144 SUBMODULE_GUIDE.md594-608

Настройка проекта

После установки настройте ваш проект для включения утилит Tailwind CSS, переменных темы и разрешения путей TypeScript.

Шаги настройки по файлам

Использование компонентов

Точка входа приложения

Конфигурационные файлы

tailwind.config.js
Пути контента, темная тема, тема

tsconfig.json
Алиасы путей для @ui8kit/core

index.css / globals.css
CSS-переменные, слои Tailwind

postcss.config.js
Tailwind + Autoprefixer

App.tsx / _app.tsx
Обертка ThemeProvider

main.tsx / index.tsx
Импорт CSS, рендер root

import Button from '@ui8kit/core'

Использование вариантов:
p='lg' rounded='xl' shadow='md'

Хук useTheme:
toggleDarkMode, isDarkMode

Источники: SUBMODULE_GUIDE.md332-437 SUBMODULE_GUIDE.md449-589

Шаг 1: Установка Tailwind CSS

Если Tailwind CSS еще не установлен:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Это генерирует tailwind.config.js и postcss.config.js. Источники: README.md29-34

Шаг 2: Настройка Tailwind

Обновите tailwind.config.js, чтобы включить пути к компонентам библиотеки и активировать темную тему:

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{ts,tsx,js,jsx}",
    "./node_modules/@ui8kit/core/dist/**/*.js"  // Полная библиотека
    // ИЛИ для submodule:
    // "./packages/@ui8kit/core/src/**/*.{ts,tsx}"
  ],
  darkMode: 'class',  // Включить темную тему на основе класса
  theme: {
    extend: {
      colors: {
        border: 'hsl(var(--border))',
        input: 'hsl(var(--input))',
        ring: 'hsl(var(--ring))',
        background: 'hsl(var(--background))',
        foreground: 'hsl(var(--foreground))',
        primary: {
          DEFAULT: 'hsl(var(--primary))',
          foreground: 'hsl(var(--primary-foreground))',
        },
        secondary: {
          DEFAULT: 'hsl(var(--secondary))',
          foreground: 'hsl(var(--secondary-foreground))',
        },
        // ... дополнительные семантические цвета
      },
      borderRadius: {
        lg: 'var(--radius)',
        md: 'calc(var(--radius) - 2px)',
        sm: 'calc(var(--radius) - 4px)',
      },
      // ... дополнительные расширения темы
    },
  },
  plugins: [],
}

Критическая конфигурация:

Пути content: Должны включать файлы исходников библиотеки, чтобы предотвратить удаление необходимых классов Tailwind
darkMode: 'class': Требуется для функциональности переключения темы
Цвета через CSS-переменные: Включают динамическое изменение темы через паттерн hsl(var(--primary))

Источники: SUBMODULE_GUIDE.md332-437

Шаг 3: Настройка CSS-переменных и слоев Tailwind

Создайте или обновите ваш глобальный CSS-файл (обычно src/index.css или app/globals.css):

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 97.2549%;
    --foreground: 240 3.3333% 11.7647%;
    --card: 0 0% 100%;
    --card-foreground: 240 3.3333% 11.7647%;
    --primary: 187.4739 173.4032% 31.3580%;
    --primary-foreground: 0 0% 100%;
    --secondary: 0 0% 94.1176%;
    --secondary-foreground: 0 0% 29.0196%;
    --border: 0 0% 87.8431%;
    --radius: 0.625rem;
    /* ... дополнительные переменные светлой темы */
  }
  
  .dark {
    --background: 0 0% 7.0588%;
    --foreground: 0 0% 87.8431%;
    --card: 0 0% 11.7647%;
    --card-foreground: 0 0% 87.8431%;
    --primary: 189.9661 161.8632% 27.5935%;
    --primary-foreground: 183.1588 99.9180% 96.2486%;
    --secondary: 0 0% 16.4706%;
    --secondary-foreground: 0 0% 80%;
    --border: 0 0% 20%;
    /* ... дополнительные переменные темной темы */
  }
}

Формат переменных:

Цвета используют формат HSL без обертки hsl(): "187.4739 173.4032% 31.3580%"
Применяются в конфигурации Tailwind как: hsl(var(--primary))
Этот паттерн позволяет переключать тему во время выполнения

Источники: SUBMODULE_GUIDE.md449-589

Шаг 4: Настройка TypeScript (Опционально)

Если используете TypeScript, добавьте алиасы путей в tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@ui8kit/core": ["./node_modules/@ui8kit/core/dist"],
      "@ui8kit/core/*": ["./node_modules/@ui8kit/core/dist/*"]
      // ИЛИ для submodule:
      // "@ui8kit/core": ["./packages/@ui8kit/core/src"],
      // "@ui8kit/core/*": ["./packages/@ui8kit/core/src/*"]
    }
  }
}

Источники: SUBMODULE_GUIDE.md187-217

Базовое использование

После настройки вы можете импортировать и использовать компоненты с системой вариантов CVA.

Паттерн импорта и использования компонентов

Рендеринг во время выполнения

Определение компонента

Фаза импорта

import Button, Card, Text
from '@ui8kit/core'

import ThemeProvider
from '@ui8kit/core'

JSX компонента:
<Card p='lg' rounded='xl'>

Пропсы вариантов:
p, m, rounded, shadow, bg, c

Дочерние компоненты:
Card.Header, Card.Content

CVA разрешает варианты
в классы Tailwind

Отрендеренный HTML:
<section class='p-8 rounded-xl'>

Применен класс темы:
.dark на <html>

Источники: README.md36-60 README.md91-103

Пример 1: Первый компонент

Создайте простую карточку с кнопкой, используя пропсы вариантов:

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

export function WelcomeCard() {
  return (
    <Card p="lg" rounded="xl" shadow="md">
      <Card.Header>
        <Text as="h2" size="xl" weight="bold">
          Welcome
        </Text>
      </Card.Header>
      <Card.Content>
        <Stack gap="md">
          <Text>Build beautiful UIs with minimal code.</Text>
          <Button variant="primary" size="md">
            Get Started
          </Button>
        </Stack>
      </Card.Content>
    </Card>
  );
}

Ключевые паттерны:

Пропсы вариантов: p="lg", rounded="xl", shadow="md" вместо className
Составные компоненты: Card.Header, Card.Content, Card.Footer для гибкой композиции
Семантические компоненты: Text as="h2" рендерит элемент <h2>
Макет Stack: Stack gap="md" для вертикальных отступов

Источники: README.md38-60

Пример 2: Настройка провайдера темы

Оберните ваше приложение в ThemeProvider для поддержки темной темы:

import { ThemeProvider, modernUITheme } from '@ui8kit/core';
import { AppContent } from './AppContent';

export default function App() {
  return (
    <ThemeProvider theme={modernUITheme}>
      <AppContent />
    </ThemeProvider>
  );
}

Затем используйте хук useTheme в компонентах:

import { useTheme } from '@ui8kit/core';
import { Button } from '@ui8kit/core';

export function ThemeToggle() {
  const { isDarkMode, toggleDarkMode } = useTheme();
  
  return (
    <Button onClick={toggleDarkMode}>
      {isDarkMode ? '☀️ Light Mode' : '🌙 Dark Mode'}
    </Button>
  );
}

Доступные темы:

modernUITheme - Современная дизайн-система
skyOSTheme - Палитра, вдохновленная небом
lesseUITheme - Минималистичная эстетика

Источники: README.md219-249 SUBMODULE_GUIDE.md277-304

Пример 3: Композиция макета

Постройте макет страницы с примитивами:

import { Block, Container, Stack, Grid, Box } from '@ui8kit/core';

export function PageLayout() {
  return (
    <Block component="main" py="xl">
      <Container maxW="7xl">
        <Stack gap="lg">
          <Box as="header" mb="md">
            <h1>Page Title</h1>
          </Box>
          
          <Grid cols={2} gap="md">
            <Box bg="card" p="lg" rounded="lg">
              Column 1
            </Box>
            <Box bg="card" p="lg" rounded="lg">
              Column 2
            </Box>
          </Grid>
        </Stack>
      </Container>
    </Block>
  );
}

Используемые примитивы:

Block: Семантический контейнер (section, nav, main, article)
Container: Адаптивная обертка с максимальной шириной
Stack: Вертикальный макет с отступами
Grid: CSS Grid с управлением колонками
Box: Универсальный div с пропсами вариантов

Источники: README.md81-103

Настройка для конкретных фреймворков

Интеграция с Next.js

App Router (Next.js 13+)

1. Установите зависимости:

npm install @ui8kit/core react react-dom
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

2. Настройте app/layout.tsx:

import { ThemeProvider, modernUITheme } from '@ui8kit/core';
import './globals.css';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider theme={modernUITheme}>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Критично: Добавьте suppressHydrationWarning к <html>, чтобы предотвратить предупреждения о несоответствии класса темы во время гидратации. 3. Обновите app/globals.css: Импортируйте слои Tailwind и CSS-переменные, как показано в Шаг 3 4. Настройте tailwind.config.js:

export default {
  content: [
    './app/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    './node_modules/@ui8kit/core/dist/**/*.js',
  ],
  darkMode: 'class',
  // ... остальная конфигурация
}

Источники: SUBMODULE_GUIDE.md277-304

Pages Router (Next.js 12 и ранее)

Настройте pages/_app.tsx:

import { ThemeProvider, modernUITheme } from '@ui8kit/core';
import type { AppProps } from 'next/app';
import '../styles/globals.css';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <ThemeProvider theme={modernUITheme}>
      <Component {...pageProps} />
    </ThemeProvider>
  );
}

Источники: README.md223-232

Интеграция с Vite

1. Создайте проект Vite React:

npm create vite@latest my-app -- --template react-swc-ts
cd my-app

2. Установите зависимости:

npm install @ui8kit/core react react-dom
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

3. Настройте vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    }
  },
})

4. Обновите src/main.tsx:

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

5. Настройте src/App.tsx:

import { ThemeProvider, modernUITheme } from '@ui8kit/core';
import { Button, Card, Text, Stack } from '@ui8kit/core';

function App() {
  return (
    <ThemeProvider theme={modernUITheme}>
      <Card p="lg" rounded="xl" shadow="md">
        <Card.Header>
          <Text size="xl" weight="bold">Vite + UI8Kit</Text>
        </Card.Header>
        <Card.Content>
          <Stack gap="md">
            <Text>Fast development with Vite</Text>
            <Button variant="primary">Get Started</Button>
          </Stack>
        </Card.Content>
      </Card>
    </ThemeProvider>
  );
}

export default App;

Источники: SUBMODULE_GUIDE.md154-184 SUBMODULE_GUIDE.md234-258 SUBMODULE_GUIDE.md260-304

Интеграция с Create React App

1. Создайте проект CRA:

npx create-react-app my-app --template typescript
cd my-app

2. Установите зависимости:

npm install @ui8kit/core react react-dom
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

3. Настройте tailwind.config.js:

export default {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@ui8kit/core/dist/**/*.js",
  ],
  darkMode: 'class',
  // ... остальная конфигурация
}

4. Обновите src/index.tsx:

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

5. Настройте src/App.tsx:

import { ThemeProvider, modernUITheme } from '@ui8kit/core';
import { Button, Card, Text } from '@ui8kit/core';

function App() {
  return (
    <ThemeProvider theme={modernUITheme}>
      <div className="min-h-screen bg-background p-8">
        <Card p="lg" rounded="xl" shadow="md">
          <Card.Header>
            <Text size="xl" weight="bold">
              Create React App + UI8Kit
            </Text>
          </Card.Header>
          <Card.Content>
            <Text mb="md">Ready to build.</Text>
            <Button variant="primary">Start Building</Button>
          </Card.Content>
        </Card>
      </div>
    </ThemeProvider>
  );
}

export default App;

Источники: README.md412-421

Проверка

После настройки проверьте вашу установку с помощью этого чек-листа:

Чек-лист проверки

Проверка	Ожидаемое поведение	Решение проблем
Импорт компонента	`import { Button } from '@ui8kit/core'` работает без ошибок	Проверьте, что существует `node_modules/@ui8kit/core`
Пропсы вариантов	`<Box p="lg" rounded="md" />` применяет классы	Проверьте, что пути content в Tailwind включают библиотеку
Переключение темной темы	Клик по переключателю темы меняет внешний вид	Проверьте `darkMode: 'class'` в конфигурации Tailwind
CSS-переменные	Цвета рендерятся корректно в светлом/темном режиме	Проверьте переменные `:root` и `.dark` в CSS
Типы TypeScript	Нет ошибок типов в IDE	Проверьте версию TypeScript ≥5.0.0
Dev-сервер	Приложение запускается без ошибок в консоли	Проверьте установку peer-зависимостей

Источники: README.md21-60 README.md412-421

Тестовый компонент

Создайте тестовый компонент для проверки всех функций:

import { 
  ThemeProvider, 
  modernUITheme, 
  useTheme,
  Card, 
  Button, 
  Text, 
  Stack,
  Box 
} from '@ui8kit/core';

function TestContent() {
  const { isDarkMode, toggleDarkMode } = useTheme();
  
  return (
    <Box p="xl" bg="background" minH="screen">
      <Stack gap="lg" align="center">
        <Card p="lg" rounded="xl" shadow="lg" maxW="md">
          <Card.Header>
            <Text size="2xl" weight="bold">
              UI8Kit Test
            </Text>
          </Card.Header>
          <Card.Content>
            <Stack gap="md">
              <Text>
                Theme: {isDarkMode ? 'Dark' : 'Light'}
              </Text>
              <Button 
                variant="primary" 
                onClick={toggleDarkMode}
              >
                Toggle Theme
              </Button>
              <Box 
                p="md" 
                bg="primary" 
                c="primary-foreground" 
                rounded="md"
              >
                <Text weight="medium">
                  ✓ Variant system working
                </Text>
              </Box>
            </Stack>
          </Card.Content>
        </Card>
      </Stack>
    </Box>
  );
}

export default function App() {
  return (
    <ThemeProvider theme={modernUITheme}>
      <TestContent />
    </ThemeProvider>
  );
}

Ожидаемые результаты:

Карточка рендерится с отступами, скругленными углами и тенью
Кнопка меняет внешний вид при наведении
Переключатель темы переключает между светлым/темным режимами
Цвета обновляются на основе CSS-переменных
Нет ошибок или предупреждений в консоли

Источники: README.md38-60 README.md236-249 SUBMODULE_GUIDE.md277-304

Следующие шаги

После завершения настройки:

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

Источники: README.md1-453 .devin/wiki.json24-44

Getting started

Architecture

Components

Development Guide

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

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

Предварительные требования

Методы установки

Процесс установки

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

Метод 2: Установка отдельных компонентов

Метод 3: Submodule для монорепозитория

Настройка проекта

Шаги настройки по файлам

Шаг 1: Установка Tailwind CSS

Шаг 2: Настройка Tailwind

Шаг 3: Настройка CSS-переменных и слоев Tailwind

Шаг 4: Настройка TypeScript (Опционально)

Базовое использование

Паттерн импорта и использования компонентов

Пример 1: Первый компонент

Пример 2: Настройка провайдера темы

Пример 3: Композиция макета

Настройка для конкретных фреймворков

Интеграция с Next.js

App Router (Next.js 13+)

Pages Router (Next.js 12 и ранее)

Интеграция с Vite

Интеграция с Create React App

Проверка

Чек-лист проверки

Тестовый компонент

Следующие шаги

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

​Предварительные требования

​Методы установки

​Процесс установки

​Метод 1: Установка полной библиотеки (Рекомендуется)

​Метод 2: Установка отдельных компонентов

​Метод 3: Submodule для монорепозитория

​Настройка проекта

​Шаги настройки по файлам

​Шаг 1: Установка Tailwind CSS

​Шаг 2: Настройка Tailwind

​Шаг 3: Настройка CSS-переменных и слоев Tailwind

​Шаг 4: Настройка TypeScript (Опционально)

​Базовое использование

​Паттерн импорта и использования компонентов

​Пример 1: Первый компонент

​Пример 2: Настройка провайдера темы

​Пример 3: Композиция макета

​Настройка для конкретных фреймворков

​Интеграция с Next.js

​App Router (Next.js 13+)

​Pages Router (Next.js 12 и ранее)

​Интеграция с Vite

​Интеграция с Create React App

​Проверка

​Чек-лист проверки

​Тестовый компонент

​Следующие шаги

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

Предварительные требования

Методы установки

Процесс установки

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

Метод 2: Установка отдельных компонентов

Метод 3: Submodule для монорепозитория

Настройка проекта

Шаги настройки по файлам

Шаг 1: Установка Tailwind CSS

Шаг 2: Настройка Tailwind

Шаг 3: Настройка CSS-переменных и слоев Tailwind

Шаг 4: Настройка TypeScript (Опционально)

Базовое использование

Паттерн импорта и использования компонентов

Пример 1: Первый компонент

Пример 2: Настройка провайдера темы

Пример 3: Композиция макета

Настройка для конкретных фреймворков

Интеграция с Next.js

App Router (Next.js 13+)

Pages Router (Next.js 12 и ранее)

Интеграция с Vite

Интеграция с Create React App

Проверка

Чек-лист проверки

Тестовый компонент

Следующие шаги