division-ds 0.1.1 → 0.2.0

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

@@ -0,0 +1,46 @@
+# Division DS: build
+
+> Load when building a new screen or page. Plans the regions and their states before any code. 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.
+
+Plan before code. The states a screen gets wrong are the ones nobody planned: an empty list
+with no message, a load that fails into a blank panel, a button that is disabled with no reason.
+
+1. **Regions.** List the screen top to bottom: the page header, each block of content (a table,
+   a form, a row of stats, a list), then anything that opens on top (a dialog, a sheet).
+2. **States.** Under each region, write one line per state, even when the answer is "none":
+   - **empty**: nothing yet, or a filter emptied it;
+   - **loading**: the first load, and a refresh;
+   - **error**: the load failed, or a save was rejected;
+   - **success**: the content, and what confirms an action;
+   - **disabled or no permission**: what someone who cannot act sees, and the reason they are told.
+3. **Components.** Pick one component per region and state from `public/llms.txt`. Each line there
+   has "Best for" and "Not for"; when "Not for" names your case, take the component it names.
+   The usual picks: page title `PageHeader`; empty `EmptyState`; loading `Skeleton` shapes in a
+   `SkeletonGroup`; failed load `Alert` in the `hostile` tone with a retry; a done action `Toast`;
+   a destructive confirm `AlertDialog`.
+4. **Read.** Open `public/docs/components/<slug>.md` for every component in the plan (Requires,
+   props, examples, Common mistakes). Load the topic files the plan touches: a field means
+   `topics/forms.md`, an overlay `topics/overlays.md`, a status colour `topics/colour.md`.
+5. **Write.** Each component imported from its own file; every colour a token from
+   `public/llms-tokens.txt`.
+6. **Check.** Run the check below and fix every finding (`commands/fix.md`), then go through
+   `commands/review.md`.
+
+A plan looks like this:
+
+```
+PageHeader: "Orders", action "New order"
+Region: orders table (DataTable, Pagination below)
+  empty:      EmptyState "No orders yet", action "Browse replicas", as emptyMessage
+  loading:    SkeletonGroup "Loading orders", one Skeleton line per row
+  error:      Alert hostile "Orders did not load", Retry button
+  success:    rows; a bulk action confirms with a Toast
+  no access:  the "New order" button is absent, a sentence says who can create orders
+```
+
+## 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/commands/fix.md

@@ -0,0 +1,28 @@
+# Division DS: fix
+
+> Load when a gate, `division-ds check` or a test has failed and named a rule. What each message means and the fix. 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.
+
+Every finding prints `path:line [rule] what was found` and a line saying what to write instead.
+Do what that line says. Never silence a gate: no new EXEMPT entry, no `token-discipline: allow`
+comment and no ALLOWED_IDIOMS entry to get past one.
+
+| Message | Fix |
+|---|---|
+| `[raw-colour]` a hex, `rgb()` or `hsl()` | Replace it with a semantic token by intent, `text-[var(--color-text-primary)]`. Pick from `public/llms-tokens.txt`. |
+| `[palette-class]` `bg-red-500`, `text-white` | Same: an arbitrary value on a token, `bg-[var(--color-surface-raised)]`. |
+| `[unknown-token]` | The name is not a token. Take the "Did you mean" suggestion, or look it up in `public/llms-tokens.txt`. Never define it yourself. |
+| `[primitive-in-component]` | A ramp step (`--color-signal-500`). Use the semantic token for what it does: `accent.<state>.text`, `.fill` or `.ink`. |
+| `touching-buttons`, "Button-spacing gate FAILED" | Wrap the buttons in one parent with a gap (`flex flex-wrap items-center gap-3`) and move any margin onto it. `DialogFooter` and `CardFooter` already are one. |
+| `[unknown-prop]` "has no prop" | The prop does not exist. Open the page the message names and use a prop from its table. |
+| `[unknown-prop]` "types X away on purpose" | The component sets that attribute itself. Use the prop it names (`label` for a name, `invalid` for an error state). |
+| `[invalid-value]` | The value is not in the prop's union. The message lists the allowed values. |
+| `[ai-in-cta]` | A button says "AI". Name what it does instead: "Summarize", "Draft a reply". |
+| `[assistant-copy]` | An assistant component's label says "answer", "please" or "!". Write "response", drop "please", drop the exclamation point. |
+| "Vocabulary gate FAILED" (this repository only) | Reword the line. If it is an ordinary idiom, ask before adding it to ALLOWED_IDIOMS. |
+| "Agent docs are stale" (this repository only) | Run `npm run agent-docs`, then `npm run verify`. |
+| A props-table test fails in `meta.test.ts` (this repository only) | The `<Name>.meta.ts` table and the real props disagree. Change the table to match the code, both ways. |
+| A type error on a component prop | Read the prop's type on its page; for a link that is disabled or busy, render the state directly instead of fighting the type. |
+
+After the fix, run the same command again until it passes.

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`.