@vegastack/design 0.7.0 → 0.7.2

package/bin/doctor.mjs

@@ -12,11 +12,17 @@
 // command and not a paragraph in a guide. Every check here maps to a documented failure
 // mode in the Troubleshooting guide.
 //
+// It also scans the project's OWN source for vocabulary the shadcn reset retired (0.5.0 → now):
+// `text-h2`, `bg-destructive-subtle`, `var(--z-toast)`, an `@/components/ui/icon-button` import.
+// A retired utility compiles to NOTHING — no build error, no type error — so a heading silently
+// renders as body text. The Regent consumer carried 338 such classes past every other check
+// (2026-09-23), which is why this is a failing check and not a guide section.
+//
 // Read-only: it never writes, installs, or edits. Exit 0 = all good, 1 = a real problem,
 // so it composes into CI as `vegastack-design doctor`.
 
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 
 const POSTCSS_CONFIGS = [
   "postcss.config.mjs",
@@ -41,6 +47,8 @@ const USAGE = `
 Usage: vegastack-design doctor [options]
 
 Checks a consuming project's VegaStack setup and reports what is wrong and how to fix it.
+Also scans the project's own source (not node_modules, build output, or the components.json
+\`ui\` alias directory) for vocabulary the shadcn reset retired, and reports each as file:line.
 
 Options:
   --dir <path>   Project root to inspect (default: the current directory)
@@ -114,6 +122,467 @@ function readJson(path) {
   }
 }
 
+// ---- retired vocabulary ----------------------------------------------------------------------
+// Each entry: a pattern over one source line, a replacement hint (from the "Migrating to the shadcn
+// reset" guide, where every row has its full table), and — for token families a project may
+// legitimately define for itself — the custom property whose DECLARATION in the scanned source
+// means "this is yours, not ours". Kept here and dependency-free on purpose: doctor must run in a
+// fresh consumer before anything else is installed correctly.
+const GUIDE = "https://design.vegastack.com/docs/guides/migrating-shadcn-reset";
+const HEADING_HINT = {
+  "text-h1": "text-3xl font-semibold (page heading)",
+  "text-h2": "text-2xl font-semibold (section heading)",
+  "text-h3": "text-lg font-semibold",
+  "text-h4": "text-base font-medium (card / dialog title)",
+};
+const DISPLAY_HINT = {
+  sm: "text-4xl",
+  md: "text-5xl",
+  lg: "text-6xl",
+  xl: "text-7xl",
+};
+// The literal each deleted `--alpha-*` token carried. Derived from the token HISTORY, not only the
+// last pre-reset snapshot: every name ever declared in packages/design-tokens (git log -S over
+// src/tokens.ts and tokens/*.tokens.json) is here. Nineteen are the migration guide's section 4.2
+// ladder, retired by the shadcn reset; five were retired before it, per the design-tokens
+// CHANGELOG — fill-hover, input-hover and surface-subtle with `track` (#77), soft-hover and
+// soft-surface with the Bubble contrast fix (#113). A theme-split token gives [light, dark].
+const ALPHA = {
+  "fill-hover": 80,
+  "input-hover": 50,
+  "surface-subtle": 10,
+  "soft-surface": [10, 20],
+  "soft-hover": [20, 30],
+  "surface-faint": 5,
+  hover: 7,
+  border: 8,
+  pressed: 10,
+  "ink-tint": 10,
+  "ink-tint-strong": 15,
+  "border-subtle": 20,
+  "border-soft": 30,
+  input: 30,
+  "wash-faint": 40,
+  wash: 50,
+  "outline-border": 50,
+  "outline-soft": 50,
+  "wash-strong": 60,
+  "backdrop-soft": 60,
+  "tint-border": 70,
+  "link-hover": 88,
+  glass: 90,
+  "glass-hover": 95,
+};
+const OPACITY = { track: 25, dim: 50, "hint-soft": 60, hint: 70 };
+const Z = {
+  raised: "z-10",
+  overlay: "z-50 — one overlay band, DOM order decides",
+  toast:
+    "nothing — the Toast viewport sets its own z-60, the one exception to z-50",
+};
+const RETIRED_COMPONENTS = {
+  "icon-button":
+    'Button with size="icon" (or icon-sm / icon-lg) and an aria-label',
+  segmented: "a joined ToggleGroup",
+  "progress-indicator": "Progress (determinate) or Spinner (indeterminate)",
+  "field-inline": "EditableCell",
+  "floating-surface": "Popover / HoverCard — FloatingSurface was internal only",
+  "section-header":
+    "nothing — removed with the marketing layer; compose your own heading",
+  sonner:
+    "toast (`@/components/ui/toast`, `toast.add({ title })`) — Sonner was retired in 0.12.0",
+};
+const B = String.raw`(?<![\w-])`; // a utility or custom property starts here
+const E = String.raw`(?![\w-])`; // …and ends here
+/** An alternation of exactly these names, longest first so `border-subtle` wins over `border`. */
+const oneOf = (names) =>
+  [...names].sort((a, b) => b.length - a.length).join("|");
+// The four STATUS families are the only ones that ever shipped a `-subtle` step (guide section 4.5);
+// `--tag-*-subtle` is kept, and a `muted`/`accent`/project family never had one, so neither is matched.
+const SUBTLE_FAMILIES = ["destructive", "success", "warning", "info"];
+export const RETIRED_VOCABULARY = [
+  {
+    id: "text-h*",
+    re: new RegExp(`${B}text-h[1-4]${E}`, "g"),
+    hint: (m) => HEADING_HINT[m],
+    declared: (m) => `--text-${m.slice(5)}`,
+  },
+  {
+    id: "text-label*",
+    re: new RegExp(`${B}text-label(?:-sm)?${E}`, "g"),
+    hint: (m) =>
+      m.endsWith("-sm") ? "text-xs font-medium" : "text-sm font-medium",
+    declared: (m) => `--${m}`,
+  },
+  {
+    id: "text-mono-label",
+    re: new RegExp(`${B}text-mono-label${E}`, "g"),
+    hint: () =>
+      "font-mono text-xs for code/data — a label is font-sans text-xs font-medium; no tracking, no uppercase",
+    declared: (m) => `--${m}`,
+  },
+  {
+    id: "text-code*",
+    re: new RegExp(`${B}text-code(?:-sm)?${E}`, "g"),
+    hint: (m) =>
+      m.endsWith("-sm") ? "font-mono text-xs" : "font-mono text-sm",
+    declared: (m) => `--${m}`,
+  },
+  {
+    id: "text-strong",
+    re: new RegExp(`${B}text-strong${E}`, "g"),
+    hint: () => "text-sm font-semibold",
+    declared: (m) => `--${m}`,
+  },
+  {
+    id: "text-display-*",
+    re: new RegExp(`${B}text-display-(?:sm|md|lg|xl)${E}`, "g"),
+    hint: (m) =>
+      `${DISPLAY_HINT[m.slice(13)]} — the ramp supplies tracking; write no tracking-*`,
+    declared: (m) => `--${m}`,
+  },
+  {
+    // The four STATUS families lost their -subtle step — and only those four ever had one, so the
+    // hint's `text-<family>-text` always names a real token.
+    id: "*-subtle",
+    re: new RegExp(
+      `${B}(?:bg|text|border|ring|outline|fill|stroke|divide|from|to|via)-(${SUBTLE_FAMILIES.join("|")})-subtle(?:-hover|-active)?${E}`,
+      "g",
+    ),
+    hint: (m, family) => {
+      return m.includes("-subtle-")
+        ? `hover:bg-${family}/20 (the -hover/-active steps are gone)`
+        : `bg-${family}/10 (a tint of the family), with text-${family}-text for text on it`;
+    },
+    declared: (m) => {
+      const name = m.replace(/^[a-z]+-/, "");
+      return [`--${name}`, `--color-${name}`];
+    },
+  },
+  {
+    // Only the names the system shipped (see ALPHA). `--alpha-*` is an open prefix other
+    // libraries use too, and a name we never shipped is not ours to call retired.
+    id: "--alpha-*",
+    re: new RegExp(`${B}--alpha-(?:${oneOf(Object.keys(ALPHA))})${E}`, "g"),
+    hint: (m) => {
+      const pct = ALPHA[m.slice(8)];
+      if (Array.isArray(pct))
+        return `the literal /${pct[0]} in light with a dark: variant at /${pct[1]}, e.g. bg-destructive/${pct[0]} dark:bg-destructive/${pct[1]}`;
+      return `the literal /${pct}, e.g. bg-foreground/${pct}`;
+    },
+    declared: (m) => m,
+  },
+  {
+    id: "--opacity-*",
+    re: new RegExp(`${B}--opacity-(?:${oneOf(Object.keys(OPACITY))})${E}`, "g"),
+    hint: (m) => `opacity-${OPACITY[m.slice(10)]}`,
+    declared: (m) => m,
+  },
+  {
+    // `--z-index`, `--z-modal`, … belong to other libraries; only the three named bands are ours.
+    id: "--z-*",
+    re: new RegExp(`${B}--z-(?:${oneOf(Object.keys(Z))})${E}`, "g"),
+    hint: (m) => Z[m.slice(4)],
+    declared: (m) => m,
+  },
+  {
+    id: "shadow-overlay",
+    re: new RegExp(`${B}(?:--)?shadow-overlay${E}`, "g"),
+    hint: () => "shadow-md (a popover) or shadow-lg (a modal)",
+    declared: () => "--shadow-overlay",
+  },
+  {
+    id: "backdrop-blur-glass",
+    re: new RegExp(`${B}backdrop-blur-glass${E}`, "g"),
+    hint: () =>
+      "delete it — the glass effect went with the marketing layer (backdrop-blur-xs is upstream's scrim blur)",
+    declared: () => "--blur-glass",
+  },
+  {
+    id: "retired component",
+    // An import/require/dynamic-import specifier whose LAST path segment is a retired item — and
+    // only when the specifier resolves INTO the ui alias directory (`accept`): a project's own
+    // `@/components/layout/section-header` or `./sonner` is its code, not a registry copy. A bare
+    // `"sonner"` (the npm package) is not a registry import and is left alone.
+    re: new RegExp(
+      String.raw`(?:from\s+|import\s*\(\s*|require\s*\(\s*|import\s+)["']([^"']*)\/(${Object.keys(RETIRED_COMPONENTS).join("|")})(?:\.[jt]sx?)?["']`,
+      "g",
+    ),
+    accept: (m, ctx) => importsIntoUi(m[1], ctx),
+    hint: (_m, _dir, name) => RETIRED_COMPONENTS[name],
+    declared: () => null,
+    label: (_m, _dir, name) => `import …/${name}`,
+  },
+];
+
+// Code and stylesheets only. Prose (`.md`/`.mdx`) that NAMES a retired token — a changelog, a
+// migration note — is not a use of it, and would bury the real findings.
+const SCAN_EXTENSIONS = /\.(?:[cm]?[jt]sx?|css|scss)$/;
+const SCAN_SKIP_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "storybook-static",
+]);
+const SCAN_MAX_FILES = 20000;
+const SCAN_MAX_BYTES = 1024 * 1024;
+
+/**
+ * The directories components.json's `ui` alias names, resolved against the file's own folder.
+ * Those files are registry copies — `check-updates` owns them, and a re-pull replaces them — so
+ * a retired name inside one is not the consumer's own code. `@/x` and `~/x` resolve to `x` or
+ * `src/x`, whichever exists (the shadcn convention for a src-dir project).
+ */
+export function uiAliasDirs(componentsJson, componentsDir) {
+  const alias = componentsJson?.aliases?.ui;
+  const candidates = [];
+  if (typeof alias === "string" && alias.length > 0) {
+    const bare = alias.replace(/^(?:@|~)\//, "");
+    candidates.push(
+      join(componentsDir, bare),
+      join(componentsDir, "src", bare),
+    );
+  } else {
+    candidates.push(
+      join(componentsDir, "components", "ui"),
+      join(componentsDir, "src", "components", "ui"),
+    );
+  }
+  return candidates.filter((d) => existsSync(d)).map((d) => resolve(d));
+}
+
+/**
+ * Does an import specifier (the part before the retired name) resolve into the ui alias directory?
+ * Three spellings do: the components.json `ui` alias (`@/components/ui`), the registry's own
+ * `@/components/ui` convention, and a relative path that lands in one of the ui alias dirs.
+ */
+function importsIntoUi(specDir, { file, uiAliases, uiDirs }) {
+  if (uiAliases.includes(specDir)) return true;
+  if (specDir === "." || specDir === ".." || /^\.\.?\//.test(specDir)) {
+    const target = resolve(dirname(file), specDir);
+    return uiDirs.includes(target);
+  }
+  return false;
+}
+
+/**
+ * Blank what is not class or CSS usage, keeping every newline so line numbers survive: `//` and
+ * `/* *\/` comments, and — in script files — a string literal that reads as prose ("Use text-strong
+ * for emphasis"). A class string is lower-case utility tokens; a capitalised word or sentence
+ * punctuation marks a sentence (never `!`, which is Tailwind's important modifier: `hidden!`).
+ *
+ * In a script file, JSX TEXT is not code, so nothing in it may open a comment or a string: an
+ * apostrophe ("Don't"), a URL's `//`, a glob's `/*`. Without a parser, position decides — a string
+ * opens only where an expression can begin (after `=`, `(`, `,`, `[`, `{`, `:`, `?`, an operator,
+ * `=>`, or a keyword such as `return`), and a comment only after whitespace or code punctuation,
+ * never after `:` (`https://`) or a word (`src/*.ts`).
+ */
+const EXPRESSION_KEYWORDS = new Set([
+  "return",
+  "case",
+  "typeof",
+  "in",
+  "of",
+  "yield",
+  "await",
+  "void",
+  "delete",
+  "throw",
+  "from",
+  "import",
+  "export",
+  "default",
+  "else",
+  "do",
+]);
+function canStartExpression(src, i) {
+  let k = i - 1;
+  while (k >= 0 && /\s/.test(src[k])) k -= 1;
+  if (k < 0) return true;
+  const p = src[k];
+  if (p === ">") return src[k - 1] === "="; // `=>`, never a JSX tag's `>`
+  if ("=(,[{:?&|!+-*%^~<;".includes(p)) return true;
+  if (/[\w$]/.test(p)) {
+    let w = k;
+    while (w >= 0 && /[\w$]/.test(src[w])) w -= 1;
+    return EXPRESSION_KEYWORDS.has(src.slice(w + 1, k + 1));
+  }
+  return false;
+}
+const canStartComment = (src, i) => i === 0 || /[\s;,{}()[\]]/.test(src[i - 1]);
+
+export function maskNonUsage(
+  src,
+  { script = true, lineComments = script } = {},
+) {
+  const out = src.split("");
+  const blank = (from, to) => {
+    for (let k = from; k < to; k += 1) if (out[k] !== "\n") out[k] = " ";
+  };
+  const isProse = (text) =>
+    /(?:^|\s)[A-Z][a-z]+(?=[\s,.;:!?]|$)|[a-z][.,;:?](?:\s|$)/.test(
+      text.replace(/\[[^\]]*\]|\([^)]*\)/g, ""),
+    );
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    const next = src[i + 1];
+    if (c === "/" && next === "*" && (!script || canStartComment(src, i))) {
+      const end = src.indexOf("*/", i + 2);
+      const stop = end === -1 ? src.length : end + 2;
+      blank(i, stop);
+      i = stop;
+    } else if (
+      c === "/" &&
+      next === "/" &&
+      lineComments &&
+      (script ? canStartComment(src, i) : i === 0 || /\s/.test(src[i - 1]))
+    ) {
+      const end = src.indexOf("\n", i);
+      const stop = end === -1 ? src.length : end;
+      blank(i, stop);
+      i = stop;
+    } else if (
+      (c === '"' || c === "'" || c === "`") &&
+      (!script || canStartExpression(src, i))
+    ) {
+      let j = i + 1;
+      while (j < src.length && src[j] !== c) {
+        if (src[j] === "\\") j += 1;
+        else if (src[j] === "\n" && c !== "`") break;
+        j += 1;
+      }
+      if (script && isProse(src.slice(i + 1, j))) blank(i + 1, j);
+      i = j + 1;
+    } else {
+      i += 1;
+    }
+  }
+  return out.join("");
+}
+
+/**
+ * Class names a stylesheet DEFINES — `@utility text-h2 { … }` (a `-*` functional utility as a
+ * prefix) and plain class selectors such as `.text-strong { … }`. A retired name the project defines
+ * itself compiles, so it is the project's, not a silent no-op.
+ */
+function definedClasses(css) {
+  const exact = new Set();
+  const prefixes = [];
+  for (const m of css.matchAll(/([^{};]+)\{/g)) {
+    const prelude = m[1].trim();
+    const utility = prelude.match(/^@utility\s+([\w-]+?)(-\*)?$/);
+    if (utility) {
+      if (utility[2]) prefixes.push(`${utility[1]}-`);
+      else exact.add(utility[1]);
+    } else if (!prelude.startsWith("@")) {
+      for (const c of prelude.matchAll(/\.((?:\\.|[\w-])+)/g))
+        exact.add(c[1].replace(/\\(.)/g, "$1"));
+    }
+  }
+  return { exact, prefixes };
+}
+
+/** Every retired-vocabulary occurrence under `root`, skipping build output and the ui alias dirs. */
+export function scanRetiredVocabulary(
+  root,
+  { skipDirs = [], uiAlias = null } = {},
+) {
+  const skip = new Set(skipDirs.map((d) => resolve(d)));
+  const uiAliases = [
+    ...new Set(
+      [uiAlias, "@/components/ui"]
+        .filter((a) => typeof a === "string" && a.length > 0)
+        .map((a) => a.replace(/\/+$/, "")),
+    ),
+  ];
+  const uiDirs = [...skip];
+  const files = [];
+  const walk = (dir) => {
+    if (files.length >= SCAN_MAX_FILES) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith(".") || SCAN_SKIP_DIRS.has(e.name)) continue;
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!skip.has(resolve(full))) walk(full);
+      } else if (e.isFile() && SCAN_EXTENSIONS.test(e.name)) {
+        files.push(full);
+        if (files.length >= SCAN_MAX_FILES) return;
+      }
+    }
+  };
+  walk(root);
+
+  const sources = [];
+  const declared = new Set();
+  const declaredClasses = new Set();
+  const classPrefixes = [];
+  for (const file of files) {
+    try {
+      if (statSync(file).size > SCAN_MAX_BYTES) continue;
+    } catch {
+      continue;
+    }
+    const raw = readIfExists(file);
+    if (raw == null) continue;
+    const css = /\.s?css$/.test(file);
+    const src = maskNonUsage(raw, {
+      script: !css,
+      lineComments: !css || file.endsWith(".scss"),
+    });
+    sources.push({ file, src });
+    for (const m of src.matchAll(/(?<![\w-])(--[\w-]+)\s*:/g))
+      declared.add(m[1]);
+    if (css) {
+      const defined = definedClasses(src);
+      for (const name of defined.exact) declaredClasses.add(name);
+      classPrefixes.push(...defined.prefixes);
+    }
+  }
+  const definesClass = (name) =>
+    declaredClasses.has(name) ||
+    classPrefixes.some((prefix) => name.startsWith(prefix));
+
+  const findings = [];
+  for (const { file, src } of sources) {
+    const lines = src.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (line.length > 4000) continue; // minified output that slipped past the dir skips
+      for (const rule of RETIRED_VOCABULARY) {
+        rule.re.lastIndex = 0;
+        for (const m of line.matchAll(rule.re)) {
+          const groups = m.slice(1);
+          if (rule.accept && !rule.accept(m, { file, uiAliases, uiDirs }))
+            continue;
+          const own = [rule.declared(m[0], ...groups)].flat().filter(Boolean);
+          if (own.some((name) => declared.has(name))) continue;
+          if (!m[0].startsWith("--") && definesClass(m[0])) continue;
+          findings.push({
+            file: relative(root, file).split(sep).join("/"),
+            line: i + 1,
+            match: rule.label ? rule.label(m[0], ...groups) : m[0],
+            hint: rule.hint(m[0], ...groups),
+          });
+        }
+      }
+    }
+  }
+  return {
+    files: sources.length,
+    findings,
+    truncated: files.length >= SCAN_MAX_FILES,
+  };
+}
+
 export function main(argv = []) {
   if (argv.includes("-h") || argv.includes("--help")) {
     console.log(USAGE);
@@ -304,6 +773,34 @@ export function main(argv = []) {
     }
   }
 
+  // ---- 7. no retired vocabulary in the project's own source --------------------------------
+  const skipDirs = componentsJson
+    ? uiAliasDirs(componentsJson, dirname(componentsJsonPath))
+    : uiAliasDirs(null, root);
+  const scan = scanRetiredVocabulary(root, {
+    skipDirs,
+    uiAlias: componentsJson?.aliases?.ui ?? null,
+  });
+  const scanned = `${scan.files} source file(s)${
+    skipDirs.length
+      ? `, skipping ${skipDirs.map((d) => relative(root, d) || ".").join(", ")}`
+      : ""
+  }${scan.truncated ? ` (stopped at ${SCAN_MAX_FILES} files)` : ""}`;
+  if (scan.findings.length === 0) {
+    ok("no retired vocabulary", scanned);
+  } else {
+    const inFiles = new Set(scan.findings.map((f) => f.file)).size;
+    results.push({
+      level: "fail",
+      name: "no retired vocabulary",
+      detail: `${scan.findings.length} occurrence(s) in ${inFiles} file(s) of ${scanned} — these compile to nothing, silently`,
+      fix: `rewrite each as its hint says; every row is in ${GUIDE}`,
+      findings: scan.findings.map(
+        (f) => `${f.file}:${f.line}  ${f.match}  →  ${f.hint}`,
+      ),
+    });
+  }
+
   // ---- report -------------------------------------------------------------------------------
   const glyph = { ok: "✓", warn: "!", fail: "✗" };
   console.log("");
@@ -311,6 +808,7 @@ export function main(argv = []) {
     console.log(
       `  ${glyph[r.level]} ${r.name}${r.detail ? ` — ${r.detail}` : ""}`,
     );
+    for (const finding of r.findings ?? []) console.log(`     ${finding}`);
     if (r.fix) console.log(`     fix: ${r.fix}`);
   }
 

package/bin/vegastack-design.mjs

@@ -5,7 +5,8 @@
 //   check-updates   Show which copied-in components have newer registry versions (what to re-pull).
 //   verify          Verify a registry item's integrity before/after `shadcn add` (Sigstore + hash).
 //   skills          Install the bundled VegaStack agent skills into the consuming project.
-//   doctor          Check a consuming project's setup (PostCSS plugin, preset import, registry).
+//   doctor          Check a consuming project's setup (PostCSS plugin, preset import, registry,
+//                   retired design-system vocabulary in its own source).
 //
 // The bin is named `vegastack-design` (NOT `vegastack`) so it never collides with a platform CLI.
 // `check-updates` is imported in-process; `verify` is spawned (it's the standalone, hash-parity-tested

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/design",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "VegaStack design system — cn utility, icon runtime, Tailwind v4 preset, and the vegastack-design CLI (tokens ship separately as @vegastack/design-tokens)",
   "license": "MIT",
   "repository": {
@@ -67,10 +67,10 @@
     "lint": "eslint . && node ../../tooling/design-lint.mjs src && pnpm run verify",
     "verify": "node ../../tooling/verify-preset-source.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "node test/compare.test.mjs && node test/check-updates.test.mjs && node test/skills-install.test.mjs"
+    "test": "node test/compare.test.mjs && node test/check-updates.test.mjs && node test/skills-install.test.mjs && node test/doctor.test.mjs"
   },
   "dependencies": {
-    "@vegastack/design-tokens": "^0.7.0",
+    "@vegastack/design-tokens": "^0.7.1",
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.6.0",
     "tsconfig-paths": "^4.2.0",

package/preset.css

@@ -13,15 +13,16 @@
  *
  * This package's own `dist` ships the icon runtime (`BrandIcon`'s
  * `inline-flex shrink-0 [&>svg]:size-full`), and `@vegastack/ui` ships a compiled
- * provider + `Toaster` whose Base UI Toast classes (e.g. `bg-popover shadow-overlay`)
+ * provider + `Toaster` whose Base UI Toast classes (e.g. `bg-popover shadow-lg`)
  * live in its published `dist/*.js`, NOT in the consumer's own source — so without
  * an explicit `@source` a real npm consumer importing ONLY this preset would get
  * a partially-unstyled provider/Toaster + icon UI.
  *
  * Why `./dist` + a RELATIVE `../ui/dist` path and NOT `@source "@vegastack/ui"`:
- *   - Tailwind v4.3.1 (the pinned version) does NOT resolve a bare package-name
- *     `@source` through node_modules — it treats `@vegastack/ui` as a literal
- *     glob and silently scans nothing (verified: tooling/verify-preset-source.mjs).
+ *   - Tailwind v4 (whatever version the lockfile pins) does NOT resolve a bare
+ *     package-name `@source` through node_modules — it treats `@vegastack/ui` as a
+ *     literal glob and silently scans nothing (re-verified against the installed
+ *     version by tooling/verify-preset-source.mjs).
  *   - Tailwind resolves `@source` relative to this file's realpath. The icon runtime
  *     is INSIDE this package now (`./dist`). `@vegastack/ui` — when present — sits as
  *     a sibling under the same `@vegastack` scope in node_modules, making `../ui`

package/skills/vegastack-design-audit/SKILL.md

@@ -17,13 +17,20 @@ These are mechanical and catch the highest-value problems:
 
 ```bash
 npx --package=@vegastack/design vegastack-design check-updates
+npx --package=@vegastack/design vegastack-design doctor
 ```
 
+`doctor` checks setup and also scans the app's own source (skipping `node_modules`, build output
+and the `components.json` `ui` directory) for vocabulary the shadcn reset retired — `text-h1`,
+`text-label`, `bg-destructive-subtle`, `--z-toast`, an `icon-button` import — and exits non-zero
+with `file:line` and the replacement for each. Its findings are §3's retired-vocabulary **errors**;
+cite them rather than re-deriving them.
+
 `⬆ update` means the registry has a newer version. `≈ drift` means the installed file differs from
-the registry item — either an upstream change or a local edit to a file you do not own. Both are
-findings; a local edit to a copied-in component is a **high** finding, because the next
-`--overwrite` silently destroys it. The fix is to move the customisation into your own wrapper
-component or a token override.
+the registry item — either an upstream change or a local edit. Both are findings. The rule for
+edits is the one the Components guide states: **don't edit a copied-in component; if you must, it
+becomes yours** — `check-updates` reports it as drifted from then on and every update is a `--diff`
+re-applied by hand (§5).
 
 Then verify setup, since these failures look like component bugs:
 
@@ -103,7 +110,7 @@ compatibility layer** — an import resolves to nothing and a deleted token sile
 nothing, which is the worse half. Both searches are mechanical:
 
 ```bash
-rg -n 'IconButton|OTPInput|PasswordInput|CheckboxGroup|FieldInline|Segmented|SplitButton|ProgressIndicator|OnboardingChecklist|FloatingSurface|MarketingSurface|ComparisonMatrix|FigureFrame|LogoRow|ParticleField|PricingSection|RuledBand|SectionHeader|Testimonial|StaggeredTextReveal' --glob '!components/ui/**'
+rg -n 'IconButton|OTPInput|CheckboxGroup|FieldInline|Segmented|SplitButton|ProgressIndicator|OnboardingChecklist|FloatingSurface|MarketingSurface|ComparisonMatrix|FigureFrame|LogoRow|ParticleField|PricingSection|RuledBand|SectionHeader|Testimonial|StaggeredTextReveal' --glob '!components/ui/**'
 rg -n 'surface-(1|2|3|raised)|--alpha-|--opacity-|--size-|--icon-|--panel-width-|--z-(raised|overlay|toast)|shadow-overlay|text-(h[1-4]|label|label-sm|code|mono-label|display-)|muted-foreground-faint|surfaceInteractive|fillInteractive|fieldControl|selectedChipVariants' --glob '!components/ui/**'
 ```
 
@@ -139,9 +146,11 @@ rg -n 'surface-(1|2|3|raised)|--alpha-|--opacity-|--size-|--icon-|--panel-width-
 rg -n '@vegastack' components/ui/ -l
 ```
 
-A copied-in component is yours to keep but not to edit — the next `--overwrite` overwrites it. Any
-diff reported by `check-updates` as `≈ drift` on a file you did not intend to change is a **high**
-finding. Route customisation through a token override, a wrapper component, or a `className` prop.
+Don't edit a copied-in component; if you must, it becomes yours. Report every `≈ drift` as a
+**warning** — the file no longer receives registry fixes and the next `--overwrite` replaces the
+edit — and name the way back: move the customisation into a token override, a wrapper component,
+or a `className` at the call site, then re-pull. A drifted file whose edit nobody meant to make
+(no commit or comment owns it) is an **error**: it is lost work waiting to happen.
 
 A missing `// @vegastack …` provenance header is **normal** and never a finding on its own: the
 shadcn CLI strips leading comments during copy-in.
@@ -150,9 +159,10 @@ shadcn CLI strips leading comments during copy-in.
 
 Group by file. Each finding: `file:line` · rule · suggested fix · severity.
 
-- **error** — a hardcoded visual value, an accessibility violation, or an edited copied-in component.
+- **error** — a hardcoded visual value, an accessibility violation, retired vocabulary, or an
+  unintended edit to a copied-in component.
 - **warning** — raw HTML where a component exists, a missing state, an off-system utility with a
-  working fallback.
+  working fallback, a deliberately edited (now owned) copied-in component.
 - **info** — a component with an available update worth a deliberate `--diff` review.
 
 Never auto-fix. Report, and let the owner decide.

package/skills/vegastack-design-system/SKILL.md

@@ -20,7 +20,7 @@ live contract for any single component is its page at
 writes:
 
 - **Retired, with no drop-in:** `IconButton` → `Button size="icon*"` · `OTPInput` → `InputOTP` ·
-  `PasswordInput` → an `InputGroup` composition · `CheckboxGroup` → `FieldSet` + `Checkbox` ·
+  `CheckboxGroup` → `FieldSet` + `Checkbox` ·
   `FieldInline` → `EditableCell` · `Segmented` → a joined `ToggleGroup` · `SplitButton` → a
   `ButtonGroup` composition · `ProgressIndicator` → `Progress` + `Spinner` · `OnboardingChecklist` →
   the `onboarding-01` block. The ten marketing components were deleted outright.
@@ -209,7 +209,29 @@ contract.
 - Hand-roll a removable pill, or a `role="status"` live region with its own sequence counter.
 - Give a form control a fixed width (`w-56`, `w-64`) — it reads fine on the page it was tuned for
   and overflows at 320px. Constrain the parent instead.
+- Write an arbitrary text size (`text-[13px]`, `text-[0.8rem]`, `text-[2rem]/9`). It bypasses the
+  `--text-*` namespace, so it receives neither the ramp's line-height nor its letter-spacing, and
+  lint rejects it. Take the nearest ramp step. Likewise no local `tracking-*` and no `uppercase`.
+- Draw a surface edge with a ring (`ring-1 ring-foreground/10`). Cards and floating surfaces use
+  `border border-border` (BRD-1); lint rejects the ring.
 - Expect a compatibility shim from before the reset. There is none — see the migration guide.
+- Write retired vocabulary. It compiles to **nothing** — no build error, no type error — so a heading
+  silently renders as body text. `vegastack-design doctor` scans your source and lists every
+  occurrence with `file:line`; run it after any upgrade or generated change.
+
+  | Retired                                                    | Write instead                                                                       |
+  | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+  | `text-h1` · `text-h2` · `text-h3` · `text-h4`              | `text-3xl` · `text-2xl` · `text-lg` + `font-semibold`; `text-base font-medium`      |
+  | `text-label` · `text-label-sm` · `text-strong`             | `text-sm font-medium` · `text-xs font-medium` · `text-sm font-semibold`             |
+  | `text-mono-label` · `text-code` · `text-code-sm`           | `text-xs font-medium` (a label is sans) · `font-mono text-sm` · `font-mono text-xs` |
+  | `text-display-{sm,md,lg,xl}`                               | `text-4xl` · `text-5xl` · `text-6xl` · `text-7xl`                                   |
+  | `bg-{destructive,success,warning,info}-subtle`             | `bg-destructive/10` (the family at `/10`), `-text` ink on it                        |
+  | `--alpha-*` · `--opacity-*`                                | the literal: `bg-foreground/10`, `opacity-50`                                       |
+  | `--z-*`                                                    | `z-10` (raised) · `z-50` (every overlay; DOM order decides)                         |
+  | `shadow-overlay` · `backdrop-blur-glass`                   | `shadow-md` (popover) / `shadow-lg` (modal) · delete it                             |
+  | `icon-button` · `segmented`                                | `Button size="icon"` + `aria-label` · joined `ToggleGroup`                          |
+  | `progress-indicator` · `field-inline` · `floating-surface` | `Progress` / `Spinner` · `EditableCell` · `Popover`                                 |
+  | `section-header` · `sonner`                                | your own heading markup · `toast` (`toast.add({ title })`)                          |
 
 ## Reference
 

package/skills/vegastack-design-system/references/components.md

@@ -3,7 +3,7 @@
 <!-- GENERATED — do not hand-edit. Regenerated from the design system's component contract,
      which is the authority for membership and counts. -->
 
-**110 components**, plus 467 animated-icon items, 11 hooks (`use-animation-replay`, `use-announcer`, `use-drag-reorder`, `use-file-drop`, `use-inline-edit`, `use-list-nav`, `use-media-query`, `use-mobile`, `use-modal-inert`, `use-overflow`, `use-platform`), 32 starter blocks (`app-shell-01`, `board-01`, `dashboard-01`, `login-01`, `login-02`, `login-03`, `login-04`, `login-05`, `onboarding-01`, `preview-03`, `settings-01`, `sidebar-01`, `sidebar-02`, `sidebar-03`, `sidebar-04`, `sidebar-05`, `sidebar-06`, `sidebar-07`, `sidebar-08`, `sidebar-09`, `sidebar-10`, `sidebar-11`, `sidebar-12`, `sidebar-13`, `sidebar-14`, `sidebar-15`, `sidebar-16`, `signup-01`, `signup-02`, `signup-03`, `signup-04`, `signup-05`), 68 chart blocks across 7 families, and 2 data libs (`geo-data`, `drag-item`) — 690 registry items in total.
+**112 components**, plus 467 animated-icon items, 11 hooks (`use-animation-replay`, `use-announcer`, `use-drag-reorder`, `use-file-drop`, `use-inline-edit`, `use-list-nav`, `use-media-query`, `use-mobile`, `use-modal-inert`, `use-overflow`, `use-platform`), 32 starter blocks (`app-shell-01`, `board-01`, `dashboard-01`, `login-01`, `login-02`, `login-03`, `login-04`, `login-05`, `onboarding-01`, `preview-03`, `settings-01`, `sidebar-01`, `sidebar-02`, `sidebar-03`, `sidebar-04`, `sidebar-05`, `sidebar-06`, `sidebar-07`, `sidebar-08`, `sidebar-09`, `sidebar-10`, `sidebar-11`, `sidebar-12`, `sidebar-13`, `sidebar-14`, `sidebar-15`, `sidebar-16`, `signup-01`, `signup-02`, `signup-03`, `signup-04`, `signup-05`), 68 chart blocks across 7 families, and 2 data libs (`geo-data`, `drag-item`) — 692 registry items in total.
 
 Install any of them with `shadcn add @vegastack/<name>`. Animated icons install as
 `@vegastack/icon-<name>`; the bare name is reserved for components, so a component whose name
@@ -37,6 +37,7 @@ starts with `icon-` is a component and never an icon.
 - **`label`** — A styled native label for form controls.
 - **`native-select`** — The platform <select>, tokenized — the OS picker on mobile, with option groups.
 - **`number-field`** — Locale-aware numeric input on Base UI's NumberField in upstream's InputGroup chrome, with full-height flanking steppers.
+- **`password-input`** — A password field with a show/hide toggle, composed from InputGroup, forwarding native input props and the ref to the inner input.
 - **`radio-group`** — Mutually-exclusive options with arrow-key navigation and a 24px invisible hit area (A11Y-2).
 - **`region-select`** — A searchable picker of states/provinces for a country, with a free-text fallback for countries with no subdivisions. A thin wrapper over SearchableSelect fed by the geo-data item.
 - **`search-input`** — A token-safe search field with a consistent clear action and controlled or uncontrolled native input semantics.
@@ -77,6 +78,7 @@ starts with `icon-` is a component and never an icon.
 
 - **`data-grid`** — The full-parity grid — TanStack-sorted multi-key sort, column picker with responsive revelation, collapsible grouping, keyboard-continuous load-more, opt-in virtualization, and an APG grid keyboard layer with inline cell editing.
 - **`data-list`** — A generic, typed data table — configurable columns, row selection, sortable headers, plus loading and empty states.
+- **`data-list-pager`** — A controlled paging footer for DataList — a tabular-numeral range summary, a rows-per-page Select, and a windowed Pagination that hides on a single page.
 - **`data-table-parts`** — The chrome DataList and DataGrid share — sort header, selection cells, skeleton rows, the empty row, column class rules, and the selection/sort/controlled-state hooks.
 - **`filter-bar`** — A row of removable filter chips, an "Add filter" dropdown, and an optional search input — for list and table filter toolbars.
 - **`filter-bar-managed`** — The stateful nested and/or filter builder — host-injected field grammar (vocabulary + per-type value editors), depth and condition caps, focus-managed removal, and a removable FilterChip summary.