inkbridge 0.1.0-beta.20 → 0.1.0-beta.21

package/src/layout/ring-utils.ts

@@ -62,7 +62,23 @@ export function parseRingColor(
 
 /**
  * Derive a RingInfo from a list of Tailwind classes.
- * Returns null when no ring is declared.
+ * Returns null when no ring is declared OR when only a ring colour is
+ * present without an accompanying width utility.
+ *
+ * CSS subtlety: in Tailwind, `ring-COLOR` (e.g. `ring-destructive`)
+ * sets the ring's color via `--tw-ring-color` but does NOT make the
+ * ring visible — that requires a width utility (`ring`, `ring-2`,
+ * `ring-[3px]`, …). shadcn's invalid-input pattern relies on this:
+ *
+ *   `aria-invalid:ring-destructive/20 focus-visible:ring-[3px]`
+ *
+ * "When invalid, the ring is destructive-tinted; when focused, the
+ *  ring becomes 3px visible." Without focus, ring width = 0, so the
+ * invalid-but-unfocused input renders with just the red border, no
+ * ring. Previously this function defaulted width to 3 whenever a
+ * color was present — so the State Matrix `error` variant rendered
+ * with a doubled red ring outside the destructive border, instead of
+ * just the border. Now: no width → no ring.
  */
 export function getRingInfoFromClasses(
   classes: string[],
@@ -79,8 +95,7 @@ export function getRingInfoFromClasses(
     if (nextColor) color = nextColor;
   }
 
-  if (width == null && color == null) return null;
-  if (width == null) width = 3;
+  if (width == null) return null;
   if (!color) {
     const fallback = colorGroup.ring || colorGroup.primary;
     if (!fallback) return null;
@@ -90,82 +105,16 @@ export function getRingInfoFromClasses(
   return { width: width, color: color };
 }
 
-/**
- * Render a ring as an absolutely-positioned overlay child frame so it sits
- * outside the node boundary (matching CSS `box-shadow` ring behavior).
- * Returns true on success, false when the node has no dimensions yet.
- */
-export function applyRingOverlay(node: FrameNode, ring: RingInfo): boolean {
-  const width = typeof node.width === 'number' ? node.width : 0;
-  const height = typeof node.height === 'number' ? node.height : 0;
-  if (!(width > 0) || !(height > 0)) return false;
-
-  // Remove any stale ring overlay from a previous run.
-  const children = node.children;
-  if (Array.isArray(children) && children.length > 0) {
-    for (let i = children.length - 1; i >= 0; i--) {
-      const child = children[i];
-      if (!child || child.name !== '__inkbridge-ring__') continue;
-      try { child.remove(); } catch (_e) {}
-    }
-  }
-
-  const overlay = figma.createFrame();
-  overlay.name = '__inkbridge-ring__';
-  overlay.resize(width + ring.width * 2, height + ring.width * 2);
-  overlay.fills = [];
-  overlay.strokes = [{
-    type: 'SOLID',
-    color: { r: ring.color.r, g: ring.color.g, b: ring.color.b },
-    opacity: ring.color.a == null ? 1 : ring.color.a,
-  }];
-  overlay.strokeWeight = ring.width;
-  try { overlay.strokeAlign = 'INSIDE'; } catch (_e) {}
-
-  const nodeRadius = node.cornerRadius;
-  if (typeof nodeRadius === 'number') {
-    overlay.cornerRadius = Math.max(0, nodeRadius + ring.width);
-  } else {
-    const tl = typeof node.topLeftRadius === 'number' ? node.topLeftRadius : null;
-    const tr = typeof node.topRightRadius === 'number' ? node.topRightRadius : null;
-    const br = typeof node.bottomRightRadius === 'number' ? node.bottomRightRadius : null;
-    const bl = typeof node.bottomLeftRadius === 'number' ? node.bottomLeftRadius : null;
-    if (tl != null && tr != null && br != null && bl != null) {
-      overlay.topLeftRadius = Math.max(0, tl + ring.width);
-      overlay.topRightRadius = Math.max(0, tr + ring.width);
-      overlay.bottomRightRadius = Math.max(0, br + ring.width);
-      overlay.bottomLeftRadius = Math.max(0, bl + ring.width);
-    }
-  }
-
-  node.appendChild(overlay);
-  try { overlay.layoutPositioning = 'ABSOLUTE'; } catch (_e) {}
-  overlay.x = -ring.width;
-  overlay.y = -ring.width;
-  try { node.clipsContent = false; } catch (_e) {}
-  try { node.insertChild(0, overlay); } catch (_e) {}
-  return true;
-}
-
-/**
- * Apply a ring derived from Tailwind classes to a frame node.
- * Prefers the overlay approach; falls back to a plain stroke when the node has
- * no dimensions yet (e.g. hug-content frames before children are added).
- */
-export function applyRingEffect(
-  node: FrameNode,
-  classes: string[],
-  colorGroup: Record<string, string>
-): void {
-  const ring = getRingInfoFromClasses(classes, colorGroup);
-  if (!ring) return;
-  if (applyRingOverlay(node, ring)) return;
-  const strokeWeight = typeof node.strokeWeight === 'number' ? node.strokeWeight : 0;
-  node.strokes = [{
-    type: 'SOLID',
-    color: { r: ring.color.r, g: ring.color.g, b: ring.color.b },
-    opacity: ring.color.a == null ? 1 : ring.color.a,
-  }];
-  node.strokeWeight = Math.max(strokeWeight, ring.width);
-  try { node.strokeAlign = 'INSIDE'; } catch (_e) {}
-}
+// Ring rendering — the OVERLAY-FRAME implementation, the FIXED-toggle
+// invariant, and the post-pass scheduling all live in
+// `src/layout/deferred-layout.ts` (`markRingNode` / `applyRingIfPossible`).
+// This file owns the *parsing* contract only:
+//
+//   parseRingWidth / parseRingColor / getRingInfoFromClasses
+//
+// Callers in the parser path (`tailwind.ts`) and the imperative frame
+// builders (`component-gen.ts`, `cva-master.ts`, `preview-builder.ts`,
+// `state-master.ts`) all funnel through that single deferred entry point.
+// See `.ai/troubleshooting.md` "DO NOT use Figma DROP_SHADOW spread" and
+// "State Matrix focus/error variants render TALLER/WIDER" for the
+// architectural rationale.

package/src/render-engine-version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by build.mjs. Do not edit manually.
-export const RENDER_ENGINE_VERSION = 'a110f024b1fc6aca';
+export const RENDER_ENGINE_VERSION = '011e89524e15bfda';

package/src/tailwind/adapter-utils.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared utilities for tree-transform "adapters" — both framework-specific
+ * (shadcn / Radix data-slot patches in `framework-adapters/shadcn.ts`) and
+ * native-HTML rewrites (e.g. `<input type="range">` in `node-ir.ts`'s
+ * transform chain).
+ *
+ * Why a separate file
+ * -------------------
+ * `framework-adapters/shadcn.ts` and `tailwind/node-ir.ts` already have a
+ * one-way `node-ir → framework-adapters` dependency for the dispatcher.
+ * Putting these helpers in either would either deepen that cycle (shadcn →
+ * node-ir for `isClassedElement`) or hide them in a "framework adapter"
+ * module when they aren't framework-specific. A sibling utility module
+ * keeps the import graph clean: both sides import down into this file.
+ *
+ * All helpers must be sandbox-safe — no value-side spread, no DOM, no
+ * external I/O — these run inside the Figma plugin's code.js.
+ */
+
+import type { NodeIR } from './node-ir';
+
+/**
+ * Type guard for nodes that carry `props` + `classes`. `text`, `fragment`,
+ * `divider`, and `ring` nodes do not; `ring` wraps a single child via a
+ * separate field. Tree-transform code typically branches first on this.
+ */
+export function isClassedElement(
+  node: NodeIR,
+): node is Extract<NodeIR, { kind: 'element' | 'component' }> {
+  return node.kind === 'element' || node.kind === 'component';
+}
+
+/**
+ * Additive class merge: append `extras` to `existing` only when not
+ * already present. Preserves order. Returns `existing` by reference when
+ * nothing was added so callers can detect "no change" and keep object
+ * identity stable (downstream caches like `NODE_LAYOUT_CACHE` rely on
+ * this).
+ *
+ * Note: this is the "injection" merge, distinct from `class-utils.ts`'s
+ * `mergeClasses` which implements Tailwind override semantics
+ * (last-wins). Use this when an adapter wants to ADD classes without
+ * disturbing the consumer's own class order.
+ */
+export function mergeMissing(existing: string[], extras: readonly string[]): string[] {
+  if (extras.length === 0) return existing;
+  const set = new Set(existing);
+  let out: string[] | null = null;
+  for (const cls of extras) {
+    if (set.has(cls)) continue;
+    if (!out) out = existing.slice();
+    out.push(cls);
+    set.add(cls);
+  }
+  return out ?? existing;
+}
+
+/**
+ * Resolve a value/min/max trio into an array of percent positions
+ * (0-100). The scanner stringifies every JSX prop, so `<input value={5}>`
+ * arrives as `props.value === "5"`. We accept numbers, strings,
+ * JSON-array strings ("[25, 75]" for shadcn range sliders), and an actual
+ * array of numbers/strings.
+ *
+ * Defaults — when `min` or `max` is missing / unparseable:
+ *   - `min` defaults to 0
+ *   - `max` defaults to 100
+ *   - If `max <= min` after parsing (degenerate range), we fall back to
+ *     `min + 100` so the percent math doesn't divide by zero.
+ *
+ * If `value` can't be parsed at all, returns `[0]` — a recognisable
+ * "left-edge" position. Callers that want a different default (e.g. HTML
+ * `<input type=range>`'s `(min+max)/2`) can post-process.
+ *
+ * Used by:
+ *   - shadcn Slider adapter (`applySliderPositioning`) — passes min=0
+ *     unconditionally because base-ui's Slider is min=0 max=`max` only.
+ *   - `<input type="range">` IR transform — passes the actual min from
+ *     the element's prop (HTML default min is 0 but consumers commonly
+ *     override).
+ */
+export function resolveValuePercents(
+  rawValue: unknown,
+  rawMin: unknown,
+  rawMax: unknown,
+): number[] {
+  const min = parseNumeric(rawMin, 0);
+  let max = parseNumeric(rawMax, 100);
+  if (!(max > min)) max = min + 100;
+  const range = max - min;
+  const toPct = (v: number): number =>
+    Math.max(0, Math.min(100, ((v - min) / range) * 100));
+
+  if (Array.isArray(rawValue)) {
+    const nums: number[] = [];
+    for (const v of rawValue) {
+      const n = typeof v === 'number' ? v : typeof v === 'string' ? parseFloat(v) : NaN;
+      if (Number.isFinite(n)) nums.push(toPct(n));
+    }
+    if (nums.length > 0) return nums;
+  }
+  if (typeof rawValue === 'number' && Number.isFinite(rawValue)) {
+    return [toPct(rawValue)];
+  }
+  if (typeof rawValue === 'string') {
+    const trimmed = rawValue.trim();
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed)) {
+          const nums: number[] = [];
+          for (const v of parsed) {
+            const n = typeof v === 'number' ? v : parseFloat(String(v));
+            if (Number.isFinite(n)) nums.push(toPct(n));
+          }
+          if (nums.length > 0) return nums;
+        }
+      } catch (_e) {
+        // Not valid JSON — fall through to numeric parse.
+      }
+    }
+    const num = parseFloat(trimmed);
+    if (Number.isFinite(num)) return [toPct(num)];
+  }
+  return [0];
+}
+
+function parseNumeric(raw: unknown, fallback: number): number {
+  if (typeof raw === 'number' && Number.isFinite(raw)) return raw;
+  if (typeof raw === 'string') {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) return fallback;
+    const n = parseFloat(trimmed);
+    if (Number.isFinite(n)) return n;
+  }
+  return fallback;
+}

package/src/tailwind/jsx-utils.ts

@@ -2,14 +2,23 @@ import { type JsxNode, type JsxElement, splitClassName } from './node-ir';
 import { type ComponentDef } from './class-utils';
 import { extractMaxWidth } from '../layout';
 import { getClassesForBreakpoint, hasSignificantResponsiveChanges } from './responsive-analyzer';
+import { isFrameworkAdapterDroppedTag } from '../framework-adapters';
 
 /**
  * Recursively collect every Tailwind class string from a JSX tree.
+ *
+ * Elements that the framework adapter will unconditionally drop at render
+ * time (e.g. `ScrollAreaPrimitive.Scrollbar` and friends) are skipped —
+ * including their subtree. Otherwise classes that never reach Figma
+ * (Scrollbar's `sm:bg-black/60`) would falsely trip pre-render scans like
+ * `treeHasResponsiveClasses`, producing duplicate-content Responsive
+ * previews on stories that are static at every breakpoint post-adapter.
  */
 export function collectTreeClasses(node: JsxNode | undefined, output: string[]): void {
   if (!node) return;
   if (node.type === 'element') {
     const el = node as JsxElement;
+    if (isFrameworkAdapterDroppedTag(el.tagName)) return;
     const className = el.props && el.props.className ? String(el.props.className) : '';
     if (className) {
       const list = splitClassName(className);

package/src/tailwind/node-ir.ts

@@ -1,6 +1,7 @@
 import { parseColor, type RGB } from '../tokens';
 import type { ComponentDef } from '../components/scanner-types';
 import { applyFrameworkAdapters } from '../framework-adapters';
+import { mergeMissing, resolveValuePercents } from './adapter-utils';
 
 // ---------------------------------------------------------------------------
 // JSX tree types
@@ -160,6 +161,10 @@ export function applyNodeTransforms(
   // downstream transform without parallel handling.
   let next = applyFrameworkAdapters(node);
   next = flattenComponentNodes(next, null, helpers);
+  // Native HTML input rewrites run BEFORE the visual transforms (space,
+  // divide, ring) so the synthetic tree they emit flows through the rest
+  // of the pipeline as ordinary div + Tailwind classes.
+  next = transformInputNodes(next);
   next = transformSpaceNodes(next);
   next = transformDivideNodes(next, colorGroup);
   next = transformRingNodes(next, colorGroup);
@@ -248,6 +253,173 @@ function flattenComponentNodes(
   });
 }
 
+// ---------------------------------------------------------------------------
+// Native HTML input rewrites
+//
+// Some `<input>` types have no built-in className-driven appearance that
+// Figma can render — most notably `type="range"`, which is a custom
+// browser widget (track + thumb). The default input branch in
+// `ui-builder.ts` reads `value` / `defaultValue` / `placeholder` and
+// emits a text node — fine for text/number/email, useless (or worse,
+// stalling) for range. This transform rewrites those special cases at
+// the IR-transform stage into a synthetic Tailwind tree the existing
+// pipeline already knows how to render.
+//
+// Currently handles: `type="range"`. Extend the dispatcher in
+// `transformInputNodes` when other types need similar treatment (e.g.
+// checkbox / radio with `checked` driving a visual indicator).
+// ---------------------------------------------------------------------------
+
+export function transformInputNodes(node: NodeIR): NodeIR {
+  if (node.kind === 'text' || node.kind === 'divider') {
+    return node;
+  }
+
+  if (node.kind === 'fragment') {
+    return recurseFragment(node, transformInputNodes);
+  }
+
+  if (node.kind === 'ring') {
+    const nextChild = transformInputNodes(node.child);
+    return nextChild === node.child ? node : Object.assign({}, node, { child: nextChild });
+  }
+
+  // Recurse first so any nested `<input>` is rewritten before its parent
+  // decides what to do with it. Preserve object identity when no
+  // descendant changed (keeps `NODE_LAYOUT_CACHE` warm).
+  let childrenChanged = false;
+  const nextChildren: NodeIR[] = [];
+  for (const child of node.children) {
+    const next = transformInputNodes(child);
+    if (next !== child) childrenChanged = true;
+    nextChildren.push(next);
+  }
+  const recursed: NodeIR = childrenChanged
+    ? (Object.assign({}, node, { children: nextChildren }) as NodeIR)
+    : node;
+
+  if (recursed.kind !== 'element') return recursed;
+  if (recursed.tagLower !== 'input') return recursed;
+  const type = (recursed.props && recursed.props.type) || '';
+  if (type !== 'range') return recursed;
+
+  return buildRangeSliderTree(recursed as NodeIRElement);
+}
+
+function recurseFragment(
+  frag: NodeIRFragment,
+  fn: (n: NodeIR) => NodeIR,
+): NodeIR {
+  let changed = false;
+  const next: NodeIR[] = [];
+  for (const c of frag.children) {
+    const r = fn(c);
+    if (r !== c) changed = true;
+    next.push(r);
+  }
+  return changed ? Object.assign({}, frag, { children: next }) : frag;
+}
+
+/**
+ * Rewrite `<input type="range" min=N max=M value=V disabled? className=...>`
+ * into a styled `<div>` tree mirroring the shape that shadcn Slider's
+ * adapter already produces (and which the renderer is known to handle):
+ *
+ *   wrapper (relative flex h-4 items-center, consumer classes preserved)
+ *     └── track  (flow child: h-1.5 w-full rounded-full overflow-hidden bg-secondary)
+ *           └── filled (flow child of track: h-full rounded-full bg-primary w-[N%])
+ *     └── thumb  (absolute sibling of track: size-4 rounded-full -translate-x-1/2 left-[N%])
+ *
+ * Why mirror shadcn's structure (track as flow child, thumb as absolute
+ * sibling)? An all-absolute-children wrapper has no flow content to size
+ * against — deferred-layout passes can stall trying to resolve a 0-content
+ * frame with `flex items-center`. The shadcn Slider already navigates this
+ * by making Track a flow child of Control; we copy that pattern.
+ *
+ * Vertical centering of the thumb comes from `flex items-center` on the
+ * wrapper combined with the thumb's static position (size-4 = wrapper
+ * height) — no `top-1/2 -translate-y-1/2` needed.
+ *
+ * Geometry: `pct = ((value - min) / (max - min)) * 100`. See
+ * `resolveValuePercents` in `./adapter-utils.ts`.
+ */
+function buildRangeSliderTree(input: NodeIRElement): NodeIR {
+  const props = input.props || {};
+  const rawValue = props.value ?? props.defaultValue;
+  const pcts = resolveValuePercents(rawValue, props.min, props.max);
+  const pct = pcts[0] ?? 0;
+  const isDisabled = props.disabled !== undefined && props.disabled !== 'false';
+
+  // Preserve sizing-related classes from the consumer (`w-full`, `w-[Npx]`,
+  // `max-w-*`) onto the wrapper. Visual / state classes that applied to the
+  // native widget shape (`accent-primary`, focus rings) are kept but
+  // typically no-ops on the synthetic div.
+  const wrapperExtras = ['relative', 'flex', 'h-4', 'items-center'];
+  if (isDisabled) wrapperExtras.push('opacity-50');
+  const wrapperClasses = mergeMissing(input.classes, wrapperExtras);
+
+  const filled: NodeIR = makeRangeChild('div', [
+    'h-full',
+    'rounded-full',
+    'bg-primary',
+    `w-[${formatPercent(pct)}%]`,
+  ]);
+
+  const track: NodeIRElement = {
+    kind: 'element',
+    tagName: 'div',
+    tagLower: 'div',
+    props: {},
+    classes: [
+      'h-1.5',
+      'w-full',
+      'rounded-full',
+      'overflow-hidden',
+      'bg-secondary',
+    ],
+    children: [filled],
+  };
+
+  const thumb: NodeIR = makeRangeChild('div', [
+    'absolute',
+    'size-4',
+    'rounded-full',
+    'border-2',
+    'border-primary',
+    'bg-background',
+    '-translate-x-1/2',
+    `left-[${formatPercent(pct)}%]`,
+  ]);
+
+  return {
+    kind: 'element',
+    tagName: 'div',
+    tagLower: 'div',
+    props: {},
+    classes: wrapperClasses,
+    children: [track, thumb],
+  };
+}
+
+function makeRangeChild(tag: string, classes: string[]): NodeIRElement {
+  return {
+    kind: 'element',
+    tagName: tag,
+    tagLower: tag,
+    props: {},
+    classes,
+    children: [],
+  };
+}
+
+function formatPercent(pct: number): string {
+  // Two-decimal precision keeps thumb placement visually correct for
+  // common (min, max, value) triples without bloating the class name.
+  // `Number.toFixed` always renders fixed decimals; trim trailing zeros.
+  const fixed = pct.toFixed(2);
+  return fixed.replace(/\.?0+$/, '') || '0';
+}
+
 function transformSpaceNodes(node: NodeIR): NodeIR {
   if (node.kind === 'text' || node.kind === 'divider') {
     return node;

package/src/tailwind/tailwind.ts

@@ -37,7 +37,8 @@ import {
   shouldApplyAtom,
   BORDER_WIDTH_CLASSES,
   DEFERRED_TOP_RELATIVE_NODES,
-  applyRingEffect,
+  getRingInfoFromClasses,
+  markRingNode,
 } from '../layout';
 
 // ---------------------------------------------------------------------------
@@ -1154,12 +1155,21 @@ function applySemanticUtilitiesToFrame(
       };
       const defs = SHADOW_MAP[shadowKey];
       if (defs !== undefined) {
+        // Figma renders multi-layer DROP_SHADOW effects as independently
+        // stacked filters — they composite "harder" than CSS box-shadow,
+        // where the browser's filter pipeline smooths overlapping
+        // shadow layers. The numeric values in SHADOW_MAP match
+        // Tailwind v3's docs exactly, but the visual result reads as
+        // ~30 % stronger in Figma at parity. Damp the alpha channel so
+        // the rendered page matches Storybook / browser intensity. Tune
+        // this single constant to dial all tiers up or down together.
+        const SHADOW_ALPHA_DAMPER = 0.7;
         const shadowEffects: Effect[] = [];
         for (let si = 0; si < defs.length; si++) {
           const d = defs[si];
           shadowEffects.push({
             type: d.type,
-            color: { r: d.r, g: d.g, b: d.b, a: d.a },
+            color: { r: d.r, g: d.g, b: d.b, a: d.a * SHADOW_ALPHA_DAMPER },
             offset: { x: d.x, y: d.y },
             radius: d.radius,
             spread: d.spread,
@@ -1733,20 +1743,17 @@ export function applyTailwindStylesToFrame(
     frame.opacity = style.opacity;
   }
 
-  // Ring utilities (`ring-1`, `ring-2`, `ring-ring`, `ring-primary/50`, …)
-  // are rendered as an absolutely-positioned overlay child frame with a
-  // stroke (CSS `box-shadow: 0 0 0 N <color>` semantics). We used to
-  // express this as a Figma DROP_SHADOW with spread=ringWidth, but Figma
-  // surfaces `The 'spread' parameter is not supported when frames or
-  // components have no visible fills` for every fills:[] frame —
-  // structural design-system layout frames are intentionally transparent.
-  // The overlay path also avoids forcing `clipsContent=true` on the host
-  // frame, which used to be a workaround for a *different* Figma spread
-  // constraint. State-frame renderings (Textarea focus row, future Input
-  // focus, …) come through this path; the NodeIR-based renderer wraps
-  // the element in a `ring` node which is the more accurate path but
-  // only fires when the node carries `kind: 'ring'`.
-  applyRingEffect(frame, classes, colorGroup);
+  // Ring utilities (`ring-1`, `ring-2`, `ring-ring`, `ring-primary/50`,
+  // `ring-offset-N`, …) are MARKED here at parse time and resolved later
+  // by `applyRingIfPossible` in the post-append pipeline, when the host's
+  // content children are all in place and its natural W × H is final.
+  // Doing this eagerly here used to inflate Hug-sized parents during the
+  // brief flex-child moment between `appendChild` and
+  // `layoutPositioning = 'ABSOLUTE'`. See `src/layout/deferred-layout.ts`
+  // (`applyRingIfPossible`) for why the deferred phase is the right
+  // place for this concern.
+  const ringInfo = getRingInfoFromClasses(classes, colorGroup);
+  if (ringInfo) markRingNode(frame, ringInfo);
 
   return style;
 }

package/src/tokens/tokens.ts

@@ -534,9 +534,15 @@ const SYSTEM_FONT_KEYWORDS = new Set([
   'arial', 'helvetica', 'georgia', 'verdana', 'tahoma', 'trebuchet ms',
   'times new roman', 'courier new', 'courier', 'palatino', 'garamond',
   'bookman', 'comic sans ms', 'impact', 'lucida sans unicode',
+  // Emoji / symbol fallback fonts — present in Tailwind's default
+  // sans-serif stack but not in Figma's font registry. Without skipping
+  // these, the resolver picks "Apple Color Emoji" as the body font on
+  // any consumer that exposes Tailwind's default `font.sans` value,
+  // then `figma.loadFontAsync` throws "couldn't load font".
+  'apple color emoji', 'segoe ui emoji', 'segoe ui symbol', 'noto color emoji',
 ]);
 
-function extractFontName(raw: unknown): string | null {
+export function extractFontName(raw: unknown): string | null {
   const parts = String(raw || '').split(',');
   let varFallback: string | null = null;
   for (const part of parts) {
@@ -581,8 +587,10 @@ export function getCoreFontFamily(tokens: Tokens): string | null {
   if (core && core.font) {
     const raw = (core.font as TokenGroup).sans || Object.values(core.font as TokenGroup)[0];
     if (raw) {
-      const first = String(raw).split(',')[0].trim().replace(/^["']|["']$/g, '');
-      if (first) return first;
+      // Filter system / emoji / generic-keyword entries — they aren't
+      // valid Figma font families. Same logic as getThemeFontFamily.
+      const name = extractFontName(raw);
+      if (name) return name;
     }
   }
   return getThemeFontFamily(tokens, 'primary');

package/templates/scan-components-route.ts

@@ -20,7 +20,17 @@ import { spawnSync } from 'child_process';
 
 const CWD = process.cwd();
 const TSX = path.resolve(CWD, 'node_modules/.bin/tsx');
-const CLI = path.resolve(CWD, 'node_modules/inkbridge/scanner/cli.ts');
+// `INKBRIDGE_LOCAL=1` (set by `pnpm inkbridge:dev:local` in projects that
+// sit next to a sibling inkbridge checkout) points the scanner at the
+// source tree directly instead of going through `node_modules/inkbridge`.
+// pnpm hard-links package files at install time, but most editors break
+// those links on save (save-as-rename semantics), so without this flag
+// every scanner edit requires a `pnpm add -D inkbridge@file:... --force`.
+// The flag turns scanner-side iteration into a true hot loop.
+const LOCAL_CLI = path.resolve(CWD, '..', 'inkbridge', 'tools', 'figma-plugin', 'scanner', 'cli.ts');
+const CLI = process.env.INKBRIDGE_LOCAL === '1' && fs.existsSync(LOCAL_CLI)
+  ? LOCAL_CLI
+  : path.resolve(CWD, 'node_modules/inkbridge/scanner/cli.ts');
 const OUTPUT = path.resolve(CWD, '.inkbridge/component-definitions.json');
 
 const CORS = {