> ## Documentation Index
> Fetch the complete documentation index at: https://ui8kit.buildy.tw/llms.txt
> Use this file to discover all available pages before exploring further.
# Начало работы
> Руководство по установке и настройке UI8Kit Core - пошаговые инструкции по интеграции библиотеки React-компонентов
# Начало работы
Этот документ охватывает установку, конфигурацию и начальную настройку `@ui8kit/core` в вашем React-приложении. Он предоставляет пошаговые инструкции по интеграции библиотеки в различные типы проектов (Next.js, Vite, Create React App) и демонстрирует базовые паттерны использования компонентов.
Для получения подробной информации об архитектуре см. [Архитектура](#3). Для полной документации по API компонентов см. [Справочник API](#4). Для продвинутых паттернов интеграции, включая настройку монорепозитория, обратитесь к [SUBMODULE\_GUIDE.md](https://github.com/ui8kit/core/blob/2afe2195/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](https://github.com/ui8kit/core/blob/2afe2195/package.json#L55-L58) [package.json59-66](https://github.com/ui8kit/core/blob/2afe2195/package.json#L59-L66)
***
## Методы установки
Библиотека поддерживает несколько подходов к установке для различных архитектур проектов и требований к оптимизации.
### Процесс установки
```
Выбор метода установки
Установка полной библиотеки
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](https://github.com/ui8kit/core/blob/2afe2195/README.md#L21-L34) [README.md252-276](https://github.com/ui8kit/core/blob/2afe2195/README.md#L252-L276) [package.json1-70](https://github.com/ui8kit/core/blob/2afe2195/package.json#L1-L70)
***
### Метод 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](https://github.com/ui8kit/core/blob/2afe2195/README.md#L25-L27) [package.json31-37](https://github.com/ui8kit/core/blob/2afe2195/package.json#L31-L37)
***
### Метод 2: Установка отдельных компонентов
Установите отдельные компоненты для оптимального размера бандла:
```
npx buildy-ui add button card text
```
Этот метод использует [src/registry.json](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json) для установки только запрошенных компонентов и их зависимостей. Каждый компонент развертывается в свою целевую директорию:
* UI-компоненты → `components/ui/`
* Компоненты макетов → `layouts/`
**Источники:** [README.md260-265](https://github.com/ui8kit/core/blob/2afe2195/README.md#L260-L265) [src/registry.json](https://github.com/ui8kit/core/blob/2afe2195/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](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L1-L713)
**Источники:** [SUBMODULE\_GUIDE.md136-144](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L136-L144) [SUBMODULE\_GUIDE.md594-608](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L594-L608)
***
## Настройка проекта
После установки настройте ваш проект для включения утилит 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](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L332-L437) [SUBMODULE\_GUIDE.md449-589](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L449-L589)
***
### Шаг 1: Установка Tailwind CSS
Если Tailwind CSS еще не установлен:
```
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
```
Это генерирует `tailwind.config.js` и `postcss.config.js`.
**Источники:** [README.md29-34](https://github.com/ui8kit/core/blob/2afe2195/README.md#L29-L34)
***
### Шаг 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](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L332-L437)
***
### Шаг 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](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L449-L589)
***
### Шаг 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](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L187-L217)
***
## Базовое использование
После настройки вы можете импортировать и использовать компоненты с системой вариантов CVA.
### Паттерн импорта и использования компонентов
```
Рендеринг во время выполнения
Определение компонента
Фаза импорта
import Button, Card, Text
from '@ui8kit/core'
import ThemeProvider
from '@ui8kit/core'
JSX компонента:
Пропсы вариантов:
p, m, rounded, shadow, bg, c
Дочерние компоненты:
Card.Header, Card.Content
CVA разрешает варианты
в классы Tailwind
Отрендеренный HTML:
Применен класс темы:
.dark на
```
**Источники:** [README.md36-60](https://github.com/ui8kit/core/blob/2afe2195/README.md#L36-L60) [README.md91-103](https://github.com/ui8kit/core/blob/2afe2195/README.md#L91-L103)
***
### Пример 1: Первый компонент
Создайте простую карточку с кнопкой, используя пропсы вариантов:
```
import { Button, Card, Text, Stack } from '@ui8kit/core';
export function WelcomeCard() {
return (
Welcome
Build beautiful UIs with minimal code.
Get Started
);
}
```
**Ключевые паттерны:**
* **Пропсы вариантов**: `p="lg"`, `rounded="xl"`, `shadow="md"` вместо `className`
* **Составные компоненты**: `Card.Header`, `Card.Content`, `Card.Footer` для гибкой композиции
* **Семантические компоненты**: `Text as="h2"` рендерит элемент ``
* **Макет Stack**: `Stack gap="md"` для вертикальных отступов
**Источники:** [README.md38-60](https://github.com/ui8kit/core/blob/2afe2195/README.md#L38-L60)
***
### Пример 2: Настройка провайдера темы
Оберните ваше приложение в `ThemeProvider` для поддержки темной темы:
```
import { ThemeProvider, modernUITheme } from '@ui8kit/core';
import { AppContent } from './AppContent';
export default function App() {
return (
);
}
```
Затем используйте хук `useTheme` в компонентах:
```
import { useTheme } from '@ui8kit/core';
import { Button } from '@ui8kit/core';
export function ThemeToggle() {
const { isDarkMode, toggleDarkMode } = useTheme();
return (
{isDarkMode ? '☀️ Light Mode' : '🌙 Dark Mode'}
);
}
```
**Доступные темы:**
* `modernUITheme` - Современная дизайн-система
* `skyOSTheme` - Палитра, вдохновленная небом
* `lesseUITheme` - Минималистичная эстетика
**Источники:** [README.md219-249](https://github.com/ui8kit/core/blob/2afe2195/README.md#L219-L249) [SUBMODULE\_GUIDE.md277-304](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L277-L304)
***
### Пример 3: Композиция макета
Постройте макет страницы с примитивами:
```
import { Block, Container, Stack, Grid, Box } from '@ui8kit/core';
export function PageLayout() {
return (
Page Title
Column 1
Column 2
);
}
```
**Используемые примитивы:**
* **Block**: Семантический контейнер (`section`, `nav`, `main`, `article`)
* **Container**: Адаптивная обертка с максимальной шириной
* **Stack**: Вертикальный макет с отступами
* **Grid**: CSS Grid с управлением колонками
* **Box**: Универсальный div с пропсами вариантов
**Источники:** [README.md81-103](https://github.com/ui8kit/core/blob/2afe2195/README.md#L81-L103)
***
## Настройка для конкретных фреймворков
### Интеграция с 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 (
{children}
);
}
```
**Критично:** Добавьте `suppressHydrationWarning` к ``, чтобы предотвратить предупреждения о несоответствии класса темы во время гидратации.
**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](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L277-L304)
***
#### 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 (
);
}
```
**Источники:** [README.md223-232](https://github.com/ui8kit/core/blob/2afe2195/README.md#L223-L232)
***
### Интеграция с 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(
,
)
```
**5. Настройте `src/App.tsx`:**
```
import { ThemeProvider, modernUITheme } from '@ui8kit/core';
import { Button, Card, Text, Stack } from '@ui8kit/core';
function App() {
return (
Vite + UI8Kit
Fast development with Vite
Get Started
);
}
export default App;
```
**Источники:** [SUBMODULE\_GUIDE.md154-184](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L154-L184) [SUBMODULE\_GUIDE.md234-258](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L234-L258) [SUBMODULE\_GUIDE.md260-304](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L260-L304)
***
### Интеграция с 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(
);
```
**5. Настройте `src/App.tsx`:**
```
import { ThemeProvider, modernUITheme } from '@ui8kit/core';
import { Button, Card, Text } from '@ui8kit/core';
function App() {
return (
Create React App + UI8Kit
Ready to build.
Start Building
);
}
export default App;
```
**Источники:** [README.md412-421](https://github.com/ui8kit/core/blob/2afe2195/README.md#L412-L421)
***
## Проверка
После настройки проверьте вашу установку с помощью этого чек-листа:
### Чек-лист проверки
| Проверка | Ожидаемое поведение | Решение проблем |
| - | - | - |
| **Импорт компонента** | `import { Button } from '@ui8kit/core'` работает без ошибок | Проверьте, что существует `node_modules/@ui8kit/core` |
| **Пропсы вариантов** | `` применяет классы | Проверьте, что пути content в Tailwind включают библиотеку |
| **Переключение темной темы** | Клик по переключателю темы меняет внешний вид | Проверьте `darkMode: 'class'` в конфигурации Tailwind |
| **CSS-переменные** | Цвета рендерятся корректно в светлом/темном режиме | Проверьте переменные `:root` и `.dark` в CSS |
| **Типы TypeScript** | Нет ошибок типов в IDE | Проверьте версию TypeScript ≥5.0.0 |
| **Dev-сервер** | Приложение запускается без ошибок в консоли | Проверьте установку peer-зависимостей |
**Источники:** [README.md21-60](https://github.com/ui8kit/core/blob/2afe2195/README.md#L21-L60) [README.md412-421](https://github.com/ui8kit/core/blob/2afe2195/README.md#L412-L421)
***
### Тестовый компонент
Создайте тестовый компонент для проверки всех функций:
```
import {
ThemeProvider,
modernUITheme,
useTheme,
Card,
Button,
Text,
Stack,
Box
} from '@ui8kit/core';
function TestContent() {
const { isDarkMode, toggleDarkMode } = useTheme();
return (
UI8Kit Test
Theme: {isDarkMode ? 'Dark' : 'Light'}
Toggle Theme
✓ Variant system working
);
}
export default function App() {
return (
);
}
```
**Ожидаемые результаты:**
* Карточка рендерится с отступами, скругленными углами и тенью
* Кнопка меняет внешний вид при наведении
* Переключатель темы переключает между светлым/темным режимами
* Цвета обновляются на основе CSS-переменных
* Нет ошибок или предупреждений в консоли
**Источники:** [README.md38-60](https://github.com/ui8kit/core/blob/2afe2195/README.md#L38-L60) [README.md236-249](https://github.com/ui8kit/core/blob/2afe2195/README.md#L236-L249) [SUBMODULE\_GUIDE.md277-304](https://github.com/ui8kit/core/blob/2afe2195/SUBMODULE_GUIDE.md#L277-L304)
***
## Следующие шаги
После завершения настройки:
1. **Изучите компоненты**: Просмотрите раздел [UI-компоненты](#3.3) для подробной документации по компонентам
2. **Изучите варианты**: Изучите [Система вариантов](#3.2), чтобы понять 12 многократно используемых вариантов
3. **Создавайте макеты**: Исследуйте [Компоненты макетов](#3.4) для шаблонов дашбордов и страниц
4. **Изучите паттерны**: Проверьте [Руководство разработчика](#5) для распространенных паттернов использования
5. **Реализуйте темную тему**: См. [Темная тема](#5.4) для продвинутого управления темами
**Источники:** [README.md1-453](https://github.com/ui8kit/core/blob/2afe2195/README.md#L1-L453) [.devin/wiki.json24-44](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L24-L44)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.