Clean up README and organize documentation

2026-10-06 23:51:41 -04:00
parent 75b6a0a783
commit 8fcabe27fc
38 changed files with 687 additions and 1249 deletions
@@ -0,0 +1,40 @@
+# 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.