Базовый рабочий процесс

Назначение и область применения

Этот документ описывает типичные рабочие процессы и паттерны разработки, используемые при создании пользовательских интерфейсов с помощью @ui8kit/core. Он охватывает распространенные сценарии, с которыми сталкиваются разработчики при компоновке компонентов, применении стилизации через систему вариантов и построении стандартных паттернов UI, таких как карточки, формы и макеты. Для продвинутых сценариев, где стандартных компонентов недостаточно (например, создание пользовательских компонентов форм), см. Продвинутый рабочий процесс. Для общих рекомендаций и советов по производительности см. Лучшие практики. Источники: .devin/wiki.json181-188 src/components/README.md1-259

Рабочий процесс выбора компонента

Первый шаг в любом рабочем процессе разработки — это выбор подходящего компонента для вашего случая использования. Библиотека следует трехуровневой иерархии, где каждый уровень служит определенным целям.

Да

Нет

Да

Нет

Да

Нет

Начало: Нужно отрисовать UI

Нужна структура
макета?

Нужен семантический
контейнер?

Нужен готовый
стилизованный компонент?

Уровень 1: Базовые примитивы

Уровень 2: UI-компоненты

Уровень 3: Макеты

Box
(универсальный контейнер)

Block
(семантический элемент)

Grid
(CSS Grid)

Flex
(Flexbox)

Stack
(вертикальный/горизонтальный)

Button

Card + подкомпоненты

Text

Title

Container

Badge

Group

Icon

Image

DashLayout

LayoutBlock

SplitBlock

Матрица принятия решений:

Сценарий	Выбор компонента	Причина
Универсальный контейнер со стилями	`Box`	Гибкий примитив с полной поддержкой вариантов
Семантический HTML-элемент (section, article, nav)	`Block`	Рендерит семантические теги через проп `component`
Сеточный макет	`Grid`	CSS Grid с адаптивными пресетами
Flexbox-макет	`Flex` или `Stack`	Flex для общих случаев, Stack для вертикального/горизонтального
Интерактивная кнопка	`Button`	Готовый стиль с вариантами и состояниями
Контентная карточка	`Card`	Составной компонент с Header/Content/Footer
Шаблон дашборда	`DashLayout`	Полный макет с боковой панелью и шапкой

Источники: README.md62-103 src/components/README.md9-19 README.md363-387

Рабочий процесс базовой стилизации

Все компоненты принимают пропы вариантов вместо строк className. Этот рабочий процесс показывает, как применять стилизацию через систему вариантов.

Вывод

Обработка CVA

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

Экземпляр компонента

Пропы отступов
p, m, px, py, и т.д.

Пропы цветов
bg, c, borderColor

Визуальные пропы
rounded, shadow, border

Пропы макета
w, h, position

Типографические пропы
size, weight, align

spacingVariants

colorVariants

roundedVariants

shadowVariants

layoutVariants

typographyVariants

Классы Tailwind
p-8 rounded-xl shadow-md

Пошагово: Стилизация компонента

Шаг 1: Применение вариантов отступов

// Импорт компонента
import { Box } from '@ui8kit/core';

// Применение внутренних и внешних отступов
<Box p="lg" m="md" mx="auto">
  Контент
</Box>

Доступные значения отступов: none, xs, sm, md, lg, xl, 2xl, auto Шаг 2: Применение вариантов цветов

<Box p="lg" bg="card" c="foreground">
  Контент с семантическими цветами
</Box>

Шаг 3: Применение визуальных эффектов

<Box p="lg" bg="card" rounded="xl" shadow="md" border="default">
  Стилизованный контейнер
</Box>

Шаг 4: Применение вариантов макета

<Box p="lg" w="full" h="screen" position="relative">
  Макет на всю ширину
</Box>

Справочник пропов вариантов

Категория	Пропы	Значения
Отступы	`p`, `px`, `py`, `pt`, `pb`, `pl`, `pr`	`none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`
Отступы	`m`, `mx`, `my`, `mt`, `mb`, `ml`, `mr`	`none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `auto`
Цвета	`bg`, `c`, `borderColor`	Токены цветов дизайн-системы
Скругление	`rounded`	`none`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full`
Тень	`shadow`	`none`, `sm`, `md`, `lg`, `xl`, `2xl`
Макет	`w`, `h`, `minH`, `maxW`	`auto`, `full`, `screen`, `fit`, `min`, `max`
Позиция	`position`	`static`, `relative`, `absolute`, `fixed`, `sticky`

Источники: README.md170-217 src/components/README.md206-222

Рабочие процессы паттернов макетов

Вертикальная укладка с `Stack`

Наиболее распространенный паттерн макета — это вертикальная укладка элементов.

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

<Stack gap="lg" align="center" p="md">
  <Title order={1}>Заголовок</Title>
  <Text>Описательный текст</Text>
  <Button variant="primary">Действие</Button>
</Stack>

Ключевые пропы Stack:

gap: Пространство между дочерними элементами (xs, sm, md, lg, xl, 2xl)
align: Выравнивание по поперечной оси (start, center, end, stretch)
justify: Выравнивание по главной оси (start, center, end, between, around)

Источники: src/components/README.md52-64

Горизонтальный макет с `Group`

Для горизонтальных расположений используйте Group.

import { Group, Button } from '@ui8kit/core';

<Group gap="md" align="center" justify="between">
  <Button variant="secondary">Отмена</Button>
  <Button variant="primary">Подтвердить</Button>
</Group>

Источники: src/components/README.md66-78

Сеточный макет с `Grid`

Для многоколоночных макетов используйте Grid с адаптивными пресетами.

import { Grid, GridCol, Card } from '@ui8kit/core';

<Grid cols="1-2-3" gap="lg" p="md">
  <GridCol span={2}>
    <Card p="lg">Широкая колонка</Card>
  </GridCol>
  <GridCol>
    <Card p="lg">Обычная колонка</Card>
  </GridCol>
</Grid>

Значения пресета cols:

"1-2-3": 1 колонка на мобильных, 2 на планшетах, 3 на десктопе
"2": 2 колонки на всех разрешениях
Кастомные: Используйте стандартные пропы Grid

Источники: src/components/README.md80-92 README.md90-103

Адаптивный контейнер

Используйте Container для центрированных макетов с максимальной шириной.

import { Container } from '@ui8kit/core';

<Container size="lg" px="md" centered>
  <Card p="lg">
    Центрированный контент с адаптивной максимальной шириной
  </Card>
</Container>

Размеры контейнера:

xs: 448px
sm: 640px
md: 768px
lg: 1024px
xl: 1280px

Источники: src/components/README.md39-50

Паттерны UI-компонентов

Работа с карточками

Card — это составной компонент с семантическими подкомпонентами.

Card (корневой контейнер)

Card.Header

Card.Title

Card.Description

Card.Content

Card.Footer

data-class='card'

data-class='card-header'

data-class='card-title'

data-class='card-content'

data-class='card-footer'

Пошагово: Построение карточки

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

<Card p="lg" rounded="xl" shadow="md" bg="card">
  <Card.Header>
    <Card.Title>Заголовок</Card.Title>
    <Card.Description>Необязательное описание</Card.Description>
  </Card.Header>
  
  <Card.Content>
    <Stack gap="md">
      <Text>Основной контент размещается здесь</Text>
      <Text c="muted-foreground">Дополнительные детали</Text>
    </Stack>
  </Card.Content>
  
  <Card.Footer>
    <Button variant="primary">Действие</Button>
  </Card.Footer>
</Card>

Источники: src/components/README.md96-117 README.md121-145

Работа с кнопками

Button поддерживает варианты, размеры, состояния загрузки и секции с иконками.

import { Button } from '@ui8kit/core';
import { Heart } from 'lucide-react';

// Базовая кнопка
<Button variant="primary" size="md">
  Нажми меня
</Button>

// Кнопка с иконкой
<Button 
  variant="default" 
  leftSection={<Heart size={16} />}
  rounded="md"
  shadow="sm"
>
  Избранное
</Button>

// Состояние загрузки
<Button variant="primary" loading={isLoading}>
  Отправить
</Button>

Варианты кнопки:

default: Стандартная кнопка
primary: Основное действие
secondary: Второстепенное действие
destructive: Опасные действия
outline: Стиль с обводкой
ghost: Минималистичный стиль
link: Стиль ссылки

Источники: src/components/README.md119-133

Работа с типографикой

Используйте Title для заголовков и Text для основного контента.

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

<Stack gap="md">
  <Title order={1} size="3xl" weight="bold" c="primary">
    Главный заголовок
  </Title>
  
  <Title order={2} size="2xl" weight="semibold">
    Подзаголовок
  </Title>
  
  <Text size="lg" c="muted-foreground" align="left">
    Основной текст с семантической стилизацией
  </Text>
  
  <Text size="sm" weight="medium" truncate>
    Усеченный текст для сценариев переполнения
  </Text>
</Stack>

Сопоставление Title order:

order={1}: тег <h1>
order={2}: тег <h2>
order={3}: тег <h3>
(продолжается до order={6})

Источники: src/components/README.md150-177

Работа с бейджами

Используйте Badge для индикаторов статуса и меток.

import { Badge, Group } from '@ui8kit/core';
import { CheckCircle } from 'lucide-react';

<Group gap="sm">
  <Badge variant="success" size="sm" rounded="full">
    Активен
  </Badge>
  
  <Badge 
    variant="default" 
    dot
    rightSection={<CheckCircle size={14} />}
  >
    Проверен
  </Badge>
</Group>

Варианты бейджа:

default: Стандартный бейдж
success: Зеленый/позитивный
warning: Желтый/предупреждение
error: Красный/негативный
outline: Стиль с обводкой

Источники: src/components/README.md135-148

Рабочий процесс семантического HTML

Используйте Block с пропом component для рендера семантических HTML5-элементов.

import { Block, Title, Text } from '@ui8kit/core';

<Block component="section" py="xl" bg="background">
  <Block component="article" p="lg" rounded="lg">
    <Title order={2}>Заголовок статьи</Title>
    <Text>Контент статьи</Text>
  </Block>
</Block>

<Block component="nav" p="md" bg="card">
  <Block component="ul">
    <Block component="li">Элемент навигации</Block>
  </Block>
</Block>

<Block component="header" py="md" border="bottom">
  <Title>Заголовок страницы</Title>
</Block>

<Block component="footer" py="lg" bg="muted">
  <Text size="sm">Контент подвала</Text>
</Block>

Распространенные семантические элементы:

section: Тематическая группировка
article: Самодостаточный контент
nav: Навигационные ссылки
header: Вводный контент
footer: Контент подвала
aside: Контент боковой панели
main: Основная область контента

Источники: src/components/README.md23-37 README.md14

Распространенные сценарии разработки

Сценарий 1: Построение карточки функции

import { Card, Title, Text, Button, Stack, Badge } from '@ui8kit/core';
import { CheckCircle } from 'lucide-react';

export function FeatureCard() {
  return (
    <Card variant="outlined" p="xl" rounded="xl" shadow="lg">
      <Card.Header>
        <Stack gap="sm">
          <Badge variant="success" size="sm">
            Новое
          </Badge>
          <Title order={3} size="xl" weight="bold">
            Премиум-функция
          </Title>
        </Stack>
      </Card.Header>
      
      <Card.Content>
        <Stack gap="md">
          <Text size="md" c="muted-foreground">
            Разблокируйте расширенные возможности с нашим премиум-планом.
          </Text>
          <Stack gap="xs">
            <Text size="sm">
              ✓ Расширенная аналитика
            </Text>
            <Text size="sm">
              ✓ Приоритетная поддержка
            </Text>
            <Text size="sm">
              ✓ Пользовательские интеграции
            </Text>
          </Stack>
        </Stack>
      </Card.Content>
      
      <Card.Footer>
        <Button 
          variant="primary" 
          w="full"
          leftSection={<CheckCircle size={16} />}
        >
          Обновить сейчас
        </Button>
      </Card.Footer>
    </Card>
  );
}

Источники: README.md310-339 src/components/README.md96-117

Сценарий 2: Построение макета формы

Когда специфичные для форм компоненты недоступны, компонуйте макеты, используя Block и Box.

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

export function FormCard() {
  return (
    <Card variant="outlined" p="xl" rounded="xl">
      <Card.Header>
        <Title order={2} size="2xl">
          Регистрация
        </Title>
      </Card.Header>
      
      <Card.Content>
        <Stack gap="md">
          <Box>
            <Text weight="medium" mb="xs">
              Email
            </Text>
            <Box 
              component="input"
              type="email"
              p="sm"
              rounded="md"
              border="default"
              w="full"
            />
          </Box>
          
          <Box>
            <Text weight="medium" mb="xs">
              Пароль
            </Text>
            <Box 
              component="input"
              type="password"
              p="sm"
              rounded="md"
              border="default"
              w="full"
            />
          </Box>
        </Stack>
      </Card.Content>
      
      <Card.Footer>
        <Stack gap="md" direction="row">
          <Button variant="secondary" w="full">
            Отмена
          </Button>
          <Button variant="primary" w="full">
            Зарегистрироваться
          </Button>
        </Stack>
      </Card.Footer>
    </Card>
  );
}

Примечание: Для продвинутых рабочих процессов с пользовательскими компонентами форм см. Продвинутый рабочий процесс. Источники: README.md310-339 src/components/README.md315-328

Сценарий 3: Построение секции дашборда

import { Block, Container, Grid, Card, Title, Text, Badge } from '@ui8kit/core';

export function DashboardSection() {
  return (
    <Block component="section" py="xl" bg="background">
      <Container size="lg">
        <Stack gap="lg">
          <Title order={1} size="3xl">
            Обзор дашборда
          </Title>
          
          <Grid cols="1-2-3" gap="lg">
            <Card p="lg" shadow="md">
              <Stack gap="sm">
                <Badge variant="success">Активно</Badge>
                <Title order={3}>Всего пользователей</Title>
                <Text size="2xl" weight="bold">1,234</Text>
              </Stack>
            </Card>
            
            <Card p="lg" shadow="md">
              <Stack gap="sm">
                <Badge variant="default">В ожидании</Badge>
                <Title order={3}>Новые заказы</Title>
                <Text size="2xl" weight="bold">56</Text>
              </Stack>
            </Card>
            
            <Card p="lg" shadow="md">
              <Stack gap="sm">
                <Badge variant="warning">Предупреждение</Badge>
                <Title order={3}>Проблемы</Title>
                <Text size="2xl" weight="bold">3</Text>
              </Stack>
            </Card>
          </Grid>
        </Stack>
      </Container>
    </Block>
  );
}

Источники: README.md155-168 src/components/README.md80-92

Сценарий 4: Адаптивная навигация

import { Block, Container, Group, Button, Image } from '@ui8kit/core';

export function Navbar() {
  return (
    <Block component="nav" py="md" bg="card" border="bottom">
      <Container size="xl">
        <Group justify="between" align="center">
          <Image 
            src="/logo.svg" 
            alt="Логотип" 
            w="auto" 
            h="8"
          />
          
          <Group gap="md">
            <Button variant="ghost" size="sm">
              Главная
            </Button>
            <Button variant="ghost" size="sm">
              О нас
            </Button>
            <Button variant="ghost" size="sm">
              Контакты
            </Button>
          </Group>
          
          <Group gap="sm">
            <Button variant="outline" size="sm">
              Войти
            </Button>
            <Button variant="primary" size="sm">
              Регистрация
            </Button>
          </Group>
        </Group>
      </Container>
    </Block>
  );
}

Источники: src/components/README.md66-78 src/components/README.md39-50

Таргетирование атрибутов данных

Все UI-компоненты включают атрибуты data-class для семантического таргетирования в CSS и тестах.

<Card data-class="card">
  <Card.Header data-class="card-header">
    <Card.Title data-class="card-title">Заголовок</Card.Title>
  </Card.Header>
  <Card.Content data-class="card-content">
    Контент
  </Card.Content>
</Card>

Пример таргетирования в CSS:

[data-class="card"] {
  /* Пользовательские стили карточки */
}

[data-class="card-header"] {
  /* Пользовательские стили шапки */
}

Пример селектора в тестах:

// В тестах
const card = screen.getByTestId('card');
const header = within(card).getByTestId('card-header');

Источники: src/components/README.md223-236

Итоговая таблица рабочих процессов

Задача	Используемые компоненты	Ключевые пропы	Паттерн
Вертикальный макет	`Stack`	`gap`, `align`	Вертикальная укладка элементов
Горизонтальный макет	`Group`	`gap`, `justify`	Горизонтальное расположение элементов
Сеточный макет	`Grid`, `GridCol`	`cols`, `gap`, `span`	Многоколоночные адаптивные макеты
Контентная карточка	`Card` + подкомпоненты	`p`, `rounded`, `shadow`	Card.Header → Content → Footer
Семантический контейнер	`Block`	`component`, варианты	Section, article, nav и т.д.
Интерактивная кнопка	`Button`	`variant`, `size`, состояния загрузки	Триггеры действий
Типографика	`Title`, `Text`	`order`, `size`, `weight`	Заголовки и основной текст
Индикатор статуса	`Badge`	`variant`, `size`, `dot`	Метки и статусы
Центрированный контент	`Container`	`size`, `centered`	Адаптивные макеты с максимальной шириной
Макет формы	`Block`, `Box`	Варианты отступов и границ	Пользовательские композиции форм

Источники: src/components/README.md1-259 README.md36-217

Getting started

Architecture

Components

Development Guide

Базовый рабочий процесс

Базовый рабочий процесс

Назначение и область применения

Рабочий процесс выбора компонента

Рабочий процесс базовой стилизации

Пошагово: Стилизация компонента

Справочник пропов вариантов

Рабочие процессы паттернов макетов

Вертикальная укладка с `Stack`

Горизонтальный макет с `Group`

Сеточный макет с `Grid`

Адаптивный контейнер

Паттерны UI-компонентов

Работа с карточками

Работа с кнопками

Работа с типографикой

Работа с бейджами

Рабочий процесс семантического HTML

Распространенные сценарии разработки

Сценарий 1: Построение карточки функции

Сценарий 2: Построение макета формы

Сценарий 3: Построение секции дашборда

Сценарий 4: Адаптивная навигация

Таргетирование атрибутов данных

Итоговая таблица рабочих процессов

​Базовый рабочий процесс

​Назначение и область применения

​Рабочий процесс выбора компонента

​Рабочий процесс базовой стилизации

​Пошагово: Стилизация компонента

​Справочник пропов вариантов

​Рабочие процессы паттернов макетов

​Вертикальная укладка с Stack

​Горизонтальный макет с Group

​Сеточный макет с Grid

​Адаптивный контейнер

​Паттерны UI-компонентов

​Работа с карточками

​Работа с кнопками

​Работа с типографикой

​Работа с бейджами

​Рабочий процесс семантического HTML

​Распространенные сценарии разработки

​Сценарий 1: Построение карточки функции

​Сценарий 2: Построение макета формы

​Сценарий 3: Построение секции дашборда

​Сценарий 4: Адаптивная навигация

​Таргетирование атрибутов данных

​Итоговая таблица рабочих процессов

Базовый рабочий процесс

Назначение и область применения

Рабочий процесс выбора компонента

Рабочий процесс базовой стилизации

Пошагово: Стилизация компонента

Справочник пропов вариантов

Рабочие процессы паттернов макетов

Вертикальная укладка с `Stack`

Горизонтальный макет с `Group`

Сеточный макет с `Grid`

Адаптивный контейнер

Паттерны UI-компонентов

Работа с карточками

Работа с кнопками

Работа с типографикой

Работа с бейджами

Рабочий процесс семантического HTML

Распространенные сценарии разработки

Сценарий 1: Построение карточки функции

Сценарий 2: Построение макета формы

Сценарий 3: Построение секции дашборда

Сценарий 4: Адаптивная навигация

Таргетирование атрибутов данных

Итоговая таблица рабочих процессов