docs: swarm-ui design guide

Distills the design-language discussion on #3444 into a durable
reference: visual language, motion, theming policy, data-freshness/
refresh, error UX, empty states, layout/viewport, component-first
design, and attention — plus an open-questions table pointing at the
still-unbuilt issues (#3452/#3453/#3454/#3456) instead of asserting
them as settled.

Mirrors css-vars.md's shape and links to it + to /components rather
than duplicating either. First draft for comment, not a final spec.

docs/web-ui.md

@@ -29,6 +29,11 @@ dashboard rather than how it's built, start at
 - **[CSS theme variables](web-ui/css-vars.md)** — the Catppuccin
   Mocha custom properties declared once in `base.css` and the rule
   that per-page stylesheets reference (never redeclare) them.
+- **[swarm-ui design guide](web-ui/design-guide.md)** — visual
+  language, motion, theming, error-UX, and component-first principles
+  for the swarm-level Preact app specifically (not this doc's
+  dashboard/agent UIs). `/components` on a running swarm-ui is the
+  companion living demo of every primitive it references.
 
 ## Reading paths