# 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.