@calibrate-ds/cli 0.1.88 → 0.1.90

package/README.md

@@ -150,7 +150,7 @@ ptb stamp component Button # mark Button as implemented against the current desi
 
 ## MCP Server — AI IDE Integration
 
-PTB exposes 22 tools over a stdio MCP server. Your AI IDE can query component design context, run scans, generate code, and manage stamps — all from chat. Everything you can do in the terminal, you can do from chat.
+PTB exposes 23 tools over a stdio MCP server. Your AI IDE can query component design context, run scans, generate code, and manage stamps — all from chat. Everything you can do in the terminal, you can do from chat.
 
 ### Available tools
 
@@ -768,6 +768,6 @@ See [PTB.md](./PTB.md) for architecture, type definitions, the generator interfa
 ```bash
 pnpm install
 pnpm build
-pnpm test            # 593 tests across core, generator, and CLI
+pnpm test            # 609 tests across core, generator, and CLI
 node apps/cli/dist/index.js --help
 ```

package/dist/commands/init.js

@@ -562,7 +562,7 @@ export function createInitCommand() {
         console.log(`       \x1b[36mptb export context\x1b[0m       \x1b[2m— write .ptb/context/ files for AI IDEs (commit these)\x1b[0m`);
         console.log(`       \x1b[2mNext.js App Router? Add \x1b[0m\x1b[33m"useClient": true\x1b[0m\x1b[2m to the \x1b[0m\x1b[33mgeneration\x1b[0m\x1b[2m section of ptb.config.json\x1b[0m`);
         console.log(`       \x1b[2mso every generated component emits \x1b[0m\x1b[36m"use client"\x1b[0m\x1b[2m as its first line.\x1b[0m\n`);
-        console.log(`  ${step++}. Connect your AI IDE via MCP — PTB exposes 22 tools (scan, generate, inspect, stamp, and more):\n`);
+        console.log(`  ${step++}. Connect your AI IDE via MCP — PTB exposes 23 tools (scan, generate, inspect, stamp, and more):\n`);
         console.log(`       \x1b[1mClaude Code:\x1b[0m  already configured via \x1b[36m.mcp.json\x1b[0m — just restart Claude Code.\n`);
         console.log(`       \x1b[1mOther IDEs\x1b[0m (Cursor, Windsurf, Antigravity, VS Code):`);
         console.log(`       Once Claude Code is connected, ask in chat:  \x1b[36m"set up MCP for cursor"\x1b[0m`);

package/dist/mcp/tools/action-tools.js

@@ -280,15 +280,18 @@ criteria, and recommended build order.
 
 TOKEN AUTHORITY — what to trust, what to verify:
 - PTB's --ptb-* cssVar names are authoritative for token identity. Always emit them.
-- If tokenConflicts is present in the response, PTB's resolved token hex diverges from
-  the raw Figma fill. These are low-confidence — verify with Figma (get_variable_defs or
-  get_screenshot) and use: var(--ptb-token, <figma-verified-hex>) as the CSS fallback.
-- PTB cannot verify exact visual appearance. Use Figma for colors/spacing when in doubt.
+- If tokenConflicts is present, PTB's resolved token hex diverges from the raw scanned
+  fill. Each conflict includes rawValue — the hex the design actually renders, captured
+  by PTB's own scan. Trust rawValue as the visual ground truth and emit:
+  var(--ptb-token, <rawValue>) as the CSS fallback.
+- For exact visual appearance, read the scan thumbnail at thumbnailPath (and per-variant
+  thumbnails) — it is PTB's captured ground truth for colors, spacing, and arrangement.
 
-DIVISION OF LABOR WITH FIGMA MCP (composite workflow — most accurate):
-  PTB  → token names, dependency graph, variant axes, state/content contracts (read contextFile)
-  Figma → exact hex values, spacing, visual arrangement (get_variable_defs, get_screenshot)
-  Map: Figma hex  →  get_token(hex)  →  --ptb-* cssVar name → emit both together
+EVERYTHING YOU NEED IS IN PTB (no external tools required):
+  token names, dependency graph, variant axes, state/content contracts → read contextFile
+  exact rendered hex → tokenConflicts[].rawValue (from the scan)
+  visual arrangement/spacing → the scan thumbnail at thumbnailPath
+  hex → token name → get_token(hex)
 
 TYPICAL WORKFLOW:
 1. Call start_work("<name>") — read blockedBy and tokenConflicts first
@@ -296,6 +299,10 @@ TYPICAL WORKFLOW:
 3. Read contextFile for the full implementation brief (it contains promptText, the
    render tree, and variantDiffs — these are intentionally NOT inlined in this
    response because they exceed the tool-call size limit on large components)
+3b. For a multi-variant component set, call get_variant_tokens("<name>") for the
+   compact per-variant build matrix — every variant's resolved --ptb-* bindings,
+   colors, radius, padding, and gap in one small response. Prefer this over
+   excavating variantDiffs from the contextFile.
 4. Implement the requested component
 5. Call submit_work("<name>") when done`, { name: z.string().describe("Component to start working on, e.g. 'SearchBar'") }, async ({ name }) => {
             let ctx;
@@ -398,11 +405,17 @@ TYPICAL WORKFLOW:
                                     options: ax.options ?? [],
                                     defaultValue: ax.defaultValue,
                                 })),
+                                // B-5: emit real binding data, not just slot names. The old map
+                                // read b.token/b.cssVar/b.collection — fields that don't exist on
+                                // a TokenBinding — so every entry serialized to just {slot}. The
+                                // actual value (rawValue) and token identity live on resolvedToken.
                                 tokenBindings: (context.tokenBindings ?? []).map((b) => ({
                                     slot: b.slot,
-                                    token: b.token,
-                                    cssVar: b.cssVar,
-                                    collection: b.collection,
+                                    rawValue: b.rawValue ?? null,
+                                    token: b.resolvedToken?.name ?? b.boundToken?.name ?? null,
+                                    cssVar: b.resolvedToken?.cssVariable ?? null,
+                                    collection: b.resolvedToken?.collection?.name ?? null,
+                                    bound: !!b.boundToken,
                                 })),
                                 dependencies: context.dependencies.map((d) => ({
                                     name: d.name,
@@ -421,8 +434,8 @@ TYPICAL WORKFLOW:
                                 instructions: promptPackage.instructions,
                                 structureSummary: promptPackage.structureSummary,
                                 // Token conflicts: slots where PTB's resolved token hex differs from
-                                // the raw Figma fill. Always low-confidence — verify against Figma
-                                // (get_screenshot / get_variable_defs) before trusting the token name.
+                                // the raw scanned fill. Each carries rawValue (what the design renders,
+                                // from PTB's scan) — trust that and emit var(--ptb-token, <rawValue>).
                                 ...(context.tokenConflicts?.length
                                     ? { tokenConflicts: context.tokenConflicts }
                                     : {}),
@@ -571,13 +584,13 @@ Returns the design context (variants, tokens, slots, contracts, render tree) for
 component PLUS a dependency check: which child components this one uses and whether they are
 already implemented in ptb.lock.
 
-TOKEN AUTHORITY — what to trust, what to verify:
+TOKEN AUTHORITY — what to trust:
 - PTB's --ptb-* cssVar names are authoritative. Always use them in emitted CSS.
-- If tokenConflicts is present, PTB's resolved token hex diverges from the raw Figma fill
-  for those slots. Cross-check with Figma (get_variable_defs / get_screenshot) and emit the
-  correct hex as a literal fallback: var(--ptb-token, <figma-hex>).
-- PTB does NOT know exact pixel positions, image assets, or precise spacing when tokens are
-  unresolved ("unknown"). Use Figma for those facts.
+- If tokenConflicts is present, PTB's resolved token hex diverges from the raw scanned fill
+  for those slots. Each conflict carries rawValue — the hex the design actually renders,
+  from PTB's scan. Emit it as the literal fallback: var(--ptb-token, <rawValue>).
+- For exact visual appearance — colors, spacing, image assets, arrangement — read the scan
+  thumbnail at thumbnailPath (and per-variant thumbnails). That is PTB's captured ground truth.
 
 WORKFLOW — follow this exactly:
 1. Check unbuiltDependencies. If any exist, call implement_component for each one in buildOrder first.
@@ -691,11 +704,17 @@ recursively when you call it for that dependency.`, { name: z.string().describe(
                                     options: ax.options ?? [],
                                     defaultValue: ax.defaultValue,
                                 })),
+                                // B-5: emit real binding data, not just slot names. The old map
+                                // read b.token/b.cssVar/b.collection — fields that don't exist on
+                                // a TokenBinding — so every entry serialized to just {slot}. The
+                                // actual value (rawValue) and token identity live on resolvedToken.
                                 tokenBindings: (context.tokenBindings ?? []).map((b) => ({
                                     slot: b.slot,
-                                    token: b.token,
-                                    cssVar: b.cssVar,
-                                    collection: b.collection,
+                                    rawValue: b.rawValue ?? null,
+                                    token: b.resolvedToken?.name ?? b.boundToken?.name ?? null,
+                                    cssVar: b.resolvedToken?.cssVariable ?? null,
+                                    collection: b.resolvedToken?.collection?.name ?? null,
+                                    bound: !!b.boundToken,
                                 })),
                                 dependencies: context.dependencies.map((d) => ({
                                     name: d.name,

package/dist/mcp/tools/component-tools.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { z } from "zod";
-import { getComponentContext } from "@calibrate-ds/core";
+import { getComponentContext, buildVariantTokenMap } from "@calibrate-ds/core";
 function toSlug(name) {
     return name.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -51,16 +51,17 @@ WHAT PTB IS AUTHORITATIVE FOR (trust these without Figma):
 - Variant axes, state contract, interaction contract, slot contract
 - Lifecycle: designHash, stampedHash, workStatus (from ptb.lock)
 
-WHAT PTB CANNOT VERIFY (cross-check with Figma when available):
-- Exact visual appearance — PTB has no rendered reference
+VISUAL GROUND TRUTH (all from PTB's own scan — no external tools needed):
+- Exact visual appearance — read the scan thumbnail at thumbnailPath (and per-variant
+  thumbnails). That is the captured reference for colors, spacing, positions, and assets.
 - tokenConflicts (if present): slots where PTB's resolved token hex diverges from the raw
-  Figma fill. Always low-confidence. Use Figma get_variable_defs or get_screenshot to
-  determine which value is correct, then use PTB's cssVar name with Figma's hex as fallback.
+  scanned fill. Each carries rawValue — the hex the design actually renders. Emit PTB's
+  cssVar name with rawValue as the literal fallback: var(--ptb-token, <rawValue>).
 
-DIVISION OF LABOR WITH FIGMA MCP (composite workflow):
-  PTB  → token names, dependency graph, variant axes, state/content contracts
-  Figma → exact hex values, spacing px, badge positions, image assets (get_variable_defs, get_screenshot)
-  Never deep-read the full render tree just to recover colors — that is Figma's job.`, {
+EVERYTHING YOU NEED IS IN PTB:
+  token names, dependency graph, variant axes, state/content contracts → this response
+  exact rendered hex → tokenConflicts[].rawValue      visual arrangement → thumbnailPath
+  hex → token name → get_token(hex)`, {
             name: z.string().describe("Component display name, e.g. 'Button' or 'Notification Item'"),
             detail: z.enum(["summary", "full"]).optional().default("summary").describe("'summary' (default): compact planning brief — variant axes, token bindings, dependencies, layout, state axis names, contextFile path. " +
                 "'full': complete context with render tree and compressed variant patches."),
@@ -200,6 +201,33 @@ DIVISION OF LABOR WITH FIGMA MCP (composite workflow):
             catch { /* non-fatal */ }
             return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         });
+        server.tool("get_variant_tokens", `Get the compact per-variant token/style build matrix for a component set.
+
+For EVERY variant (all combinations of the variant axes), returns the resolved
+design-system bindings and spacing needed to implement it:
+  - background / text-color / border-color → { cssVar (--ptb-*), value (hex), token }
+  - border-radius, padding, gap             → resolved values (px)
+  - per-node text content, stroke weight + align (inside/outside)
+
+This is the data an agent needs to build all variants WITHOUT reading the large
+context render tree or reconstructing it from variantDiffs. Emit each slot as
+var(<cssVar>, <value>) when cssVar is present; use value directly when it is not.
+Returns variantCount:0 with a note for single (non-set) components.`, { name: z.string().describe("Component set name, e.g. 'ChipsWeb'") }, async ({ name }) => {
+            let ctx;
+            try {
+                ctx = await getContext();
+            }
+            catch (e) {
+                return { content: [{ type: "text", text: e.message }] };
+            }
+            const comp = findComponent(ctx.snapshot, name);
+            if (!comp) {
+                const available = ctx.snapshot.components.map((c) => c.name).slice(0, 15).join(", ");
+                return { content: [{ type: "text", text: `Component '${name}' not found.\nAvailable (first 15): ${available}` }] };
+            }
+            const map = buildVariantTokenMap(comp);
+            return { content: [{ type: "text", text: JSON.stringify(map, null, 2) }] };
+        });
     },
 };
 //# sourceMappingURL=component-tools.js.map

package/dist/mcp/tools/info-tools.js

@@ -3,6 +3,23 @@ import * as path from "node:path";
 import { z } from "zod";
 import { resolveToken } from "@calibrate-ds/core";
 const UPGRADE_CHECKLIST = {
+    "0.1.90": [
+        "BAKE-OFF audit fixes (docs/PTB_VS_FIGMA_BAKEOFF.md). A cold PTB-only vs Figma-only head-to-head exposed that PTB's verifier declined to enforce the one thing PTB uniquely provides: design-system token binding.",
+        "FIX (B-1, the moat gate): verify computed cssVarScore (fraction of the design's bound --ptb-* vars present in the CSS) then NEVER read it — a token-blind component that renders correctly but binds ZERO design tokens PASSED. cssVarScore is now a HARD GATE: cssVarScore === 0 → fail, and tokenScore cannot rescue it. cssVarScore is now surfaced in the run_verify / get_verify_report responses.",
+        "FIX (B-1, naming): tokenScore was misnamed — it measures rendered TEXT content, not token binding. The response now also returns textContentScore (the accurate name); tokenScore is kept as a deprecated alias so nothing breaks.",
+        "FIX (B-2, scaffold CSS): a token-bound border emitted 'border: var(--x, #hex)' — a bare color with no width/style, which is INVALID and dropped, leaving outlined components with no border. Now emits 'border: 1px solid var(...)'. Also: slots that map to the same CSS property (text/fill/iconColor → color) no longer emit a duplicate declaration. Regenerate components (generate-components --force) to pick these up.",
+        "FIX (B-5): start_work's tokenBindings returned just {slot} with no values (it read fields that don't exist on the type). It now returns rawValue, token name, cssVar, collection, and bound flag.",
+        "NEW TOOL (B-3, the cost win): get_variant_tokens(name) returns a compact PRE-RESOLVED per-variant token matrix — for every variant, the --ptb-* binding + value for background/text/border, plus radius/padding/gap/text and stroke weight+align. No more scripting through variantDiffs: ChipsWeb's full 42-variant matrix is ~6k tokens (vs ~86k to read context naively). start_work now points agents to it for multi-variant sets. Restart your MCP server to see the new tool.",
+        "FIX (B-4): Storybook loaded no fonts, so text rendered in a fallback and CAPPED every text component's pixel score (~0.82) regardless of correctness. setup now writes .storybook/preview-head.html loading the design's fonts (from typography.css) via Google Fonts. Re-run Storybook setup / ptb init to get it.",
+        "FIX (B-8): per-variant verify now names how many variants had no reference thumbnail and were skipped (was silently undercounting). FIX (B-9): the primary diff image is retained + its path kept in the verify report, so a low score is inspectable (was deleting all pngs).",
+        "B-7 strokeAlign is now available to the agent via get_variant_tokens (weight+align). Deferred (verified, not changed): B-2 double-padding, B-6 radius alias tier (risky core change), B-10 unbound raw hexes (design-side, not a PTB bug). Restart MCP; regenerate components for the CSS fixes. 609 tests.",
+    ],
+    "0.1.89": [
+        "INDEPENDENCE release — PTB no longer recommends or depends on any external tool. Previously several MCP tool descriptions told the agent to 'cross-check with Figma MCP' (get_variable_defs / get_screenshot) for exact hex and visual truth.",
+        "That guidance was redundant: PTB already has that data from its own scan. tokenConflicts now direct the agent to rawValue — the hex the design actually renders, captured by the scan — with var(--ptb-token, <rawValue>) as the fallback; and the scan thumbnail at thumbnailPath is the visual ground truth for colors/spacing/arrangement.",
+        "Net effect: fewer round-trips, no dependency on a third-party MCP, and the agent gets a concrete value instead of being sent to another tool. No code behavior changed — only agent-facing guidance in start_work / get_component / get_token descriptions and two type comments.",
+        "Restart your IDE's MCP server to pick up the updated tool descriptions. No re-scan. 593 tests.",
+    ],
     "0.1.88": [
         "0.1.87 audit fixes (docs/PTB_0187_REPORT.md). Closes the last functional beta blocker plus the emitter-parity residuals. Six-plus releases, zero regressions.",
         "FIX (NEW-8, open since .79 — was FAILING HARD): start_work's MCP response inlined promptText (100 KB+, 94.7% of the payload), so start_work on a large component-set EXCEEDED the tool-call token limit and the call failed outright. promptText is no longer inlined in the response. The contextFile on disk is UNCHANGED — it still contains promptText and every detail; read the full brief from there (the tool description says so). This unblocks the primary agent entry point.",

package/dist/mcp/tools/token-tools.js

@@ -141,8 +141,9 @@ Accepts:
 
 Returns: collection, tokenName, cssVar (--ptb-* variable), resolvedValue, aliasChain (when present).
 
-PTB owns the token identity map — use hex lookup when Figma's get_variable_defs returns a
-raw color and you need the canonical --ptb-* name instead of guessing the convention.`, { query: z.string().describe("Token name, path, Figma variable name (surface/surface-info-light), or hex color (#E5F3FF)") }, async ({ query }) => {
+PTB owns the token identity map — use hex lookup when you have a raw color (e.g. a
+tokenConflicts rawValue from the scan) and need the canonical --ptb-* name instead of
+guessing the convention.`, { query: z.string().describe("Token name, path, Figma variable name (surface/surface-info-light), or hex color (#E5F3FF)") }, async ({ query }) => {
             let ctx;
             try {
                 ctx = await getContext();

package/dist/mcp/tools/verify-tool.js

@@ -86,6 +86,16 @@ Returns: pixel match score, AI assessment ("matches" / "minor-differences" / "si
                                 passFail,
                                 verdictScore,
                                 verdictMetric,
+                                // B-1: cssVarScore is the design-system BINDING signal — fraction
+                                // of the design's bound --ptb-* vars present in the CSS. 0 = the
+                                // component renders correctly but is disconnected from the design
+                                // system (hard fail via the verdict gate). Surfaced so agents/users
+                                // can see it, not just its warning string.
+                                cssVarScore: result.cssVarScore ?? null,
+                                // textContentScore is the accurate name for what tokenScore measures
+                                // (rendered TEXT content, NOT token binding). tokenScore is a
+                                // deprecated alias kept for existing consumers.
+                                textContentScore: result.textContentScore ?? result.tokenScore ?? null,
                                 tokenScore: result.tokenScore ?? null,
                                 structureScore: result.structureScore ?? null,
                                 pixelMatchScore: score,
@@ -122,6 +132,8 @@ Returns: pixel match score, AI assessment ("matches" / "minor-differences" / "si
                 const summary = {
                     component: report.componentName,
                     checkedAt: report.checkedAt,
+                    cssVarScore: report.cssVarScore ?? null,
+                    textContentScore: report.textContentScore ?? report.tokenScore ?? null,
                     pixelMatchScore: report.pixelMatch?.score ?? null,
                     assessment: report.aiFeedback?.overallAssessment ?? null,
                     summary: report.aiFeedback?.summary ?? null,

package/dist/verify/run-verify.js

@@ -493,6 +493,17 @@ export async function runVerify(component, config, snapshot, options = {}) {
     // warning gate can check whether per-variant thumbnails are available before
     // deciding whether to fire a "no design reference" warning.
     const variantThumbs = component.variantThumbnails ?? [];
+    // B-8: the true number of variants in the set (every variant child), which can
+    // exceed the number of reference thumbnails when some variants failed to export.
+    // Previously the "capped at N of M" message used only the thumbnail count, so
+    // missing variants were silently unaccounted for. Surface the real gap.
+    const declaredVariantCount = component.variantNodeRefs?.length ??
+        component.variantSnapshots?.length ??
+        variantThumbs.length;
+    if (declaredVariantCount > variantThumbs.length) {
+        warnings.push(`${declaredVariantCount - variantThumbs.length} of ${declaredVariantCount} variants have no reference ` +
+            `thumbnail and were not pixel-verified (re-run 'ptb scan' to regenerate variant references).`);
+    }
     // GAP-022: prefer the single-variant reference for pixel-diff (a single-variant
     // story can't match the full variant grid). Fall back to the grid thumbnail.
     const thumbnailPath = component.variantThumbnailPath ?? component.thumbnailPath ?? null;
@@ -621,6 +632,9 @@ export async function runVerify(component, config, snapshot, options = {}) {
                         report.designTokenCount = designTokens.length;
                         report.foundTokenCount = found.length;
                         report.tokenScore = parseFloat((found.length / designTokens.length).toFixed(4));
+                        // B-1: same value under the accurate name (tokenScore measures
+                        // rendered TEXT content, not token binding). tokenScore kept as alias.
+                        report.textContentScore = report.tokenScore;
                     }
                 }
             }
@@ -756,14 +770,23 @@ export async function runVerify(component, config, snapshot, options = {}) {
         }
     }
     // ── Step 5: Cleanup PNG artifacts ───────────────────────────────────────
-    // All scores and feedback are in report.json; the PNGs are no longer needed.
-    // At scale (100+ components × 20 variants) keeping them wastes significant disk.
+    // B-9: retain the single primary diff image so a low score is inspectable —
+    // previously ALL pngs were deleted and screenshots.diff nulled, so an agent
+    // seeing a low pixelMatch had no way to see WHERE it diverged (it had to find
+    // report.json on disk and re-run Playwright by hand). The figma/impl and
+    // per-variant pngs are still removed; one diff per component is negligible disk.
     // Thumbnails live in .ptb/thumbnails/ — outside verifyDir — and are not touched.
-    report.screenshots = { figma: null, figmaSource: report.screenshots.figmaSource, impl: null, diff: null };
+    const keepDiff = report.screenshots.diff ? path.basename(report.screenshots.diff) : null;
+    report.screenshots = {
+        figma: null,
+        figmaSource: report.screenshots.figmaSource,
+        impl: null,
+        diff: report.screenshots.diff ?? null,
+    };
     // Persist report
     const reportPath = path.join(verifyDir, "report.json");
     await fs.writeFile(reportPath, JSON.stringify(report, null, 2), "utf-8");
-    const pngs = (await fs.readdir(verifyDir)).filter(e => e.endsWith(".png"));
+    const pngs = (await fs.readdir(verifyDir)).filter(e => e.endsWith(".png") && e !== keepDiff);
     await Promise.all(pngs.map(e => fs.unlink(path.join(verifyDir, e)).catch(() => undefined)));
     return { ...report, warnings };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calibrate-ds/cli",
-  "version": "0.1.88",
+  "version": "0.1.90",
   "license": "FSL-1.1-MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -44,10 +44,10 @@
     "commander": "^14.0.3",
     "openai": "^6.34.0",
     "zod": "^4.3.6",
-    "@calibrate-ds/core": "^0.1.88",
-    "@calibrate-ds/figma-client": "^0.1.88",
-    "@calibrate-ds/generator-react": "^0.1.88",
-    "@calibrate-ds/shared-types": "^0.1.88"
+    "@calibrate-ds/core": "^0.1.90",
+    "@calibrate-ds/figma-client": "^0.1.90",
+    "@calibrate-ds/generator-react": "^0.1.90",
+    "@calibrate-ds/shared-types": "^0.1.90"
   },
   "devDependencies": {
     "@types/node": "^22.13.5",