electric-cherry/docs/development/ui-patterns.md

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.

Activity history

Use ActivityLog for the fleet timeline and scoped history. The server History tab fixes the server filter; Maintenance fixes the maintenance/recovery source. The API counts and pages retained records together, with stable ordering. Parent operations represent their host receipts and maintenance verification so a single user action does not appear multiple times. Routine successful host checks stay in the technical Host operation history. Keep detail links contextual so their parent breadcrumb restores filters and pagination.

Type and numbers

Use the shared --text-* scale, with 12 px as the minimum. Mobile inputs use --text-input (16 px) to avoid browser zoom. npm run check:styles, also included in npm run check, rejects raw pixel font sizes. Use Inter with tabular figures for counts, scores, durations and charts; reserve mono for code, IDs, paths and logs. Static values use text or state colors; the accent marks links and controls.

Product language

Concept	Visible label
A managed game instance	Server; use the friendly map and lobby name
Creating a server	Create server
Removing a server	Remove server
Favourite server	Pin
Game does not answer	Not responding
Games	Black Ops I / Black Ops II; BO1 / BO2 in compact labels
Releasing file changes	Campaigns
Player completion evidence	Present in final report / Not present in final report

Keep internal values such as t5, t6, destroy, instance IDs, and filenames in API fields and technical details. User-facing actions use the labels above. Player presence in the final report does not establish a win or continuous survival. A missing timestamp is Not recorded, not Never.

Use RelativeTime for observed history: seconds, minutes or hours for the last 24 hours, Yesterday for the preceding calendar day, then the shared absolute format. It includes the full timestamp in a tooltip and follows the account's timezone. Scheduled future actions use timeFormat.dateTime directly. Database timestamps without an offset are UTC; never parse them as browser-local time. Receipt freshness uses the browser clock and shows Paused or a retry reason when updates are unavailable. These clocks are not live regions.

Provisioning detail pages show the requester, absolute start time and duration in the summary. Keep the finish time, raw IDs and copy controls in collapsed Technical details. Show freshness only while the operation is active. Poll active operations and finished operations whose recovery capacity is still held. Use OperationTime for steps, checks and activity: offsets from the operation start (+m:ss or +h:mm:ss), with negative offsets for earlier evidence. Missing timestamps stay Not recorded.

Use plural or countLabel from src/lib/ui/plural.ts for count-dependent language, including verbs: plural(count, 'needs', 'need'). The helper uses Intl.PluralRules; supply irregular plural forms explicitly. Keep separators inside string expressions when a Svelte conditional would trim their leading space, for example {offline ? ' · Offline' : ''}.

Recommend an agent upgrade only when its reported version is known to lack a needed capability. Missing calibration samples can simply mean the host is still collecting measurements.