division-ds 0.1.2 → 0.2.0

package/skills/division-ds/commands/review.md

@@ -0,0 +1,25 @@
+# Division DS: review
+
+> Load when a screen is written and you are about to say it is done. The checklist to run over it. Generated by `npm run agent-docs`; the procedure lives in scripts/lib/agent-docs.mjs.
+
+Paths starting `public/` are in the Division DS repository. In a project that uses the components, read them online: `public/llms.txt` is `https://victor-ilioiu.vercel.app/systems/division-ds/llms.txt`, and so on.
+
+Go through every line. A line that does not hold is a change to make, not a note to leave.
+
+- [ ] **States.** Every region has its empty, loading, error, success and disabled or no-permission state, as planned in `commands/build.md`. An empty list says what is empty and offers the action that fills it.
+- [ ] **Headings.** One `PageHeader`, so one `h1`. Section headings continue the outline: `h2` under the `h1`, `h3` inside an `h2`, no level skipped. `SectionHeading` is given the level.
+- [ ] **Tokens only.** No hex, `rgb()`, palette class or invented token name. `division-ds check` passes.
+- [ ] **Buttons.** Two or more side by side share a parent with a gap. One primary button per view. A busy button takes `loading`; a disabled one says why nearby. Icon-only actions are `IconButton` with a `label`.
+- [ ] **Forms.** Every `Input`, `Textarea`, `Select`, `MultiSelect` and `QuantityStepper` is inside a `FormField`; `Switch`, `Checkbox` and `Radio` have an `id` and a `<label htmlFor>`. A failed submit shows `ErrorSummary` and focuses it.
+- [ ] **Status.** Every status has a word, not only a colour.
+- [ ] **Focus.** Everything interactive is reached by Tab in reading order and shows the focus ring; anything styled by hand has the `focus-visible:outline-*` classes. An overlay hands focus back to what opened it. A button that removes its own row or item (Acknowledge, Delete, Dismiss) moves focus to the next one, else the previous one, else the empty state; focus never drops to the page.
+- [ ] **Text size.** Secondary text is 14px or larger; 11 to 12px only for uppercase mono labels.
+- [ ] **320px.** At 320px wide nothing scrolls sideways (`document.documentElement.scrollWidth <= 320`) and button rows wrap.
+- [ ] **Both themes.** It reads in dark and in light (`data-theme="light"` on `<html>`).
+- [ ] **Motion.** Anything animated by hand stops under reduced motion; nothing moves on its own.
+- [ ] **Live data.** Values that update on their own change in place, with no announcement for each number; a change of status (good to unhealthy) is announced once, through one polite live region (`role="status"`). Charts animate only their first draw, so new data every few seconds is fine.
+
+## Check
+
+- In a project that uses the components: `npx division-ds check <files or dirs>` (the checker is on npm; Node 22 or newer). It flags a raw colour, an invented token, touching buttons, an unknown prop and a value outside a prop's union.
+- In the Division DS repository itself: `npm run verify` (type-check, every gate, the unit tests).

package/skills/division-ds/topics/ai.md

@@ -0,0 +1,7 @@
+# Division DS: assistant copy
+
+> Load when wording a chat. Generated from AGENTS.md by `npm run agent-docs`. Edit the rules there, not here.
+
+**Assistant copy.** A button names the action ("Summarize"), never "AI". Say "response", not
+"answer". No "please" or "!" in assistant labels. The interface says "Assistant"; only its own
+messages say "I".

package/skills/division-ds/topics/colour.md

@@ -0,0 +1,11 @@
+# Division DS: colour roles
+
+> Load when choosing an accent, the text on a fill, or a status colour. Generated from AGENTS.md by `npm run agent-docs`. Edit the rules there, not here.
+
+**Fill, text, ink.** Each accent has three roles. `accent.<state>.fill` is a solid block;
+`accent.<state>.ink` is the text on that block; `accent.<state>.text` is coloured text on a
+normal surface. Never put `text.primary` on a fill.
+
+**Status tones.** `ok` done or healthy; `warning` degraded or needs attention; `hostile` failed
+or destructive; `info` in progress or neutral news; `signal` brand emphasis (a sale, the
+selected thing); `neutral` inactive. Always with a word: colour alone is not a status.

package/skills/division-ds/topics/feedback.md

@@ -0,0 +1,9 @@
+# Division DS: feedback
+
+> Load when a screen reports a result or a wait: a toast, an alert, progress, a spinner. Generated from AGENTS.md by `npm run agent-docs`. Edit the rules there, not here.
+
+**Feedback.** A `Toast` confirms something the person just did and then leaves, so it never holds
+the only copy of anything; a message that must stay is an `Alert` in the page. A failed load is
+an `Alert` in the `hostile` tone with a retry, not an `EmptyState`. Measurable work is
+`Progress`; a short wait inside a control or a line of text is `Spinner`; a busy `Button` takes
+`loading`.

package/skills/division-ds/topics/forms.md

@@ -0,0 +1,19 @@
+# Division DS: forms and actions
+
+> Load when a screen has a field, a form or more than one button. Generated from AGENTS.md by `npm run agent-docs`. Edit the rules there, not here.
+
+**Forms.** In a form, `Input`, `Textarea`, `Select`, `MultiSelect` and `QuantityStepper` go inside a `FormField`,
+which supplies the label, help and error and keeps an `id` you pass to the control. The one
+exception is a control repeated per row of a list (a role `Select` on each member): leave it
+bare and name it through its own `label` prop ("Role for Ilse Varga"). `Switch`, `Checkbox` and
+`Radio` are not `FormField` children: give them an `id` and a `<label htmlFor>`. A failed submit
+renders `ErrorSummary` at the top and focuses it; `useFieldErrors` holds the state (signature in
+`public/docs/helpers.md`).
+
+**Buttons.** Two or more buttons side by side need a parent with a gap
+(`flex flex-wrap gap-3`); `DialogFooter` and `CardFooter` already are one. A `Button` is
+`type="button"` unless you say `type="submit"`. A busy button takes `loading`, not `disabled`.
+`disabled` is for an action that is not available; say why in text nearby.
+
+**Icon-only buttons** are `IconButton` with a required `label`. A `Tooltip` adds detail; it does
+not replace the label.

package/skills/division-ds/topics/layout.md

@@ -0,0 +1,34 @@
+# Division DS: layout and type
+
+> Load when laying out a page: the shell, background, width, type sizes, cards, links. Generated from AGENTS.md by `npm run agent-docs`. Edit the rules there, not here.
+
+**Themes.** The theme is `data-theme="light"` or `"dark"` on `<html>` (`src/lib/theme.ts`); dark
+is the default. Tokens switch on their own, so a screen built from tokens needs no theme logic.
+The shell paints the page background (`surface.base`) and supplies the gutter; a screen sets its
+own `max-w-*` and vertical spacing, and no page background. A form or an overlay is the
+exception: it paints `surface.base` on itself, so its field colours never depend on what is
+behind it. In a project that uses the components, your own root does this
+(step 4 of `install.md`).
+
+**Type.** Three families, as utilities: `font-display` (headings, figures), `font-body` (the
+default, set by the shell), `font-mono` (labels, code, tabular numbers). A page title is
+`<h1 className="font-display font-semibold text-2xl">`; body is `text-base` or `text-sm`; a label
+is `font-mono text-xs font-semibold uppercase tracking-[0.18em]`. Tailwind's own size, weight
+and spacing utilities are fine; only colour is restricted to tokens.
+
+**Text size.** Secondary text is 14px or larger. 11 to 12px is for uppercase mono labels only.
+
+**Cards.** To highlight or select a `Card`, set the border inline with a token:
+`style={{ border: '2px solid var(--color-accent-signal-fill)' }}`. A border utility class does
+not win against the panel's own border. `interactive` is only for a card that holds one link or
+button; give that link `className={cardLinkClass}` (from `Card`) to stretch it over the card.
+
+**Links.** Components that render links take `renderLink`, defaulting to a plain `<a>`. Under a
+router, pass an adapter: `({ href, ...rest }) => <Link to={href} {...rest} />`. No component
+imports a router.
+
+**Charts and bundle size.** `ChartPanel` and `Sparkline` bring in recharts, a few hundred kB.
+Load the route or screen that uses them with `React.lazy` and a `<Suspense>` fallback, so recharts
+lands in its own chunk and screens without a chart never download it. Without that, Vite warns
+about a chunk over 500 kB; the warning is about load time only, and the build is fine. On a
+live page, data may change as often as you like: a chart animates its first draw only.

package/skills/division-ds/topics/motion.md

@@ -0,0 +1,10 @@
+# Division DS: motion
+
+> Load when animating anything yourself. Generated from AGENTS.md by `npm run agent-docs`. Edit the rules there, not here.
+
+**Motion.** The components animate themselves, and the shell animates a route change. A screen
+adds no keyframes of its own: use the classes in `src/styles/motion.css` (`anim-snap-in` for an
+element arriving, `anim-draw-on` for a hairline) and the motion tokens (`--duration-fast` for
+hover, `--duration-base` by default, `--duration-slow` for a larger change, `--ease-snap`).
+Anything you animate yourself stops under `prefers-reduced-motion` (`motion-reduce:` in
+Tailwind), and nothing moves on its own: no autoplay.

package/skills/division-ds/topics/overlays.md

@@ -0,0 +1,9 @@
+# Division DS: overlays
+
+> Load when adding a Dialog, an AlertDialog or a Sheet. Generated from AGENTS.md by `npm run agent-docs`. Edit the rules there, not here.
+
+**Overlays.** A task on top of the page is a `Dialog`; a destructive confirm is `AlertDialog`,
+not `Dialog`; filters, navigation on a narrow screen or one item's detail beside a list is a
+`Sheet`. Never open a dialog from a dialog or a sheet from a sheet. Never open one from a
+`DropdownMenu` item: the item is gone by the time the overlay closes, so focus has nowhere to go.
+Put a dialog's actions in `DialogFooter`.