division-ds 0.1.2 → 0.2.1

package/scripts/lib/contrast.mjs

@@ -0,0 +1,111 @@
+// Contrast maths for the AA gate. Two jobs: parse a colour, and composite it over whatever it is
+// actually painted on before measuring.
+//
+// The compositing half exists because this design system writes real translucent tokens
+// (`border.hairline`, `surface.raised`), and a hex-only parser silently could not evaluate them —
+// which is how a whole class of SC 1.4.11 failure on the form controls' boundaries stayed
+// invisible to a gate that reported 28/28 green. A translucent colour has no contrast ratio of
+// its own; it only has one against a named backdrop. So every alpha-carrying colour here must be
+// given one, and the gate names it explicitly rather than guessing.
+
+/** Parses #rgb, #rrggbb, #rrggbbaa, rgb()/rgba() (comma or space separated, alpha as number or
+ *  percentage) into `[r, g, b, a]` with channels 0–255 and alpha 0–1. */
+function parseColor(color) {
+  if (typeof color !== 'string') throw new Error(`Not a colour: ${String(color)}`)
+  const value = color.trim()
+
+  if (value.startsWith('#')) {
+    const hex = value.slice(1)
+    if (hex.length === 3 || hex.length === 4) {
+      const channels = [...hex].map(c => parseInt(c + c, 16))
+      return [channels[0], channels[1], channels[2], channels[3] === undefined ? 1 : channels[3] / 255]
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      const channels = [0, 2, 4, 6]
+        .filter(i => i < hex.length)
+        .map(i => parseInt(hex.slice(i, i + 2), 16))
+      return [channels[0], channels[1], channels[2], channels[3] === undefined ? 1 : channels[3] / 255]
+    }
+    throw new Error(`Unparseable hex colour: ${color}`)
+  }
+
+  const fn = value.match(/^rgba?\(([^)]*)\)$/i)
+  if (fn) {
+    const parts = fn[1].split(/[\s,/]+/).filter(Boolean)
+    if (parts.length < 3) throw new Error(`Unparseable rgb() colour: ${color}`)
+    const channel = part =>
+      part.endsWith('%') ? (parseFloat(part) / 100) * 255 : parseFloat(part)
+    const alpha = parts[3] === undefined
+      ? 1
+      : parts[3].endsWith('%')
+        ? parseFloat(parts[3]) / 100
+        : parseFloat(parts[3])
+    const [r, g, b] = parts.slice(0, 3).map(channel)
+    if ([r, g, b, alpha].some(Number.isNaN)) throw new Error(`Unparseable rgb() colour: ${color}`)
+    return [r, g, b, alpha]
+  }
+
+  throw new Error(`Unsupported colour format: ${color} (expected #hex or rgb()/rgba())`)
+}
+
+const toHex = n => Math.round(Math.min(255, Math.max(0, n))).toString(16).padStart(2, '0')
+
+/** Source-over compositing: paints `color` onto `backdrop` and returns the resulting opaque hex.
+ *  An opaque `color` is returned unchanged (and needs no backdrop). A translucent one without a
+ *  backdrop throws rather than silently measuring its own nominal RGB, which is exactly the
+ *  mistake the old hex-only parser could not even make visible. */
+export function composite(color, backdrop) {
+  const [r, g, b, a] = parseColor(color)
+  if (a >= 1) return `#${toHex(r)}${toHex(g)}${toHex(b)}`
+  if (backdrop === undefined || backdrop === null) {
+    throw new Error(
+      `${color} is translucent (alpha ${a}) and has no contrast ratio on its own — ` +
+        'pass the colour it is painted over as the backdrop.'
+    )
+  }
+  const [br, bg, bb] = parseColor(composite(backdrop))
+  return `#${toHex(r * a + br * (1 - a))}${toHex(g * a + bg * (1 - a))}${toHex(b * a + bb * (1 - a))}`
+}
+
+function relativeLuminance(color) {
+  const [r, g, b] = parseColor(color)
+  const linear = [r, g, b]
+    .map(v => v / 255)
+    .map(v => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
+  return 0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2]
+}
+
+/**
+ * Contrast ratio between `a` (the foreground) and `b` (its background).
+ *
+ * `backdrop` is what `b` itself is painted on, and is only needed when a translucent colour is
+ * involved: `b` is composited over `backdrop`, then `a` is composited over that result — the
+ * same order the browser paints them in. Two opaque hexes behave exactly as before, so every
+ * existing caller (`generate-ramps.mjs`, `ColorGuideline.tsx`) is unaffected.
+ */
+export function contrastRatio(a, b, backdrop) {
+  const bg = composite(b, backdrop)
+  const fg = composite(a, bg)
+  const [lighter, darker] = [relativeLuminance(fg), relativeLuminance(bg)].sort((x, y) => y - x)
+  return (lighter + 0.05) / (darker + 0.05)
+}
+
+/**
+ * Measures every pair and says whether each one holds.
+ *
+ * `maxRatio` is optional and is a CEILING, which most pairs have no use for: an accessibility
+ * minimum is a floor and more contrast is never a failure. One role in this system is the
+ * exception. The dimmed leading-zero pad on a hero numeral is decorative and `aria-hidden`, so no
+ * SC 1.4.3 obligation attaches to it at all, and its actual design rule is the opposite shape:
+ * it must stay well UNDER the ink it pads or it stops reading as padding and starts reading as a
+ * digit. That is exactly what happened in light theme, where the pad measured 65% of ink contrast
+ * while dark measured 31%, and a floor-only gate could not see it. A rule that is not a gate is a
+ * suggestion, so the gate learned to express a band.
+ */
+export function checkPairs(pairs) {
+  return pairs.map(({ name, fg, bg, backdrop, minRatio, maxRatio }) => {
+    const ratio = contrastRatio(fg, bg, backdrop)
+    const pass = ratio >= minRatio && (maxRatio === undefined || ratio <= maxRatio)
+    return { name, ratio, minRatio, maxRatio, pass }
+  })
+}

package/scripts/lib/host-inline.mjs

@@ -0,0 +1,59 @@
+// The inline-card limits of MCP Apps hosts, as a gate. Claude's design guidelines and OpenAI's
+// Apps SDK UI guidelines agree on an inline card: at most two actions, no nested scrolling (the
+// card auto-fits its content and the host clips what overflows), and no menus or popovers (they
+// are clipped by the iframe or fight the host's z-index). A screen opts in by marking the card:
+// `<Card data-host-mode="inline">`. Only marked elements are judged.
+//
+// It reuses button-spacing's JSX scanner, so it has the same blind spots: mapped or conditional
+// children, and anything rendered by a component defined elsewhere, are invisible to it.
+import { buildTree, isButtonLike, lineColAt, lineIndex, tokenizeTags } from './button-spacing.mjs'
+
+export const MAX_INLINE_ACTIONS = 2
+
+/** Division components that open a floating layer: a menu, a listbox or a tooltip. */
+export const POPOVER_TAGS = new Set(['DropdownMenu', 'Select', 'MultiSelect', 'Tooltip', 'CommandPalette', 'Dialog', 'Sheet', 'AlertDialog'])
+
+const SCROLL_CLASS = /(^|[\s'"`])overflow(-[xy])?-(auto|scroll)(?=[\s'"`]|$)/
+
+const isInline = node => node.attrs.get('data-host-mode') === 'inline'
+
+/** Every rule an inline-marked element in `text` breaks: `{ line, column, rule, found, fix }`. */
+export function findInlineViolations(text) {
+  const tree = buildTree(tokenizeTags(text))
+  const offsets = lineIndex(text)
+  const violations = []
+  const at = (node, rule, found, fix) => violations.push({ ...lineColAt(offsets, node.start), rule, found, fix })
+
+  function judge(card) {
+    let actions = 0
+    const walk = node => {
+      for (const child of node.children) {
+        // An asChild wrapper and its Button are one action: count it and do not descend.
+        if (isButtonLike(child)) {
+          actions++
+          continue
+        }
+        if (POPOVER_TAGS.has(child.name)) {
+          at(child, 'inline-no-popover', `<${child.name}> inside an inline card`, 'Use visible controls instead (SegmentedControl, Switch, Radio), or move this to fullscreen.')
+        }
+        if (SCROLL_CLASS.test(child.attrs.get('className') ?? '')) {
+          at(child, 'inline-no-nested-scroll', `<${child.name}> scrolls inside an inline card`, 'Let the card grow to its content, or request fullscreen for a scrolling view.')
+        }
+        walk(child)
+      }
+    }
+    walk(card)
+    if (actions > MAX_INLINE_ACTIONS) {
+      at(card, 'inline-max-actions', `${actions} actions in an inline card`, `Keep at most ${MAX_INLINE_ACTIONS} (one primary, one secondary); put the rest in fullscreen or in the chat.`)
+    }
+  }
+
+  const visit = node => {
+    if (node.name !== null && isInline(node)) return judge(node)
+    node.children.forEach(visit)
+  }
+  visit(tree)
+  return violations.sort((a, b) => a.line - b.line || a.column - b.column)
+}
+
+export const formatInlineViolation = (v, path) => `${path}:${v.line}:${v.column}  ${v.found} (${v.rule}). ${v.fix}`

package/scripts/lib/mcp-server.mjs

@@ -0,0 +1,116 @@
+// A Model Context Protocol server over stdio, for `division-ds mcp`. Hand-written rather than
+// built on @modelcontextprotocol/sdk: the npm package has one dependency (typescript) and a tools-
+// only server needs four methods. The transport is one JSON-RPC message per line on stdin and
+// stdout; anything written to stdout that is not a message breaks the client, so logs go to stderr.
+//
+// `handle` is pure (a message in, a reply or nothing out) so the tests drive it without a process.
+import { ToolError } from './mcp-tools.mjs'
+
+// Newest first. A client asking for one of these gets it back; any other gets the newest, and the
+// client decides whether it can work with that (the spec's negotiation).
+export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05']
+
+const INSTRUCTIONS = `Division DS: a React 19, Tailwind 4 and Radix design system.
+Before writing a component, call get_component for its props and examples. Use only tokens from get_tokens or search, as var(--name).
+Before saying a screen is done, call validate_code on each file you wrote (.css too) and fix every finding, then go through get_review_checklist.
+Shared helpers (theme toggle, form errors, money, links): https://victor-ilioiu.vercel.app/systems/division-ds/docs/helpers.md`
+
+/** A JSON-RPC error reply. */
+const failure = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } })
+
+/** The first problem with `args` against a tool's input schema, or undefined. Only what the tools
+ *  declare: required keys, unknown keys, and the JSON type of each value. */
+export function argumentProblem(schema, args) {
+  if (args === null || typeof args !== 'object' || Array.isArray(args)) return 'arguments must be an object.'
+  const properties = schema.properties ?? {}
+  for (const key of schema.required ?? []) if (args[key] === undefined) return `${key} is required.`
+  for (const [key, value] of Object.entries(args)) {
+    const property = properties[key]
+    if (!property) return `Unknown argument ${key}. This tool takes: ${Object.keys(properties).join(', ') || 'nothing'}.`
+    const type = Array.isArray(value) ? 'array' : Number.isInteger(value) ? 'integer' : typeof value
+    const ok = property.type === type || (property.type === 'number' && type === 'integer')
+    if (!ok) return `${key} must be ${/^[aeiou]/.test(property.type) ? 'an' : 'a'} ${property.type}.`
+    if (property.enum && !property.enum.includes(value)) return `${key} is one of ${property.enum.join(', ')}.`
+    if (property.type === 'array' && property.items?.type && value.some(item => typeof item !== property.items.type)) return `${key} holds ${property.items.type}s.`
+  }
+  return undefined
+}
+
+export function createServer({ tools, version }) {
+  const byName = new Map(tools.map(tool => [tool.name, tool]))
+
+  function call(params) {
+    const tool = byName.get(params?.name)
+    if (!tool) return { content: [{ type: 'text', text: `No tool "${params?.name}". Tools: ${[...byName.keys()].join(', ')}.` }], isError: true }
+    const args = params.arguments ?? {}
+    const problem = argumentProblem(tool.inputSchema, args)
+    if (problem) return { content: [{ type: 'text', text: `${tool.name}: ${problem}` }], isError: true }
+    try {
+      return { content: [{ type: 'text', text: tool.run(args) }] }
+    } catch (error) {
+      // A ToolError is the agent's mistake and says how to fix it. Anything else is ours; it is
+      // still reported as a tool result, so one bad call does not take the session down.
+      const text = error instanceof ToolError ? error.message : `division-ds ${version} failed on ${tool.name}: ${error.message}`
+      return { content: [{ type: 'text', text }], isError: true }
+    }
+  }
+
+  /** One parsed message in; the reply to send, or undefined for a notification. */
+  function handle(message) {
+    if (message === null || typeof message !== 'object' || message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+      return failure(message?.id ?? null, -32600, 'Invalid request.')
+    }
+    const { id, method, params } = message
+    // A notification (no id) never gets a reply, even one we do not understand.
+    if (id === undefined) return undefined
+    switch (method) {
+      case 'initialize': {
+        const asked = params?.protocolVersion
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: {
+            protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+            capabilities: { tools: {} },
+            serverInfo: { name: 'division-ds', version },
+            instructions: INSTRUCTIONS,
+          },
+        }
+      }
+      case 'ping':
+        return { jsonrpc: '2.0', id, result: {} }
+      case 'tools/list':
+        return { jsonrpc: '2.0', id, result: { tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) } }
+      case 'tools/call':
+        return { jsonrpc: '2.0', id, result: call(params) }
+      default:
+        return failure(id, -32601, `Method not found: ${method}`)
+    }
+  }
+
+  /** Reads messages from `input` line by line and writes replies to `output`. */
+  function listen(input, output) {
+    let buffer = ''
+    const send = reply => reply && output.write(JSON.stringify(reply) + '\n')
+    input.setEncoding('utf8')
+    input.on('data', chunk => {
+      buffer += chunk
+      let newline
+      while ((newline = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, newline).trim()
+        buffer = buffer.slice(newline + 1)
+        if (!line) continue
+        let message
+        try {
+          message = JSON.parse(line)
+        } catch {
+          send(failure(null, -32700, 'Parse error: each line must be one JSON-RPC message.'))
+          continue
+        }
+        send(handle(message))
+      }
+    })
+  }
+
+  return { handle, listen }
+}

package/scripts/lib/mcp-tools.mjs

@@ -0,0 +1,266 @@
+// The tools `division-ds mcp` serves, as plain functions over the two manifests. The protocol
+// (JSON-RPC over stdio) lives in mcp-server.mjs; nothing here knows it exists, so every tool is
+// unit-tested by calling it.
+//
+// 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'
+
+export const REGISTRY_BASE = 'https://raw.githubusercontent.com/Victor-Ilioiu/division-ds/main/public/r'
+const TIERS = ['atoms', 'molecules', 'organisms']
+const LAYERS = ['primitive', 'spacing', 'motion', 'semantic', 'component']
+// WCAG 2.2 minimums: SC 1.4.3 for text, SC 1.4.11 for the boundary of a control or a graphic.
+const MINIMUMS = { normal: 4.5, large: 3, ui: 3 }
+
+const words = text => String(text).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+
+/** `context`: { manifest, tokens, version, readDoc(slug) -> string|undefined, readChecklist() -> string|undefined } */
+export function createTools(context) {
+  const { manifest, tokens, version } = context
+  const components = manifest.components
+  const index = buildIndex(manifest)
+  const tokenNames = tokens.tokens.map(token => token.name)
+  const tokenByName = new Map(tokens.tokens.map(token => [token.name, token]))
+  // Every reply says which data it came from, because the agent's project may have installed an
+  // older copy of the components than the manifest this server reads (Dialtone does the same).
+  const stamp = `\n\n(division-ds ${version}; data: ${components.length} components, ${tokenNames.length} tokens. It describes the current release; a project that installed the components earlier may differ.)`
+
+  function findComponent(name) {
+    const wanted = String(name ?? '').trim().toLowerCase()
+    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) {
+    const guess = closest(String(name), components.map(c => c.name))
+    throw new ToolError(`No component "${name}".${guess ? ` Did you mean ${guess}?` : ''} list_components gives every name.`)
+  }
+
+  /** A token's value in one theme, following var() references down to a colour. */
+  function tokenValue(name, theme, seen = new Set()) {
+    if (seen.has(name)) throw new ToolError(`Token ${name} refers to itself.`)
+    seen.add(name)
+    const token = tokenByName.get(name)
+    if (!token) {
+      const guess = closest(name, tokenNames)
+      throw new ToolError(`No token ${name}.${guess ? ` Did you mean ${guess}?` : ''} get_tokens lists them.`)
+    }
+    const value = typeof token.value === 'object' ? token.value[theme] : token.value
+    const ref = /^var\((--[a-z0-9-]+)\)$/.exec(value)
+    return ref ? tokenValue(ref[1], theme, seen) : value
+  }
+
+  const colour = (input, theme) => (String(input).startsWith('--') ? tokenValue(String(input), theme) : String(input))
+
+  const tools = [
+    {
+      name: 'list_components',
+      description: 'Every Division DS component with its tier and one line on when to use it. Start here to pick a component; then call get_component for its props and examples.',
+      inputSchema: {
+        type: 'object',
+        properties: { tier: { type: 'string', enum: TIERS, description: 'Only this tier.' } },
+        additionalProperties: false,
+      },
+      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 => {
+            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')
+      },
+    },
+    {
+      name: 'get_component',
+      description: 'One component: import path, props with types and defaults, keyboard behaviour, do and don\'t, and working examples. Read it before writing the component, so props and values are real.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'Component name or slug, e.g. "Button" or "icon-button".' },
+          section: { type: 'string', enum: ['all', 'props'], description: '"props" returns only the import and the prop table. Default "all".' },
+        },
+        required: ['name'],
+        additionalProperties: false,
+      },
+      run({ name, section = 'all' }) {
+        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\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).
+        // Without it, fall back to the same facts from the manifest.
+        if (page) return page
+        const list = (title, items) => (items?.length ? `\n\n## ${title}\n\n${items.map(item => `- ${item}`).join('\n')}` : '')
+        const keyboard = (c.keyboard ?? []).map(k => `${k.keys.join(' + ')}: ${k.does}`)
+        const examples = (c.examples ?? []).map(e => `### ${e.caption}\n\n\`\`\`tsx\n${e.source}\n\`\`\``).join('\n\n')
+        return head + list('Keyboard', keyboard) + list('Do', c.dos) + list('Don\'t', c.donts) + (examples ? `\n\n## Examples\n\n${examples}` : '')
+      },
+    },
+    {
+      name: 'search',
+      description: 'Find components and tokens by what they are for, e.g. "confirm delete", "page background", "loading". Returns exact names to pass to get_component or to use as var(--name).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string' },
+          limit: { type: 'integer', minimum: 1, maximum: 50, description: 'Default 10.' },
+        },
+        required: ['query'],
+        additionalProperties: false,
+      },
+      run({ query, limit = 10 }) {
+        const terms = words(query)
+        if (terms.length === 0) throw new ToolError('query has no words to search for.')
+        // `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)
+          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 = [
+          // 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 ?? '') })),
+        ]
+          .filter(hit => hit.score > 0)
+          .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+          .slice(0, limit)
+        if (hits.length === 0) return `Nothing matches "${query}". Try a broader word, or list_components / get_tokens.`
+        return hits.map(hit => `- ${hit.name} (${hit.kind}): ${hit.line}`).join('\n')
+      },
+    },
+    {
+      name: 'get_tokens',
+      description: 'Design tokens with their values (light and dark for themed colours) and when to use each. Screens use semantic and component tokens only, as var(--name) inside a Tailwind arbitrary value: text-[var(--color-text-primary)].',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          layer: { type: 'string', enum: LAYERS, description: 'Only this layer. Default: every layer except primitive.' },
+          query: { type: 'string', description: 'Only tokens whose name or use contains this text.' },
+        },
+        additionalProperties: false,
+      },
+      run({ layer, query } = {}) {
+        if (layer !== undefined && !LAYERS.includes(layer)) throw new ToolError(`layer is one of ${LAYERS.join(', ')}.`)
+        const needle = query?.toLowerCase()
+        const rows = tokens.tokens
+          .filter(t => (layer ? t.layer === layer : t.layer !== 'primitive'))
+          .filter(t => !needle || `${t.name} ${t.use ?? ''}`.toLowerCase().includes(needle))
+        if (rows.length === 0) return 'No tokens match.'
+        const value = v => (typeof v === 'object' ? `dark ${v.dark}, light ${v.light}` : v)
+        return `${tokens.rule}\n\n${rows.map(t => `- ${t.name} (${t.layer}) = ${value(t.value)}${t.use ? `. ${t.use}` : ''}`).join('\n')}`
+      },
+    },
+    {
+      name: 'validate_code',
+      description: 'Checks code you wrote with Division DS components, before you say it is done: raw colours, Tailwind palette classes, token names that do not exist, two buttons with no gap, unknown props, prop values outside their union, "AI" in a button label and "answer"/"please"/"!" in assistant component labels. Props are checked only on elements imported from Division DS paths. Each finding says what to write instead. Same gates as `npx division-ds check`.',
+      inputSchema: {
+        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: 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|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.`
+        }
+        return `${findings.length} finding(s) in ${filename}. Fix each, then validate again.\n\n${findings.map(f => `- [${f.gate}] line ${f.line}: ${f.found}\n  Fix: ${f.fix}`).join('\n')}`
+      },
+    },
+    {
+      name: 'check_contrast',
+      description: 'The WCAG 2.2 AA contrast of a foreground on a background, in both themes. Each colour is a token name (--color-text-secondary) or a colour (#a1a1aa, rgb()). Translucent colours are composited over --color-surface-base. Use it before pairing two tokens the system does not already pair.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          foreground: { type: 'string' },
+          background: { type: 'string' },
+          use: { type: 'string', enum: ['normal', 'large', 'ui'], description: 'normal text (4.5:1), large text (3:1: 24px, or 18.66px bold), or a control boundary / graphic (3:1). Default normal.' },
+        },
+        required: ['foreground', 'background'],
+        additionalProperties: false,
+      },
+      run({ foreground, background, use = 'normal' }) {
+        const min = MINIMUMS[use]
+        if (min === undefined) throw new ToolError('use is one of normal, large, ui.')
+        const lines = ['dark', 'light'].map(theme => {
+          const fg = colour(foreground, theme)
+          const bg = colour(background, theme)
+          let ratio
+          try {
+            ratio = contrastRatio(fg, bg, tokenValue('--color-surface-base', theme))
+          } catch (error) {
+            throw new ToolError(error.message)
+          }
+          return `- ${theme}: ${ratio.toFixed(2)}:1 ${ratio >= min ? 'PASS' : 'FAIL'} (${fg} on ${bg})`
+        })
+        const failed = lines.some(line => line.includes('FAIL'))
+        return `${foreground} on ${background}, ${use} (needs ${min}:1):\n${lines.join('\n')}${failed ? '\n\nPick another pair: search for a text or border token meant for this surface.' : ''}`
+      },
+    },
+    {
+      name: 'get_add_command',
+      description: 'The shadcn command that installs components into a project, with their dependencies. Use when the project does not have the components yet.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          components: { type: 'array', items: { type: 'string' }, description: 'Names or slugs. Empty or "all" gives the command for every component.' },
+        },
+        additionalProperties: false,
+      },
+      run({ components: wanted = [] } = {}) {
+        if (wanted.length === 0 || (wanted.length === 1 && wanted[0] === 'all')) {
+          return `npx shadcn@latest add ${REGISTRY_BASE}/division-ds-all.json\n\nIt installs under src/division-ds/. Then mount one <Toaster> and one <TooltipProvider> at the root of the app.`
+        }
+        const urls = wanted.map(name => `${REGISTRY_BASE}/${(findComponent(name) ?? unknownComponent(name)).slug}.json`)
+        return `npx shadcn@latest add ${urls.join(' ')}\n\nIt installs under src/division-ds/, with the components these depend on.`
+      },
+    },
+    {
+      name: 'get_review_checklist',
+      description: 'The checklist to run over a screen before saying it is done: states, headings, focus, forms, 320px, both themes, motion. validate_code covers the code; this covers behaviour.',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      run() {
+        const checklist = context.readChecklist?.()
+        if (!checklist) throw new ToolError('The review checklist is not in this package. Read it at https://github.com/Victor-Ilioiu/division-ds/blob/main/skills/division-ds/commands/review.md')
+        return checklist
+      },
+    },
+  ]
+
+  return tools.map(tool => ({ ...tool, run: args => tool.run(args ?? {}) + stamp }))
+}
+
+/** A mistake in the agent's arguments: reported to it as a tool error it can act on, not as a
+ *  protocol failure. */
+export class ToolError extends Error {}

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 ?? []) {
@@ -218,7 +219,7 @@ function literalValues(initializer) {
   return collect(initializer.expression)
 }
 
-function scriptKind(path) {
+export function scriptKind(path) {
   if (/\.tsx$/.test(path)) return ts.ScriptKind.TSX
   if (/\.jsx$/.test(path)) return ts.ScriptKind.JSX
   if (/\.[cm]?js$/.test(path)) return ts.ScriptKind.JSX

package/scripts/lib/rules-installer.mjs

@@ -12,8 +12,8 @@
 //   agents  AGENTS.md                       Codex, Claude Code (via AGENTS.md), Copilot, Jules, ...
 //   cursor  .cursor/rules/division-ds.mdc   Cursor project rules; the whole file is ours
 //   gemini  GEMINI.md                       Gemini CLI
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
 
 export const START = '<!-- division-ds:start -->'
 export const END = '<!-- division-ds:end -->'
@@ -102,14 +102,52 @@ export function planRules({ targetDir, rules, only = TARGETS, remove = false })
   })
 }
 
-/** Writes a plan to disk. */
-export function applyPlan(plan) {
+// The skill installer (`division-ds skill`): the generated skills/division-ds/ folder, copied whole
+// into the folders agents scan for skills. Checked 2026-10-26 against each agent's docs:
+//   agents  .agents/skills/division-ds/   Codex (repo scope), Cursor (also reads .claude/skills)
+//   claude  .claude/skills/division-ds/   Claude Code project skills
+// The folder is ours whole, like the .mdc: a file in it that the skill no longer ships is deleted.
+export const SKILL_TARGETS = ['agents', 'claude']
+const SKILL_DIRS = { agents: '.agents/skills/division-ds', claude: '.claude/skills/division-ds' }
+
+const filesUnder = dir =>
+  !existsSync(dir)
+    ? []
+    : readdirSync(dir, { recursive: true }).map(String).filter(name => statSync(join(dir, name)).isFile()).map(name => name.split('\\').join('/')).sort()
+
+/** Every file change to install (or `remove`) the skill in `sourceDir` into each target, in the
+ *  same shape as planRules: `[{ target, path, action, before, after }]`. */
+export function planSkill({ targetDir, sourceDir, only = SKILL_TARGETS, remove = false }) {
+  const source = filesUnder(sourceDir)
+  return only.flatMap(target => {
+    const dir = join(targetDir, SKILL_DIRS[target])
+    const names = [...new Set([...source, ...filesUnder(dir)])].sort()
+    return names.map(name => {
+      const path = join(dir, name)
+      const before = read(path)
+      const after = remove || !source.includes(name) ? null : readFileSync(join(sourceDir, name), 'utf8')
+      let action
+      if (before === null) action = after === null ? 'absent' : 'create'
+      else if (after === null) action = 'delete'
+      else action = after === before ? 'unchanged' : 'update'
+      return { target, path, action, before, after }
+    })
+  })
+}
+
+/** Writes a plan to disk. A deletion also removes the folders it left empty, up to `stopAt`. */
+export function applyPlan(plan, stopAt) {
   for (const change of plan) {
     if (change.action === 'create' || change.action === 'update') {
       mkdirSync(dirname(change.path), { recursive: true })
       writeFileSync(change.path, change.after)
     } else if (change.action === 'delete') {
       rmSync(change.path)
+      if (!stopAt) continue
+      for (let dir = dirname(change.path); relative(stopAt, dir) && !relative(stopAt, dir).startsWith('..'); dir = dirname(dir)) {
+        if (readdirSync(dir).length > 0) break
+        rmdirSync(dir)
+      }
     }
   }
 }