` already applies `p-6` inside `@container/main mx-auto max-w-screen-2xl`, so a page that pads itself renders at 48px. Every page currently complies; keep it that way. - `h1` is `flex items-center gap-2 text-3xl font-bold text-foreground` with an `h-8 w-8 text-primary` Lucide icon. **Heading size is genuinely mixed** — 22 `text-3xl` against 18 `text-2xl` (plus 3 `text-xl` on dense detail headers). `text-3xl` is the one to reach for on a new top-level page, but match the neighbouring screens rather than treating either as absolute. - The page's primary action is a `primary` Button top-right; secondary actions sit beside it in a `flex flex-wrap items-center gap-2` group. Buttons already supply `gap-2` from `cva`. - Toolbar: search on `flex-1`, `ViewToggle` after it. Persist the choice with `getStoredViewMode(page)` / `setStoredViewMode(page, mode)` from `src/components/shared/view-mode.ts` — all 6 pages with a `ViewToggle` do. Where a result count is shown, it is a `text-xs font-semibold uppercase tracking-wider text-muted-foreground` line above the grid. - Inline guidance banners: `rounded-xl border border-primary/20 bg-primary/5 p-4`. ## The three content states, in this order Loading → error → empty → content, as guarded blocks (the `agents.tsx` form): ```tsx // A failed *background* refetch keeps the last good data (see the gating rule // below), so only a failed initial load has nothing left to show. const loadFailed = isError && !data; {isLoading && (

{Array.from({ length: 4 }).map((_, i) => (

))}

)} {loadFailed && ( refetch()} retryLabel={t("common.retry", "Retry")} /> )} {!isLoading && !loadFailed && items.length === 0 && ( setCreateOpen(true) : undefined} /> )} ``` Use the `Skeleton` primitive inside a card-shaped wrapper, not a bare `animate-pulse` div. `ErrorState` is in 19 pages, `EmptyState` in 9. Empty state distinguishes "no results for this search" from "nothing exists yet", and only the latter offers the create action. **Every page that loads data has an error branch — keep it that way.** Falling through to the empty state on a failed fetch is the recurring bug here: it tells the user "nothing exists yet" or "data will appear automatically" when the truth is "we could not reach the backend". Pick the shape by surface: - `ErrorState` — replaces the container. For a page or panel with nothing else to show. Carries `data-testid="error-state"` and `data-testid="error-state-retry"`; assert on those rather than on the translated copy, which changes with the locale. **Gate it on the data being absent** (`isError && !data`), not on `isError` alone: TanStack Query keeps the last good result when a background refetch fails (and `refetchOnWindowFocus` is on by default), so an ungated branch replaces a usable page with an error over a focus blip. `isError` alone is only correct when there can be no cached data. - `RefetchErrorNotice` — a compact amber strip that keeps the last good data on screen. For a *background* refetch failure on a polling page, or an inline control (a picker inside a form) where a full error box would be out of scale. Pass an explicit `message` when the initial load failed — its default wording says data is merely stale. - A neutral "unknown" state — when the value drives a decision. `gdpr.tsx` renders a grey "status unavailable" chip rather than its green "Processing Active" badge, and disables the toggle, because reporting an unknown restriction state as a known-safe one is worse than showing nothing. ## Card grid vs table Card grid: `grid gap-4 sm:grid-cols-2 lg:grid-cols-3`. When the page can sit next to the open chat drawer, prefer the container-query classes from `src/index.css` — `cq-card-grid` (1→2→3→4) or `cq-stat-grid` (1→2→4) — which respond to the content area, not the viewport. Table: wrap in `rounded-xl border border-border/50 overflow-hidden`, header row `border-b bg-muted/50` with `text-start px-4 py-3 font-medium` cells, body rows `border-b border-border/30 hover:bg-muted/30 cursor-pointer transition-colors`, whole row navigates, IDs in `font-mono text-xs text-muted-foreground`, numeric/version columns `text-end`. Give each row `data-testid={\`thing-row-\${id}\`}`. ## Detail pages `BackLink` at the top, then the same header block (title + subtitle + actions), then content in `Card`s. Deletes go through `AlertDialog` with `isPending` bound to the mutation. Resource routes carry the version: `/manage/channels/:id?version=N`. ## Config editors Never build editor chrome. `ConfigEditorLayout` (`src/components/editors/config-editor-layout.tsx`) owns the Form↔JSON tabs, version picker, compare, dirty indicator, Save / Discard / Save & Test, and the unsaved-changes guard. A new editor supplies only the form body: ```tsx ( )} /> ``` Then register it in `EDITOR_MAP` (`src/components/editors/editor-registry.tsx`), add an MSW handler, add i18n keys, add a test — the four steps in AGENTS.md §3. ## Wizards `agent-wizard.tsx` and `group-wizard.tsx` are the reference. Entry is `CreateOrWizardDialog` (quick create vs. guided). Keep step state local; only commit on finish. ## Accessibility baked into the patterns Tab bars and toggles are `role="tablist"`/`radiogroup` with arrow-key handling and roving `tabIndex` — copy the handler from `ConfigEditorLayout` or `ViewToggle` rather than writing plain buttons. Icons that repeat a visible label get `aria-hidden="true"`; icon-only controls get `aria-label` via `t()`. The global focus ring is already defined in `src/index.css` — don't remove outlines.

{t("pages.agents.title", "Agents")}