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

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

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

Этот документ описывает типичные рабочие процессы и паттерны разработки, используемые при создании пользовательских интерфейсов с помощью @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
Сеточный макетGridCSS Grid с адаптивными пресетами
Flexbox-макетFlex или StackFlex для общих случаев, 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, prnone, xs, sm, md, lg, xl, 2xl
Отступыm, mx, my, mt, mb, ml, mrnone, xs, sm, md, lg, xl, 2xl, auto
Цветаbg, c, borderColorТокены цветов дизайн-системы
Скруглениеroundednone, sm, md, lg, xl, 2xl, 3xl, full
Теньshadownone, sm, md, lg, xl, 2xl
Макетw, h, minH, maxWauto, full, screen, fit, min, max
Позицияpositionstatic, 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

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

ЗадачаИспользуемые компонентыКлючевые пропыПаттерн
Вертикальный макетStackgap, alignВертикальная укладка элементов
Горизонтальный макетGroupgap, justifyГоризонтальное расположение элементов
Сеточный макетGrid, GridColcols, gap, spanМногоколоночные адаптивные макеты
Контентная карточкаCard + подкомпонентыp, rounded, shadowCard.Header → Content → Footer
Семантический контейнерBlockcomponent, вариантыSection, article, nav и т.д.
Интерактивная кнопкаButtonvariant, size, состояния загрузкиТриггеры действий
ТипографикаTitle, Textorder, size, weightЗаголовки и основной текст
Индикатор статусаBadgevariant, size, dotМетки и статусы
Центрированный контентContainersize, centeredАдаптивные макеты с максимальной шириной
Макет формыBlock, BoxВарианты отступов и границПользовательские композиции форм
Источники: src/components/README.md1-259 README.md36-217