@calibrate-ds/core 0.1.88 → 0.1.90

package/dist/context/variant-token-map.d.ts

@@ -0,0 +1,50 @@
+import type { ComponentDefinition } from "@calibrate-ds/shared-types";
+/**
+ * B-3: a compact, pre-resolved per-variant token/style map.
+ *
+ * The full per-variant data lives in `variantDiffs` (default-relative deltas) and
+ * `variantSnapshots` (absolute per-variant state) — both large and awkward to parse,
+ * which forced agents to script their way through a 300 KB+ JSON to reconstruct a
+ * per-variant token matrix. This projects `variantSnapshots` down to exactly what an
+ * agent needs to implement each variant: for every variant selection, the resolved
+ * token bindings (canonical `--ptb-*` cssVar + resolved value) and spacing for the
+ * nodes that carry them. No render tree, no diffs — just the build matrix.
+ */
+/** One resolved style slot for a node within a variant. */
+export type VariantTokenSlot = {
+    /** Node path within the component, e.g. "root" or "root/label". */
+    node: string;
+    /** The CSS-facing property this slot drives. */
+    property: "background" | "text-color" | "border-color" | "border-radius" | "padding" | "gap";
+    /** Canonical --ptb-* variable to emit (the design-system binding). Absent when unbound. */
+    cssVar?: string;
+    /** Resolved concrete value (hex or px) — use as the literal / var() fallback. */
+    value: string;
+    /** Human-readable token name when known (e.g. "surface/primary/light"). */
+    token?: string;
+    /** Stroke weight in px (border-color slots only). */
+    weight?: number;
+    /** Stroke alignment: inside | outside | center (border-color slots only). */
+    align?: string;
+};
+export type VariantTokenEntry = {
+    selection: Record<string, string>;
+    /** Visible text content per node, when the variant sets any (e.g. label text). */
+    text?: Record<string, string>;
+    slots: VariantTokenSlot[];
+};
+export type VariantTokenMap = {
+    component: string;
+    axes: string[];
+    variantCount: number;
+    variants: VariantTokenEntry[];
+    /** Present (with an explanation) when the component has no per-variant snapshot data. */
+    note?: string;
+};
+/**
+ * Builds the compact per-variant token/style map for a component. Returns an empty
+ * map with a `note` when the component has no variant snapshots (single components,
+ * or old-format snapshots predating variantSnapshots).
+ */
+export declare function buildVariantTokenMap(component: ComponentDefinition): VariantTokenMap;
+//# sourceMappingURL=variant-token-map.d.ts.map

package/dist/context/variant-token-map.js

@@ -0,0 +1,97 @@
+function pxOrNum(n) {
+    return `${Math.round(n * 1000) / 1000}px`;
+}
+/** Extract the resolved token/style slots from one variant node's style. */
+function slotsForNode(nodePath, style) {
+    const slots = [];
+    const isText = style.type === "TEXT";
+    const tokens = (style.tokens ?? {});
+    // Fill → background (containers) or text-color (TEXT nodes). textFill is the TEXT variant.
+    const fill = tokens.textFill ?? tokens.fill;
+    if (fill && typeof fill.color === "string") {
+        slots.push({
+            node: nodePath,
+            property: isText || tokens.textFill ? "text-color" : "background",
+            value: fill.color,
+            ...(fill.cssVar ? { cssVar: fill.cssVar } : {}),
+            ...(fill.token ? { token: fill.token } : {}),
+        });
+    }
+    // Stroke → border-color (carries weight + align — the strokeAlign inside/outside signal).
+    const stroke = tokens.stroke;
+    if (stroke && typeof stroke.color === "string") {
+        slots.push({
+            node: nodePath,
+            property: "border-color",
+            value: stroke.color,
+            ...(stroke.cssVar ? { cssVar: stroke.cssVar } : {}),
+            ...(stroke.token ? { token: stroke.token } : {}),
+            ...(typeof stroke.weight === "number" ? { weight: stroke.weight } : {}),
+            ...(stroke.align ? { align: stroke.align } : {}),
+        });
+    }
+    // Radius → border-radius (uniform value + optional binding).
+    if (style.radius && typeof style.radius.uniform === "number") {
+        slots.push({
+            node: nodePath,
+            property: "border-radius",
+            value: pxOrNum(style.radius.uniform),
+            ...(style.radius.cssVar ? { cssVar: style.radius.cssVar } : {}),
+            ...(style.radius.token ? { token: style.radius.token } : {}),
+        });
+    }
+    // Layout spacing (raw — Figma stores gap/padding as numbers, not bound vars here).
+    if (style.layout) {
+        if (typeof style.layout.gap === "number" && style.layout.gap > 0) {
+            slots.push({ node: nodePath, property: "gap", value: pxOrNum(style.layout.gap) });
+        }
+        const p = style.layout.padding;
+        if (p && (p.top || p.right || p.bottom || p.left)) {
+            const value = (p.top === p.bottom && p.left === p.right)
+                ? (p.top === p.left ? pxOrNum(p.top) : `${pxOrNum(p.top)} ${pxOrNum(p.right)}`)
+                : `${pxOrNum(p.top)} ${pxOrNum(p.right)} ${pxOrNum(p.bottom)} ${pxOrNum(p.left)}`;
+            slots.push({ node: nodePath, property: "padding", value });
+        }
+    }
+    return slots;
+}
+function entryForVariant(snapshot) {
+    const slots = [];
+    const text = {};
+    for (const [nodePath, style] of Object.entries(snapshot.nodes ?? {})) {
+        slots.push(...slotsForNode(nodePath, style));
+        if (typeof style.textContent === "string" && style.textContent.trim()) {
+            text[nodePath] = style.textContent;
+        }
+    }
+    return {
+        selection: snapshot.variantSelection ?? {},
+        ...(Object.keys(text).length > 0 ? { text } : {}),
+        slots,
+    };
+}
+/**
+ * Builds the compact per-variant token/style map for a component. Returns an empty
+ * map with a `note` when the component has no variant snapshots (single components,
+ * or old-format snapshots predating variantSnapshots).
+ */
+export function buildVariantTokenMap(component) {
+    const axes = (component.variantAxes ?? []).map(a => a.name);
+    const snapshots = component.variantSnapshots ?? [];
+    if (snapshots.length === 0) {
+        return {
+            component: component.name,
+            axes,
+            variantCount: 0,
+            variants: [],
+            note: "No per-variant snapshots for this component (not a multi-variant component set, or scanned before variant snapshots were captured — re-run 'ptb scan').",
+        };
+    }
+    return {
+        component: component.name,
+        axes,
+        variantCount: snapshots.length,
+        variants: snapshots.map(entryForVariant),
+    };
+}
+//# sourceMappingURL=variant-token-map.js.map

package/dist/docs/setup-storybook.d.ts

@@ -15,6 +15,19 @@ export declare function detectPackageManager(dir: string): Promise<PackageManage
  *  Walks up the directory tree so monorepos with hoisted node_modules are handled correctly. */
 export declare function checkStorybookReadiness(packageRoot: string): Promise<StorybookReadiness>;
 export declare function detectBundler(projectRoot: string): Promise<"vite" | "webpack">;
+/**
+ * B-4: Storybook never loaded the design's fonts, so text rendered in a fallback
+ * (e.g. "Inter" → whatever the browser had), measuring a different width than the
+ * design and capping every text component's pixel-match score regardless of
+ * correctness. We generate a preview-head.html that loads the fonts the design
+ * actually uses (extracted from the generated typography.css) from Google Fonts —
+ * the standard, self-contained way to make a Storybook preview font-accurate.
+ * Non-Google fonts degrade gracefully (the link no-ops; same as before).
+ */
+/** Extracts primary font-family names from a generated typography.css / tokens.css string. */
+export declare function extractFontFamilies(css: string): string[];
+/** Builds a Google Fonts <link> preview-head.html for the given family names. */
+export declare function previewHead(fontFamilies: string[]): string;
 /**
  * Injects a tokens.css import at the top of an existing .storybook/preview.ts|js
  * without overwriting the rest of the file. No-ops if the import is already present.

package/dist/docs/setup-storybook.js

@@ -137,6 +137,47 @@ const config: StorybookConfig = {
 export default config;
 `;
 }
+/**
+ * B-4: Storybook never loaded the design's fonts, so text rendered in a fallback
+ * (e.g. "Inter" → whatever the browser had), measuring a different width than the
+ * design and capping every text component's pixel-match score regardless of
+ * correctness. We generate a preview-head.html that loads the fonts the design
+ * actually uses (extracted from the generated typography.css) from Google Fonts —
+ * the standard, self-contained way to make a Storybook preview font-accurate.
+ * Non-Google fonts degrade gracefully (the link no-ops; same as before).
+ */
+/** Extracts primary font-family names from a generated typography.css / tokens.css string. */
+export function extractFontFamilies(css) {
+    const families = new Set();
+    const re = /font-family:\s*([^;]+);/gi;
+    let m;
+    while ((m = re.exec(css)) !== null) {
+        // The primary family is the first entry; strip quotes/whitespace.
+        const primary = m[1].split(",")[0].trim().replace(/^["']|["']$/g, "");
+        // Skip CSS keywords and generic families — they need no @font-face.
+        const generic = ["inherit", "initial", "unset", "serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "-apple-system", "ui-monospace", "ui-sans-serif", "ui-serif"];
+        if (primary && !generic.includes(primary.toLowerCase()))
+            families.add(primary);
+    }
+    return [...families];
+}
+/** Builds a Google Fonts <link> preview-head.html for the given family names. */
+export function previewHead(fontFamilies) {
+    if (fontFamilies.length === 0)
+        return "";
+    const familyParams = fontFamilies
+        .map(f => `family=${encodeURIComponent(f).replace(/%20/g, "+")}:wght@300;400;500;600;700`)
+        .join("&");
+    return `<!--
+  Auto-generated by Calibrate so Storybook renders your design system's fonts,
+  making 'ptb verify' pixel scores accurate. If a font is self-hosted or not on
+  Google Fonts, replace this link with your own @font-face / <link>.
+-->
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?${familyParams}&display=swap" rel="stylesheet" />
+`;
+}
 function previewTs(tokensRelPath) {
     const tokenImport = tokensRelPath ? `import "${tokensRelPath}";\n` : "";
     return `import type { Preview } from "@storybook/react";
@@ -242,9 +283,22 @@ tokensDir) {
             tokensRelPath = rel.startsWith(".") ? rel : `./${rel}`;
         }
     }
+    // B-4: derive the design's fonts from the generated typography.css so the
+    // Storybook preview loads them (accurate pixel-diff). Best-effort — if the CSS
+    // isn't present yet, we simply skip preview-head.html.
+    let fontFamilies = [];
+    if (tokensDir) {
+        for (const cssName of ["typography.css", "tokens.css"]) {
+            const css = await fs.readFile(path.join(tokensDir, cssName), "utf-8").catch(() => "");
+            if (css)
+                fontFamilies.push(...extractFontFamilies(css));
+        }
+        fontFamilies = [...new Set(fontFamilies)];
+    }
     const files = [
         { name: "main.ts", content: mainTs(bundler, storiesGlob, frameworkPkg) },
         { name: "preview.ts", content: previewTs(tokensRelPath) },
+        ...(fontFamilies.length > 0 ? [{ name: "preview-head.html", content: previewHead(fontFamilies) }] : []),
     ];
     const created = [];
     const skipped = [];

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from "./tokens/index.js";
 export * from "./plan/index.js";
 export * from "./manifest/index.js";
 export * from "./context/get-component-context.js";
+export * from "./context/variant-token-map.js";
 export * from "./context/hashing.js";
 export * from "./context/metadata-extraction.js";
 export * from "./context/export-context.js";

package/dist/index.js

@@ -19,6 +19,7 @@ export * from "./tokens/index.js";
 export * from "./plan/index.js";
 export * from "./manifest/index.js";
 export * from "./context/get-component-context.js";
+export * from "./context/variant-token-map.js";
 export * from "./context/hashing.js";
 export * from "./context/metadata-extraction.js";
 export * from "./context/export-context.js";

package/dist/verify/types.d.ts

@@ -89,8 +89,18 @@ export type VerifyReport = {
      * components — it catches implementations that render wrong/placeholder content,
      * and is immune to font rendering and pixel-alignment differences.
      * Undefined when no design text tokens are found (e.g. icons, purely visual).
+     *
+     * NOTE: despite the name, this measures rendered TEXT content, NOT design-token
+     * (CSS variable) binding — that is `cssVarScore`. Prefer `textContentScore`, which
+     * carries the same value under the accurate name; `tokenScore` is kept as a
+     * deprecated alias so existing consumers do not break.
      */
     tokenScore?: number;
+    /**
+     * The correctly-named alias of `tokenScore`: the fraction of the design's TEXT
+     * content rendered by the implementation. Use this name going forward.
+     */
+    textContentScore?: number;
     /** Number of unique design text tokens extracted from the renderTree. */
     designTokenCount?: number;
     /** Number of design text tokens found in the rendered DOM. */

package/dist/verify/verdict.d.ts

@@ -29,7 +29,7 @@ export type VerifyVerdictResult = {
     /** The score the verdict was computed from (0–1), or null when nothing comparable existed. */
     score: number | null;
     /** Which metric drove the verdict. */
-    metric: "token" | "structure" | "pixel-content" | "pixel" | "none";
+    metric: "token" | "structure" | "pixel-content" | "pixel" | "css-var" | "none";
 };
 /**
  * Computes a single verdict from a VerifyReport.
@@ -49,5 +49,5 @@ export type VerifyVerdictResult = {
  * false-pass vector with no corroborating evidence behind it. Pixel rescue never
  * downgrades a result the old chain passed (if token was highest, it still wins).
  */
-export declare function computeVerifyVerdict(report: Pick<VerifyReport, "tokenScore" | "structureScore" | "pixelMatch" | "variantMeanScore">): VerifyVerdictResult;
+export declare function computeVerifyVerdict(report: Pick<VerifyReport, "tokenScore" | "structureScore" | "pixelMatch" | "variantMeanScore" | "cssVarScore">): VerifyVerdictResult;
 //# sourceMappingURL=verdict.d.ts.map

package/dist/verify/verdict.js

@@ -41,6 +41,17 @@ export const CONTENT_COVERAGE_FLOOR = 0.35;
  * downgrades a result the old chain passed (if token was highest, it still wins).
  */
 export function computeVerifyVerdict(report) {
+    // B-1 (design-system binding gate): cssVarScore is the fraction of the design's
+    // bound --ptb-* variables actually present in the generated CSS. It is defined
+    // ONLY when the design has bound variables for this component. A component that
+    // should carry the design system's tokens but carries NONE (cssVarScore === 0) is
+    // token-blind — visually it may be perfect, but it is disconnected from the design
+    // system, which is the one property PTB uniquely guarantees. This is a hard fail
+    // that text/pixel evidence cannot rescue: tokenScore only measures rendered TEXT
+    // content, not token identity, so it must never pass a token-blind component.
+    if (report.cssVarScore === 0) {
+        return { verdict: "fail", score: 0, metric: "css-var" };
+    }
     let primary = null;
     if (report.tokenScore !== undefined) {
         primary = { score: report.tokenScore, metric: "token" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calibrate-ds/core",
-  "version": "0.1.88",
+  "version": "0.1.90",
   "license": "FSL-1.1-MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -42,8 +42,8 @@
     "pixelmatch": "^6.0.0",
     "pngjs": "^7.0.0",
     "zod": "^4.3.6",
-    "@calibrate-ds/shared-types": "^0.1.88",
-    "@calibrate-ds/figma-client": "^0.1.88"
+    "@calibrate-ds/shared-types": "^0.1.90",
+    "@calibrate-ds/figma-client": "^0.1.90"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",