themelia-ui 1.0.0

package/scripts/consumer/find-component.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/*
+ * Which component to reach for, answered from the packaged index.
+ *
+ * The repository finder and the published docs read the same generated catalogue. This
+ * consumer entry reads `references/components/INDEX.json` beside the installed skill, so it answers from
+ * `node_modules` with no checkout and no network.
+ *
+ *   node node_modules/themelia-ui/scripts/consumer/find-component.mjs "bulk selection"
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+export const INDEX_PATH = resolve(HERE, '..', '..', '.agents/skills/themelia-ui/references/components/INDEX.json')
+
+export function loadIndex(path = INDEX_PATH) {
+  if (!existsSync(path)) throw new Error(`the packaged component index is missing at ${path}`)
+  return JSON.parse(readFileSync(path, 'utf8')).families
+}
+
+const text = (value) => (Array.isArray(value) ? value.join(' ') : String(value ?? ''))
+const normalizedWords = (value) => String(value ?? '')
+  .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+  .toLowerCase()
+  .replace(/[^a-z0-9@]+/g, ' ')
+  .trim()
+  .split(/\s+/)
+  .filter(Boolean)
+
+const stem = (word) => {
+  if (word.length > 4 && word.endsWith('ies')) return `${word.slice(0, -3)}y`
+  for (const suffix of ['ing', 'ed', 'es', 's']) {
+    if (word.length <= suffix.length + 3 || !word.endsWith(suffix)) continue
+    let base = word.slice(0, -suffix.length)
+    if (base.length > 3 && base.at(-1) === base.at(-2)) base = base.slice(0, -1)
+    return base
+  }
+  return word
+}
+
+const meaningfulTerms = (value) => normalizedWords(value)
+  .filter((word) => word.length > 2 && !STOPWORDS.has(word))
+  .map(stem)
+
+const termHits = (queryTerms, corpus) => {
+  const words = normalizedWords(corpus)
+  const stems = new Set(words.map(stem))
+  return queryTerms.filter((term) =>
+    stems.has(term) || words.some((word) => term.length >= 4 && word.startsWith(term)),
+  ).length
+}
+
+/**
+ * Ranked, because the useful answer is usually one family and the useful ordering is by how
+ * directly the query names it.
+ *
+ * An exact public symbol beats a family id, which beats prose. Without the ranking a search
+ * for `Badge` returned every family whose avoidWhen sentence happens to mention a badge.
+ */
+/*
+ * Words that appear in nearly every sentence of guidance.
+ *
+ * Without this, "the a is" matched every family: `the` is four characters short of nothing
+ * and three characters long, so a length cut-off either keeps it or throws away `row`,
+ * `tab` and `nav`. The list is the honest version of the rule.
+ */
+const STOPWORDS = new Set([
+  'the', 'and', 'for', 'not', 'but', 'its', 'with', 'that', 'this', 'from', 'into', 'when',
+  'where', 'which', 'what', 'you', 'your', 'are', 'was', 'has', 'have', 'one', 'two', 'use',
+  'used', 'using', 'than', 'then', 'them', 'they', 'there', 'their', 'each', 'any', 'all',
+])
+
+export function findComponents(families, query, filters = {}) {
+  const needle = query.trim().toLowerCase()
+  const hasFilter = ['layer', 'profile', 'status', 'family', 'peer', 'route', 'symbol']
+    .some((name) => Boolean(filters[name]))
+  if (!needle && !hasFilter) return []
+
+  const scored = []
+  for (const family of families) {
+    if (filters.layer && family.layer !== filters.layer) continue
+    if (filters.profile && family.profile !== filters.profile) continue
+    if (filters.status && family.status !== filters.status) continue
+    if (filters.family && family.family !== filters.family) continue
+    if (filters.peer && !(family.optionalPeers ?? []).includes(filters.peer)) continue
+    if (filters.route && !(family.previews ?? []).some((preview) => preview.route === filters.route)) continue
+
+    const symbols = (family.publicSymbols ?? []).map((s) => String(s).toLowerCase())
+    if (filters.symbol && !symbols.includes(filters.symbol.toLowerCase())) continue
+
+    if (!needle) {
+      scored.push({ family, score: 0 })
+      continue
+    }
+
+    let score = 0
+    const queryTerms = meaningfulTerms(needle)
+    const phrase = normalizedWords(needle).join(' ')
+    const normalizedSymbols = (family.publicSymbols ?? []).map((symbol) => normalizedWords(symbol).join(' '))
+    const normalizedFamily = normalizedWords(family.family).join(' ')
+    const identityItems = [family.family, ...(family.publicSymbols ?? []), ...(family.components ?? [])]
+    const identity = identityItems.map(text).join(' ')
+    const identityHits = termHits(queryTerms, identity)
+    const identityWholeMatch = identityItems.some(
+      (item) => termHits(queryTerms, item) === queryTerms.length,
+    )
+    if (normalizedSymbols.includes(phrase)) score = 100
+    else if (normalizedFamily === phrase) score = 90
+    else if (normalizedSymbols.some((symbol) => symbol.includes(phrase))) score = 75
+    else if (normalizedFamily.includes(phrase)) score = 70
+    else if (queryTerms.length > 1 && identityWholeMatch) score = 65
+    else {
+      const positive = [
+        family.chooseWhen,
+        family.doc,
+        family.components,
+        ...(family.previews ?? []).flatMap((preview) => [preview.page, preview.route]),
+        ...(family.recipes ?? []).flatMap((recipe) => [recipe.id, recipe.title, recipe.page, recipe.route]),
+      ].map(text).join(' ').toLowerCase()
+      if (positive.includes(needle)) score = 40
+      else {
+        /*
+         * By TERM, not by phrase. A person asks for "key value facts"; the guidance says
+         * "label/value facts". A whole-phrase substring finds neither that nor any other
+         * query whose words the author happened to order differently, which made the prose
+         * half of this search almost unreachable.
+         *
+         * Half the terms, so a single common word does not drag in every family.
+         */
+        const terms = queryTerms
+        const hits = termHits(terms, positive)
+        if (terms.length > 0 && hits * 2 >= terms.length) {
+          const chooseHits = termHits(terms, family.chooseWhen)
+          score = 10 + Math.round((20 * hits) / terms.length) + chooseHits * 4 + identityHits * 2
+        }
+      }
+    }
+    if (score > 0) scored.push({ family, score })
+  }
+
+  return scored
+    .sort((a, b) => b.score - a.score || String(a.family.family).localeCompare(String(b.family.family)))
+    .map((entry) => entry.family)
+}
+
+export const FINDER_USAGE = `usage: find-component.mjs [query] [options]
+
+Search, or list a filtered part of, the packaged component catalogue.
+
+Options:
+  --layer=<layer>       primitives, base, layout, features, patterns, admin, foundation
+  --profile=<profile>   general or admin
+  --status=<status>     exact stability status from the catalogue
+  --family=<id>         exact family id, for example base/buttons
+  --symbol=<Name>       exact public export name
+  --peer=<package>      families that require this optional peer
+  --route=</path>       families represented on this live preview route
+  --limit=<N>           return at most N matches (default 8)
+  --json                emit complete machine-readable records
+  --help                show this help
+
+A text query is optional when at least one catalogue filter is present.`
+
+const VALUE_FLAGS = new Set(['layer', 'profile', 'status', 'family', 'symbol', 'peer', 'route', 'limit'])
+const BOOLEAN_FLAGS = new Set(['json', 'help'])
+
+export function parseFinderArgs(args) {
+  const options = {}
+  const query = []
+  for (const arg of args) {
+    if (!arg.startsWith('--')) {
+      query.push(arg)
+      continue
+    }
+    const [rawName, ...rest] = arg.slice(2).split('=')
+    if (BOOLEAN_FLAGS.has(rawName)) {
+      if (rest.length) throw new Error(`--${rawName} does not take a value`)
+      options[rawName] = true
+      continue
+    }
+    if (!VALUE_FLAGS.has(rawName)) throw new Error(`unknown option --${rawName}`)
+    const value = rest.join('=')
+    if (!value) throw new Error(`--${rawName} requires a value written as --${rawName}=...`)
+    options[rawName] = value
+  }
+  const limit = options.limit === undefined ? 8 : Number(options.limit)
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new Error('--limit must be an integer from 1 to 100')
+  }
+  return { query: query.join(' ').trim(), options: { ...options, limit } }
+}
+
+export function runFinderCli(args = process.argv.slice(2), io = console) {
+  let parsed
+  try {
+    parsed = parseFinderArgs(args)
+  } catch (error) {
+    io.error(`FAIL find-component — ${error.message}\n\n${FINDER_USAGE}`)
+    return 1
+  }
+  if (parsed.options.help) {
+    io.log(FINDER_USAGE)
+    return 0
+  }
+  const filters = Object.fromEntries(
+    ['layer', 'profile', 'status', 'family', 'symbol', 'peer', 'route']
+      .filter((name) => parsed.options[name])
+      .map((name) => [name, parsed.options[name]]),
+  )
+  if (!parsed.query && Object.keys(filters).length === 0) {
+    io.error(FINDER_USAGE)
+    return 1
+  }
+  const matches = findComponents(loadIndex(), parsed.query, filters).slice(0, parsed.options.limit)
+  if (matches.length === 0) {
+    io.error(
+      `no component matches ${JSON.stringify(parsed.query)}.\n` +
+        '  Try a shorter term, a public symbol, or fewer filters.\n' +
+        '  The full index is at .agents/skills/themelia-ui/references/components/INDEX.json.',
+    )
+    return 1
+  }
+  if (parsed.options.json) io.log(JSON.stringify(matches, null, 2))
+  else io.log(matches.map(renderMatch).join('\n\n'))
+  return 0
+}
+
+export function renderMatch(family) {
+  const lines = [
+    `${family.family}  (${family.layer} · ${family.profile}${family.status ? ` · ${family.status}` : ''})`,
+    `  import   ${family.publicImport}`,
+  ]
+  if (family.cssImport ?? family.css) lines.push(`  css      ${family.cssImport ?? family.css}`)
+  if (family.apiDoc) lines.push(`  api      node_modules/themelia-ui/docs/generated/${family.apiDoc}`)
+  if (family.chooseWhen) lines.push(`  choose   ${text(family.chooseWhen)}`)
+  if (family.avoidWhen) lines.push(`  avoid    ${text(family.avoidWhen)}`)
+  if (family.alternatives?.length) lines.push(`  instead  ${text(family.alternatives)}`)
+  return lines.join('\n')
+}
+
+/*
+ * Was this file run, or imported?
+ *
+ * The usual idiom compares `process.argv[1]` with `fileURLToPath(import.meta.url)`, and the
+ * two disagree the moment the path crosses a symlink: on macOS `/tmp` IS a symlink, and
+ * pnpm's store links every package. The script then exits 0 having done nothing, which is
+ * the worst way to fail — it looks like it worked.
+ */
+function runFromCommandLine(moduleUrl) {
+  if (!process.argv[1]) return false
+  const real = (path) => {
+    try {
+      return realpathSync(path)
+    } catch {
+      return resolve(path)
+    }
+  }
+  return real(process.argv[1]) === real(fileURLToPath(moduleUrl))
+}
+
+const invokedDirectly = runFromCommandLine(import.meta.url)
+if (invokedDirectly) {
+  process.exitCode = runFinderCli()
+}

package/scripts/consumer/install-skill.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/*
+ * Copy this package's agent skill into a consuming project.
+ *
+ * The skill says which component to reach for, the exact subpath to import it from, and
+ * what not to do — and it shipped nowhere. `files` was `["dist"]`, so a consumer got 1,867
+ * build artefacts and no guidance, while the repository's own agents read a copy under
+ * `.claude/` that npm never saw.
+ *
+ * Offline by construction: the source is resolved from `import.meta.url`, so this works
+ * from `node_modules` with no network and no registry lookup.
+ *
+ *   node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=.
+ */
+import {
+  cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync,
+  statSync,
+} from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+/** scripts/consumer/ → the package root. */
+export const PACKAGE_ROOT = resolve(HERE, '..', '..')
+export const SOURCE = join(PACKAGE_ROOT, '.agents/skills/themelia-ui')
+
+/**
+ * The line that says a destination is ours to replace.
+ *
+ * Without it an install would overwrite a skill someone had written by hand, in a directory
+ * whose whole purpose is to hold hand-written instructions. Matching on the marker rather
+ * than on the directory name means a project can keep its own skill of the same name.
+ */
+export const GENERATED_MARKER = '<!-- GENERATED by themelia-ui/scripts/gen-agent-skill.mjs -->'
+
+export const TARGET_DIRECTORIES = {
+  agents: '.agents/skills/themelia-ui',
+  claude: '.claude/skills/themelia-ui',
+}
+
+/** Whether a destination may be replaced: absent, or carrying our marker. */
+export function mayOverwrite(destination) {
+  const skill = join(destination, 'SKILL.md')
+  if (!existsSync(skill)) return true
+  return readFileSync(skill, 'utf8').includes(GENERATED_MARKER)
+}
+
+export function installSkill({ project = '.', target = 'both', source = SOURCE } = {}) {
+  const targets = target === 'both' ? ['agents', 'claude'] : [target]
+  if (targets.some((name) => !(name in TARGET_DIRECTORIES))) {
+    throw new Error(`unknown --target=${target}; expected agents, claude or both`)
+  }
+  if (!existsSync(source)) throw new Error(`the packaged skill is missing at ${source}`)
+
+  const nonce = `${process.pid}-${Date.now()}`
+  const destinations = targets.map((name, index) => {
+    const destination = resolve(project, TARGET_DIRECTORIES[name])
+    return {
+      name,
+      destination,
+      stage: `${destination}.installing-${nonce}-${index}`,
+      backup: `${destination}.backup-${nonce}-${index}`,
+      committed: false,
+      hadExisting: existsSync(destination),
+    }
+  })
+
+  /* Preflight every target before writing any of them. */
+  for (const { destination } of destinations) {
+    if (resolve(source) === destination) {
+      throw new Error(`source and destination are the same directory: ${destination}`)
+    }
+    if (!mayOverwrite(destination)) {
+      throw new Error(
+        `${relative(process.cwd(), destination)} holds a SKILL.md this package did not write.\n` +
+          '  Move it aside, or install only the other target with --target=agents|claude.',
+      )
+    }
+  }
+
+  try {
+    for (const item of destinations) {
+      mkdirSync(dirname(item.destination), { recursive: true })
+      cpSync(source, item.stage, { recursive: true })
+    }
+    for (const item of destinations) {
+      if (item.hadExisting) renameSync(item.destination, item.backup)
+      renameSync(item.stage, item.destination)
+      item.committed = true
+    }
+    for (const item of destinations) rmSync(item.backup, { recursive: true, force: true })
+    return destinations.map(({ destination }) => destination)
+  } catch (error) {
+    for (const item of [...destinations].reverse()) {
+      rmSync(item.stage, { recursive: true, force: true })
+      if (item.committed) rmSync(item.destination, { recursive: true, force: true })
+      if (existsSync(item.backup)) renameSync(item.backup, item.destination)
+    }
+    throw error
+  }
+}
+
+/** Every file under a directory, relative and sorted — for tests and for the summary. */
+export function listFiles(root) {
+  const out = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry)
+      if (statSync(full).isDirectory()) walk(full)
+      else out.push(relative(root, full))
+    }
+  }
+  if (existsSync(root)) walk(root)
+  return out.sort()
+}
+
+/*
+ * Was this file run, or imported?
+ *
+ * The usual idiom compares `process.argv[1]` with `fileURLToPath(import.meta.url)`, and the
+ * two disagree the moment the path crosses a symlink: on macOS `/tmp` IS a symlink, and
+ * pnpm's store links every package. The script then exits 0 having done nothing, which is
+ * the worst way to fail — it looks like it worked.
+ */
+function runFromCommandLine(moduleUrl) {
+  if (!process.argv[1]) return false
+  const real = (path) => {
+    try {
+      return realpathSync(path)
+    } catch {
+      return resolve(path)
+    }
+  }
+  return real(process.argv[1]) === real(fileURLToPath(moduleUrl))
+}
+
+const invokedDirectly = runFromCommandLine(import.meta.url)
+if (invokedDirectly) {
+  const USAGE = `usage: install-skill.mjs [--project=<directory>] [--target=agents|claude|both]
+
+Copies the packaged themelia-ui consumer skill into a project. Existing generated
+copies are replaced atomically; a same-named hand-written skill is never overwritten.`
+  try {
+    const options = { project: '.', target: 'both' }
+    for (const argument of process.argv.slice(2)) {
+      if (argument === '--help') {
+        console.log(USAGE)
+        process.exit(0)
+      }
+      const match = argument.match(/^--(project|target)=(.+)$/)
+      if (!match) throw new Error(`unknown argument ${argument}\n\n${USAGE}`)
+      options[match[1]] = match[2]
+    }
+    const installed = installSkill(options)
+    for (const destination of installed) {
+      console.log(`installed ${listFiles(destination).length} file(s) into ${relative(process.cwd(), destination) || '.'}`)
+    }
+  } catch (error) {
+    console.error(`FAIL install-skill — ${error.message}`)
+    process.exit(1)
+  }
+}

package/src/styles/FACTORS.md

@@ -0,0 +1,65 @@
+# The scale chain
+
+Four factors for the whole kit. There is no per-component factor.
+
+```
+--scale            everything
+  ├── --space-scale     gaps and padding   (defaults to --scale)
+  ├── --density-scale   heights and rows   (defaults to --scale)
+  └── --text-scale      all typography     (defaults to --scale)
+```
+
+`--scale` is the one-knob default: geometry, spacing, icons, prose, and control labels move
+together. `UIProvider`'s `typography.scale` overrides `--text-scale` at one scope when type
+must move independently. It applies to every type role, including control labels, so the
+same `sm` role cannot render at two sizes merely because one instance sits in a button.
+
+```css
+/* everything denser */
+:root { --scale: 0.875; }
+
+/* tighter spacing, same control heights */
+:root { --space-scale: 0.875; }
+
+/* larger type, control geometry untouched */
+:root { --text-scale: 1.125; }
+```
+
+Density presets set `--space-scale` and `--density-scale` per scope, so a region can be
+denser than the page without shrinking readable type:
+
+```html
+<div data-density="compact">…</div>
+```
+
+Use `UIProvider config={{ scale: 0.875 }}` only when the entire interface—including its
+type ramp—should move together.
+
+## Why there is no `--button-scale`
+
+There was, and 44 more like it. Every family declared its own factor defaulting to the
+global one, so a consumer could scale one family alone. It read well and cost 215 tokens —
+close to half the theming layer — because carrying the multiplication meant minting a name
+for every measurement in every family:
+
+```css
+/* before: one name per measurement, per family */
+--accordion-scale: var(--scale);
+--accordion-media-gap: calc(0.75rem * var(--accordion-scale));
+
+/* after: the step already carries the factor */
+gap: var(--space-lg);
+```
+
+`--space-lg` **is** `calc(0.75rem * var(--space-scale))`. The family version was the same
+number wearing a different hat: of the 385 references that carried a family factor, 217
+turned out to be a spacing step that already had a name.
+
+The ability to scale one family alone is genuinely gone. It was traded for a theming layer
+a person can read, which is the thing a consumer actually reaches for first.
+
+`scripts/verify-factors.mjs` fails if a per-family factor reappears, if a declaration
+multiplies two factors directly, or if an ordinary CSS property multiplies an
+already-scaled token by another factor. At scale 0.5 a squared factor is 0.25, which reads
+as a rendering bug rather than a maths one. Separate additive terms remain valid because
+each term carries its factor exactly once.

package/src/styles/SCOPES.md

@@ -0,0 +1,37 @@
+# Why derived tokens are not declared on `:root`
+
+A custom property's `var()` references are substituted **where the property is declared**.
+So a derived token declared once at `:root`:
+
+```css
+:root {
+  --action: calc(var(--height-action) * var(--density-scale));
+  --button-default-bg: var(--primary);
+}
+```
+
+…resolves `--density-scale` and `--primary` at `:root`, and the RESULT is what inherits.
+Setting `--density-scale: 0.875` or `--primary: red` on a nested element changes nothing —
+`--action` is already `calc(2.25rem * 1)` and `--button-default-bg` is already the root
+colour. Scoped density and scoped theming are impossible.
+
+Declaring them at every **scope boundary** instead makes each boundary re-derive from its
+own inputs, and descendants inherit that scope's values:
+
+```css
+:root,
+[data-ui-scope],
+[data-density],
+[data-theme],
+.light,
+.dark {
+  --action: calc(var(--height-action) * var(--density-scale));
+}
+```
+
+`<UIProvider>` renders `[data-ui-scope]`, so any provider — nested or not — re-derives the
+whole system from whatever it overrides. `[data-density]` and `[data-theme]` do the same
+for the CSS-only path, where a consumer sets the attribute without a provider.
+
+This is not `*`: re-deriving on every element in the document would be wasteful. Only
+elements that can CHANGE an input need to recompute.

package/src/styles/TOKENS.md

@@ -0,0 +1,143 @@
+# The token contract
+
+Only the first two layers are the theme. The third is where components keep their own
+measurements, and it is not a place a theme author needs to go.
+
+<!-- token-report:start -->
+```text
+themes/default.css      55 tokens   what a rebrand touches
+tokens/*.css           111 tokens   ramps and ladders behind the theme
+global contract        166 tokens   themes plus token ramps
+styles/theming/*.css   170 tokens   cross-cutting wiring (14 files)
+*.module.css           278 tokens   component-owned and runtime transport
+component total        429 tokens
+```
+
+The component total contains 102 responsive
+transport variables written by `Stack`, `Grid`, `GridCell`, `AdaptiveGrid`, `Split`,
+`Bleed`, and `AspectRatio`. They are
+runtime prop values carried into breakpoint fallback chains, not theme extension points.
+The remaining classifications are 196 earns its name, 96 extension point, 5 keyframe holder, 30 runtime hook.
+<!-- token-report:end -->
+
+**Quote the global contract count above, not the component total.** They answer
+different questions and only the first is a theme surface: a theme author sets the
+contract and every component follows, because a component token is either derived from it
+or a measurement a rebrand has no opinion about.
+
+**A component's variables live with the component.** `theming/tooltip.css` declaring three
+arrow measurements read by exactly one stylesheet was never theming; it was tooltip's CSS
+filed under the wrong heading. Forty such files moved to their modules, keeping the same
+scope-selector block so the cascade is unchanged. What a file in `theming/` has to earn now
+is being read by *many* components.
+
+`scripts/verify-token-budget.mjs` holds these numbers, and looks in both trees — a check
+scoped to one directory stops covering a token the moment it moves to where it belongs. It
+fails on a dead token, a PASS-THROUGH (a second name for another token, doing no arithmetic
+and never re-pointed — see below), an override nothing reads, a runtime token no stylesheet
+declares, a colour literal below `tokens/`, and a length off the 2px grid.
+
+## What earns a component token
+
+One of three things, and a name that does none of them is noise:
+
+* **arithmetic** — `--heatmap-pitch: calc(var(--heatmap-cell) + var(--space-2xs))`
+* **a variant or scope re-points it** — `--badge-hue`, declared once per tone
+* **JS writes it** — `style={{ "--micro-bar": "62%" }}`, the interface a chart arrives through
+
+`--sidebar-p: var(--space-md)` does none. Read six times, it is still one name standing in
+front of one step, and all six readers can say `--space-md`. Eighty-two of those were
+removed in one pass with no pixel changing; `verify:token-budget` now fails on them.
+
+Two exemptions, both load-bearing. A **family with a member re-declared in another file**
+is an extension point — inlining `--text-role-main` breaks the auth panel that re-points it
+for its own subtree. And a token **named in TSX or a test** has a reader a `var()` scan
+cannot see.
+
+## What a theme owns
+
+`themes/default.css` is generated from `scripts/theme-manifest.mjs` — edit the manifest,
+run `npm run tokens:theme`. It is shadcn-shaped on purpose, so a shadcn theme drops in.
+
+**Colour** resolves through the ramp in `tokens/palette.css`; there are no literals in the
+theme file, so a rebrand moves the ramp rather than forty separate values.
+
+```css
+--background --foreground --card --popover --primary --secondary
+--muted --accent --destructive --border --input --ring
+--chart-1…5 --sidebar-*
+```
+
+**Edge** — the three properties that describe every border in the kit, kept together
+because they are one decision:
+
+```css
+--border: var(--neutral-200);   /* colour */
+--border-width: 1px;            /* weight */
+--radius: 0.625rem;             /* corner  */
+```
+
+**Shape** derives from `--radius`, and the ROLES are what components ask for. A component
+never picks a step off the scale; it names what it is, so a retheme moves every surface
+together:
+
+| role | used by |
+|---|---|
+| `--radius-surface` | cards, dialogs, popovers, menus |
+| `--radius-control` | buttons, inputs, tabs, badges |
+| `--radius-inner` | menu rows, chips, calendar cells — nested inside a control |
+| `--radius-pill` | switches, avatars, pills |
+
+## What the ramps own
+
+`tokens/` holds the ladders the theme resolves against: the colour ramp, the type scale
+(`--text-xs` … `--text-2xl` and its paired line heights), the spacing scale, the content
+widths, and the raw tunables — `--height-action`, `--control-x`, `--row-x/y`,
+`--surface-x/y`, `--icon`, `--avatar`, `--scale`.
+
+**Spacing sits on a 2px grid.** Every length under `4rem` is a multiple of `0.125rem`.
+This is not decoration: `--menu-row-px: calc(0.6875rem * var(--space-scale))` was 11px,
+next to a 12px row inset, and nobody reviewing one menu ever saw the mismatch.
+
+**Type is exempt from the grid**, because a type ramp is geometric — `0.75`, `0.8125`,
+`0.875`, `1`, `1.125` — and lands off a 2px grid by construction. `0.8125rem` is the
+`--text-pxs` step, not a stray 13px.
+
+## What components own
+
+**A component reads the theme directly.** `background-color: var(--foreground)` in the
+module, not `--tooltip-bg: var(--foreground)` somewhere else and `var(--tooltip-bg)` here.
+The second form is a name with one reader, and 376 of them is not a design system, it is a
+layer of indirection nobody asked for. Tooltip declared twelve tokens; it declares three.
+
+Where a component does need to adjust a theme value, it does the arithmetic in its own
+rule — `calc(var(--space-lg) * 2)` — rather than minting a name for the result.
+
+A token earns a NAME only when one of these is true:
+
+| | |
+|---|---|
+| **read by two or more rules** | naming it is what keeps them equal |
+| **an extension point** | another file re-declares it, so inlining kills the override |
+| **read from TS/TSX** | a runtime hook; the indirection is the API |
+| **an `--animate-*`** | CSS Modules scope keyframe names; inlined, the animation dies |
+| **a bare length a module may not hold** | `verify-composition` forbids raw px in a module |
+
+Everything else belongs in the rule that uses it. It may still not hold a colour literal —
+colour always resolves through the palette.
+
+And a token that earns a name lives with whatever owns it: in the component's own module if
+one component reads it, in `styles/theming/` only if many do.
+
+**An extension point is anything another file re-declares**, and that includes a one-line
+rule: `.columns4 { --choice-card-min: 9rem; }` is how a variant re-points a token, and
+inlining the default silently kills all three column variants. `verify-token-budget` reads
+declarations after a `{` or `;`, not only at a line start, precisely because that is the
+form these take.
+
+There is no per-component scale factor. See [FACTORS.md](./FACTORS.md) for what replaced
+the 45 of them.
+
+See [FACTORS.md](./FACTORS.md) for how the four global factors compose without family
+factors, and [SCOPES.md](./SCOPES.md) for why derived values are declared at every scope
+boundary rather than once at `:root`.