Web UI design

This is the design for wellfed-server's web UI: the browser front end household members use to feed, schedule, follow history and run the server. It is for contributors. It covers the architecture, the conventions and the quality bar.

The UI is a single-page app embedded in the server binary. It talks only to the server, never to a feeder, and ships in the same binary as the API it calls. So the two can never disagree about a version.

Status. The foundations are built: the token pipeline and contrast test, @wellfed/ui on bits-ui, the bench on the new tokens, and ESLint and Prettier in make check-web. The server app itself is not started. See the roadmap and the build order.

It serves the product architecture and sits on the server HTTP API.

Who it is for#

Every screen works at phone width (mobile-first, full parity). Developers use the bench page, a separate app that never ships to owners.

Decisions#

Workspace#

src/web/
  apps/
    bench/                 the bench page (its own stack, on the shared tokens and components)
    server/                the server UI: SvelteKit, embedded by wellfed-server
    site/                  well-fed.dev, the prerendered landing page (site.md)
    docs/                  docs.well-fed.dev, this docs/ folder as a searchable site (docs-site.md)
  packages/
    tokens/                generated CSS from assets/brand/tokens.json, plus the contrast test
    ui/                    styled components over bits-ui, format helpers, shared by both apps
    api/                   server.gen.ts (from openapi.json) and bench.gen.ts (ts-rs, as today)

Allowed imports (each arrow means "may import"):

apps/server ─► packages/ui ─► packages/tokens
     │              └─► bits-ui
     └─► packages/api ─► openapi-fetch

• Only packages/ui imports bits-ui. Apps use our components, so a widget's behavior and look change in one place.
• Only packages/api and the app's lib/api touch the network. No fetch, EventSource or BroadcastChannel anywhere else.
• The bench keeps its own stack. It is a dev tool with three views and its ts-rs types; it shares the tokens and components, nothing else.
• ESLint's no-restricted-imports enforces these boundaries, as crate boundaries enforce the server's.

Inside the server app#

apps/server/src/
  routes/                  thin: read params, compose features, set titles
    (auth)/login, (auth)/welcome          first-owner setup
    (app)/+layout.svelte                  auth guard, shell, stream, connection banner
    (app)/feeders, feeders/[id], feeders/[id]/plans, feeders/[id]/settings
    (app)/history, (app)/pets, pets/[id], (app)/food
    (app)/settings, settings/users, settings/tokens, settings/releases, settings/data
  lib/
    api/                   client.ts, stream.ts, keys.ts, errors.ts
    features/<area>/       queries.ts (query keys, createQuery, createMutation) and components
    i18n/                  Paraglide's generated messages

• Routes stay thin. They never call the client; each feature exposes its queries and components through its own index.ts, and features don't import each other's internals.
• lib/api/client.ts builds the openapi-fetch client with a base URL resolved against document.baseURI (api/v1/, no leading slash), so the UI works at / and under any proxy subpath.
• lib/api/keys.ts is the one place query keys are built, so the stream and the features invalidate the same keys.

Navigation#

• Phones: a bottom bar with Home, History, Pets and Settings.
• Wide screens: the same four as a left rail, with list-and-detail panes where they help (history, plans, users).
• Settings holds the household, users and tokens, releases and installs, and export and import; owner-only pages are hidden from members, and the server enforces the same rule.
• Hash URLs (#/feeders/<id>/plans) survive reloads and can be shared within the household.

Screens and their data#

The installer (stock to replacement) is not in v1; the Android app and the CLI install first.

Server state and live updates#

• Queries. Every read is a TanStack query keyed from keys.ts. Server data is held as immutable snapshots ($state.raw where components keep their own). Defaults: 30 s stale time, refetch on window focus, three retries for reads.
• Mutations never retry. TanStack's mutation retry stays at 0 everywhere, and a lint rule refuses a retry option on a mutation.
• The stream. lib/api/stream.ts holds the one EventSource and maps each typed event to the cache:
  • small resources (feeder status, settings, a command result) carry their new snapshot, written with setQueryData;
  • list events (a new feeder event, a sample) prepend to the open history or chart, or invalidate it when it isn't loaded;
  • a resync event (the server could not resume from Last-Event-ID) invalidates everything.
• One stream for all tabs. Tabs elect a leader over BroadcastChannel with heartbeats (1 s, takeover after 3 s). The leader holds the EventSource and relays each event with its ID; followers apply the same cache updates. If the leader tab closes, another takes over and resumes from the last ID it saw.
• Connection state is one store with three states, connected, reconnecting and server unreachable, plus each feeder's own connection from the server. The shell shows a banner naming which is down; data stays visible with its age.

Feeding safety in the UI#

The feeding rules of the device API and the server carry through to the browser. An uncertain write is never resent under a new key or on another path:

1. One intent, one key. Pressing Feed opens a confirm step with the portion count. Confirming creates the request's Idempotency-Key (a UUIDv7 from crypto.getRandomValues) and stores it in sessionStorage under that feeder until the result is terminal, so a reload mid-feed keeps it.
2. No automatic retry. A timeout or a lost connection shows "result unknown" with "Check again" and "Retry with the same request". Retrying resends the same key, which the server and the feeder's request ring and journal turn into the first answer, never a second feed.
3. Live result. The command result arrives over the stream. It is one of: sent, running, done (with requested and delivered portions), refused (locked, empty, busy, offline) or uncertain.
   • A refusal from the feeder is final for its key, so feeding again is a new confirm and a new key.
   • An uncertain feed reads as uncertain everywhere, never as success. It is terminal: the feeder may have dispensed, so no retry is offered, as in the app.
   • Only "result unknown" (no answer reached the browser) offers a retry, and only with the same key.
4. No double press. The button is disabled from confirm to a terminal result, and the confirm dialog takes focus so a second tap lands on it.

Concurrent edits. Plans and settings save with If-Match. A 412 opens a conflict view showing what changed on the server since the edit began, and the owner chooses to reload or reapply their change on top. Nothing overwrites silently.

Errors#

• One error type. lib/api/errors.ts turns every non-2xx response into an ApiError carrying the problem's typed code from openapi.json, and network failures into ConnectionError.
• One message table. messageFor(code) is an exhaustive switch over the code enum, so a new server code fails the type check until it has a message.
• Field errors come from the problem's field map and attach to their inputs; the server is the validator, and client checks are only for quick feedback (required fields, ranges the feeder's capabilities report).
• 401 sends the user to login and back to the page they were on; 403 shows what needs an owner.

Look and feel#

• Brand: Midnight (brand): Night #0B1424, Navy #13213A, Signal #2563EB (signal_on_dark #3B82F6 on dark grounds), Mist #F4F6FA, and Kibble #E0A13A for food states only. Inter: 800 for display, 400 to 600 for UI. Radii 12 (controls), 20 (cards), 14 (icons).
• A light app with one confident blue, with dark surfaces for brand moments (login, welcome, empty states), and a full dark theme in neutral graphite grays (graphite* in tokens.json), with the signal blue kept for accents. Night and navy stay for the brand surfaces.
• Device imagery comes only from assets/renders/: card and card-dark on cards, front-food-* for the food level, panel with hotspots for button and indicator help. Indicators are drawn over the render from the hotspot JSON; only the fault light's red is a recorded color, so other lit indicators show as a highlight, not a guessed color. The "not affiliated" line stays wherever the device appears with our brand.
• Tokens to add to tokens.json: state colors (ok, warning, fault, info) for both themes, a spacing scale, a type scale, focus ring, elevation and motion durations. The generator fails the build when a text and background pair named in the file misses WCAG AA contrast.
• The bench moves to the same tokens, keeping its denser layout and monospace numbers.

Plain HTTP on the LAN#

Most owners will open http://<server>:<port> with no TLS. That is not a secure context, which rules out several browser APIs:

The UI must work in both contexts, and Playwright runs every test over plain HTTP with one project behind a TLS proxy.

Serving#

• Embedding. wellfed-server --features ui embeds apps/server/build/ with rust-embed, as the bench does. Release builds enable it; make check builds without it, so Rust checks never need Node, and a build without the UI serves a page saying so.
• Caching. Hashed files under _app/immutable/ get Cache-Control: public, max-age=31536000, immutable; index.html gets no-cache.
• Headers. A strict CSP (default-src 'self', script-src 'self' plus SvelteKit's generated hashes, style-src 'self', style-src-attr 'unsafe-inline' for widget positioning, connect-src 'self', frame-ancestors 'none'), X-Content-Type-Options: nosniff and Referrer-Policy: no-referrer.
• Subpaths. Behind a proxy at /wellfed/, relative asset and API paths keep working; the server redirects a missing trailing slash so relative URLs resolve. Cookies use Path=/ and Secure only when a trusted proxy reports HTTPS.
• Development. pnpm dev serves the app with hot reload and proxies api/ to a wellfed-server running against the host simulator, so nothing touches a real feeder.

What the UI relies on in the API#

The server HTTP API already provides each of these:

• Types. The web gets its types and client from openapi.json through openapi-typescript, and wellfed-api carries no ts-rs. The bench keeps ts-rs for its own views.
• CSRF. The check is SameSite=Strict, a JSON body, a matching Origin, and Sec-Fetch-Site: same-origin when present.
• Stream events are typed schemas in openapi.json (a StreamEvent enum), with a resync event when Last-Event-ID is too old to resume.
• Resources for the UI's own needs: /setup (first owner), /household (name, units, time format) and /audit. The derived views /pets/{id}/intake and the remaining food in /feeders/{id}/food are not built yet.

Quality standard#

The TypeScript standard is the full rule set for the code (strict types, no any, ! or as outside the API boundary, zero warnings, runes only, the dependency policy) and names what enforces each rule. On top of it, the UI holds to:

• Components: typed props, snippets for content, one concern each. A component that fetches is a feature component; packages/ui components never fetch.
• Accessibility: WCAG 2.2 AA. Semantic HTML first, every control reachable and operable by keyboard, visible focus, 44 px touch targets on phones, prefers-reduced-motion respected, and tests that find elements by role and name.
• Performance budgets, checked after the build: at most 150 KB of gzipped JavaScript for the first route, and charts loaded only on chart routes.

Tests by layer#

Visual screenshot tests are left out of v1: fonts and rendering differ across machines, and role-based assertions catch what matters.

Build order#

1. Foundations (done): the token pipeline and contrast test, @wellfed/ui on bits-ui, the bench moved to the new tokens, ESLint and Prettier in make check-web.
2. Skeleton: the SvelteKit app, client, errors, stream with leader election, auth and first-owner setup, Paraglide, the shell and navigation, and the Playwright harness against the server and simulator.
3. Feed, status and schedules: home, feeder, plans and settings, with the feeding-safety tests.
4. History and charts.
5. Pets, food and the derived views.
6. Admin: users and tokens, releases and installs, export and import, adoption.

Each step waits on the server endpoints it uses. Plans and the derived views are not on the server yet.

Open questions#

• Does SvelteKit's generated CSP cover the hash-router fallback page's inline bootstrap script, or does it need a hash added by the build?
• Which bits-ui widgets need style-src-attr 'unsafe-inline', and can positioning move to CSS anchor positioning on the target browsers?
• The first-visitor rule leaves a window where anyone on the LAN can claim a fresh server (/setup closes once the first account exists). Should the server also log the claim prominently, so an owner can tell if someone beat them to it?
• Image sizes for the renders in srcset, and whether 1024 px sources are enough for wide screens.
• Whether a component gallery page (for design review of @wellfed/ui) is worth its upkeep.