design-conventionslisted

# Design conventions (portal) Grounding: `docs/decisions/0003-agentic-first-frontend-stack.md` — the stack and the verification harness are decided there; this skill is the working style. ## Components & theme - **shadcn/ui on Base UI primitives only** (`src/main/frontend/src/components/ui/`) — never add a second component library or primitive layer. Missing component? Add it with `pnpm dlx shadcn@latest add <name>`. - Theme tokens live in `src/main/frontend/src/index.css` (light + `.dark` blocks). Accent is violet/purple (`--primary`). Never hardcode colors where a token exists. - Icons: lucide-react only. - Dark mode via next-themes (`class` attribute); every surface must work in both themes — use token classes (`bg-background`, `text-muted-foreground`…). ## Layout language - Left sidebar with grouped nav: tiny uppercase group labels (`text-[11px] uppercase tracking-wider text-muted-foreground`), active item filled with `bg-sidebar-primary`. - Top bar: uppercase purple breadcrumb left, mode toggle right. - Content: `max-w-6xl`, page `h1` + one-line muted description, then cards. - Overview-style pages: row cards with icon + title + status badge, stat chips (`rounded-md border bg-muted px-2 py-0.5 text-xs`), action button right. - States: every page renders loading, empty, and error (`role="alert"`) states. ## Forms (hard rules) Canonical implementation: `src/main/frontend/src/pages/tokens.tsx`. Copy its shape rather than inventing a new one. - **Disabl