@talelk/newui-tailwind 0.0.0-stage → 1.0.2

package/src/generated.test.ts

@@ -0,0 +1,161 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import {
+  colors,
+  duration,
+  easing,
+  fontSize,
+  radius,
+  screens,
+  semanticColors,
+  shadowRoles,
+  shadows,
+  spacing,
+  tracking,
+  zIndex,
+} from '@talelk/newui-tokens'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Generator parity: `@talelk/newui-tokens` data ↔ generated `@theme`.
+ *
+ * `scripts/build-css.ts` derives `theme.css` from the token data, so the
+ * expected vocabulary is derived here the same way instead of hand-listed.
+ * A renamed generator branch or a dropped token family then fails here
+ * instead of silently compiling a component's utility to nothing.
+ *
+ * This is the data→CSS direction only. The reverse direction (every token a
+ * component *references* exists) is `tokens.test.ts`; nothing is asserted
+ * twice.
+ */
+const themeCss = readFileSync(
+  path.join(process.cwd(), 'packages/tailwind/src/generated/theme.css'),
+  'utf8',
+)
+
+// Every custom property theme.css declares (`--spacing-0.5` needs the dot).
+const defined = new Set<string>(
+  [...themeCss.matchAll(/^\s*(--[a-z0-9.-]+):/gm)].flatMap((m) =>
+    m[1] ? [m[1]] : [],
+  ),
+)
+
+// Mirrors build-css.ts: semantic categories, primitive + dark ramps, overlay
+// ramps, then the hand-added chart series (build-css.ts chart branch).
+function expectedColors(): Set<string> {
+  const names = new Set<string>()
+  for (const [category, entries] of Object.entries(semanticColors.light)) {
+    for (const name of Object.keys(entries)) {
+      names.add(`--color-${category}-${name}`)
+    }
+  }
+  for (const [family, shades] of Object.entries(colors.light)) {
+    for (const shade of Object.keys(shades)) {
+      names.add(`--color-${family}-${shade}`)
+    }
+  }
+  for (const [family, shades] of Object.entries(colors.dark)) {
+    for (const shade of Object.keys(shades)) {
+      names.add(`--color-dark-${family}-${shade}`)
+    }
+  }
+  for (const [name, shades] of Object.entries(colors.overlay)) {
+    if (typeof shades !== 'object') continue
+    for (const shade of Object.keys(shades)) {
+      names.add(`--color-${name}-overlay-${shade}`)
+    }
+  }
+  for (let index = 1; index <= 8; index += 1) {
+    names.add(`--color-chart-${index}`)
+  }
+  names.add('--color-chart-grid')
+  names.add('--color-chart-axis')
+  return names
+}
+
+function expectedShadows(): Set<string> {
+  const names = new Set<string>()
+  for (const key of Object.keys(shadows)) {
+    if (key === 'none') continue
+    names.add(key === 'DEFAULT' ? '--shadow' : `--shadow-${key}`)
+  }
+  for (const role of Object.keys(shadowRoles)) {
+    names.add(`--shadow-${role}`)
+  }
+  return names
+}
+
+const WEIGHTS = ['medium', 'semibold', 'bold'] as const
+
+// `--text-<size>` always; `--text-<size>-<weight>` only where the tracking
+// table has an entry for that size+weight (build-css.ts typography branch).
+function expectedText(): Set<string> {
+  const names = new Set<string>()
+  for (const key of Object.keys(fontSize)) {
+    names.add(`--text-${key}`)
+    const isParagraph = key.startsWith('p-')
+    const group = isParagraph ? 'paragraph' : 'text'
+    const size = isParagraph ? key.slice(2) : key
+    const byWeight = tracking[group]?.[size]
+    if (!byWeight) continue
+    for (const weight of WEIGHTS) {
+      if (byWeight[weight] !== undefined) names.add(`--text-${key}-${weight}`)
+    }
+  }
+  return names
+}
+
+describe('generated theme parity with @talelk/newui-tokens', () => {
+  it('emits every derived --color-* token', () => {
+    const missing = [...expectedColors()].filter((name) => !defined.has(name))
+    expect(missing).toEqual([])
+  })
+
+  it('defines no --color-* token the data does not derive', () => {
+    const expected = expectedColors()
+    const extra = [...defined].filter(
+      (name) => name.startsWith('--color-') && !expected.has(name),
+    )
+    expect(extra).toEqual([])
+  })
+
+  it('emits every radius, spacing and shadow token', () => {
+    const expected = [
+      ...Object.keys(radius).map((key) => `--radius-${key}`),
+      ...Object.keys(spacing).map((key) => `--spacing-${key}`),
+      ...expectedShadows(),
+    ]
+    const missing = expected.filter((name) => !defined.has(name))
+    expect(missing).toEqual([])
+  })
+
+  it('emits every derived text-size token', () => {
+    const missing = [...expectedText()].filter((name) => !defined.has(name))
+    expect(missing).toEqual([])
+  })
+
+  it('emits the stacking and motion scales', () => {
+    const expected = [
+      ...Object.keys(zIndex).map((key) => `--z-${key}`),
+      ...Object.keys(duration).map((key) => `--duration-${key}`),
+      ...Object.keys(easing).map((key) => `--ease-${key}`),
+    ]
+    const missing = expected.filter((name) => !defined.has(name))
+    expect(missing).toEqual([])
+  })
+
+  it('emits the breakpoint, animation and mono scales', () => {
+    // The animation names are composed in build-css.ts from the duration and
+    // easing tokens; the list is mirrored here so a dropped branch fails.
+    const expected = [
+      ...Object.keys(screens).map((key) => `--breakpoint-${key}`),
+      '--animate-overlay-in',
+      '--animate-drawer-in',
+      '--animate-shimmer',
+      '--animate-progress',
+      '--font-mono',
+    ]
+    const missing = expected.filter((name) => !defined.has(name))
+    expect(missing).toEqual([])
+  })
+})

package/src/keyframes.test.ts

@@ -0,0 +1,67 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Referenced-but-undefined animation guard.
+ *
+ * A component can reference `animate-[name_…]` while no `@keyframes name`
+ * exists anywhere — the class compiles, the utility is emitted, and the element
+ * simply never animates. That is a silent no-op no other test catches (it is how
+ * the indeterminate Progress bar shipped dead once). This asserts every custom
+ * animation a component names is actually defined.
+ */
+const TAILWIND_SRC = path.join(process.cwd(), 'packages/tailwind/src')
+const VISUAL_SRCS = [
+  'atoms',
+  'molecules',
+  'organisms',
+  'templates',
+  'charts',
+  'editor',
+  'code-editor',
+].map((pkg) => path.join(process.cwd(), `packages/${pkg}/src`))
+const TAILWIND_BUILTINS = new Set(['spin', 'pulse', 'ping', 'bounce'])
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = path.join(dir, entry)
+    if (statSync(full).isDirectory()) walk(full, out)
+    else if (/\.(tsx?|css)$/.test(entry)) out.push(full)
+  }
+  return out
+}
+
+const defined = new Set<string>()
+for (const file of walk(TAILWIND_SRC)) {
+  const source = readFileSync(file, 'utf8')
+  for (const match of source.matchAll(/@keyframes\s+([\w-]+)/g)) {
+    const name = match[1]
+    if (name) defined.add(name)
+  }
+}
+
+const referenced = new Map<string, string>()
+for (const file of VISUAL_SRCS.flatMap((dir) => walk(dir))) {
+  const source = readFileSync(file, 'utf8')
+  for (const match of source.matchAll(/animate-\[([\w-]+?)_/g)) {
+    const name = match[1]
+    if (name) referenced.set(name, path.relative(process.cwd(), file))
+  }
+}
+
+describe('animation keyframes', () => {
+  it('defines every custom animation a component references', () => {
+    const missing: string[] = []
+    for (const [name, file] of referenced) {
+      if (TAILWIND_BUILTINS.has(name)) continue
+      if (!defined.has(name)) missing.push(`${name} (referenced in ${file})`)
+    }
+    expect(missing).toEqual([])
+  })
+
+  it('respects prefers-reduced-motion', () => {
+    const css = readFileSync(path.join(TAILWIND_SRC, 'utilities.css'), 'utf8')
+    expect(css).toContain('@media (prefers-reduced-motion: reduce)')
+  })
+})

package/src/plugins/icon-pack.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import plugin from 'tailwindcss/plugin'
+
+/**
+ * Exposes every SVG in `iconsDir` as a `<prefix>-<name>` utility that masks the
+ * icon with the current text color:
+ *
+ *   <span class="lucide-menu size-4 text-ink-gray-6" />
+ *
+ * Tailwind v4 removed `matchComponents`, so this registers as a normal utility
+ * (`matchUtilities`). The icon utility deliberately sets NO width/height — the
+ * call site always pairs it with a `size-*` — which dodges the layer-order race
+ * v3 solved by putting icons in the components layer.
+ *
+ * @param {object} options
+ * @param {string} options.prefix
+ * @param {string} options.iconsDir
+ * @param {number} [options.normalizeStrokeWidth]
+ * @param {string} [options.defaultColor]
+ */
+export function iconPackPlugin({
+  prefix,
+  iconsDir,
+  normalizeStrokeWidth,
+  defaultColor,
+}) {
+  if (!prefix) throw new Error('iconPackPlugin: `prefix` is required')
+  if (!iconsDir) throw new Error('iconPackPlugin: `iconsDir` is required')
+
+  const cache = new Map()
+
+  function encode(name) {
+    if (cache.has(name)) return cache.get(name)
+    const file = path.join(iconsDir, `${name}.svg`)
+    let uri = null
+    if (fs.existsSync(file)) {
+      let svg = fs.readFileSync(file, 'utf8')
+      if (normalizeStrokeWidth != null) {
+        svg = svg.replace(
+          /stroke-width="[^"]+"/g,
+          `stroke-width="${normalizeStrokeWidth}"`,
+        )
+      }
+      svg = svg.replace(/\s+/g, ' ').trim()
+      uri = `url("data:image/svg+xml;utf8,${encodeURIComponent(svg)}")`
+    }
+    cache.set(name, uri)
+    return uri
+  }
+
+  function available() {
+    try {
+      return fs
+        .readdirSync(iconsDir)
+        .filter((f) => f.endsWith('.svg'))
+        .map((f) => f.slice(0, -4))
+    } catch {
+      return []
+    }
+  }
+
+  return plugin(({ matchUtilities }) => {
+    const values = Object.fromEntries(available().map((n) => [n, n]))
+    matchUtilities(
+      {
+        [prefix]: (value) => {
+          const mask = encode(value)
+          if (!mask) return {}
+          return {
+            display: 'block',
+            'background-color': defaultColor ?? 'currentColor',
+            '-webkit-mask-image': mask,
+            'mask-image': mask,
+            '-webkit-mask-repeat': 'no-repeat',
+            'mask-repeat': 'no-repeat',
+            '-webkit-mask-position': 'center',
+            'mask-position': 'center',
+            '-webkit-mask-size': 'contain',
+            'mask-size': 'contain',
+          }
+        },
+      },
+      { values },
+    )
+  })
+}

package/src/plugins/lucide.js

@@ -0,0 +1,28 @@
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import plugin from 'tailwindcss/plugin'
+import { iconPackPlugin } from './icon-pack.js'
+
+// Resolve lucide-static's icons directory once. Guarded: a consumer that does
+// not install lucide-static should still get a working stylesheet, just with
+// no `lucide-*` utilities.
+let iconsDir = null
+try {
+  const nodeRequire = createRequire(import.meta.url)
+  iconsDir = path.join(
+    path.dirname(nodeRequire.resolve('lucide-static/package.json')),
+    'icons',
+  )
+} catch {
+  iconsDir = null
+}
+
+// Lucide ships every icon at stroke-width="2"; 1.5 matches the rest of the
+// design system. No defaultColor — icons inherit the parent's text color.
+export default iconsDir
+  ? iconPackPlugin({
+      prefix: 'lucide',
+      iconsDir,
+      normalizeStrokeWidth: 1.5,
+    })
+  : plugin(() => {})

package/src/plugins/theme.js

@@ -0,0 +1,89 @@
+import plugin from 'tailwindcss/plugin'
+
+/**
+ * Base layer for the design system.
+ *
+ * In the v3 layer (frappe-ui's `plugin.js`) this also minted the color theme,
+ * text styles and focus-ring components. In v4 all of those come from
+ * `@theme` (generated) and `@utility` (utilities.css), so this plugin only
+ * carries what genuinely has to live in the base layer.
+ */
+export default plugin(({ addBase }) => {
+  addBase({
+    // `@tailwindcss/forms` is loaded before this plugin and resets every native
+    // text control: a 1px `gray-500` border, a white fill, `padding: 0.5rem
+    // 0.75rem`, a 16px font and a blue focus ring. Our recipes own all of that,
+    // so the reset only ever leaks into the controls that deliberately want
+    // none of it — the bare `<input>` inside Combobox / MultiSelect /
+    // DatePicker / TimePicker / DateRangePicker / DateTimePicker, which
+    // otherwise renders as a bordered 16px box inside the field's own 14px
+    // surface. Neutralised once, here, rather than restated in every recipe;
+    // utilities still win, so a recipe that asks for a border, padding or a
+    // size gets it. Checkboxes, radios and file inputs are left to the plugin —
+    // those *are* its widgets.
+    "input:not([type='checkbox'], [type='radio'], [type='file']), textarea, select":
+      {
+        'border-width': '0',
+        'border-radius': '0',
+        'background-color': 'transparent',
+        padding: '0',
+        'font-size': 'inherit',
+        'line-height': 'inherit',
+      },
+    // The plugin's `:focus` rule paints a 1px blue ring on the control itself.
+    // Focus indication belongs to the field (`focus-within:focus-ring`), so the
+    // inner control must not draw a second, clipped ring.
+    "input:not([type='checkbox'], [type='radio'], [type='file']):focus, textarea:focus, select:focus":
+      {
+        'box-shadow': 'none',
+      },
+    body: {
+      'font-size': 'var(--text-interface)',
+      'line-height': 'var(--text-interface--line-height)',
+    },
+    html: {
+      'font-family': 'InterVar, ui-sans-serif, system-ui, sans-serif',
+      'font-optical-sizing': 'auto',
+    },
+    'html, body, button, p, span, div': {
+      fontVariationSettings: "'opsz' 24, 'cv11' 1",
+      WebkitFontSmoothing: 'antialiased',
+      MozOsxFontSmoothing: 'grayscale',
+    },
+    // A bare <p> reads as body copy. At element specificity (0,0,1) with
+    // :where() so any explicit text-* / text-p-* line-height wins.
+    ':where(p)': {
+      'line-height': '1.6',
+    },
+    // The baseline focus ring, keyboard-only. `:where()` gives it zero
+    // specificity, so a component's own `focus-ring` utility (or an explicit
+    // `outline-none`) still wins — but every interactive element that forgot
+    // to opt in gets a visible ring instead of the browser default.
+    ':where(:focus-visible)': {
+      outline: 'var(--focus-outline-default)',
+      'outline-offset': '0px',
+    },
+    // Tell the browser which scheme native UI (scrollbars, form controls,
+    // autofill) should render. Without this, a dark page keeps light
+    // scrollbars and light form widgets.
+    ':root': {
+      'color-scheme': 'light',
+    },
+    '[data-theme="dark"]': {
+      'color-scheme': 'dark',
+    },
+    // Selection reads as a tinted brand highlight rather than the OS default.
+    '::selection': {
+      'background-color':
+        'color-mix(in oklab, var(--surface-blue-6) 28%, transparent)',
+    },
+    // `useColorScheme` stamps this for the two frames around a light/dark swap
+    // so every transitioning surface does not cross-fade at once (a flash).
+    '.no-transition, .no-transition *': {
+      transition: 'none !important',
+    },
+    '.no-transition *::before, .no-transition *::after': {
+      transition: 'none !important',
+    },
+  })
+})

package/src/source.d.ts

@@ -0,0 +1 @@
+export declare const source: string[]

package/src/source.ts

@@ -0,0 +1,23 @@
+/**
+ * Source globs that emit Tailwind classes in newui. A consuming app spreads
+ * these into its own `@source` list (Tailwind v4 scans sources declared in
+ * CSS, not a JS config):
+ *
+ *   @source '@talelk/newui-tailwind/source';
+ */
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../..',
+)
+
+function glob(pattern: string) {
+  return path.join(packageRoot, pattern).split(path.sep).join('/')
+}
+
+export const source = [
+  glob('ui/src/**/*.{ts,tsx}'),
+  glob('icons/src/**/*.{ts,tsx}'),
+]

package/src/style.css

@@ -0,0 +1,41 @@
+/* The single stylesheet an app imports.
+ *
+ *   @import '@talelk/newui-tailwind/style.css';
+ *
+ * Everything below is generated or framework-neutral; nothing here is
+ * app-specific. The consuming app adds its own `@source` globs. */
+@import "./fonts/Inter/inter.css";
+@import "tailwindcss";
+@import "./generated/tokens.css";
+@import "./generated/theme.css";
+@import "./utilities.css";
+
+@plugin "@tailwindcss/forms";
+@plugin "@tailwindcss/typography";
+@plugin "./plugins/theme.js";
+@plugin "./plugins/lucide.js";
+
+/* Dark mode is the document switch, not a per-component variant. Color
+ * utilities already flip through the runtime tokens; this variant exists for
+ * the occasional `dark:` edge case. */
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
+
+/* Scan every atomic visual package so a component's classes always emit.
+ * `not` excludes the merge config (vocabulary, not usage) and each package's
+ * test fixtures, whose strings are not component markup. */
+@source "../../atoms/src/**/*.{ts,tsx}";
+@source not "../../atoms/src/lib/tw-merge.config.ts";
+@source not "../../atoms/src/**/*.test.{ts,tsx}";
+@source "../../molecules/src/**/*.{ts,tsx}";
+@source not "../../molecules/src/**/*.test.{ts,tsx}";
+@source "../../icons/src/**/*.{ts,tsx}";
+@source "../../organisms/src/**/*.{ts,tsx}";
+@source not "../../organisms/src/**/*.test.{ts,tsx}";
+@source "../../templates/src/**/*.{ts,tsx}";
+@source not "../../templates/src/**/*.test.{ts,tsx}";
+@source "../../charts/src/**/*.{ts,tsx}";
+@source not "../../charts/src/**/*.test.{ts,tsx}";
+@source "../../editor/src/**/*.{ts,tsx}";
+@source not "../../editor/src/**/*.test.{ts,tsx}";
+@source "../../code-editor/src/**/*.{ts,tsx}";
+@source not "../../code-editor/src/**/*.test.{ts,tsx}";

package/src/tokens.test.ts

@@ -0,0 +1,145 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { layoutSpacing, radiusRoles } from '@talelk/newui-tokens'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Token discipline.
+ *
+ * Two failure modes this catches, both of which have shipped here before:
+ *
+ *  1. A component referencing a semantic token that does not exist
+ *     (`bg-surface-modal`) — the utility silently compiles to nothing and the
+ *     element renders transparent.
+ *  2. A component reaching for a raw Tailwind palette colour
+ *     (`bg-red-500`) instead of the semantic vocabulary (P: semantic tokens
+ *     only). Brand customization and dark mode both depend on this.
+ */
+const REPO = process.cwd()
+const VISUAL_SRCS = [
+  'atoms',
+  'molecules',
+  'organisms',
+  'templates',
+  'charts',
+  'editor',
+  'code-editor',
+].map((pkg) => path.join(REPO, `packages/${pkg}/src`))
+const THEME_CSS = path.join(REPO, 'packages/tailwind/src/generated/theme.css')
+
+const themeCss = readFileSync(THEME_CSS, 'utf8')
+const definedColors = new Set(
+  [...themeCss.matchAll(/--color-([a-z0-9-]+):/g)].map((m) => m[1]),
+)
+
+const TOKENS_CSS = path.join(REPO, 'packages/tailwind/src/generated/tokens.css')
+const tokensCss = readFileSync(TOKENS_CSS, 'utf8')
+
+/**
+ * Every custom property tokens.css *declares* — both sides of the `name: value`.
+ * A pointer at an undeclared property is the chart-palette bug: `--chart-1:
+ * var(--blue-6)` named a shade that does not exist, so the property was
+ * guaranteed-invalid, every `var(--chart-1)` fell back to `transparent`, and
+ * charts and the palette swatches rendered invisible with no error anywhere.
+ */
+const declaredVars = new Set(
+  [...tokensCss.matchAll(/^\s*(--[a-z0-9-]+):/gm)].map((m) => m[1]),
+)
+
+const SEMANTIC_PREFIX = '(?:surface|ink|outline|black-overlay|white-overlay)'
+const COLOR_UTILITIES =
+  '(?:bg|text|border|outline|fill|stroke|divide|ring|decoration|placeholder|caret|accent|from|via|to|shadow)'
+
+// A raw palette ramp, e.g. `bg-red-500`, `text-gray-700`. Semantic uses are
+// always prefixed (`bg-surface-red-2`), so a bare family+shade is the smell.
+const PALETTE_FAMILIES =
+  '(?:gray|slate|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)'
+const RAW_PALETTE = new RegExp(
+  `${COLOR_UTILITIES}-${PALETTE_FAMILIES}-\\d{2,3}\\b`,
+  'g',
+)
+
+// Colours with no semantic equivalent that are legitimately used raw.
+const RAW_ALLOWLIST = new Set(['text-white', 'text-black'])
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = path.join(dir, entry)
+    if (statSync(full).isDirectory()) walk(full, out)
+    else if (/\.tsx?$/.test(entry) && !/\.test\.tsx?$/.test(entry))
+      out.push(full)
+  }
+  return out
+}
+
+const files = VISUAL_SRCS.flatMap((dir) => walk(dir))
+
+function scan(regex: RegExp): Map<string, string> {
+  const found = new Map<string, string>()
+  for (const file of files) {
+    const source = readFileSync(file, 'utf8')
+    for (const match of source.matchAll(regex)) {
+      found.set(match[0], path.relative(REPO, file))
+    }
+  }
+  return found
+}
+
+describe('token discipline', () => {
+  it('emits the semantic layout spacing and radius roles', () => {
+    for (const name of Object.keys(layoutSpacing))
+      expect(themeCss).toContain(`--spacing-${name}:`)
+    for (const name of Object.keys(radiusRoles))
+      expect(themeCss).toContain(`--radius-${name}:`)
+  })
+
+  it('only references semantic tokens that exist in the theme', () => {
+    const semanticUse = new RegExp(
+      `${COLOR_UTILITIES}-(${SEMANTIC_PREFIX}-[a-z0-9-]+)`,
+      'g',
+    )
+    const missing: string[] = []
+    for (const file of files) {
+      const source = readFileSync(file, 'utf8')
+      for (const match of source.matchAll(semanticUse)) {
+        const token = match[1]
+        if (!definedColors.has(token)) {
+          missing.push(
+            `${match[0]} → --color-${token} (in ${path.relative(REPO, file)})`,
+          )
+        }
+      }
+    }
+    expect(missing).toEqual([])
+  })
+
+  it('does not use raw Tailwind palette colours', () => {
+    const offenders = [...scan(RAW_PALETTE)].filter(
+      ([token]) => !RAW_ALLOWLIST.has(token),
+    )
+    expect(offenders).toEqual([])
+  })
+
+  it('does not hard-code colours in class strings', () => {
+    // A literal hex/rgb/hsl value cannot follow the theme, so it breaks dark
+    // mode and brand customization. Colours come from tokens, always.
+    const HARDCODED =
+      /(?:bg|text|border|ring|fill|stroke|outline|shadow|from|via|to|decoration|caret|accent)-\[(?:#|rgba?\(|hsla?\()/g
+    const offenders = [...scan(HARDCODED)]
+    expect(offenders).toEqual([])
+  })
+
+  it('every runtime token pointer names a token that is declared', () => {
+    // `--x: var(--y)` where `--y` is declared nowhere is worse than a typo: it
+    // is silently valid CSS that makes every consumer transparent. Catches the
+    // whole class, not just the chart ramp that shipped broken.
+    const missing: string[] = []
+    for (const match of tokensCss.matchAll(
+      /^\s*(--[a-z0-9-]+):\s*var\((--[a-z0-9-]+)\)/gm,
+    )) {
+      const [, name, target] = match
+      if (!declaredVars.has(target)) missing.push(`${name} → ${target}`)
+    }
+    expect(missing).toEqual([])
+  })
+})