EvoBGP/.agents/skills/shadcn-react/SKILL.md

---
name: shadcn-react
description: Управление shadcn/ui (React) + ReUI компонентами в EvoBGP — registry, CLI, импорты, матрица выбора. Использовать при любых UI-задачах в apps/web/ или packages/ui/ (новые экраны, компоненты, формы, data-grid, filters и др.).
---

# shadcn/ui (React) + ReUI в EvoBGP

EvoBGP использует **React 19 + shadcn/ui (base-nova) + ReUI** (`style: base-nova`, не Radix). Источники правды: MCP `plugin-shadcn-shadcn` + [ui.shadcn.com/docs](https://ui.shadcn.com/docs/components) + [reui.io/docs](https://reui.io/docs/components/base/).

См. `.cursor/rules/web-shadcn.mdc` (основные правила) и `.cursor/rules/context7-stack.mdc` (Context7 ID стека).

## Порядок UI-задачи (строго)

0. **Codegraph** `codegraph_explore` — найти существующие реализации и shared-обёртки.
1. **MCP `plugin-shadcn-shadcn`** — `get_project_registries` (должны быть `@shadcn` и `@reui`).
2. **`search_items_in_registries`** — компонент/block/example:
   - shadcn primitives/blocks → omit `registries` или `["@shadcn"]`
   - Data Grid, Filters, Stepper, Kanban, Autocomplete и др. → `registries: ["@reui"]`
3. **`get_item_examples_from_registries`** — полный код примера перед JSX.
4. **`get_add_command_for_items`** — точная CLI-команда `pnpm dlx shadcn@latest add ...`.
5. Выполнить add **из `apps/web`** (не из корня монорепо, не из `packages/ui`).
6. **CLI docs (обязательно):**
   - `@shadcn/*` → `cd apps/web && pnpm dlx shadcn@latest docs <component>` — [ui.shadcn.com/docs/components](https://ui.shadcn.com/docs/components)
   - `@reui/*` → [ReUI docs](https://reui.io/docs/components/base/<name>) + [llms.txt](https://reui.io/llms.txt)
7. Сверить examples из MCP с API из docs CLI — реализовать только после совпадения.
8. Адаптировать под TanStack Router / Query → `apps/web/src/`.
9. **`get_audit_checklist`** — перед merge PR.

## Размещение и импорты

| Слой | Путь | Импорт |
|------|------|--------|
| shadcn primitives | `packages/ui/src/components/` | `@evobgp/ui/components/*` |
| ReUI enterprise | `apps/web/src/components/reui/` | `@/components/reui/*` |
| Проектные обёртки | `apps/web/src/components/` | `@/components/<name>` |

```bash
cd apps/web
pnpm dlx shadcn@latest add button          # @shadcn primitive → packages/ui/src/components/
pnpm dlx shadcn@latest add @reui/data-grid # ReUI enterprise → apps/web/src/components/reui/
```

## Матрица выбора shadcn vs ReUI

| Задача | Registry | Импорт |
|--------|----------|--------|
| Button, Card, Sheet, Field, Sidebar | `@shadcn` | `@evobgp/ui/components/*` |
| Blocks (sidebar-07, dashboard-01) | `@shadcn` | blocks → `apps/web/src/components/` |
| Data Grid (sort, pagination, virtual) | `@reui` | `@/components/reui/data-grid/*` → `reui-kit/ResourcePage` |
| Мультифильтры | `@reui` | `@/components/reui/filters` |
| Number field со stepper | `@reui` | `@/components/reui/number-field` |
| Autocomplete | `@reui` | `@/components/reui/autocomplete` → `AutoCompleteInput` |
| Date selector / range | `@reui` | `@/components/reui/date-selector` |
| Semantic badge (success/info/warning) | `@reui` | `@/components/reui/badge` или `StatusBadge` |

**Простые списки** — shadcn `Table`. **Сложные data-списки** — ReUI data-grid через `ResourcePage`, не shadcn Data Table.

## Уже установленные shared-обёртки

В `apps/web/src/components/`:
- `PageHeader`, `PageShell` — заголовки и обёртки страниц
- `QueryState` — обёртка loading/error/empty для TanStack Query
- `EmptyState` — пустые списки (empty-state-14 DNA)
- `ConfirmDialog` — подтверждения (не `window.confirm`)
- `LoadingButton` — SoT кнопка с loading (`Button` + `Spinner`)
- `StatusBadge` / `CategoryBadge` / `ModeBadge` — semantic ReUI Badge
- `SegmentedTabs` — секции страницы (c-tabs-9)
- `StatusToggleGroup` — статус грида (c-toggle-group-5)
- `FormDrawer` — Sheet overlay (sheet-8 / form-7)
- `Skeletons` (`TableSkeleton`, `KpiStatGridSkeleton`) — скелетоны
- `TruncatedText` — текст с тултипом

Kit: `reui-kit/ResourcePage`, `KpiStatGrid`, `QuickActionGrid`, `OpsDashboard`, `SettingsShell`, `DetailPanel`, `FrameSection`.

Перед созданием новой обёртки — проверить существующие через Codegraph.

## Уже установленные ReUI-компоненты

В `apps/web/src/components/reui/`:
- `autocomplete`, `badge`, `data-grid/*`, `date-selector`, `filters`, `number-field`

Перед добавлением дубликата — проверить Codegraph и существующие обёртки.

## Зависимости (только `apps/web`, не `packages/ui`)

| npm-пакет | ReUI-компоненты |
|-----------|-----------------|
| `@tanstack/react-table` | data-grid |
| `@tanstack/react-virtual` | data-grid (virtual) |
| `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/modifiers`, `@dnd-kit/utilities` | data-grid dnd, sortable, kanban |
| `date-fns`, `react-day-picker` | date-selector |

После `shadcn add @reui/...` — проверить, что CLI добавил недостающие deps в `apps/web/package.json`.

## Semantic tokens (Styling)

ReUI расширяет тему shadcn токенами `--success`, `--info`, `--warning`, `--destructive-foreground`, `--invert` — уже в `packages/ui/src/styles/globals.css`.

- Badge/Alert: `variant="success"` / `"info"` / `"warning"` — не `bg-emerald-*`
- Базовая тема: `pnpm dlx shadcn@latest apply b2fA --only theme`
- ReUI-токены: по [Styling guide](https://reui.io/docs/styling); не править `globals.css` вручную без сверки с docs

## Запрещено

- Писать UI по памяти, не проверив MCP
- Копипаст с ui.shadcn.com без examples/add из MCP
- Самописные примитивы, если есть item в registry
- Пропускать MCP «потому что компонент простой»
- Класть ReUI в `packages/ui` или импортировать как `@evobgp/ui`
- Radix-варианты (`/docs/components/radix/...`) — только Base UI
- Raw Tailwind-цвета вместо ReUI semantic `variant`
- Использовать Tabler/Bootstrap/Material UI

## Чеклист перед завершением UI-задачи

- [ ] MCP search (с правильным registry) + examples
- [ ] `shadcn add <name>` (или `@reui/<name>`) из `apps/web`
- [ ] Импорты: `@evobgp/ui/components/*` для shadcn, `@/components/reui/*` для ReUI
- [ ] Зависимости в `apps/web/package.json`
- [ ] `pnpm --filter @evobgp/web run typecheck` — exit 0
- [ ] `pnpm --filter @evobgp/web run lint` — exit 0
- [ ] `pnpm --filter @evobgp/web run build` — exit 0