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 visual noise — the base16 palette has several accent slots
(`--purple`, `--cyan`, `--pink`, …); use more than one where it adds (`--purple`, `--cyan`, `--pink`, …); use more than one where it adds
distinction, not decoration for its own sake. distinction, not decoration for its own sake.
- **Whimsy** — small, delightful touches are welcome (the home page's - **Whimsy** — small, delightful touches are welcome (the per-hive
matrix-rain background is the reference example). Whimsy still has to dashboard's home-page matrix-rain background, `packages/dashboard/src/
clear the accessibility bar below (motion, in particular). 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. - **Efficient navigation** — minimize clicks/hops for a common task.
- **Avoid junk drawers.** A control belongs next to the thing it - **Avoid junk drawers.** A control belongs next to the thing it
affects, not tucked into a catch-all menu. Concrete anti-example (not 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 **General rule, not case-by-case: every non-essential CSS animation
gates on `prefers-reduced-motion` and pauses when its tab/section is gates on `prefers-reduced-motion` and pauses when its tab/section is
hidden.** The matrix-rain background is the existing reference hidden.** The dashboard's matrix-rain background (`packages/dashboard/
implementation of this pattern — every future animation follows it, not src/home.js`/`.css`) is the existing reference implementation of this
just whimsy pieces. 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 An in-app override (independent of the OS-level media query, for
someone who wants motion on despite a system-wide reduced-motion 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) When something needs a table, a form field, a button — build (or adopt)
a `src/ui/` primitive that enforces consistent theming and behaviour, a `src/ui/` primitive that enforces consistent theming and behaviour,
rather than styling it inline on the page that happens to need it first. rather than styling it inline on the page that happens to need it first.
`Panel`/`StatusChip`/`Table`/`FormField`/`TextField`/`SelectField`/ `Panel`/`StatusChip`/`Table`/`TextField`/`SelectField`/`Button` are the
`Button` are the primitives that exist as of this writing; `/components` primitives that exist as of this writing, each with its own
always has the current, complete list — this doc won't try to keep a `/components` demo; `/components` always has the current, complete list
duplicate inventory in sync. — this doc won't try to keep a duplicate inventory in sync.
Default heuristic for *when* to promote page-scoped styling into a Default heuristic for *when* to promote page-scoped styling into a
shared primitive: the day a second real page needs the same thing, not 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.) that's a judgement call each time, not a rule change.)
**Every new `ui/` component gets a demo section on `/components` the **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 ## Attention