Назначение

<ComponentName> — <atom/molecule/organism> компонент в <frontend app>. Используется для <краткая цель>.

Metadata

Поле	Значение
App	<pin-admin/...>
FSD Layer	shared/ui/atoms / shared/ui/molecules / shared/ui/organisms / entities/<entity>/ui
Атомарный уровень	atom / molecule / organism
Файл	src/shared/ui/<level>/<ComponentName>.tsx или <ComponentName>/index.tsx
Статус	draft / approved / deprecated
HeroUI базис	<HeroUI-компонент или комбинация>

Где Используется

Использующий компонент	Слой	Назначение
<PageName>	pages/	<контекст>
<WidgetName>	widgets/	<контекст>
<FeatureName>	features/	<контекст>

Props

Prop	Тип	Required	Default	Описание	Валидация
<prop>	<type>	да/нет	<default>	<смысл>	<ограничения>

Прочие interfaces

• forwardRef: да / нет.
• children: разрешён / запрещён / типизирован.
• className: разрешён override (через cn() utility) / запрещён.
• data-*: список используемых dataset-атрибутов.

Slots И Children

Slot	Назначение	Контракт
<slot>	<описание>	<React.ReactNode / specific component>

States

State	Триггер	Визуально	A11Y
default	—	<описание>	—
hover	mouse over	<токен>	—
focus-visible	keyboard focus	<ring>	outline обязателен
active / pressed	click/tap	<токен>	—
disabled	prop isDisabled	<токен>	aria-disabled="true"
loading	prop isLoading	spinner	aria-busy="true"
readonly	prop isReadonly	<токен>	aria-readonly="true"
invalid / error	prop isInvalid	<токен>	aria-invalid="true"
success	prop isSuccess	<токен>	—

Variants

Variant	Назначение	Визуально
primary	Основное действие	<токен>
secondary	Вторичное действие	<токен>
danger	Деструктивное действие	<токен>
ghost	Без фона	<токен>
<custom>	<описание>	<токен>

Sizes

Size	Назначение	Высота	Padding
sm	Компактный UI	<value>	<value>
md	Стандартный	<value>	<value>
lg	Крупный	<value>	<value>

Дизайн И Композиция

• HeroUI composition: <какие компоненты HeroUI собираются>.
• Tailwind utility-классы: только токенные; кастомные классы запрещены.
• Иконка: <from lucide-react> или <from iconify>; обязательно aria-hidden="true", если decorative.
• Spacing: <token>.
• Border radius: <token>.
• Shadow: <token> или none.
• Анимация: <duration> <easing>; уважает prefers-reduced-motion.

Responsive

Breakpoint	Поведение
< md	<описание>
md – lg	<описание>
≥ lg	<описание>

Container queries (@container): использовать / не использовать.

Accessibility

Требование	Реализация
Keyboard	<какие клавиши обрабатываются>
ARIA role	<role>
ARIA attributes	<aria-label / aria-labelledby / aria-describedby / aria-controls>
Focus management	<правило для focus trap, фокус при открытии/закрытии>
Screen reader text	<через sr-only или aria-label>
Color contrast	<минимум 4.5:1 для текста>

Внутреннее Состояние

• Локальный state: <какие useState, useReducer>.
• Контролируемый / неконтролируемый режим: <правило>.
• Side effects (useEffect): <когда возникают>.
• Запрос данных: компонент не делает данных-запросов (атомы/молекулы) / делает через TanStack Query (organism).

Тестовые Сценарии

#	Сценарий	Что проверяется
1	render default	Корректное отображение без props
2	render all variants	Каждый variant визуально согласован
3	render all states	hover/focus/disabled/loading/error
4	keyboard interaction	Tab/Enter/Space/Escape
5	accessibility	axe-core без violation
6	responsive	Layout не ломается на 320/768/1280/1920
7	controlled vs uncontrolled	Оба режима работают
8	event handlers	onClick/onChange/onBlur вызываются

Обратные ссылки

Автоссылки: где используется этот документ.

• index.md (1): Шаблоны Документации

Связанные Документы

• HeroUI: <ссылка на конкретный HeroUI компонент>.
• Storybook: <ссылка на story>.
• Дизайн-токены: docs/04-frontends/<app>/01-design-system/.
• Atomic design правила: docs/01-engineering-rules/frontend-fsd-and-atomic-rules.md.
• Accessibility правила: docs/01-engineering-rules/ui-accessibility-rules.md.
• Responsive правила: docs/01-engineering-rules/ui-responsive-design-rules.md.