division-ds 0.1.2 → 0.2.0

package/scripts/lib/mcp-server.mjs

@@ -0,0 +1,115 @@
+// 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 and fix every finding, then go through get_review_checklist.`
+
+/** 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,241 @@
+// 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 { 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)
+  }
+
+  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 => `- ${c.name} (${c.tier}): ${c.useWhen}${c.notFor ? ` Not for: ${c.notFor}` : ''}`).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\nPaths are from the Division DS repository root; installed with shadcn they start src/division-ds/.\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.')
+        const score = (title, body) => {
+          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 hits = [
+          ...components.map(c => ({ kind: 'component', name: c.name, line: c.useWhen, score: score(c.name, `${c.summary} ${c.useWhen}`) })),
+          // 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. 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.')
+        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

@@ -218,7 +218,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)
+      }
     }
   }
 }

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

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

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