@vegastack/design 0.2.0 → 0.3.0

package/bin/check-updates.mjs

@@ -653,19 +653,38 @@ export async function main(argv) {
     installed = installed.filter((c) => res.some((re) => re.test(c.name)));
   }
   if (installed.length === 0) {
+    // `--fail-on-update` is the CI drift gate. Exiting 0 here would make it FAIL OPEN: a project
+    // whose components live outside the default path (any monorepo, any package-based layout, or a
+    // wrong `--dir`) would get a permanently green gate that checked nothing at all. Zero components
+    // under an explicit gate is a misconfiguration, not a clean bill of health — say so and fail.
+    // Without the gate flag this stays informational and exits 0, since "no components yet" is a
+    // legitimate state for a project mid-setup.
+    const gateOnEmpty = opts.failOnUpdate === true;
     if (opts.json)
       console.log(
         JSON.stringify(
-          { registry: idxUrl, checked: 0, updates: 0, items: [] },
+          {
+            registry: idxUrl,
+            checked: 0,
+            updates: 0,
+            items: [],
+            ...(gateOnEmpty ? { error: "no-components-found" } : {}),
+          },
           null,
           2,
         ),
       );
+    else if (gateOnEmpty)
+      console.error(
+        `✗ no VegaStack components found in ${terminalText(dir)}, but --fail-on-update was set.\n` +
+          `  A drift gate that scans nothing passes vacuously, so this is an error, not a pass.\n` +
+          `  Point it at the right directory (\`--dir <path>\`) or drop --fail-on-update.`,
+      );
     else
       console.log(
         `No VegaStack components found in ${terminalText(dir)}. (Add some with \`shadcn add @vegastack/<name>\`.)`,
       );
-    return 0;
+    return gateOnEmpty ? 1 : 0;
   }
 
   const aliases = componentsJson?.aliases ?? {};

package/bin/doctor.mjs

@@ -0,0 +1,332 @@
+// `vegastack-design doctor` — check a consuming project's setup.
+//
+// Motivated by a real consumer failure (VegaStack CRM, 2026-07-27): a missing
+// `@tailwindcss/postcss` plugin produces two different, equally misleading results.
+// Under Turbopack the build dies with `Can't resolve 'tw-animate-css'`, naming a
+// dependency that is installed and fine. Under webpack the build SUCCEEDS, the token
+// theme lands (it is literal CSS inside preset.css), and zero utility classes are
+// generated — so the app renders with correct colours and no spacing or layout, which
+// reads as "the design system is broken".
+//
+// A human will not attribute either symptom correctly, which is exactly why this is a
+// command and not a paragraph in a guide. Every check here maps to a documented failure
+// mode in the Troubleshooting guide.
+//
+// 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";
+
+const POSTCSS_CONFIGS = [
+  "postcss.config.mjs",
+  "postcss.config.js",
+  "postcss.config.cjs",
+  "postcss.config.ts",
+  "postcss.config.json",
+  ".postcssrc",
+  ".postcssrc.json",
+];
+
+const CSS_SEARCH_DIRS = [
+  "app",
+  "src/app",
+  "src/styles",
+  "styles",
+  "src",
+  "apps",
+];
+
+const USAGE = `
+Usage: vegastack-design doctor [options]
+
+Checks a consuming project's VegaStack setup and reports what is wrong and how to fix it.
+
+Options:
+  --dir <path>   Project root to inspect (default: the current directory)
+  -h, --help     Show this help
+
+Exit codes: 0 = no problems · 1 = at least one failure · 2 = bad usage
+`.trim();
+
+/** Collect .css files under a few conventional roots, shallowly, without walking node_modules. */
+function findCssFiles(root, max = 200) {
+  const out = [];
+  const seen = new Set();
+  const walk = (dir, depth) => {
+    if (out.length >= max || depth > 4) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (out.length >= max) return;
+      if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+      const full = join(dir, e.name);
+      if (seen.has(full)) continue;
+      seen.add(full);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (e.name.endsWith(".css")) out.push(full);
+    }
+  };
+  for (const d of CSS_SEARCH_DIRS) {
+    const full = join(root, d);
+    if (existsSync(full) && statSync(full).isDirectory()) walk(full, 0);
+  }
+  return out;
+}
+
+/** CSS comments frequently *mention* the thing we are looking for — strip them before matching. */
+function stripCssComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+/** Nearest ancestor of `from` (inclusive) that has a package.json, bounded by `root`. */
+function nearestPackageRoot(from, root) {
+  let dir = from;
+  for (let i = 0; i < 8; i += 1) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    if (dir === root) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return root;
+}
+
+function readIfExists(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function readJson(path) {
+  const raw = readIfExists(path);
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function main(argv = []) {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    console.log(USAGE);
+    return 0;
+  }
+  const dirFlag = argv.indexOf("--dir");
+  if (dirFlag !== -1 && argv[dirFlag + 1] == null) {
+    console.error("doctor: --dir requires a path\n");
+    console.error(USAGE);
+    return 2;
+  }
+  const root = dirFlag === -1 ? process.cwd() : argv[dirFlag + 1];
+
+  if (!existsSync(root)) {
+    console.error(`doctor: no such directory: ${root}`);
+    return 2;
+  }
+
+  const results = [];
+  const ok = (name, detail) => results.push({ level: "ok", name, detail });
+  const warn = (name, detail, fix) =>
+    results.push({ level: "warn", name, detail, fix });
+  const fail = (name, detail, fix) =>
+    results.push({ level: "fail", name, detail, fix });
+
+  // ---- 1. the design system is installed -------------------------------------------------
+  const pkg = readJson(join(root, "package.json"));
+  const deps = {
+    ...(pkg?.dependencies ?? {}),
+    ...(pkg?.devDependencies ?? {}),
+  };
+  const designInstalled =
+    "@vegastack/design" in deps ||
+    existsSync(join(root, "node_modules", "@vegastack", "design"));
+
+  if (designInstalled) {
+    const installed = readJson(
+      join(root, "node_modules", "@vegastack", "design", "package.json"),
+    );
+    ok(
+      "@vegastack/design installed",
+      installed?.version
+        ? `v${installed.version}`
+        : (deps["@vegastack/design"] ?? ""),
+    );
+  } else {
+    fail(
+      "@vegastack/design installed",
+      "not found in package.json or node_modules",
+      "pnpm add @vegastack/design",
+    );
+  }
+
+  // ---- 2. the preset is imported ----------------------------------------------------------
+  const cssFiles = findCssFiles(root);
+  const presetFiles = cssFiles.filter((f) =>
+    (readIfExists(f) ?? "").includes("@vegastack/design/preset.css"),
+  );
+
+  if (presetFiles.length > 0) {
+    ok(
+      "preset.css imported",
+      presetFiles.map((f) => relative(root, f)).join(", "),
+    );
+  } else {
+    fail(
+      "preset.css imported",
+      cssFiles.length === 0
+        ? "no .css files found under app/, src/, or styles/"
+        : `none of ${cssFiles.length} .css file(s) import it`,
+      'add `@import "@vegastack/design/preset.css";` to your global stylesheet',
+    );
+  }
+
+  // ---- 3. THE BIG ONE: the Tailwind PostCSS plugin ----------------------------------------
+  // Without it Tailwind never runs: no utilities are generated, and depending on the bundler
+  // you either get a misleading `Can't resolve 'tw-animate-css'` or a silently unstyled app.
+  // In a workspace the config correctly lives in the APP package, not the repo root, so search
+  // every package that owns a preset-importing stylesheet as well as the root itself.
+  const postcssRoots = [
+    root,
+    ...presetFiles.map((f) => nearestPackageRoot(dirname(f), root)),
+  ].filter((d, i, a) => a.indexOf(d) === i);
+  const postcssPath = postcssRoots
+    .flatMap((d) => POSTCSS_CONFIGS.map((n) => join(d, n)))
+    .find(existsSync);
+  const postcssOwnerPkg = postcssPath
+    ? readJson(join(dirname(postcssPath), "package.json"))
+    : null;
+  const postcssInline = (postcssOwnerPkg ?? pkg)?.postcss
+    ? JSON.stringify((postcssOwnerPkg ?? pkg).postcss)
+    : null;
+  const postcssSource = postcssPath ? readIfExists(postcssPath) : postcssInline;
+  const hasPlugin =
+    postcssSource != null && postcssSource.includes("@tailwindcss/postcss");
+
+  if (hasPlugin) {
+    ok(
+      "Tailwind PostCSS plugin",
+      postcssPath ? relative(root, postcssPath) : "package.json#postcss",
+    );
+  } else if (postcssSource != null) {
+    fail(
+      "Tailwind PostCSS plugin",
+      `${postcssPath ? relative(root, postcssPath) : "package.json#postcss"} exists but does not configure @tailwindcss/postcss`,
+      'add `"@tailwindcss/postcss": {}` to its plugins',
+    );
+  } else {
+    fail(
+      "Tailwind PostCSS plugin",
+      "no PostCSS config found — Tailwind will not run, so NO utility classes are generated",
+      'pnpm add -D @tailwindcss/postcss, then create postcss.config.mjs:\n     const config = { plugins: { "@tailwindcss/postcss": {} } };\n     export default config;',
+    );
+  }
+
+  // ---- 4. no duplicate Tailwind import ----------------------------------------------------
+  // preset.css already imports Tailwind; a second bare import is the documented cause of
+  // "utilities exist but everything is unstyled".
+  const duplicateTailwind = presetFiles.filter((f) => {
+    const src = stripCssComments(readIfExists(f) ?? "");
+    return /@import\s+["']tailwindcss["']/.test(src);
+  });
+  if (duplicateTailwind.length > 0) {
+    warn(
+      "no duplicate Tailwind import",
+      `${duplicateTailwind.map((f) => relative(root, f)).join(", ")} also imports "tailwindcss" directly`,
+      "remove it — preset.css imports Tailwind itself",
+    );
+  } else if (presetFiles.length > 0) {
+    ok("no duplicate Tailwind import", "preset.css is the only Tailwind entry");
+  }
+
+  // ---- 5. registry access is configured ---------------------------------------------------
+  let componentsJsonPath = join(root, "components.json");
+  let componentsJson = readJson(componentsJsonPath);
+  if (componentsJson == null) {
+    // Walk up: in a workspace the canonical components.json commonly sits at the repo root.
+    let dir = root;
+    for (let i = 0; i < 5 && componentsJson == null; i += 1) {
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+      const candidate = join(dir, "components.json");
+      if (existsSync(candidate)) {
+        componentsJsonPath = candidate;
+        componentsJson = readJson(candidate);
+      }
+    }
+  }
+  if (componentsJson == null) {
+    warn(
+      "registry configured",
+      "no components.json here or in any parent directory",
+      "see the Quickstart — needed before `shadcn add @vegastack/<name>`",
+    );
+  } else if (componentsJson.registries?.["@vegastack"] == null) {
+    fail(
+      "registry configured",
+      'components.json has no `registries["@vegastack"]` entry',
+      "add the registries block from the Quickstart",
+    );
+  } else {
+    ok(
+      "registry configured",
+      `${relative(root, componentsJsonPath) || "components.json"} declares @vegastack`,
+    );
+  }
+
+  // ---- 6. monorepo hint --------------------------------------------------------------------
+  // Source detection is relative to the CSS file, so components living outside the app's tree
+  // compile to nothing unless declared. Only worth saying when this actually looks like a workspace.
+  const isWorkspace =
+    existsSync(join(root, "pnpm-workspace.yaml")) ||
+    Array.isArray(pkg?.workspaces) ||
+    pkg?.workspaces != null;
+  if (isWorkspace && presetFiles.length > 0) {
+    const declaresSource = presetFiles.some((f) =>
+      (readIfExists(f) ?? "").includes("@source"),
+    );
+    if (declaresSource) {
+      ok("monorepo sources declared", "@source directives present");
+    } else {
+      warn(
+        "monorepo sources declared",
+        "workspace detected but no @source directive — components outside this app's tree will compile to nothing",
+        'add e.g. `@source "../../../../packages/ui/src";` next to the preset import',
+      );
+    }
+  }
+
+  // ---- report -------------------------------------------------------------------------------
+  const glyph = { ok: "✓", warn: "!", fail: "✗" };
+  console.log("");
+  for (const r of results) {
+    console.log(
+      `  ${glyph[r.level]} ${r.name}${r.detail ? ` — ${r.detail}` : ""}`,
+    );
+    if (r.fix) console.log(`     fix: ${r.fix}`);
+  }
+
+  const failures = results.filter((r) => r.level === "fail").length;
+  const warnings = results.filter((r) => r.level === "warn").length;
+  console.log("");
+  if (failures > 0) {
+    console.log(
+      `  ${failures} problem(s), ${warnings} warning(s). See https://design.vegastack.com/docs/guides/troubleshooting`,
+    );
+    return 1;
+  }
+  console.log(
+    warnings > 0
+      ? `  setup looks correct (${warnings} warning(s)).`
+      : "  setup looks correct.",
+  );
+  return 0;
+}

package/bin/vegastack-design.mjs

@@ -5,6 +5,7 @@
 //   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).
 //
 // 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
@@ -23,6 +24,7 @@ Commands:
   check-updates     Show which copied-in components have newer registry versions
   verify            Verify a registry item's integrity (pre/post \`shadcn add\`)
   skills            Install the VegaStack agent skills (Claude Code + Codex)
+  doctor            Check this project's setup and report what is wrong
 
 Run \`vegastack-design <command> --help\` for command options.
   -v, --version     Print version
@@ -61,6 +63,12 @@ if (cmd === "skills") {
   process.exit(main(rest));
 }
 
+if (cmd === "doctor") {
+  // imported in-process (our own code, read-only, no network, no credentials)
+  const { main } = await import(new URL("./doctor.mjs", HERE).href);
+  process.exit(main(rest));
+}
+
 if (cmd === "verify") {
   // spawn the standalone verifier untouched; mark the dispatch so it skips its deprecation notice.
   const verifier = fileURLToPath(new URL("./verify-registry-item.mjs", HERE));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/design",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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": {

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

@@ -81,7 +81,9 @@ contract.
 - **Compound parts import flat** — `import { DialogTrigger, DialogContent }`. Sub-property access
   (`<Dialog.Trigger>`) only works inside a `'use client'` file, because across the RSC boundary the
   compound is a client-reference proxy and the sub-property is `undefined`.
-- **Polymorphism** uses Base UI's `render` prop, never Radix's `asChild`.
+- **Polymorphism** uses Base UI's `render` prop, never Radix's `asChild`. When `render` swaps a
+  button-like component's element for a non-button (e.g. `Button render={<Link/>}`), also pass
+  `nativeButton={false}` — Base UI warns otherwise.
 
 ## Do / Don't
 

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. -->
 
-**96 components**, plus 439 animated-icon items, 2 hooks (`use-animation-replay`, `use-mobile`), and 1 starter block (`dashboard-01`) — 538 registry items in total.
+**108 components**, plus 439 animated-icon items, 6 hooks (`use-animation-replay`, `use-drag-reorder`, `use-file-drop`, `use-list-nav`, `use-mobile`, `use-platform`), and 1 starter block (`dashboard-01`) — 554 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 `icon-button` is the
@@ -23,15 +23,19 @@ component and never an icon.
 
 - **`auto-save-input`** — An input that debounces edits and persists them via an async onSave, with an inline idle/saving/saved/error status.
 - **`checkbox`** — A binary (or tri-state) toggle — checked, unchecked, indeterminate, disabled, built on Base UI Checkbox.
+- **`chip-input`** — Free-token entry field — Enter/comma/paste commits chips, Backspace removes, per-chip validation marks invalid entries instead of dropping them. Combobox field chrome + real Tag chips.
 - **`color-picker`** — A swatch-triggered popover presenting a grid of preset colors — pick one, fire onValueChange, mark the selection.
 - **`combobox`** — A filterable, keyboard-navigable listbox behind a text input — type-to-filter, grouped items, async status, and a multi-select chip mode.
 - **`country-select`** — A searchable country combobox returning the ISO 3166-1 alpha-2 code, with flag + name. Built on Combobox.
 - **`date-picker`** — Pick a single date or a date range from a calendar popover — token-styled, keyboard-navigable, with optional quick presets.
+- **`dropzone`** — File acquisition surface — drop, click-to-browse, and paste — as a thin shell over use-file-drop; the surface is the named focusable control over a hidden picker-bridge input; data-dragging/data-drag-invalid styling flags.
+- **`editable-cell`** — Inline-editable value with an async commit lifecycle — optimistic display, saving/saved/error status, revert on a rejected write, and a typed text/select/custom editor registry.
 - **`emoji-picker`** — A popover with a searchable, category-grouped grid of emoji that returns the selected character via onSelect (curated set, not full Unicode).
 - **`field`** — A form-field wrapper — label, inline label action, description, and error/success message, built on Base UI Field.
 - **`field-inline`** — Click-to-edit text — displays a value, swaps to a focused input on click, commits on Enter or blur, cancels on Escape.
 - **`input`** — A styled Base UI input — all input types, Field state data attributes, error and disabled states, focus-visible ring, and optional prefix/suffix addons.
 - **`label`** — A styled native label for form controls — htmlFor association, disabled dimming, optional required indicator.
+- **`number-field`** — Locale-aware numeric input on Base UI's NumberField in Input's field chrome — Intl formatting (money is a format prop), min/max/step, keyboard stepping, wheel scrub, full-height steppers.
 - **`otp-input`** — A multi-slot one-time-passcode input — keyboard navigation, paste distribution, masking, disabled, built on Base UI OTP Field.
 - **`password-input`** — A password field with a show/hide eye toggle and an optional live requirements checklist.
 - **`radio-group`** — A set of mutually-exclusive options — single selection, arrow-key navigation, disabled, built on Base UI Radio Group.
@@ -64,13 +68,17 @@ component and never an icon.
 - **`relative-time`** — Render a date as a human-relative string ("2 hours ago", "yesterday") with native Intl.RelativeTimeFormat — self-updating, with an absolute-date tooltip.
 - **`status-icon`** — A small status indicator icon — todo, in progress, blocked, done — each mapping to a lucide icon and semantic color.
 - **`table`** — Styled semantic table primitives — a scrollable container plus header, body, footer, row, head, cell, caption.
+- **`timeline`** — Rail geometry for chronological records — a continuous connector with a node per entry. Rows compose Item parts; separators render through Marker; entries carry content-visibility render skipping.
 - **`truncated-text`** — Truncate text to one line or N lines with an ellipsis, revealing the full text in a tooltip only when it overflows.
 
 ## Data
 
+- **`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.
 - **`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.
 - **`property-list`** — Record-facts rows: an icon+label column beside a value column, as an accessible definition list.
+- **`sortable-list`** — Reorderable rows on ItemGroup/Item via use-drag-reorder — pointer drag with drop indicators, keyboard move mode, a lossless Move menu, and server-refusable moves. Controlled; the host owns the order.
 
 ## Overlay
 
@@ -81,6 +89,7 @@ component and never an icon.
 - **`hover-card`** — A rich preview panel that opens on hover or focus — interactive content, four directions, forgiving delays.
 - **`popover`** — A click-triggered floating panel for arbitrary content — positioning, an optional arrow, and built-in dismiss.
 - **`sheet`** — A dialog that slides in from a screen edge — four sides, header/footer layout, focus trapping, animated slide.
+- **`shortcut-overlay`** — The ?-triggered dialog listing keyboard shortcuts, rendered from a declaration registry (keys, label, category, when) — grouped, filterable, platform-aware via use-platform + Kbd.
 - **`tooltip`** — A floating label on hover or focus — smart shared delay, rich content, optional keyboard hints, collision-aware positioning.
 
 ## Navigation
@@ -91,10 +100,12 @@ component and never an icon.
 - **`page-header`** — The standardized header at the top of a page — back button, breadcrumb trail, title, description, actions, secondary menu, and a favorite star.
 - **`pagination`** — Page navigation — previous/next, numbered page links, an ellipsis for long ranges, and the active page.
 - **`sidebar`** — A collapsible app navigation rail — header/content/footer, labelled groups, menu items with active state, and an expand/collapse trigger.
+- **`stepper`** — A bounded linear process as an ordered list — complete/current/upcoming/error states on StatusIcon's vocabulary, aria-current=step, advance-gating message, focus follows the process.
 - **`tabs`** — Layered content sections — line or pill variants, optional icons and count badges, horizontal or vertical, full keyboard navigation.
 
 ## Feedback
 
+- **`action-bar`** — Floating contextual bar — status region + action children, CSS-only enter/exit, raised band. Bulk selection, unsaved changes, and batch progress are recipes over it.
 - **`alert`** — A status banner — five semantic variants, an optional icon, and an optional dismiss button.
 - **`progress`** — A determinate horizontal progress bar for measurable, ongoing tasks — built on Base UI Progress.
 - **`progress-indicator`** — A compact circular pie-fill progress indicator (0–100%) — a server-safe SVG glyph in circle or squircle shapes.
@@ -106,6 +117,7 @@ component and never an icon.
 ## Layout
 
 - **`app-shell`** — The shared dashboard layout — a skip-linked sidebar + header + scrollable main region, composing Sidebar/SidebarTrigger into one reusable, hash-tracked shell.
+- **`board`** — Kanban columns over use-drag-reorder — content/chrome split (host renders card content only), pointer drag, keyboard move mode + roving focus, lossless per-card Move menu with lock reasons, server-refusable moves, collapsed lanes, Empty-bordered drop targets.
 - **`resizable`** — Draggable, keyboard-resizable split panes — horizontal or vertical, nestable, with an optional collapsible panel. Built on react-resizable-panels.
 - **`scroll-area`** — A scroll container with custom, auto-hiding scrollbars — dual-axis, token-styled, built on Base UI ScrollArea.
 - **`separator`** — A thin rule dividing content — horizontal or vertical, decorative by default, built on Base UI.