docs: fix design-guide accuracy nits argus flagged

- matrix-rain reference is in packages/dashboard/src/home.js, not
  swarm-ui — cite it correctly (dashboard package) rather than implying
  it lives inside this doc's own scope.
- drop FormField from the visible component-first inventory (it has no
  /components demo, deliberately — a real exception to the 'every new
  ui/ component gets a demo' rule stated two paragraphs later) and note
  the exception explicitly instead of leaving the contradiction.
This commit is contained in:
iris 2026-08-18 20:48:42 +02:00 committed by mara
commit a5864c0fde

View file

@ -27,9 +27,12 @@ context than fits here.
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 home page's
matrix-rain background is the reference example). Whimsy still has to
clear the accessibility bar below (motion, in particular).
- **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
@ -41,9 +44,12 @@ context than fits here.
**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 matrix-rain background is the existing reference
implementation of this pattern — every future animation follows it, not
just whimsy pieces.
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.
An in-app override (independent of the OS-level media query, for
someone who wants motion on despite a system-wide reduced-motion
@ -151,10 +157,10 @@ just bare column headers floating over nothing.
When something needs a table, a form field, a button — build (or adopt)
a `src/ui/` primitive that enforces consistent theming and behaviour,
rather than styling it inline on the page that happens to need it first.
`Panel`/`StatusChip`/`Table`/`FormField`/`TextField`/`SelectField`/
`Button` are the primitives that exist as of this writing; `/components`
always has the current, complete list — this doc won't try to keep a
duplicate inventory in sync.
`Panel`/`StatusChip`/`Table`/`TextField`/`SelectField`/`Button` are the
primitives that exist as of this writing, each with its own
`/components` demo; `/components` always has the current, complete list
— this doc won't try to keep a duplicate inventory in sync.
Default heuristic for *when* to promote page-scoped styling into a
shared primitive: the day a second real page needs the same thing, not
@ -163,7 +169,12 @@ a primitive ahead of a second caller, as happened with the form kit —
that's a judgement call each time, not a rule change.)
**Every new `ui/` component gets a demo section on `/components` the
same day it lands** — no primitive without a place to see it.
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 —
that's a real, considered exception (see its own doc comment), not an
oversight this rule missed.
## Attention