# UI patterns

Use the shared components in `src/lib/ui/components` to keep pages consistent.
Primitives live in its `primitives` directory.

## Page structure and controls

- Use `SectionHeader` for page titles and primary actions. The page owns spacing
  between sections.
- Use `Field` with `Input`, `Select` or `Textarea` for labels, help and errors.
  Give controls distinct `ariaLabel` values when several share one field.
- Pair `Tabs` with a labeled panel. Use `ListFooter` for long lists.
- Use `StatusBadge` for workflow states and `ServerIdentity` for server names.
  Keep raw IDs available for copying and troubleshooting.

## Dialogs and feedback

Use `Dialog` for modal workflows and `confirmAction` from `src/lib/ui/confirm.ts`
for ordinary confirmations. Browser unload protection remains native.

Keep loaded data visible when a refresh fails, show the error and provide a
retry action. Distinguish loading, empty and failed states so operators know
whether to wait or act.

## Live data

Use `pollVisible` from `src/lib/ui/poll.ts` for scheduled page refreshes. It avoids
overlapping requests, pauses while the page is hidden and returns a cleanup
function for use when the component unmounts.

Read live server data through `src/lib/ui/stores/fleet.ts` instead of adding
another `/api/servers` polling loop. Server detail views use a scoped Fleet store
so their snapshots do not replace the shared fleet.

## Accessibility and small screens

Preserve visible keyboard focus, associated field labels and separate navigation
and action targets. Avoid nested buttons or placing a button inside a link.
Allow long server identities to wrap and tab/filter rows to scroll on narrow
screens.

## Navigation

Use the shared navigation metadata for Fleet, Releases, Activity, Players, and
Admin. Campaigns stays under Releases beside Scripts, Configs, Plugins, Game
files, and Betas. The Servers page is the Fleet landing page. Desktop navigation
uses a collapsible sidebar; mobile navigation uses a modal drawer.

Use Cmd/Ctrl K to search pages, servers, hosts, players, and recorded matches.
Common actions open their existing forms and retain role checks and confirmations.
Keyboard shortcut help is available from the account menu and with `?`.

Detail pages use `Breadcrumbs`. Its parent link restores the validated `returnTo`
URL, including filters, sorting, pagination, and anchors. Supply `fallback` when
the default parent also needs filters. Do not add a duplicate Back link.