division-ds 0.1.2 → 0.2.1

package/scripts/lib/token-discipline.mjs

@@ -9,6 +9,12 @@
 // Colour only, on purpose. Spacing is not gated: enforcing it before the scale is complete makes
 // an author (or an agent) invent a token name to satisfy the rule, which is the worse failure.
 
+import { DOCS_SITE } from './agent-docs.mjs'
+
+/** Where a token list lives for whoever reads the finding: the MCP tool, or the docs site. A
+ *  repository path meant nothing in a project that installed the components (2026-10-29 test). */
+const TOKEN_LIST = `get_tokens over MCP, or ${DOCS_SITE}llms-tokens.txt`
+
 export const SCANNED_ROOTS = ['src']
 export const SCANNED_EXTENSIONS = /\.(tsx?|css)$/
 
@@ -16,6 +22,7 @@ export const SCANNED_EXTENSIONS = /\.(tsx?|css)$/
  *  A new entry needs a reason as good as these; "it was easier" is the case the gate exists for. */
 export const EXEMPT = [
   { pattern: /^src\/styles\/tokens\.css$/, why: 'generated from tokens/: this is where the literals are meant to be' },
+  { pattern: /(^|\/)division-ds\/styles\/tokens\.css$/, why: 'the same file, installed into a project by shadcn; it also names the MCP Apps host\'s own variables' },
   { pattern: /\.test\.tsx?$/, why: 'tests assert on literal values and on deliberately wrong input' },
   { pattern: /^src\/demo\/(scene|blob|terrain)\//, why: 'WebGL materials: three.js takes colours as numbers, not CSS variables' },
   { pattern: /^src\/components\/atoms\/loading-animation\/(palette|scene|kit|variants)\.ts$/, why: 'WebGL materials, read from the tokens at runtime where they can be' },
@@ -98,9 +105,9 @@ export function findViolations(text, path, tokenNames) {
       if (name.endsWith('-')) continue
       if (!known.has(name)) {
         const near = suggest(name, tokenNames)
-        add('unknown-token', `var(${name})`, near.length ? `No such token. Did you mean ${near.join(', ')}?` : 'No such token. The full list is public/manifest/tokens.json.')
+        add('unknown-token', `var(${name})`, near.length ? `No such token. Did you mean ${near.join(', ')}?` : `No such token. The full list: ${TOKEN_LIST}.`)
       } else if (PRIMITIVE_RAMP.test(name) && inComponents(path)) {
-        add('primitive-in-component', `var(${name})`, 'A component reads semantic tokens, not a ramp step. Pick one by intent from public/manifest/tokens.json (accent.<state>.text, .fill or .ink).')
+        add('primitive-in-component', `var(${name})`, `A component reads semantic tokens, not a ramp step. Pick one by intent (accent.<state>.text, .fill or .ink): ${TOKEN_LIST}.`)
       }
     }
 
@@ -108,7 +115,7 @@ export function findViolations(text, path, tokenNames) {
     // where a literal colour would be.
     const rest = line.replace(/var\([^)]*\)/g, '')
     for (const match of rest.matchAll(HEX)) {
-      add('raw-colour', match[0], 'Use a semantic token: text-[var(--color-text-primary)], bg-[var(--color-surface-base)]. Tokens and what each is for: public/manifest/tokens.json.')
+      add('raw-colour', match[0], `Use a semantic token: text-[var(--color-text-primary)], bg-[var(--color-surface-base)]. Tokens and what each is for: ${TOKEN_LIST}.`)
     }
     for (const match of rest.matchAll(COLOR_FUNCTION)) {
       add('raw-colour', match[0] + '…)', 'Use a semantic token. If no token fits, the colour is a change to the system: add it under tokens/ with a contrast pair.')

package/skills/division-ds/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: division-ds
+description: Use when building or changing UI with Division DS (React 19, Tailwind 4, Radix; 68 components). Covers which component and token to use, the composition rules prop types cannot express (providers, FormField, button gaps, card borders), planning a screen's states, and how to check the result. Load it before writing any screen or component in a project that has Division DS components.
+---
+
+# Division DS
+
+Generated from AGENTS.md by `npm run agent-docs`. Edit the rules there, not here.
+
+This file is the core: what every screen needs. The topic and command files below hold the rest; load one when the work reaches it, not before.
+
+## Plan first
+
+Before writing a screen, list its regions and, for each, its states: empty, loading, error, success, and disabled or no permission. Pick a component for each from `public/llms.txt` by its "Best for" and "Not for". `commands/build.md` is the whole procedure.
+
+## Where things are
+
+| You want | Read |
+|---|---|
+| Every component, one line each with best for and not for | `public/llms.txt` |
+| One component: props, examples, keyboard, mistakes | `public/docs/components/<slug>.md` |
+| Which token to use for what | `public/llms-tokens.txt` |
+| Shared helpers: form errors, money, links, theme, streamed text | `public/docs/helpers.md` |
+| The same as data | `public/manifest/components.json`, `public/manifest/tokens.json` |
+
+Outside this repository, read the same files online: `https://victor-ilioiu.vercel.app/systems/division-ds/llms.txt`, `https://victor-ilioiu.vercel.app/systems/division-ds/docs/components/<slug>.md`, and so on. Add a component to a project with `npx shadcn@latest add https://raw.githubusercontent.com/Victor-Ilioiu/division-ds/main/public/r/<slug>.json`, or every component with `division-ds-all` as the slug. The setup steps, in plain text: `https://victor-ilioiu.vercel.app/systems/division-ds/install.md`.
+
+## Check your work
+
+- 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).
+
+A finding says what to write instead. `commands/fix.md` explains each one.
+
+## Topics: load when
+
+- `topics/colour.md`: choosing an accent, the text on a fill, or a status colour.
+- `topics/layout.md`: laying out a page: the shell, background, width, type sizes, cards, links.
+- `topics/forms.md`: a screen has a field, a form or more than one button.
+- `topics/overlays.md`: adding a Dialog, an AlertDialog or a Sheet.
+- `topics/feedback.md`: a screen reports a result or a wait: a toast, an alert, progress, a spinner.
+- `topics/motion.md`: animating anything yourself.
+- `topics/ai.md`: wording a chat.
+
+## Commands: load when
+
+- `commands/build.md`: building a new screen or page. Plans the regions and their states before any code.
+- `commands/add.md`: adding one component to a screen that already exists.
+- `commands/fix.md`: a gate, `division-ds check` or a test has failed and named a rule. What each message means and the fix.
+- `commands/review.md`: a screen is written and you are about to say it is done. The checklist to run over it.
+
+## Core rules
+
+Each of these is something an agent got wrong or had to guess when it first used the system.
+
+**Imports.** Import a component from its own file, by relative path. There is no path alias: the
+docs write `src/components/atoms/button/Button`, and from `src/pages/Screen.tsx` that is
+`'../components/atoms/button/Button'`. Helpers work the same way: `src/lib/money` is
+`'../lib/money'` from there. The tier barrels (`components/atoms`, `/molecules`,
+`/organisms`) are for the system's own composition; the organisms barrel pulls the chart library
+into whatever imports it. Icons come from `lucide-react`, with `aria-hidden="true"` unless the
+icon is the only content. Installed with shadcn, paths start `src/division-ds/` instead of `src/`.
+
+**Colour.** Every colour is a semantic token inside a Tailwind arbitrary value:
+`text-[var(--color-text-primary)]`, `bg-[var(--color-surface-base)]`. Never a hex, never
+`rgb()`, never a Tailwind palette class (`bg-red-500`, `text-white`), never a token name you
+have not seen in `llms-tokens.txt`. An invented name fails silently in the browser and loudly in
+`npm run verify`.
+
+**Providers.** One `<Toaster>` and one `<TooltipProvider>` sit at the root of the app (`AppShell`,
+`DemoLayout` in this repository). Assume both, including for a screen you are writing that is not
+mounted anywhere yet: it will be mounted under one of the two shells. Call `useToast()` freely; do
+not mount a second `Toaster`, and do not drop a toast or a tooltip because you cannot see the
+provider. A project that uses the components mounts both itself (step 4 of `install.md`).
+
+**Focus.** Anything focusable that you style yourself gets
+`focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-focus-ring)]`.
+
+**Page title, empty, loading.** Plan these before writing a screen. A page title is `PageHeader`
+(it renders the `h1`). An empty list or result is `EmptyState`; inside a `DataTable`, pass it as
+`emptyMessage`. A loading region is `Skeleton` shapes inside a `SkeletonGroup`. The demo's
+`src/demo/states/` files are not part of the system.
+
+**What the system does not have.** No Popover, no Combobox (single value: use `Select`; several:
+`MultiSelect`), no date picker. Do not reach into `src/demo/` from a component.
+
+**Vocabulary.** Inside this repository, `npm run check:vocabulary` bans a list of words in `src/`,
+`scripts/` and `e2e/` (the list is `scripts/lib/vocabulary.mjs`; it is not published with the
+docs). Run it on sample copy too: an ordinary phrase can match. Products in sample data are
+"replicas". The gate does not apply to a project that only uses the components.

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

@@ -0,0 +1,25 @@
+# Division DS: add
+
+> Load when adding one component to a screen that already exists. 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. The other procedures named here (`commands/build.md` and the rest) are in the skill: `https://github.com/Victor-Ilioiu/division-ds/blob/main/skills/division-ds/commands/<name>.md`, or `npx division-ds skill` to install them.
+
+1. Find it in `public/llms.txt`. Its "Best for" should describe your case and its "Not for"
+   should not; if "Not for" names your case, use the component it names instead.
+2. Open `public/docs/components/<slug>.md` and read, in order: **Requires** (a provider, a
+   wrapper such as `FormField`, a landmark), **Props**, **Examples**, **Common mistakes** and
+   **Don't**.
+3. Take the import from the page's Import block and rewrite it as a relative path from your
+   file. Import a type with `import type`.
+4. Start from the closest example on the page and change only the content. Keep what it sets
+   for access: `label`, `id`, `aria-*`, the heading level.
+5. Supply what Requires names: a field inside a `FormField`; `Switch`, `Checkbox` and `Radio`
+   with an `id` and a `<label htmlFor>`; a button beside another inside a parent with a gap.
+6. Add the states it brings with it: why a control is disabled, what a list shows when empty,
+   a button's `loading`.
+7. Run the check below on the file.
+
+## 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/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. The other procedures named here (`commands/build.md` and the rest) are in the skill: `https://github.com/Victor-Ilioiu/division-ds/blob/main/skills/division-ds/commands/<name>.md`, or `npx division-ds skill` to install them.
+
+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. The other procedures named here (`commands/build.md` and the rest) are in the skill: `https://github.com/Victor-Ilioiu/division-ds/blob/main/skills/division-ds/commands/<name>.md`, or `npx division-ds skill` to install them.
+
+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. The other procedures named here (`commands/build.md` and the rest) are in the skill: `https://github.com/Victor-Ilioiu/division-ds/blob/main/skills/division-ds/commands/<name>.md`, or `npx division-ds skill` to install them.
+
+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 before the code (the regions-and-states plan of `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,8 @@
+# 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". Response feedback: `ResponseFeedback` in `actions`.
+A value the assistant filled is `aiValue` on that `Input` or `Textarea` only; leaving it accepts it.

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,22 @@
+# 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`).
+
+A `RadioGroup` in a form sits in a `<fieldset>` whose `<legend>` names it (code on the Radio
+page). A date is `<Input type="date">` in a `FormField`.
+
+**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,36 @@
+# 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`). Toggle it with `setTheme()` from `src/lib/theme.ts`.
+
+**App navigation.** A few views: `Navbar` (`current: true` on the open one). Many: `Sidebar`.
+
+**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`.