From a5864c0fde3ff262bba7051169cc2ca082323819 Mon Sep 17 00:00:00 2001 From: iris Date: Tue, 18 Aug 2026 20:48:42 +0200 Subject: [PATCH] docs: fix design-guide accuracy nits argus flagged MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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. --- docs/web-ui/design-guide.md | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/web-ui/design-guide.md b/docs/web-ui/design-guide.md index 0a07b523..62d29217 100644 --- a/docs/web-ui/design-guide.md +++ b/docs/web-ui/design-guide.md @@ -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