division-ds 0.2.0 → 0.2.1

package/scripts/lib/mcp-tools.mjs

@@ -5,6 +5,7 @@
 // Most design-system MCP servers stop at list / search / get docs (shadcn, Chakra, Dialtone,
 // Blade, Vibe; surveyed 2026-10-25). `validate_code` is the one they lack: it runs the same gates
 // as `division-ds check` on the code the agent has just written, before the agent says it is done.
+import { alsoExports, INSTALLED_PATHS } from './agent-docs.mjs'
 import { checkText } from './check-text.mjs'
 import { contrastRatio } from './contrast.mjs'
 import { buildIndex, closest } from './props-validator.mjs'
@@ -30,7 +31,11 @@ export function createTools(context) {
 
   function findComponent(name) {
     const wanted = String(name ?? '').trim().toLowerCase()
-    return components.find(c => c.name.toLowerCase() === wanted || c.slug === wanted)
+    return (
+      components.find(c => c.name.toLowerCase() === wanted || c.slug === wanted) ??
+      // A component documented on another's page (ResponseFeedback on ChatMessage's) opens that page.
+      components.find(c => alsoExports(c).some(other => other.toLowerCase() === wanted))
+    )
   }
 
   function unknownComponent(name) {
@@ -66,7 +71,12 @@ export function createTools(context) {
       run({ tier } = {}) {
         if (tier !== undefined && !TIERS.includes(tier)) throw new ToolError(`tier is one of ${TIERS.join(', ')}.`)
         const rows = components.filter(c => !tier || c.tier === tier)
-        return rows.map(c => `- ${c.name} (${c.tier}): ${c.useWhen}${c.notFor ? ` Not for: ${c.notFor}` : ''}`).join('\n')
+        return rows
+          .map(c => {
+            const also = alsoExports(c)
+            return `- ${c.name} (${c.tier}): ${c.useWhen}${c.notFor ? ` Not for: ${c.notFor}` : ''}${also.length ? ` Also on its page: ${also.join(', ')}.` : ''}`
+          })
+          .join('\n')
       },
     },
     {
@@ -85,7 +95,7 @@ export function createTools(context) {
         const c = findComponent(name) ?? unknownComponent(name)
         const imports = c.imports.map(i => `import { ${i.names.join(', ')} } from '${i.from}'`).join('\n')
         const props = c.props.map(p => `- ${p.name}: ${p.type}${p.default ? ` = ${p.default}` : ''}. ${p.description ?? ''}`.trimEnd()).join('\n')
-        const head = `# ${c.name} (${c.tier})\n\n${c.summary}\n\n${imports}\n\nPaths are from the Division DS repository root; installed with shadcn they start src/division-ds/.\n\n## Props\n\n${props}`
+        const head = `# ${c.name} (${c.tier})\n\n${c.summary}\n\n${imports}\n\n${INSTALLED_PATHS}\n\n## Props\n\n${props}`
         if (section === 'props') return head
         const page = context.readDoc?.(c.slug)
         // The page is the full contract (examples, keyboard, do and don't, written for agents).
@@ -112,13 +122,28 @@ export function createTools(context) {
       run({ query, limit = 10 }) {
         const terms = words(query)
         if (terms.length === 0) throw new ToolError('query has no words to search for.')
-        const score = (title, body) => {
+        // `props` is the prop descriptions: a word found there counts once, as a hint, so a long
+        // prop table does not outrank a component or token whose own summary is about the query.
+        const score = (title, body, props = '', propNames = '') => {
           const t = words(title).join(' ')
           const b = words(body)
-          return terms.reduce((sum, term) => sum + (t.includes(term) ? 3 : 0) + b.filter(w => w.startsWith(term)).length, 0)
+          const p = words(props)
+          const n = words(propNames)
+          const inMain = term => t.includes(term) || b.some(w => w.startsWith(term))
+          // Every word of the query in the name or summary beats one word found often: "page
+          // background" is the surface token, not PageHeader, whose name matches "page" alone.
+          const all = terms.length > 1 && terms.every(inMain) ? 5 : 0
+          return all + terms.reduce((sum, term) => sum + (t.includes(term) ? 3 : 0) + Math.min(b.filter(w => w.startsWith(term)).length, 3) + (inMain(term) ? 0 : n.some(w => w.startsWith(term)) ? 2 : p.some(w => w.startsWith(term)) ? 1 : 0), 0)
         }
         const hits = [
-          ...components.map(c => ({ kind: 'component', name: c.name, line: c.useWhen, score: score(c.name, `${c.summary} ${c.useWhen}`) })),
+          // The title holds every name on the page (ChatMessage and ResponseFeedback); the body adds
+          // the prop descriptions, where what a part does is written ("helpful", "thumbs up").
+          ...components.map(c => {
+            const also = alsoExports(c)
+            const props = c.props.map(p => `${p.name} ${p.description ?? ''}`).join(' ')
+            const line = `${c.useWhen}${also.length ? ` Also on its page: ${also.join(', ')}.` : ''}`
+            return { kind: 'component', name: c.name, line, score: score(`${c.name} ${also.join(' ')}`, `${c.summary} ${c.useWhen}`, props, c.props.map(p => p.name).join(' ')) }
+          }),
           // Primitives are not for screens (tokens.json's rule), so they never come up as an answer.
           ...tokens.tokens.filter(t => t.layer !== 'primitive').map(t => ({ kind: `${t.layer} token`, name: t.name, line: t.use ?? '', score: score(t.name, t.use ?? '') })),
         ]
@@ -158,13 +183,13 @@ export function createTools(context) {
         type: 'object',
         properties: {
           code: { type: 'string', description: 'The whole file, imports included: props are matched through the imports.' },
-          filename: { type: 'string', description: 'Its name, e.g. "src/pages/Settings.tsx". The extension decides which gates run. Default "Screen.tsx".' },
+          filename: { type: 'string', description: 'Its name, e.g. "src/pages/Settings.tsx". The extension decides which gates run: a .css file gets the colour and token checks, and setting a real token (--color-surface-base: ...) is allowed there, since that is how a project themes the system. Default "Screen.tsx".' },
         },
         required: ['code'],
         additionalProperties: false,
       },
       run({ code, filename = 'Screen.tsx' }) {
-        if (!/\.(tsx|jsx|ts)$/.test(filename)) throw new ToolError('filename ends in .tsx, .jsx or .ts.')
+        if (!/\.(tsx|jsx|ts|css)$/.test(filename)) throw new ToolError('filename ends in .tsx, .jsx, .ts or .css.')
         const findings = checkText(String(code), filename, index, tokenNames)
         if (findings.length === 0) {
           return `No findings in ${filename}: colours, tokens, button spacing, props and AI copy are clean.\nNot checked: how the screen behaves. Run get_review_checklist, in a browser.`

package/scripts/lib/props-validator.mjs

@@ -28,6 +28,7 @@
 //   accepted; one the rest type names in its Omit<> is not. With a `...rest` row of a Radix
 //   component's props, any other prop is accepted (the Radix surface is not in the manifest).
 import ts from 'typescript'
+import { DOCS_SITE } from './agent-docs.mjs'
 import { parseRowName, resolvePart } from './component-props.mjs'
 
 /** Always accepted on any component: React's own props, and attributes every DOM wrapper takes. */
@@ -125,7 +126,7 @@ export function buildIndex(manifest) {
     if (exportNames.length === 0) continue
     const components = Object.fromEntries(exportNames.map(name => [name, true]))
     const specs = Object.fromEntries(
-      exportNames.map(name => [name, { entry: entry.name, docs: entry.docs, props: new Map(), rest: null }])
+      exportNames.map(name => [name, { entry: entry.name, docs: entry.docs && `${DOCS_SITE}${entry.docs.replace(/^\//, '')}`, props: new Map(), rest: null }])
     )
     let unresolved = false
     for (const row of entry.props ?? []) {

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/commands/add.md

@@ -2,7 +2,7 @@
 
 > 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.
+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.

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

@@ -2,7 +2,7 @@
 
 > 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.
+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.

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

@@ -2,7 +2,7 @@
 
 > 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.
+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`

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

@@ -2,11 +2,11 @@
 
 > 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.
+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 in `commands/build.md`. An empty list says what is empty and offers the action that fills it.
+- [ ] **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`.

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

@@ -4,4 +4,5 @@
 
 **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".
+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/forms.md

@@ -10,6 +10,9 @@ bare and name it through its own `label` prop ("Role for Ilse Varga"). `Switch`,
 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`.

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

@@ -8,7 +8,9 @@ The shell paints the page background (`surface.base`) and supplies the gutter; a
 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`).
+(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