logistics-dashboard-shadcn/AGENTS.md

AGENTS.md

FreightOps Control — dense internal logistics dashboard; сохраняй утилитарный интерфейс, sidebar-навигацию, таблицы/статусы/charts и не превращай его в маркетинговый лендинг.

Project Specifics

• Source content lives in src/entities/site-content.ts; keep visible copy there or directly in route JSX.
• src/app is routing only; page composition belongs to per-page widgets (src/widgets/<page>.tsx). См. File Map.
• Keep cards at 8px radius or less and preserve the selected palette in src/app/globals.css.
• This is a static frontend template: do not add real payments, auth, persistence, external API calls, or backend contracts without an explicit product request.
• After changes run pnpm lint and pnpm build.

Визуальные правки

• Кириллица обязательна для видимого текста и выбранных Google Fonts.
• При AI-правках сохраняйте доменные блоки этого шаблона: они отличают проект от generic landing.

Design System

Источник токенов — src/app/globals.css (@theme + :root/.dark). Два шрифта: тело — Inter (--font-sans), заголовки/метрики/числа — IBM Plex Mono (--font-display, через класс .font-display и на h1/h2/h3). Работай через семантические классы Tailwind (bg-card, text-foreground, text-primary, text-muted-foreground, border-border), не хардкодь hex/oklch. Статусные оттенки (emerald/amber/rose) централизованы в src/shared/lib/ops-tone.ts — переиспользуй их, а не пиши классы заново.

Личность: utilitarian control room — холодный сине-серый фон (почти белый, лёгкая синяя примесь), глубокий teal primary как рабочий акцент и янтарный accent для предупреждений. Тёмный foreground используется как сплошная заливка контрастных панелей (risk queue). Это плотный operator-интерфейс: данные, не маркетинг.

Роль	Light	Характер
background	холодный почти-белый (oklch 0.972 0.004 255)	фон рабочей области
foreground	тёмный сине-чёрный (oklch 0.16 0.012 255)	текст + инверс-панели (bg-foreground text-background)
primary	глубокий teal (oklch 0.39 0.105 186)	кнопки, иконки, числа, ring, bar-chart
secondary	светлый сине-серый	вторичные badge
muted / muted-foreground	сине-серый	подложки иконок, table head, вторичный текст
accent	янтарь (oklch 0.74 0.14 72)	предупреждения (вне семантики — чаще точечно)
card	чистый белый	все панели (Panel)
border	мягкий сине-серый	тонкие границы border border-border

Узнаваемые приёмы (держи их, это и есть «лицо» проекта):

• Mono-числа: метрики, SLA, проценты и заголовки — font-display (IBM Plex Mono), font-semibold, tracking-normal/tracking-[0.12em–0.18em] для caps-лейблов.
• Panel-система: компонент Panel (@/shared/ui/panel) — rounded-md border border-border bg-card + почти невидимая тень shadow-[0_1px_0_rgba(15,23,42,0.04)]. Всё строится из панелей.
• Умеренный radius: --radius = 0.375rem; везде rounded-md — мягко, но не «pill».
• Dashboard shell: DashboardShell даёт sticky sidebar (236px) + header-bar с live-бейджами; все рабочие страницы оборачиваются им.
• Статус-токены: statusTone/routeTone/severityTone — emerald = healthy/green, amber = watch/P2, rose = risk/red/P1; цветные точки и outline-бейджи.
• Тонкие данные: Progress h-2 для capacity/score, CSS bar-chart на style={{ height }}, плотные таблицы (min-w-[860px], uppercase thead).
• Inverse hero-блок: bg-foreground text-background для risk queue — единственная тёмная панель на светлом дашборде.

Do / Don't:

• Do: держи Panel-сетку, mono-заголовки/числа, sidebar shell, статус-токены из ops-tone.ts, плотные таблицы и прогресс-бары; данные — first-class.
• Don't: маркетинговый hero с крупным sans-заголовком и градиентом, скруглённые «pill»-карточки, тяжёлые тени, декоративные фото — это ломает control-room личность. (.grainient-field существует в CSS, но это не часть дашборда — не тащи её в рабочие страницы.)

File Map

Route	Widget
/	src/widgets/ops-dashboard.tsx (OpsDashboard)
/dashboard	src/widgets/ops-dashboard.tsx (OpsDashboard)
/shipments	src/widgets/shipment-control.tsx (ShipmentControl)
/routes	src/widgets/routes-workspace.tsx (RoutesWorkspace)
/returns	src/widgets/returns-workspace.tsx (ReturnsWorkspace)
/analytics	src/widgets/analytics-workspace.tsx (AnalyticsWorkspace)
/settings	src/widgets/settings-workspace.tsx (SettingsWorkspace)

Переиспользуемые блоки:

• src/widgets/site-shell.tsx — SiteHeader, SiteFooter (рендерятся в app/layout.tsx), DashboardShell (sidebar + header-bar обёртка всех рабочих страниц).
• src/widgets/metric-strip.tsx — MetricStrip (Dashboard + Analytics).
• src/widgets/control-room-board.tsx — ControlRoomBoard (Dashboard + Routes).
• src/widgets/exception-board.tsx — ExceptionBoard (Dashboard + Shipments + Returns).
• src/widgets/shipment-table.tsx — ShipmentTable (Dashboard + Shipments).
• src/widgets/icon-cards.tsx — IconCards (Returns + Settings).
• src/shared/ui/panel.tsx / container.tsx — Panel, Container (layout-примитивы шаблона).
• src/shared/lib/ops-tone.ts — statusTone, routeTone, severityTone.

Одноразовые блоки колоцированы со своей страницей: ShiftBriefing в ops-dashboard.tsx; CatalogToolbar + FeaturedGrid в shipment-control.tsx; PricingTiles + RouteTimeline в routes-workspace.tsx; ReturnsBoard в returns-workspace.tsx; OpsAnalytics + TestimonialBand в analytics-workspace.tsx; SettingsPanel в settings-workspace.tsx.