UI system

shared/ui — единая дизайн-система фронтенда Accessible University. Здесь живут универсальные, типизированные и не зависящие от предметной области компоненты: controls, feedback, typography, overlays и layout-примитивы.

Цель системы — собирать страницы композицией компонентов, а не создавать для каждой страницы новую разметку и большой SCSS-файл.

Быстрый старт

Запустить каталог компонентов:

cd frontend
npm run storybook

Публичные компоненты и их типы экспортируются из src/shared/ui/index.ts:

import { Button, Card, Grid, Stack, Text } from "@shared/ui";

export function Example() {
  return (
    <Stack gap="6">
      <Text as="h1" size="h1" weight="bold">
        Сервисы
      </Text>
      <Grid columns={1} columnsMd={2} columnsLg={3} gap="4">
        <Card>...</Card>
      </Grid>
      <Button>Продолжить</Button>
    </Stack>
  );
}

Что находится в shared/ui

| Группа | Компоненты | | -------- | -------------------------------------------------------------------------------------------------- | | Layout | Container, Section, Stack, Inline, Grid | | Actions | Button, IconButton, Pressable, BackButton, CloseButton, Pagination | | Forms | Input, Textarea, Select, Checkbox, Switch, FormField, OtpInput, DatePickerModal | | Content | Card, Badge, Alert, Heading, Text, Tabs | | Feedback | Skeleton, Spinner, InlineSpinner, Loader, EmptyState, ErrorState, NotificationStatus | | Overlay | Modal, ResponsiveModal, ModalHeader, TicketCodeModal |

Правила композиции

1. Сначала ищем готовый компонент в shared/ui и его пример в Storybook.
2. Верх страницы строим через Container; смысловой блок с заголовком — через Section.
3. Для расположения элементов используем Stack (вертикаль), Inline (горизонталь) и Grid (адаптивные колонки).
4. Отступы задаём только токенами: gap="1" | "2" | "3" | "4" | "5" | "6" | "8" | "12".
5. Бизнес-логику, API-вызовы и сущностные типы не помещаем в shared/ui.

Не превращаем layout-компоненты в универсальный CSS-конструктор: не добавляем props для произвольных цветов, размеров, position, margin, padding или style. Если визуальный паттерн стал повторяться — обсуждаем отдельный компонент или новый токен.

Токены и темы

Все новые стили используют CSS-переменные из src/app/styles/tokens.scss:

• цветовые роли: --ui-color-bg, --ui-color-surface, --ui-color-text, --ui-color-border, --ui-color-brand;
• spacing: --ui-space-*;
• типографика: --ui-font-size-*, --ui-font-weight-*, --ui-line-height-*;
• радиусы, тени, размеры контролов и motion-токены.

Поддерживаются light/dark-тема, палитры, контрастный режим и масштаб текста через data-атрибуты на document.documentElement. Компонент должен работать в этих режимах без дополнительных theme-override селекторов.

Не используем новые raw hex-значения, градиенты и произвольные значения отступов в shared-компонентах.

Доступность и состояния

Каждый интерактивный компонент должен иметь:

• нативный элемент (button, input, select, a) или корректную семантику;
• доступный label / aria-label, если видимого текста нет;
• :focus-visible через общий focus-токен;
• состояния disabled, loading, error или empty там, где они применимы;
• touch-friendly размер и корректную клавиатурную навигацию.

Loading не должен сдвигать layout. Кнопка в загрузке отключена и получает aria-busy; скелетон повторяет геометрию загружаемого контента.

Ошибки и поддержка

Ошибка должна объяснять, что произошло, и по возможности предлагать безопасное повторное действие. Если проблема не устраняется, добавляйте понятный путь к поддержке:

Не удалось решить проблему? Напишите в поддержку расписания.

Ссылку показываем в ErrorState, на критичных экранах и там, где пользователь не может продолжить работу самостоятельно. Не используем её как замену локальному сообщению об ошибке или кнопке «Повторить».

Как добавить компонент

1. Убедиться, что подходящего компонента или варианта ещё нет.
2. Создать отдельную папку: Component/Component.tsx, Component.scss, Component.stories.tsx, index.ts.
3. Использовать токены и существующие shared-примитивы.
4. Экспортировать компонент и типы из локального index.ts и shared/ui/index.ts.
5. В Storybook показать нормальное, крайнее и интерактивное состояния; описать все публичные props через argTypes.
6. Проверить npm run typecheck, npm run lint:css, npm run lint.

Подробные визуальные правила и решения по доступности: Design Component Guidelines.