hyperhive/docs/web-ui/design-guide.md

swarm-ui design guide

Scope: swarm-ui only (the swarm-level Preact app — not the per-hive dashboard, which has its own older visual language). This doc is the why: the principles behind how swarm-ui looks and behaves, and the concrete rules that follow from them. It deliberately doesn't show what things look like — that's ComponentsPage (/components), the living, always-current demo of every primitive in src/ui/. Code can't go stale the way a doc's screenshots can, so treat ComponentsPage as the source of truth for appearance and this doc as the source of truth for intent. Colour variables specifically are docs/web-ui/css-vars.md's job, not repeated here.

Visual language

• Frosted / tinted glass where it fits — translucency over flat panels, not a hard rule for every surface.
• Playful use of the multiple accent colours, without tipping into visual noise — the base16 palette has several accent slots (--purple, --cyan, --pink, …); use more than one where it adds distinction, not decoration for its own sake.
• Whimsy — small, delightful touches are welcome (the per-hive dashboard's home-page matrix-rain background, packages/dashboard/src/ home.js, is the reference example — currently in the dashboard package, not swarm-ui itself, but the pattern it sets applies here too). Whimsy still has to clear the accessibility bar below (motion, in particular).
• Efficient navigation — minimize clicks/hops for a common task.
• Avoid junk drawers. A control belongs next to the thing it affects, not tucked into a catch-all menu. Concrete anti-example (not swarm-ui, but the standard to avoid): the per-hive agent terminal's model selector living in a three-dot overflow menu instead of next to the thing that shows the current model.
• Loosely influenced by Material Design's current (Material You) generation, mainly for shape/elevation ideas — colour theming is governed entirely by the base16/stylix contract below, not Material's dynamic-colour system.

Motion

General rule, not case-by-case: every non-essential CSS animation gates on prefers-reduced-motion and pauses when its tab/section is hidden. The dashboard's matrix-rain background (packages/dashboard/ src/home.js/.css) is the existing reference implementation of this pattern — genuinely does both today, confirmed by reading it — even though it lives in the dashboard package rather than swarm-ui; every future swarm-ui animation follows the same pattern, not just whimsy pieces.

Prefer CSS-driven animation over JS-driven where possible, and avoid jarring content swaps (layout shift, hard cuts) where a transition can smooth them instead.

Theming

The mechanical contract (base16 slots, semantic vars, what a page's CSS is and isn't allowed to reference) lives in docs/web-ui/css-vars.md — read that for the how. This section is the policy layered on top:

• User-theming compatible by construction. The whole point of the base16/colors.css swap contract is that a user's own theme (stylix today) takes over with zero swarm-ui code changes. Don't build anything that assumes a specific palette's exact colours (contrast ratios, "this accent is always purple") beyond what the semantic var names promise.
• stylix wins outright when it's active, no in-between state. When an operator has stylix supplying swarm-ui's palette, that palette is authoritative — swarm-ui's own light/dark preference (below) doesn't override it. This is a deliberate simplification, not a limitation to fix: a stylix-using operator has already made their choice.
• Light theme is accessibility, not a cosmetic extra. Some people need light for contrast/low-vision reasons, others need dark for photosensitivity — there's no universally-correct default. The OS preference (prefers-color-scheme) drives the default, with an explicit user override available, same shape as motion above.

Data freshness & refresh

The governing question for anything that shows time-sensitive data: would a user returning to this tab expect current data? If yes, it needs a refresh story; a value that's silently gone stale with no way to tell is worse than one that's visibly stale.

• Relative-time labels must actually tick. A label like "fresh (5s ago)" is computed from a stored timestamp and re-renders itself on an interval — never a value frozen at fetch time that quietly goes stale while still reading as current. Pauses while its tab is hidden.
• Pages that poll get a refresh-interval control, not silent staleness. A small, Grafana-like "refresh every: off / 10s / 30s / 1m / …" control the operator sets per page, paused while the tab is backgrounded and resumed on foreground.
• A refresh must never clobber input the operator is mid-edit on. Any polling component's contract needs to make this the caller's problem to opt out of correctly, not something the next adopter discovers by shipping a bug.

Errors

ApiErrorPanel + the RFC 9457 ProblemDetails shape it renders is the canonical error surface for every API failure in swarm-ui, not just its original callers — nobody should build a softer/quieter error UI later. Concretely: full untruncated detail, a copy button, no "something went wrong, try reloading."

This follows from power-user-first, one of the standing principles: swarm-ui instances are mostly self-hosted and operators are techies, so errors should give them what they need to actually diagnose a problem rather than a friendly wall. Power-user-first doesn't mean newcomer-hostile — the UI should still be self-explanatory, warn or ask for confirmation before a destructive/dangerous action, and offer helpful hints — it just shouldn't get in the way of someone who already knows what they're doing.

Empty states

Graceful fallbacks, always — a table with zero rows should show something that represents "no rows" (a real empty-state message), not just bare column headers floating over nothing.

Layout & viewport

• swarm-ui adapts to screen size and fully supports touch — this is not a desktop-only app. Concrete floor: every interactive control from the shared ui/ kit (buttons, inputs, selects) carries a minimum touch target (2.75em ≈ 44px, WCAG 2.5.5) by default, so this isn't something each page has to remember.
• Phone is a second-class citizen, not an unsupported one. Things must not break at phone width, but don't over-invest in phone optimization beyond that. swarm-ui is installable as a PWA, so a phone can check status or do basic interactions.
• A narrow viewport isn't only a phone — a tiling-window-manager user with swarm-ui in a narrow tile hits the same layout constraints a phone does. Design for the constraint (narrow viewport), not the device.

Component-first design

Build the src/ui/ primitive before or alongside the first real page that needs it, not after it's been styled inline and left for later — a page reaching for a component that's already there has ready-made blocks to build with, instead of the next contributor duplicating ad-hoc styling that someone then has to hunt down and consolidate. Panel/StatusChip/Table/TextField/SelectField/Button are the primitives that exist; /components always has the current, complete list — this doc won't try to keep a duplicate inventory in sync.

Every new ui/ component gets a demo section on /components the same day it lands — no primitive without a place to see it. One deliberate exception exists today: FormField, the internal label+ control wrapper TextField/SelectField share, isn't itself a primitive a page reaches for directly, so it has no demo of its own — a considered exception, not an oversight this rule missed.

Attention

"Attention-optimized" here means the system should lead the operator's attention to where it actually matters (an error, a state change worth noticing) — not attention-optimized in the engagement/growth sense of maximizing time-on-page.