division-ds 0.1.1 → 0.2.0

package/scripts/division-ds.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 // division-ds: the system's gates and rules, for a project that USES the components.
 //
-//   division-ds check [files, dirs or globs...]   token discipline, touching buttons, props
+//   division-ds check [files, dirs or globs...]   token discipline, touching buttons, props, AI copy
 //   division-ds rules [--target <dir>] ...         install the agent rules into a project
+//   division-ds skill [--target <dir>] ...         install the agent skill into a project
+//   division-ds mcp                                serve the docs, tokens and gates to an agent (MCP)
 //   division-ds help
 //
 // Inside this repository `npm run verify` is the loop. A consumer project has none of that: an
@@ -18,10 +20,11 @@ import { existsSync, globSync, readdirSync, readFileSync, statSync } from 'node:
 import { dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { extractRules } from './lib/agent-docs.mjs'
-import { findViolations as buttonSpacing, formatViolation as formatButtonSpacing } from './lib/button-spacing.mjs'
-import { buildIndex, findPropViolations, formatPropViolation } from './lib/props-validator.mjs'
-import { applyPlan, diff, planRules, TARGETS } from './lib/rules-installer.mjs'
-import { findViolations as tokenDiscipline, formatViolation as formatTokenDiscipline } from './lib/token-discipline.mjs'
+import { checkText } from './lib/check-text.mjs'
+import { createServer } from './lib/mcp-server.mjs'
+import { createTools } from './lib/mcp-tools.mjs'
+import { buildIndex } from './lib/props-validator.mjs'
+import { applyPlan, diff, planRules, planSkill, SKILL_TARGETS, TARGETS } from './lib/rules-installer.mjs'
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
 const DEFAULT_MANIFEST = join(ROOT, 'public/manifest/components.json')
@@ -33,12 +36,16 @@ const HELP = `division-ds: Division DS gates and agent rules for a project that
 Usage:
   division-ds check [paths...] [--manifest <path|url>] [--tokens <path|url>] [--json]
       Checks .tsx, .jsx and .ts files (default: ./src). A path may be a file, a directory or a
-      glob ("src/**/*.tsx"). Runs three gates and exits 1 on any finding:
+      glob ("src/**/*.tsx"). Runs five gates and exits 1 on any finding:
         token-discipline   raw colours, Tailwind palette classes, token names that do not exist
         button-spacing     two Buttons/IconButtons side by side with no gap on their parent
+        host-inline        an element marked data-host-mode="inline" (an MCP Apps inline card)
+                           with over 2 actions, a scroll container, or a menu/popover inside
         props              an unknown prop or an enum value outside the union, on elements
                            imported from Division DS (components/atoms|molecules|organisms, or
                            the package name); a component of your own with the same name is skipped
+        ai-copy            "AI" in a button label; "answer", "please" or "!" in the labels of
+                           the assistant components (ChatThread, PromptInput, ApprovalRequest, ...)
       --manifest  components.json to check props against (default: the one beside this script)
       --tokens    tokens.json for token names (default: tokens.json beside the manifest)
       --json      one JSON object on stdout instead of text
@@ -49,6 +56,17 @@ Usage:
       .cursor/rules/division-ds.mdc. --dry-run prints the changes and writes nothing. --remove
       takes the blocks out and deletes the .mdc (and a file left holding nothing).
 
+  division-ds skill [--target <dir>] [--only agents,claude] [--dry-run] [--remove]
+      Copies the Division DS skill (SKILL.md, topics/, commands/) into .agents/skills/division-ds/
+      (Codex and Cursor read it) and .claude/skills/division-ds/ (Claude Code). The folders are
+      replaced whole on re-run. --dry-run lists the changes and writes nothing; --remove deletes them.
+
+  division-ds mcp [--manifest <path|url>] [--tokens <path|url>]
+      An MCP server on stdio, for Claude Code, Cursor and other agents. Tools: list_components,
+      get_component, search, get_tokens, validate_code (the gates above, on code the agent just
+      wrote), check_contrast, get_add_command, get_review_checklist. Register it once:
+        claude mcp add division-ds -- npx -y division-ds mcp
+
   division-ds help
 `
 
@@ -115,27 +133,7 @@ async function check(options) {
   const findings = []
   for (const file of files) {
     const path = relative(process.cwd(), file).split('\\').join('/')
-    const text = readFileSync(file, 'utf8')
-    for (const v of tokenDiscipline(text, path, tokenNames)) {
-      findings.push({ gate: 'token-discipline', path, line: v.line, rule: v.rule, found: v.found, fix: v.fix, text: formatTokenDiscipline(v) })
-    }
-    if (/\.[jt]sx$/.test(path)) {
-      for (const v of buttonSpacing(text, path)) {
-        findings.push({
-          gate: 'button-spacing',
-          path,
-          line: v.line,
-          column: v.column,
-          rule: 'touching-buttons',
-          found: `<${v.tag}> with ${v.count} button-like children`,
-          fix: 'Wrap the buttons in one parent with a flex/grid class and a gap- utility (flex flex-wrap items-center gap-3), and move any margin from the buttons onto it.',
-          text: formatButtonSpacing({ ...v, file: path }),
-        })
-      }
-    }
-    for (const v of findPropViolations(text, path, index)) {
-      findings.push({ gate: 'props', path, line: v.line, column: v.column, rule: v.rule, found: v.found, fix: v.fix, text: formatPropViolation(v) })
-    }
+    findings.push(...checkText(readFileSync(file, 'utf8'), path, index, tokenNames))
   }
 
   if (options.json) {
@@ -143,7 +141,7 @@ async function check(options) {
     console.log(JSON.stringify({ files: files.length, manifest: manifestSource, findings: out }, null, 2))
   } else if (findings.length > 0) {
     console.error(`\ndivision-ds check FAILED: ${findings.length} finding(s) in ${files.length} file(s).\n`)
-    for (const gate of ['token-discipline', 'button-spacing', 'props']) {
+    for (const gate of ['token-discipline', 'button-spacing', 'host-inline', 'props', 'ai-copy']) {
       const ofGate = findings.filter(finding => finding.gate === gate)
       if (ofGate.length === 0) continue
       console.error(`${gate} (${ofGate.length})`)
@@ -154,35 +152,76 @@ async function check(options) {
     console.error('Each component\'s props, values and examples: /docs/components/<slug>.md. Tokens: public/manifest/tokens.json.')
   } else {
     console.log(`division-ds check passed: ${files.length} file(s), ${index.size} components, ${tokenNames.length} tokens, 0 findings.`)
+    // It reads code, not the running page: say so, or a pass reads as "the screen works" (the
+    // 2026-10-20 outside test shipped three runtime bugs past a clean check).
+    console.log('Checked: colours, tokens, button spacing, inline host cards, props and AI copy. Not checked: how the screen behaves; run the review checklist (commands/review.md) in a browser.')
   }
   process.exit(findings.length > 0 ? 1 : 0)
 }
 
-function rules(options) {
-  const only = options.only ? options.only.split(',').map(target => target.trim()) : TARGETS
-  const unknown = only.filter(target => !TARGETS.includes(target))
-  if (unknown.length) usage(`--only takes ${TARGETS.join(', ')}; not ${unknown.join(', ')}.`)
+async function mcp(options) {
+  const manifestSource = options.manifest ?? DEFAULT_MANIFEST
+  const tokensSource = options.tokens ?? manifestSource.replace(/components\.json$/, 'tokens.json')
+  const [manifest, tokens] = await Promise.all([load(manifestSource), load(tokensSource)])
+  const version = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version
+  const readIfThere = path => (existsSync(path) ? readFileSync(path, 'utf8') : undefined)
+  const tools = createTools({
+    manifest,
+    tokens,
+    version,
+    // Shipped beside the manifests in the npm package (build-cli-package.mjs); a slug comes from
+    // the manifest, never from the agent, so it cannot reach outside the docs folder.
+    readDoc: slug => readIfThere(join(ROOT, 'public/docs/components', `${slug}.md`)),
+    readChecklist: () => readIfThere(join(ROOT, 'skills/division-ds/commands/review.md')),
+  })
+  createServer({ tools, version }).listen(process.stdin, process.stdout)
+  // stdout is the protocol channel: this goes to stderr, where MCP clients put server logs.
+  console.error(`division-ds ${version} MCP server on stdio: ${tools.length} tools, ${manifest.components.length} components.`)
+}
+
+/** --only and --target, checked the same way for `rules` and `skill`. */
+function targetsOf(options, all) {
+  const only = options.only ? options.only.split(',').map(target => target.trim()) : all
+  const unknown = only.filter(target => !all.includes(target))
+  if (unknown.length) usage(`--only takes ${all.join(', ')}; not ${unknown.join(', ')}.`)
   const targetDir = resolve(options.target ?? '.')
   if (!existsSync(targetDir) || !statSync(targetDir).isDirectory()) usage(`--target is not a directory: ${targetDir}`)
-  // This repository's AGENTS.md is the source; a block of its own rules appended to it would be
-  // read twice by every agent here, and regenerated nowhere.
+  // This repository's AGENTS.md and skills/ are the source; a copy of its own rules beside them
+  // would be read twice by every agent here, and regenerated nowhere.
   if (resolve(targetDir) === resolve(ROOT)) usage('--target is Division DS itself. Point it at the project that uses the components.')
+  return { only, targetDir }
+}
+
+function rules(options) {
+  const { only, targetDir } = targetsOf(options, TARGETS)
   const source = readFileSync(join(ROOT, 'AGENTS.md'), 'utf8').replace(/\r\n/g, '\n')
-  const plan = planRules({ targetDir, rules: extractRules(source), only, remove: Boolean(options.remove) })
+  report(planRules({ targetDir, rules: extractRules(source), only, remove: Boolean(options.remove) }), options)
+}
+
+function skill(options) {
+  const { only, targetDir } = targetsOf(options, SKILL_TARGETS)
+  const plan = planSkill({ targetDir, sourceDir: join(ROOT, 'skills/division-ds'), only, remove: Boolean(options.remove) })
+  // A diff of every skill file is pages long; the list of files is the review.
+  report(plan, { ...options, quiet: true }, targetDir)
+}
 
+/** Prints a plan (with a diff per file on --dry-run, unless quiet) and applies it unless --dry-run. */
+function report(plan, options, stopAt) {
   for (const change of plan) {
     const shown = relative(process.cwd(), change.path) || change.path
     console.log(`${options['dry-run'] ? 'would ' : ''}${change.action.padEnd(9)} ${shown}`)
-    if (options['dry-run'] && change.action !== 'unchanged' && change.action !== 'absent') {
+    if (options['dry-run'] && !options.quiet && change.action !== 'unchanged' && change.action !== 'absent') {
       console.log(diff(change.before, change.after).replace(/^/gm, '    '))
     }
   }
-  if (!options['dry-run']) applyPlan(plan)
+  if (!options['dry-run']) applyPlan(plan, stopAt)
 }
 
 const [command, ...rest] = process.argv.slice(2)
 const options = parseArgs(rest)
 if (command === 'check') await check(options)
 else if (command === 'rules') rules(options)
+else if (command === 'skill') skill(options)
+else if (command === 'mcp') await mcp(options)
 else if (command === undefined || command === 'help' || command === '--help' || command === '-h') console.log(HELP)
 else usage(`Unknown command "${command}".`)

package/scripts/lib/agent-docs.mjs

@@ -124,6 +124,7 @@ export function llmsIndex(entries, { rules }) {
     '## Start here',
     '',
     '- [Rules](llms-guidelines.txt): imports, colour, providers, forms. Short. Read it first.',
+    '- [DESIGN.md](DESIGN.md): the system in one file (colour, type, spacing, motion, every component in a line, the rules), for a tool that takes a single design file.',
     '- [Tokens](llms-tokens.txt): every semantic and component token with when to use it.',
     '- [Helpers](docs/helpers.md): the shared functions and types under src/lib (form errors, money, links, theme, streamed text).',
     '- [All components, compact](llms-components.txt): every prop signature in one file.',
@@ -145,7 +146,7 @@ export function ruleHeadlines(rules) {
     .split(/\n\s*\n/)
     .map(block => block.replace(/\s*\n\s*/g, ' ').trim())
     .filter(block => block.startsWith('**'))
-    .map(block => block.match(/^\*\*[^*]+\*\*\s+.*?[.:](?=\s|$)/)?.[0] ?? block)
+    .map(block => block.match(/^\*\*[^*]+\*\*\s+.*?\.(?=\s|$)/)?.[0] ?? block)
 }
 
 /** Every component's contract in one compact file: no examples, no prose beyond the summary. */
@@ -203,6 +204,54 @@ export function tokensBundle(manifest) {
   ].join('\n')
 }
 
+/** DESIGN.md: the whole system in one short file, for a tool that takes a single design file.
+ *  It carries the choosing layer only (semantic colour, spacing, motion, type, one line per
+ *  component, the rule headlines) and links the full pages rather than inlining them. `fonts` is
+ *  `[{ name, stack }]` from the `--font-*` theme variables in src/styles/tailwind.css. */
+export function designFile(entries, manifest, { fonts, rules }) {
+  const value = token => (typeof token.value === 'string' ? token.value : `dark ${token.value.dark}, light ${token.value.light}`)
+  const table = layer => [
+    '| Token | Use | Value |',
+    '|---|---|---|',
+    ...manifest.tokens
+      .filter(token => token.layer === layer)
+      .map(token => `| ${code(token.name)} | ${cell(token.use)} | ${code(value(token))} |`),
+    '',
+  ]
+  const out = [
+    '# Division DS: design',
+    '',
+    `> A React 19, Tailwind 4 and Radix design system: ${entries.length} components, design tokens in three layers, light and dark themes, WCAG 2.2 AA. This file is the system in one page; each component links its full page with props and examples.`,
+    '',
+    'Links are relative to this file. Generated by `npm run agent-docs`.',
+    '',
+    '## Colour',
+    '',
+    manifest.rule,
+    '',
+    'Write a token as a CSS variable: `bg-[var(--color-surface-base)]`. Use only the names below. Component tokens and the full list: [llms-tokens.txt](llms-tokens.txt).',
+    '',
+    ...table('semantic'),
+    '## Type',
+    '',
+    ...fonts.map(font => `- ${code(`font-${font.name}`)}: ${code(font.stack)}`),
+    '',
+    '## Spacing',
+    '',
+    ...table('spacing'),
+    '## Motion',
+    '',
+    ...table('motion'),
+  ]
+  for (const [tier, group] of byTier(entries)) {
+    out.push(`## ${tier[0].toUpperCase()}${tier.slice(1)}`, '')
+    for (const entry of group) out.push(`- [${entry.name}](${entry.docs.replace(/^\//, '')}): ${firstSentence(entry.summary)}`)
+    out.push('')
+  }
+  out.push('## Rules', '', 'In full: [llms-guidelines.txt](llms-guidelines.txt).', '', ...ruleHeadlines(rules).map(line => `- ${line}`), '')
+  return out.join('\n')
+}
+
 /** The shared helpers under src/lib, one section per file: exported types whole, functions as
  *  signatures, each with its doc comment. `helpers` is `[{ from, api }]`. */
 export function helpersPage(helpers) {
@@ -265,6 +314,7 @@ export const SKILL_TOPICS = {
   overlays: { title: 'Overlays', when: 'adding a Dialog, an AlertDialog or a Sheet' },
   feedback: { title: 'Feedback', when: 'a screen reports a result or a wait: a toast, an alert, progress, a spinner' },
   motion: { title: 'Motion', when: 'animating anything yourself' },
+  ai: { title: 'Assistant copy', when: 'wording a chat' },
 }
 
 /**
@@ -397,6 +447,8 @@ const SKILL_COMMANDS = {
       '| `[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. |',
@@ -416,11 +468,12 @@ const SKILL_COMMANDS = {
       '- [ ] **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.',
+      '- [ ] **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',
       '',
@@ -502,6 +555,10 @@ export function skillFiles(split, componentCount) {
       '',
       `> Load when ${command.when}. Generated by \`npm run agent-docs\`; the procedure lives in scripts/lib/agent-docs.mjs.`,
       '',
+      // A project that installed the components has no public/ folder of ours (the 2026-10-20
+      // outside test followed these steps to files that did not exist).
+      `Paths starting \`public/\` are in the Division DS repository. In a project that uses the components, read them online: \`public/llms.txt\` is \`${DOCS_SITE}llms.txt\`, and so on.`,
+      '',
       ...command.body,
       '',
     ].join('\n')

package/scripts/lib/ai-copy.mjs

@@ -0,0 +1,106 @@
+// The AI copy gate: the parts of the "Assistant copy" rule (AGENTS.md, topic `ai`) that a script
+// can check without guessing. Run in a consumer project through `division-ds check` and the MCP
+// `validate_code` (both via check-text.mjs).
+//
+// Where the rules come from: GitLab Pajamas (no "AI" in a call-to-action label: name the action),
+// Cloudscape's generative-AI chat pattern ("response", not "answer"; no exclamation points; no
+// "please") and Intuit's content design guide on writing about AI. The rest of that guidance
+// (who speaks in which person, hedging, naming the model) needs a reader, so it stays prose.
+//
+// Scope is kept narrow on purpose, because a false positive teaches an agent to stop reading the
+// gate:
+// - `ai-in-cta`: the word "AI" (upper case, a whole word) in a button's own label: the text of a
+//   <Button> or <button>, an <IconButton label>, an `aria-label` on either, and the button props
+//   of the assistant components (approveLabel, rejectLabel, jumpLabel). Any button, imported from
+//   Division DS or not: a copy rule is about the words, not the component.
+// - `assistant-copy`: "answer", "please" or "!" in the interface text of the assistant components
+//   (ChatThread, ChatMessage, PromptInput, ApprovalRequest, ToolCall): their label-like string
+//   props only. Message bodies, a ToolCall's input and output and PromptInput's suggestions are
+//   content written by the person or the model, not the interface, and are never read.
+// Only literals are read (a string attribute, JSX text, a ternary of two literals). A variable is
+// not judged, the same as the props gate.
+import ts from 'typescript'
+import { scriptKind } from './props-validator.mjs'
+
+const BUTTONS = new Set(['Button', 'button'])
+/** Each assistant component's interface-text props. Everything else on them is content or data. */
+const ASSISTANT_COPY = {
+  ChatThread: ['label', 'busyLabel', 'jumpLabel'],
+  ChatMessage: ['author', 'timeLabel'],
+  PromptInput: ['label', 'placeholder', 'hint'],
+  ApprovalRequest: ['title', 'approveLabel', 'rejectLabel', 'approvedLabel', 'rejectedLabel'],
+  ToolCall: ['title'],
+}
+const BUTTON_PROPS = { IconButton: ['label', 'aria-label'], Button: ['aria-label'], button: ['aria-label'], ApprovalRequest: ['approveLabel', 'rejectLabel'], ChatThread: ['jumpLabel'] }
+
+const AI_WORD = /\bAI\b/
+const ASSISTANT_WORDS = [
+  { pattern: /\banswer(s|ed|ing)?\b/i, fix: 'Write "response" (or "reply"), not "answer": the assistant responds; it is not always right.' },
+  { pattern: /\bplease\b/i, fix: 'Drop "please": the interface states the action plainly.' },
+  { pattern: /!/, fix: 'Drop the exclamation point: assistant copy stays calm, whatever the result.' },
+]
+const AI_FIX = 'Name the action ("Summarize", "Draft a reply"), not the technology: a call to action never says "AI".'
+
+/** The literal strings an attribute can hold, as nodes; none when it is not a literal. */
+function literals(initializer) {
+  if (!initializer) return []
+  if (ts.isStringLiteral(initializer)) return [initializer]
+  if (!ts.isJsxExpression(initializer) || !initializer.expression) return []
+  const collect = node => {
+    while (ts.isParenthesizedExpression(node)) node = node.expression
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return [node]
+    if (ts.isConditionalExpression(node)) return [...collect(node.whenTrue), ...collect(node.whenFalse)]
+    return []
+  }
+  return collect(initializer.expression)
+}
+
+/** Every AI copy finding in one file: `{ path, line, column, rule, found, fix }`. */
+export function findAiCopyViolations(text, path) {
+  const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind(path))
+  const violations = []
+  const add = (node, rule, found, fix) => {
+    const at = source.getLineAndCharacterOfPosition(node.getStart(source))
+    violations.push({ path, line: at.line + 1, column: at.character + 1, rule, found, fix })
+  }
+  const checkCta = (node, value, where) => {
+    if (AI_WORD.test(value)) add(node, 'ai-in-cta', `${where}: "${value.trim()}"`, AI_FIX)
+  }
+
+  const visit = node => {
+    if (ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) {
+      const tag = node.tagName.getText(source)
+      for (const attribute of node.attributes.properties) {
+        if (!ts.isJsxAttribute(attribute)) continue
+        const prop = attribute.name.getText(source)
+        for (const value of literals(attribute.initializer)) {
+          if (BUTTON_PROPS[tag]?.includes(prop)) checkCta(value, value.text, `<${tag} ${prop}>`)
+          if (ASSISTANT_COPY[tag]?.includes(prop)) {
+            for (const word of ASSISTANT_WORDS) {
+              if (word.pattern.test(value.text)) add(value, 'assistant-copy', `<${tag} ${prop}>: "${value.text}"`, word.fix)
+            }
+          }
+        }
+      }
+    }
+    if (ts.isJsxElement(node) && BUTTONS.has(node.openingElement.tagName.getText(source))) {
+      const tag = node.openingElement.tagName.getText(source)
+      const parts = []
+      for (const child of node.children) {
+        if (ts.isJsxText(child)) parts.push(child.text)
+        else if (ts.isJsxExpression(child) && child.expression && (ts.isStringLiteral(child.expression) || ts.isNoSubstitutionTemplateLiteral(child.expression))) {
+          parts.push(child.expression.text)
+        }
+      }
+      const label = parts.join(' ').replace(/\s+/g, ' ')
+      if (label.trim()) checkCta(node, label, `<${tag}> label`)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(source)
+  return violations.sort((a, b) => a.line - b.line || a.column - b.column)
+}
+
+export function formatAiCopyViolation({ path, line, column, rule, found, fix }) {
+  return `${path}:${line}:${column}  [${rule}] ${found}\n      ${fix}`
+}

package/scripts/lib/button-spacing.mjs

@@ -91,7 +91,7 @@ function scanAttrs(text, start) {
 
 /** Every JSX tag token in `text`, in source order: `{ type: 'open' | 'close' | 'self', name,
  *  attrsText, start }`. `start` is the index of the tag's leading `<`. */
-function tokenizeTags(text) {
+export function tokenizeTags(text) {
   const tokens = []
   let i = 0
   while (i < text.length) {
@@ -306,7 +306,7 @@ function hasWorkingGap(className) {
  * on the stack, otherwise it is ignored -- real TSX is always balanced; this only has to not throw
  * on the odd case this scanner misreads.
  */
-function buildTree(tokens) {
+export function buildTree(tokens) {
   const root = { name: null, attrsText: '', attrs: new Map(), start: -1, children: [] }
   const stack = [root]
   for (const token of tokens) {
@@ -343,7 +343,7 @@ function buildTree(tokens) {
  *  only child element is a button -- the `SheetClose asChild><Button/></SheetClose>` shape that is
  *  exactly what shipped broken. Only one level of unwrapping: an `asChild` wrapper around an
  *  `asChild` wrapper is not chased further. */
-function isButtonLike(node) {
+export function isButtonLike(node) {
   if (BUTTON_TAGS.has(node.name)) return true
   if (node.attrs.get('asChild') === 'true' && node.children.length === 1) {
     return BUTTON_TAGS.has(node.children[0].name)
@@ -351,7 +351,7 @@ function isButtonLike(node) {
   return false
 }
 
-function lineIndex(text) {
+export function lineIndex(text) {
   const offsets = [0]
   for (let i = 0; i < text.length; i++) {
     if (text[i] === '\n') offsets.push(i + 1)
@@ -359,7 +359,7 @@ function lineIndex(text) {
   return offsets
 }
 
-function lineColAt(offsets, index) {
+export function lineColAt(offsets, index) {
   let lo = 0
   let hi = offsets.length - 1
   while (lo < hi) {

package/scripts/lib/check-text.mjs

@@ -0,0 +1,44 @@
+// The five consumer gates over one file's text, as data. `division-ds check` runs it per file
+// on disk; the MCP server's `validate_code` runs it on a snippet an agent passes in. One function,
+// so the two can never disagree about what a finding is.
+import { findAiCopyViolations, formatAiCopyViolation } from './ai-copy.mjs'
+import { findViolations as buttonSpacing, formatViolation as formatButtonSpacing } from './button-spacing.mjs'
+import { findInlineViolations, formatInlineViolation } from './host-inline.mjs'
+import { findPropViolations, formatPropViolation } from './props-validator.mjs'
+import { findViolations as tokenDiscipline, formatViolation as formatTokenDiscipline } from './token-discipline.mjs'
+
+export const BUTTON_SPACING_FIX =
+  'Wrap the buttons in one parent with a flex/grid class and a gap- utility (flex flex-wrap items-center gap-3), and move any margin from the buttons onto it.'
+
+/** Every finding in `text`. `path` decides which gates apply (button spacing and AI copy need JSX) and is
+ *  echoed into each finding. `index` is buildIndex(manifest); `tokenNames` the token names. */
+export function checkText(text, path, index, tokenNames) {
+  const findings = []
+  for (const v of tokenDiscipline(text, path, tokenNames)) {
+    findings.push({ gate: 'token-discipline', path, line: v.line, rule: v.rule, found: v.found, fix: v.fix, text: formatTokenDiscipline(v) })
+  }
+  if (/\.[jt]sx$/.test(path)) {
+    for (const v of buttonSpacing(text, path)) {
+      findings.push({
+        gate: 'button-spacing',
+        path,
+        line: v.line,
+        column: v.column,
+        rule: 'touching-buttons',
+        found: `<${v.tag}> with ${v.count} button-like children`,
+        fix: BUTTON_SPACING_FIX,
+        text: formatButtonSpacing({ ...v, file: path }),
+      })
+    }
+    for (const v of findInlineViolations(text)) {
+      findings.push({ gate: 'host-inline', path, line: v.line, column: v.column, rule: v.rule, found: v.found, fix: v.fix, text: formatInlineViolation(v, path) })
+    }
+    for (const v of findAiCopyViolations(text, path)) {
+      findings.push({ gate: 'ai-copy', path, line: v.line, column: v.column, rule: v.rule, found: v.found, fix: v.fix, text: formatAiCopyViolation(v) })
+    }
+  }
+  for (const v of findPropViolations(text, path, index)) {
+    findings.push({ gate: 'props', path, line: v.line, column: v.column, rule: v.rule, found: v.found, fix: v.fix, text: formatPropViolation(v) })
+  }
+  return findings
+}

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 }
+  })
+}