inkbridge 0.1.0-beta.21 → 0.1.0-beta.23

package/src/design-system/design-system.ts

@@ -33,6 +33,7 @@ import {
 } from '../tokens';
 import { createUIComponents, pruneGeneratedComponentLibrary } from './ui-builder';
 import { hashString, stableStringify, getFrameHash, setFrameHash, findChildByName } from '../cache';
+import { RENDER_ENGINE_VERSION } from '../render-engine-version';
 import { isGeneratedDesignSystemNode, tagGeneratedNode } from './generated-node';
 
 const DESIGN_SYSTEM_PAGE_NAME = 'Design System';
@@ -53,11 +54,26 @@ function removeStalePageLabels(page: PageNode | null, labels: string[]): void {
   }
 }
 
+/**
+ * Frame name used for the design-tokens row (the section showing the
+ * consumer's custom-defined colors, fonts, radii, etc.). Renamed from
+ * the historical "Design Tokens" to make it clear in Figma's frame
+ * label that the contents are the consumer's OVERRIDES — values they
+ * wrote on top of Tailwind's defaults — not the full theme.
+ *
+ * Legacy name kept in `KNOWN_TOP_LEVEL_SECTIONS` + `removeStalePageLabels`
+ * so existing files with a "Design Tokens" frame get cleaned up on the
+ * next run instead of leaving an orphan next to the new frame.
+ */
+const TOKENS_ROW_NAME = 'Custom Tokens';
+const LEGACY_TOKENS_ROW_NAME = 'Design Tokens';
+
 // Remove orphaned top-level nodes left behind by failed/interrupted runs.
 // The Design System page is plugin-managed: only these named sections are
 // expected as direct children. Anything else is stale generator output.
 const KNOWN_TOP_LEVEL_SECTIONS = new Set([
-  'Design Tokens',
+  TOKENS_ROW_NAME,
+  LEGACY_TOKENS_ROW_NAME,
   'UI Components',
   COMPONENT_LIBRARY_ROOT_NAME,
 ]);
@@ -211,13 +227,19 @@ export async function buildDesignSystemSinglePage(
   figma.currentPage = ds;
   removeDuplicateTopLevelSections(ds);
   removeOrphanedTopLevelNodes(ds);
-  removeStalePageLabels(ds, ['Design Tokens', 'UI Components']);
+  removeStalePageLabels(ds, [TOKENS_ROW_NAME, LEGACY_TOKENS_ROW_NAME, 'UI Components']);
 
   const themeNames = getThemeNames(TOKENS);
 
   // Compute a single token hash for this run. Passed into createUIComponents
   // so component blocks can include token state in their own hashes.
-  const tokenHash = hashString(stableStringify(TOKENS));
+  //
+  // Includes RENDER_ENGINE_VERSION so changes to the demoFrame* rendering
+  // code (e.g. wrapping fontsize cells into a row, swapping shadow layout)
+  // invalidate the cached row even when TOKENS values are unchanged. Same
+  // pattern buildStateComponentSetHash uses for state masters — without
+  // this, a "fix" lands in code.js but the row paints from the stale cache.
+  const tokenHash = hashString(stableStringify(TOKENS) + ':' + RENDER_ENGINE_VERSION);
 
   // The design-tokens toggle is a synthetic preflight item; strip it before
   // forwarding the excluded list to the component builder so it isn't treated
@@ -228,7 +250,11 @@ export async function buildDesignSystemSinglePage(
   // --- Design Tokens row (incremental) ---
   // Rebuilt only when token values have changed since the last run, and only
   // when the design-tokens preflight toggle is selected.
-  let tokensRow: FrameNode | null = findChildByName(ds, 'Design Tokens') as FrameNode | null;
+  // Look for the renamed frame first; fall back to the legacy name so
+  // existing Figma files with a "Design Tokens" frame migrate in place
+  // (the next rebuild renames it via `.name = TOKENS_ROW_NAME` below).
+  let tokensRow: FrameNode | null = (findChildByName(ds, TOKENS_ROW_NAME)
+    || findChildByName(ds, LEGACY_TOKENS_ROW_NAME)) as FrameNode | null;
   const tokensNeedRebuild = !skipDesignTokens && (!tokensRow || getFrameHash(tokensRow) !== tokenHash);
   if (tokensNeedRebuild) await onStatus('Building design tokens…');
   if (tokensNeedRebuild) {
@@ -237,7 +263,7 @@ export async function buildDesignSystemSinglePage(
     if (tokensRow) tokensRow.remove();
 
     tokensRow = figma.createFrame();
-    tokensRow.name = 'Design Tokens';
+    tokensRow.name = TOKENS_ROW_NAME;
     tokensRow.layoutMode = 'VERTICAL';
     tokensRow.primaryAxisSizingMode = 'AUTO';
     tokensRow.counterAxisSizingMode = 'AUTO';
@@ -258,9 +284,9 @@ export async function buildDesignSystemSinglePage(
       themeNames.map((themeName) => demoFrameFonts(themeName))
     ));
     appendIfPresent(buildTokensCategorySection('Font sizes', [demoFrameFontSizes()]));
-    appendIfPresent(buildTokensCategorySection('Radius', [demoFrameRadii()]));
     appendIfPresent(buildTokensCategorySection('Spacing', [demoFrameSpacing()]));
     appendIfPresent(buildTokensCategorySection('Breakpoints', [demoFrameBreakpoints()]));
+    appendIfPresent(buildTokensCategorySection('Radius', [demoFrameRadii()]));
     appendIfPresent(buildTokensCategorySection(
       'Shadows',
       themeNames.map((themeName) => demoFrameShadows(themeName))
@@ -279,7 +305,10 @@ export async function buildDesignSystemSinglePage(
   // Default y for a new UI Components section (below tokens row).
   // Only used when the section does not yet exist on the page. When the design
   // tokens row was skipped and never existed, fall back to the page top.
-  const defaultUiY = tokensRow ? (tokensRow.y + tokensRow.height + 80) : 48;
+  // The 240px gap is intentionally larger than the inter-row spacing inside
+  // each section so the visual hierarchy reads as two distinct top-level
+  // chapters (custom tokens vs. UI components) instead of a continuous stream.
+  const defaultUiY = tokensRow ? (tokensRow.y + tokensRow.height + 240) : 48;
 
   // Keep hidden master library aligned with current scanner output and themes.
   // Removes stale/duplicate generated masters from old runs.

package/src/design-system/frame-stabilizers.ts

@@ -23,6 +23,102 @@ import { getNodeEffectiveClasses, getNodeMarginTopPx } from './node-helpers';
  *   its parent's content width so the tab bar visually fills the row.
  */
 
+/**
+ * True when a scene node is "text-bearing" — either a TEXT leaf or a
+ * frame whose entire visible subtree is text (paragraphs, spans, text
+ * nodes wrapped in transparent frames). Buttons, inputs, icons, and
+ * other interactive primitives are NOT text-bearing — they're the
+ * shrink-resistant siblings we measure around.
+ *
+ * Used by `constrainSingleHorizontalTextChild` to treat shadcn's
+ * canonical `<div><p>Heading</p><p>Description…</p></div>` wrapper
+ * the same way as a direct `<p>` child: pick it as the shrink target
+ * in a `flex justify-between` row, constrain its width to the
+ * available space, and wrap the text inside.
+ */
+function isTextBearingNode(node: SceneNode | undefined | null): boolean {
+  if (!node) return false;
+  if (node.type === 'TEXT') return true;
+  if (node.type !== 'FRAME') return false;
+  const children = (node as FrameNode).children;
+  if (!Array.isArray(children) || children.length === 0) return false;
+  for (const child of children) {
+    if (!child) return false;
+    if ('layoutPositioning' in child && child.layoutPositioning === 'ABSOLUTE') continue;
+    if (!isTextBearingNode(child)) return false;
+  }
+  return true;
+}
+
+/**
+ * Recursively pin every TEXT descendant of a text-bearing wrapper to
+ * `textAutoResize = 'HEIGHT'` and resize it to the given width so the
+ * text wraps within the wrapper. Without this, Figma keeps text at
+ * its single-line content width and the text visually overflows even
+ * when its parent frame got the right width.
+ */
+function wrapTextDescendants(node: SceneNode, width: number): void {
+  if (!node) return;
+  if (node.type === 'TEXT') {
+    if (node.textAutoResize === undefined) return;
+    try {
+      node.textAutoResize = 'HEIGHT';
+      node.resize(Math.max(1, width), node.height);
+    } catch (_err) {
+      // ignore resize errors
+    }
+    return;
+  }
+  if (node.type !== 'FRAME') return;
+  const innerWidth = Math.max(
+    0,
+    width - ((node.paddingLeft || 0) + (node.paddingRight || 0)),
+  );
+  for (const child of node.children || []) {
+    wrapTextDescendants(child, innerWidth);
+  }
+}
+
+/**
+ * Resize a text-bearing wrapper frame to `width` and force its
+ * sizing mode to FIXED on the axis the parent dictates. Mirrors
+ * what `applyFullWidthIfPossible` does for `w-full` children — but
+ * applied locally here without requiring the wrapper to be marked
+ * full-width.
+ */
+function resizeTextBearingChild(child: SceneNode, width: number): void {
+  if (child.type === 'TEXT') {
+    try {
+      child.textAutoResize = 'HEIGHT';
+      child.resize(Math.max(1, width), child.height);
+    } catch (_err) {
+      // ignore resize errors
+    }
+    return;
+  }
+  if (child.type !== 'FRAME') return;
+  try {
+    child.resize(Math.max(1, width), child.height);
+    // The parent row is HORIZONTAL, so the wrapper's primary axis (its OWN
+    // width contribution) must be fixed on the horizontal axis. Whether that
+    // maps to primary or counter on the wrapper depends on the wrapper's
+    // own layoutMode.
+    if (child.layoutMode === 'HORIZONTAL' && 'primaryAxisSizingMode' in child) {
+      child.primaryAxisSizingMode = 'FIXED';
+    } else if (child.layoutMode === 'VERTICAL' && 'counterAxisSizingMode' in child) {
+      child.counterAxisSizingMode = 'FIXED';
+    }
+    if ('layoutAlign' in child) {
+      // STRETCH would otherwise let the wrapper inherit the row height too,
+      // which collapses paragraph spacing.
+      child.layoutAlign = 'INHERIT';
+    }
+  } catch (_err) {
+    // ignore resize errors
+  }
+  wrapTextDescendants(child, width);
+}
+
 export function constrainSingleHorizontalTextChild(node: SceneNode): void {
   if (node.type !== 'FRAME') return;
   const frame = node;
@@ -46,21 +142,26 @@ export function constrainSingleHorizontalTextChild(node: SceneNode): void {
     return;
   }
 
-  const textChildren = frame.children.filter((child): child is TextNode => child?.type === 'TEXT');
-  if (textChildren.length !== 1) return;
+  // Text-bearing children: either a direct TEXT node or a transparent
+  // wrapper frame whose entire subtree is text. Wrappers are needed for
+  // patterns like `<div><p>Title</p><p>Description…</p></div>` next to
+  // a `<Button>` — the description hugs to its one-line width and
+  // overlaps the button in `flex justify-between` rows.
+  const textBearing = frame.children.filter((child) => isTextBearingNode(child));
+  if (textBearing.length !== 1) return;
 
   // CSS flex: absolute/fixed siblings are out-of-flow and don't consume space
   // in the row. Including them would steal width from the text and force wrap
   // (e.g. a Select item's absolute check-indicator shrinking the label text).
   const inFlowNonText = frame.children.filter((child) => {
-    if (!child || child.type === 'TEXT') return false;
+    if (!child || isTextBearingNode(child)) return false;
     if ('layoutPositioning' in child && child.layoutPositioning === 'ABSOLUTE') return false;
     return true;
   });
   const nonTextWidth = inFlowNonText.reduce((sum, child) => {
     return sum + ('width' in child ? child.width : 0);
   }, 0);
-  const gapContributingCount = inFlowNonText.length + textChildren.length;
+  const gapContributingCount = inFlowNonText.length + textBearing.length;
 
   const availableWidth = Math.max(
     0,
@@ -73,18 +174,13 @@ export function constrainSingleHorizontalTextChild(node: SceneNode): void {
 
   if (availableWidth <= 0) return;
 
-  const textChild = textChildren[0];
+  const textChild = textBearing[0];
   // CSS-default behavior for text in a horizontal flex row is to overflow, not
   // wrap. Only constrain if the text would actually exceed the available space
   // AND there's another in-flow sibling competing for it.
   if (inFlowNonText.length === 0) return;
-  if ((textChild.width || 0) <= availableWidth) return;
-  try {
-    textChild.textAutoResize = 'HEIGHT';
-    textChild.resize(availableWidth, textChild.height);
-  } catch (_err) {
-    // ignore resize errors
-  }
+  if (!('width' in textChild) || (textChild.width || 0) <= availableWidth) return;
+  resizeTextBearingChild(textChild, availableWidth);
 }
 
 export function stabilizeHorizontalStretchChild(child: SceneNode, parent: SceneNode): void {
@@ -189,3 +285,4 @@ export function enforceTabsChildSizing(
     // ignore resize errors
   }
 }
+

package/src/design-system/preview-builder.ts

@@ -736,3 +736,41 @@ export function shouldRenderStatesForStory(def: ComponentDef, story: ComponentSt
   return storyIndex === 0;
 }
 
+/**
+ * Should the plugin render responsive-breakpoint frames for this story?
+ *
+ * Explicit opt-in/opt-out via Storybook's
+ * `parameters.inkbridge.responsive` (read by the scanner into
+ * `story.responsive`) wins. When unset, the default policy is to
+ * render responsive frames only for the canonical "Default" story of
+ * each component (or first export if no Default exists) — mirrors
+ * `shouldRenderStatesForStory`. Variant stories like `Loading`,
+ * `WithError`, `WithLegend` get a single non-responsive frame unless
+ * they explicitly opt in via `parameters: { inkbridge: { responsive: true } }`.
+ *
+ * Rationale: most variant stories repeat the same responsive shape as
+ * Default. Rendering responsive frames for every variant explodes the
+ * design-system page with redundant frames and increases build time.
+ */
+export function shouldRenderResponsiveForStory(
+  def: ComponentDef,
+  story: ComponentStory,
+  storyIndex: number
+): boolean {
+  if (story && story.responsive === true) return true;
+  if (story && story.responsive === false) return false;
+  const name = String(story && story.name ? story.name : '').toLowerCase();
+  if (name === 'default' || name.indexOf('default') !== -1) return true;
+  const stories = def && def.stories ? def.stories : [];
+  let hasDefault = false;
+  for (let i = 0; i < stories.length; i++) {
+    const storyName = String(stories[i] && stories[i].name ? stories[i].name : '').toLowerCase();
+    if (storyName && (storyName === 'default' || storyName.indexOf('default') !== -1)) {
+      hasDefault = true;
+      break;
+    }
+  }
+  if (hasDefault) return false;
+  return storyIndex === 0;
+}
+

package/src/design-system/selectable-state.ts

@@ -1,5 +1,6 @@
 import { isTruthyStateProp } from './state-utils';
 import { isSelectItemTag } from './tag-predicates';
+import { isEffectivelyHiddenOrSrOnly } from '../tailwind';
 import type { NodeIR, NodeIRElement } from '../tailwind';
 import type { RenderContext } from './render-context';
 
@@ -106,7 +107,13 @@ export function collectTextContent(node: NodeIR): string {
       walk(current.child);
       return;
     }
-    if (current.classes.includes('hidden') || current.classes.includes('sr-only')) {
+    // Skip nodes that resolve to `display: hidden` or `sr-only` after
+    // the last-wins cascade. Uses the shared helper so this stays in
+    // lock-step with the outer hidden gate in `buildFigmaNode` — the
+    // recurring "<p hidden sm:block> disappeared" bug was exactly this
+    // function drifting away from the gate via a raw
+    // `classes.includes('hidden')` check.
+    if (isEffectivelyHiddenOrSrOnly(current.classes)) {
       return;
     }
     for (const child of current.children || []) {

package/src/design-system/story-builder.ts

@@ -40,7 +40,9 @@ import {
   applyAspectRatioIfPossible,
   applyFullWidthIfPossible,
   applyRingIfPossible,
+  applyTableColumnAlignment,
   applyVerticalFlexGrowIfPossible,
+  breakHugStretchDeadlocks,
   enforceGrowChildPrimaryFixed,
   extractGridColumns,
   extractMaxWidth,
@@ -71,7 +73,7 @@ import { getActivePack } from '../plugin';
 import { normalizeLayoutClasses } from './story-layout';
 import { isGeneratedDesignSystemNode, setGeneratedFallbackReason, tagGeneratedNode } from './generated-node';
 import { type StoryBuilderContext, type StoryRenderContext } from './story-builder-context';
-import { createStatePreviewBlock, createResponsivePreviewBlock, shouldRenderStatesForStory } from './preview-builder';
+import { createStatePreviewBlock, createResponsivePreviewBlock, shouldRenderResponsiveForStory, shouldRenderStatesForStory } from './preview-builder';
 import {
   getComponentSectionName,
   groupComponentDefs,
@@ -99,14 +101,6 @@ import {
   renderStoryInstances,
 } from './instance-rendering';
 
-// Per-component + per-phase build timings to the Figma plugin console.
-// Off by default for end users — flip to `true` locally when you need to
-// see where build time goes during a "Generate Design System Page" run.
-// The loading-panel status messages are always emitted via `onStatus`;
-// this flag only gates the extra `console.log` lines that include
-// elapsed-seconds + per-component millisecond timings.
-const INKBRIDGE_PERF_LOGS = false;
-
 function ensureHeaderBlock(
   parent: FrameNode,
   frameName: string,
@@ -552,10 +546,34 @@ function populateStoryLayout(
   // positions settle against the final heights.
   walkVerticalFlexGrow(layout);
 
+  // Break the STRETCH-in-HUG-chain deadlock that CSS resolves via
+  // max-content but Figma cannot. For every HUG container in an
+  // unanchored chain that broadcasts STRETCH to its children, flip
+  // counterAxisAlignItems to MIN so children hug naturally and the
+  // container hugs to the widest child. See
+  // `src/layout/intrinsic-sizing.ts` for the predicate contract and
+  // `src/layout/intrinsic-applier.ts` for the transform rationale.
+  // Runs before the absolute-reflow pass so width readings downstream
+  // see the post-flip values.
+  breakHugStretchDeadlocks(layout);
+
   // Final pass: resolve deferred absolute positioning after all story-level
   // width/height/layout operations have completed.
   reflowDeferredAbsolutePositioningTree(layout);
 
+  // Unify column widths across rows of every <table> in the tree.
+  // CSS / `table-fixed` align columns globally; Figma sizes each row's
+  // cells independently, so rows whose content sums to different
+  // totals render with misaligned columns and `whitespace-nowrap`
+  // cells visually run into their neighbours. The pass picks per-
+  // column max-content widths from settled cell widths and resizes
+  // every cell to its column's max. Runs after the absolute-reflow
+  // pass so cell widths are final at the time we sample them.
+  // See `src/layout/table-layout.ts` for the predicate / transform
+  // rationale and known-skip cases (colspan>1, explicit width
+  // overrides).
+  applyTableColumnAlignment(layout);
+
   return { added, renderMode, useStoryTree };
 }
 
@@ -710,12 +728,7 @@ export async function createUIComponents(parent: FrameNode | PageNode, opts: Cre
   // main.ts (Reading components / Building tokens / Building components)
   // still yield 50ms so the canvas paints between top-level phases.
   const onStatus = options.onStatus;
-  const phaseStart = Date.now();
   async function emit(message: string): Promise<void> {
-    if (INKBRIDGE_PERF_LOGS) {
-      const elapsed = ((Date.now() - phaseStart) / 1000).toFixed(1);
-      console.log('[Inkbridge][build] +' + elapsed + 's  ' + message);
-    }
     if (onStatus) {
       await Promise.resolve(onStatus({ detail: message, noYield: true }));
     }
@@ -767,7 +780,9 @@ export async function createUIComponents(parent: FrameNode | PageNode, opts: Cre
   // `createUIComponents` returns; this one front-loads it. Mirrors the
   // post-build math (only pushes y down, never up) so designer-set
   // positions further down are preserved.
-  const tokensSibling = findChildByName(parent, 'Design Tokens') as FrameNode | null;
+  // Renamed sibling name first, legacy fallback for in-flight migration.
+  const tokensSibling = (findChildByName(parent, 'Custom Tokens')
+    || findChildByName(parent, 'Design Tokens')) as FrameNode | null;
   if (tokensSibling) {
     const tokensY = typeof tokensSibling.y === 'number' ? tokensSibling.y : 0;
     const tokensHeight = typeof tokensSibling.height === 'number' ? tokensSibling.height : 0;
@@ -792,7 +807,11 @@ export async function createUIComponents(parent: FrameNode | PageNode, opts: Cre
   }
 
   function formatThemeLabel(theme: string): string {
-    if (!theme) return 'Theme';
+    // Empty / missing theme → 'Default'. With the trailing ' Theme'
+    // suffix in `ensureHeaderBlock` this becomes `Default Theme`
+    // rather than the double-word `Theme Theme` an empty fallback
+    // used to produce.
+    if (!theme) return 'Default';
     return theme.charAt(0).toUpperCase() + theme.slice(1);
   }
 
@@ -856,13 +875,16 @@ export async function createUIComponents(parent: FrameNode | PageNode, opts: Cre
         const statesBlock = createStatePreviewBlock(def, story, theme, ctx);
         if (statesBlock) storyWrap.appendChild(statesBlock);
       }
-      // No pre-flight gate — `createResponsivePreviewBlock` already
-      // returns null when the story has no responsive signals (layout /
-      // tree / instance classes all lack `sm:`/`md:`/`lg:` etc.) or when
-      // the breakpoint set collapses to one, so the gate would have been
-      // a strict subset of the renderer's existing check.
-      const responsiveBlock = createResponsivePreviewBlock(def, story, theme, ctx);
-      if (responsiveBlock) storyWrap.appendChild(responsiveBlock);
+      // Two-stage gate:
+      //   1. Story-level opt-in/opt-out (parameters.inkbridge.responsive)
+      //      with default = only the canonical Default story.
+      //   2. The renderer's own no-responsive-signals fallback inside
+      //      createResponsivePreviewBlock (returns null when layout / tree
+      //      / instance classes lack `sm:`/`md:`/`lg:` etc.).
+      if (shouldRenderResponsiveForStory(def, story, storyIndex)) {
+        const responsiveBlock = createResponsivePreviewBlock(def, story, theme, ctx);
+        if (responsiveBlock) storyWrap.appendChild(responsiveBlock);
+      }
       block.appendChild(storyWrap);
     }
 
@@ -908,7 +930,14 @@ export async function createUIComponents(parent: FrameNode | PageNode, opts: Cre
     colFrame.counterAxisSizingMode = 'AUTO';
     colFrame.counterAxisAlignItems = 'MIN';
     colFrame.paddingLeft = colFrame.paddingRight = BOARD_LAYOUT.columnPaddingX;
-    colFrame.paddingTop = colFrame.paddingBottom = BOARD_LAYOUT.columnPaddingY;
+    // Top padding is 0 so the column's "Default Theme" header sits flush
+    // under the section's "UI Components" header (separated only by the
+    // section-level `boardGap`). The full `columnPaddingY` value still
+    // applies at the bottom as a tail buffer before the next section.
+    // Previously top == bottom == 160 left a 256-px gap between the two
+    // headers that made the section header look orphaned at the top.
+    colFrame.paddingTop = 0;
+    colFrame.paddingBottom = BOARD_LAYOUT.columnPaddingY;
     colFrame.fills = [];
     // Keep columns transparent; story surfaces are responsible for their own backgrounds.
     ctx.applyClipBehavior(colFrame, []);
@@ -1153,12 +1182,7 @@ export async function createUIComponents(parent: FrameNode | PageNode, opts: Cre
         // Per-component timing log to the plugin console (no toast,
         // no yield — would balloon overhead). Lets us see in dev tools
         // which components dominate build time without slowing the run.
-        const componentStart = Date.now();
         const newBlock = buildComponentBlock(def, theme, colFrame);
-        const componentMs = Date.now() - componentStart;
-        if (INKBRIDGE_PERF_LOGS && componentMs > 50) {
-          console.log('[Inkbridge][build]   · ' + def.name + ' (' + theme + ')  ' + componentMs + 'ms');
-        }
         setFrameHash(newBlock, blockHash);
         tagGeneratedNode(newBlock, 'component-block:' + sectionTitle + ':' + theme + ':' + def.name);
 
@@ -1226,9 +1250,15 @@ export async function createUIComponents(parent: FrameNode | PageNode, opts: Cre
   const multiMode = isMultiModeEnabled();
   if (multiMode) {
     const activeTheme = requestedThemes[0] || 'primary';
-    expectedColumnNames['Theme Column'] = true;
-    const singleCol = await addColumn('Theme', activeTheme);
-    if (findChildIndexByName(columns, 'Theme Column') !== 0) {
+    // Single-column multi-mode rendering: there's one frame but its
+    // contents flip via Figma variable modes. Use `'Default'` as the
+    // generic label so the header reads `Default Theme` (not the
+    // double-word `Theme Theme` that resulted from a literal `'Theme'`
+    // label getting suffixed with ` Theme` by `ensureHeaderBlock`).
+    // Also flows into the progress notice (`Building default theme…`).
+    expectedColumnNames['Default Column'] = true;
+    const singleCol = await addColumn('Default', activeTheme);
+    if (findChildIndexByName(columns, 'Default Column') !== 0) {
       columns.insertChild(0, singleCol);
     }
     setThemeMode(singleCol, activeTheme);

package/src/design-system/story-dimensioning.ts

@@ -1,5 +1,6 @@
 import {
   extractLeadingContainerMaxWidthFromTree,
+  findAnyMaxWidthInTree,
   splitClassName,
   treeHasFullWidth,
   type JsxElement,
@@ -176,10 +177,20 @@ export function resolveStoryLayoutWidth(
   const fixedWidth = extractFixedWidth(layoutClasses);
   const maxWidthFromLayout = extractMaxWidth(layoutClasses);
   const maxWidthFromTree = extractLeadingContainerMaxWidthFromTree(story.jsxTree);
+  // Looser fallback: any `max-w-*` anywhere in the tree. Catches portal-mounted
+  // dialogs (shadcn DialogContent: `sm:max-w-lg` without `w-full`, wrapped by
+  // a multi-child Dialog → leading-container helper bails). Only consulted
+  // when the strict helper returns null, so existing behaviour is unchanged.
+  const looseMaxWidthFromTree = maxWidthFromTree == null
+    ? findAnyMaxWidthInTree(story.jsxTree)
+    : null;
+  const effectiveMaxWidthFromTree = maxWidthFromTree != null
+    ? maxWidthFromTree
+    : looseMaxWidthFromTree;
   const constrainedMaxWidth = (
-    maxWidthFromLayout != null && maxWidthFromTree != null
-      ? Math.min(maxWidthFromLayout, maxWidthFromTree)
-      : (maxWidthFromTree != null ? maxWidthFromTree : maxWidthFromLayout)
+    maxWidthFromLayout != null && effectiveMaxWidthFromTree != null
+      ? Math.min(maxWidthFromLayout, effectiveMaxWidthFromTree)
+      : (effectiveMaxWidthFromTree != null ? effectiveMaxWidthFromTree : maxWidthFromLayout)
   );
   const mobileOnlyWidth = mobileOnlyRootWidth(story, layoutClasses);
   const fallbackWidth = !fixedWidth && story.jsxTree && treeHasFullWidth(story.jsxTree, null, {

package/src/design-system/tag-predicates.ts

@@ -55,6 +55,14 @@ export function isSelectRootTag(tagName: string): boolean {
   return tagName === 'Select' || tagName === 'SelectPrimitive.Root';
 }
 
+export function isDialogRootTag(tagName: string): boolean {
+  return tagName === 'Dialog' || tagName === 'DialogPrimitive.Root';
+}
+
+export function isDialogContentTag(tagName: string): boolean {
+  return tagName === 'DialogContent' || tagName === 'DialogPrimitive.Content';
+}
+
 export function isSelectContentTag(tagName: string): boolean {
   return tagName === 'SelectContent' || tagName === 'SelectPrimitive.Content';
 }

package/src/design-system/typography.ts

@@ -86,6 +86,32 @@ export function getResolvedTextSizeFromClasses(classes: string[], fallback?: num
   return resolved;
 }
 
+/**
+ * Map the active Tailwind `font-*` family class to a theme font role
+ * (`sans` / `mono` / `serif` / `heading`). Falls back to the tag-based
+ * heading detection when no `font-*` family class is present.
+ *
+ * Without this, every text node — including `<span className="font-mono">`
+ * — was created with `fontRole: 'sans'`, so the mono family override
+ * never reached `createTextNode` and prices / numbers stayed in the
+ * surrounding sans face.
+ */
+export function getFontRoleFromClasses(classes: string[], tagLower: string): string {
+  // Last `font-*` class in the array wins (mirrors CSS cascade — a
+  // child `font-mono` overrides a parent `font-sans` even when both
+  // appear in the same merged array).
+  for (let i = classes.length - 1; i >= 0; i--) {
+    const c = classes[i];
+    if (c === 'font-mono') return 'mono';
+    if (c === 'font-serif') return 'serif';
+    if (c === 'font-sans') return 'sans';
+  }
+  if (tagLower === 'h1' || tagLower === 'h2' || tagLower === 'h3' || tagLower === 'h4' || tagLower === 'h5' || tagLower === 'h6') {
+    return 'heading';
+  }
+  return 'sans';
+}
+
 export function getResolvedBoldFromClasses(classes: string[], fallback?: boolean): boolean | undefined {
   let rank = fallback ? 7 : 4;
   let seenWeight = false;