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.