inkbridge 0.1.0-beta.1

package/src/story-builder.ts

@@ -0,0 +1,1706 @@
+import { TOKENS, COMPONENT_DEFS, getThemeColors, getThemeNames, getThemeRadius } from './tokens';
+import { parseColor, debug, type RGB } from './colors';
+import { bindColorVariable, setThemeMode, isMultiModeEnabled } from './variables';
+import { tailwindClassesToStyle, applyTailwindStylesToFrame, applyFullWidthIfPossible } from './tailwind';
+import { createCompoundComponent } from './component-gen';
+import { getActivePack } from './packs';
+import { extractTextColorToken, resolveTextColorValue } from './color-resolver';
+import { defaultGridWidth, extractGridBreakpointWidthFromTree, extractGridColumnsFromTree, normalizeLayoutClasses } from './story-layout';
+import { extractFixedWidth, extractMaxWidth, extractGridBreakpointWidth, extractGridColumns, shouldSkipFullWidthForClasses } from './width-solver';
+import { treeHasFullWidth } from './class-utils';
+import { createTextNode } from './text-builder';
+import { type JsxNode, splitClassName } from './node-ir';
+import { extractStatesFromClasses, mergeStatesWithDefinition, type StateInfo } from './state-analyzer';
+import { extractBreakpointsFromClasses, getClassesForBreakpoint, hasSignificantResponsiveChanges, getBreakpointLabel } from './responsive-analyzer';
+import { extractArbitraryValue, parseLength, parseUtilityClass } from './utility-resolver';
+
+declare const figma: any;
+
+export type StoryRenderContext = {
+  maxWidth?: number;
+  textAlign?: 'LEFT' | 'CENTER' | 'RIGHT';
+  parentLayout?: 'HORIZONTAL' | 'VERTICAL';
+  textColor?: string | RGB | null;
+  textColorToken?: string;
+  parentCompoundDef?: any;
+};
+
+type ThemeContext = {
+  theme: string;
+  colorGroup: Record<string, string>;
+  radiusGroup: Record<string, string> | null;
+};
+
+export type StoryBuilderContext = {
+  getComponentDefByName: (name: string) => any | null;
+  normalizeComponentDef: (raw: any) => any;
+  applyClipBehavior: (frame: FrameNode, classes: string[] | undefined) => void;
+  applyLayoutClasses: (
+    frame: FrameNode,
+    classes: string[] | undefined,
+    colorGroup: Record<string, string>,
+    radiusGroup: Record<string, string> | null,
+    theme: string
+  ) => void;
+  hasExplicitHeight: (classes: string[] | undefined) => boolean;
+  renderJsxTree: (
+    node: JsxNode,
+    colorGroup: Record<string, string>,
+    radiusGroup: Record<string, string> | null,
+    theme: string,
+    depth?: number,
+    context?: StoryRenderContext
+  ) => SceneNode | null;
+  applyAbsoluteIfAllowed: (child: SceneNode, parent: FrameNode, allowAbsolute: boolean) => void;
+  applyGridColumnsWithReflow: (frame: FrameNode, widthOverride?: number, colsOverride?: number) => void;
+  hasWidthHintInClasses: (classes: string[]) => boolean;
+  propsContainWidthHint: (props: Record<string, any> | undefined) => boolean;
+};
+
+const THEME_CONTEXT_CACHE: Record<string, ThemeContext> = {};
+
+function getThemeContext(theme: string): ThemeContext {
+  if (THEME_CONTEXT_CACHE[theme]) return THEME_CONTEXT_CACHE[theme];
+  const colorGroup = getThemeColors(TOKENS, theme);
+  const radiusGroup = getThemeRadius(TOKENS, theme);
+  const ctx: ThemeContext = {
+    theme: theme,
+    colorGroup: colorGroup,
+    radiusGroup: radiusGroup,
+  };
+  THEME_CONTEXT_CACHE[theme] = ctx;
+  return ctx;
+}
+
+function applyStyleToFrame(frame: any, style: any, theme: string): void {
+  if (!style) return;
+
+  if (style.bg) {
+    const bgBound = style.bgToken && bindColorVariable(frame, style.bgToken, 'fill', theme);
+    if (!bgBound) {
+      const bg = parseColor(style.bg);
+      const bgOpacity = style.bgOpacity != null ? style.bgOpacity : (bg.a == null ? 1 : bg.a);
+      frame.fills = [{ type: 'SOLID', color: { r: bg.r, g: bg.g, b: bg.b }, opacity: bgOpacity }];
+    }
+  }
+
+  if (style.border) {
+    const borderBound = style.borderToken && bindColorVariable(frame, style.borderToken, 'stroke', theme);
+    if (!borderBound) {
+      const borderColor = parseColor(style.border);
+      frame.strokes = [{ type: 'SOLID', color: { r: borderColor.r, g: borderColor.g, b: borderColor.b } }];
+    }
+    frame.strokeWeight = 1;
+  }
+
+  if (style.opacity != null) {
+    frame.opacity = style.opacity;
+  }
+}
+
+type RingInfo = { width: number; color: { r: number; g: number; b: number; a?: number } };
+
+function getStateEntry(states: StateInfo[], name: string): StateInfo | null {
+  for (let i = 0; i < states.length; i++) {
+    if (states[i].name === name) return states[i];
+  }
+  return null;
+}
+
+function getStateNames(states: StateInfo[]): string[] {
+  const names: string[] = ['default'];
+  for (let i = 0; i < states.length; i++) {
+    const name = states[i].name;
+    if (name === 'default') continue;
+    names.push(name);
+  }
+  return names;
+}
+
+function buildStateClasses(states: StateInfo[], name: string): string[] {
+  const defaultEntry = getStateEntry(states, 'default');
+  const baseClasses = defaultEntry ? defaultEntry.classes.slice() : [];
+  if (name === 'default') return baseClasses;
+  const entry = getStateEntry(states, name);
+  if (!entry) return baseClasses;
+  return baseClasses.concat(entry.classes);
+}
+
+function isVisualStateUtility(cls: string): boolean {
+  const atom = parseUtilityClass(cls);
+  const utility = atom.utility || cls;
+  if (!utility) return false;
+  if (utility.startsWith('text-')) return false;
+  if (utility.startsWith('font-')) return false;
+  if (utility === 'underline' || utility === 'no-underline') return false;
+  if (utility.startsWith('decoration-')) return false;
+
+  return (
+    utility.startsWith('bg-')
+    || utility.startsWith('border')
+    || utility.startsWith('ring')
+    || utility.startsWith('shadow')
+    || utility.startsWith('opacity-')
+    || utility.startsWith('outline')
+    || utility.startsWith('cursor-')
+    || utility.startsWith('pointer-events-')
+    || utility.startsWith('scale-')
+    || utility.startsWith('translate-')
+    || utility.startsWith('rotate-')
+    || utility.startsWith('skew-')
+  );
+}
+
+function shouldSkipStatePreview(def: any): boolean {
+  if (!def || def.type !== 'state') return false;
+  const states = def.states || {};
+  const names = Object.keys(states).filter(name => name !== 'default');
+  if (names.length === 0) return true;
+
+  let hasVisualState = false;
+  for (let i = 0; i < names.length; i++) {
+    const state = states[names[i]];
+    const classes = state && state.classes ? state.classes : [];
+    for (let j = 0; j < classes.length; j++) {
+      if (isVisualStateUtility(classes[j])) {
+        hasVisualState = true;
+        break;
+      }
+    }
+    if (hasVisualState) break;
+  }
+  if (hasVisualState) return false;
+
+  const stories = def.stories || [];
+  for (let i = 0; i < stories.length; i++) {
+    const tree = stories[i] && stories[i].jsxTree ? stories[i].jsxTree : null;
+    if (!tree || tree.type !== 'element') continue;
+    const tagName = String((tree as any).tagName || '').toLowerCase();
+    if (
+      tagName === 'div'
+      || tagName === 'section'
+      || tagName === 'header'
+      || tagName === 'footer'
+      || tagName === 'main'
+      || tagName === 'article'
+      || tagName === 'nav'
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function parseRingWidth(utility: string): number | null {
+  if (utility === 'ring') return 3;
+  if (!utility.startsWith('ring-')) return null;
+  const token = utility.substring(5);
+  if (token === 'inset' || token.startsWith('offset-')) return null;
+  if (token.startsWith('[')) {
+    const arbitrary = extractArbitraryValue(utility);
+    if (!arbitrary) return null;
+    return parseLength(arbitrary);
+  }
+  const num = parseFloat(token);
+  if (!Number.isNaN(num) && String(num) === token) return num;
+  return null;
+}
+
+function parseRingColor(utility: string, colorGroup: Record<string, string>): { r: number; g: number; b: number; a?: number } | null {
+  if (!utility.startsWith('ring-')) return null;
+  const token = utility.substring(5);
+  if (token === 'inset' || token.startsWith('offset-')) return null;
+  if (token.startsWith('[')) return null;
+  const num = parseFloat(token);
+  if (!Number.isNaN(num) && String(num) === token) return null;
+  const resolved = colorGroup[token];
+  if (!resolved) return null;
+  return parseColor(resolved);
+}
+
+function getRingInfoFromClasses(classes: string[], colorGroup: Record<string, string>): RingInfo | null {
+  let width: number | null = null;
+  let color: { r: number; g: number; b: number; a?: number } | null = null;
+
+  for (let i = 0; i < classes.length; i++) {
+    const cls = classes[i];
+    const nextWidth = parseRingWidth(cls);
+    if (nextWidth != null) width = nextWidth;
+    const nextColor = parseRingColor(cls, colorGroup);
+    if (nextColor) color = nextColor;
+  }
+
+  if (width == null && color == null) return null;
+  if (width == null) width = 3;
+  if (!color) {
+    const fallback = colorGroup.ring || colorGroup.primary;
+    if (!fallback) return null;
+    color = parseColor(fallback);
+  }
+  if (!width || width <= 0) return null;
+  return { width, color };
+}
+
+function hasVisibleFill(node: FrameNode): boolean {
+  const fills = (node as any).fills;
+  if (!Array.isArray(fills)) return false;
+  for (let i = 0; i < fills.length; i++) {
+    const fill = fills[i];
+    if (!fill || fill.visible === false) continue;
+    if (fill.opacity != null && fill.opacity <= 0) continue;
+    return true;
+  }
+  return false;
+}
+
+function applyRingEffect(node: FrameNode, classes: string[], colorGroup: Record<string, string>): void {
+  const ring = getRingInfoFromClasses(classes, colorGroup);
+  if (!ring) return;
+  const useSpread = (node as any).clipsContent === true && hasVisibleFill(node);
+  if (!useSpread) {
+    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);
+    return;
+  }
+  const effect: DropShadowEffect = {
+    type: 'DROP_SHADOW',
+    color: { r: ring.color.r, g: ring.color.g, b: ring.color.b, a: ring.color.a == null ? 1 : ring.color.a },
+    offset: { x: 0, y: 0 },
+    radius: 0,
+    spread: ring.width,
+    visible: true,
+    blendMode: 'NORMAL'
+  };
+  const effects: Effect[] = [];
+  if (node.effects && node.effects.length > 0) {
+    for (let i = 0; i < node.effects.length; i++) effects.push(node.effects[i]);
+  }
+  effects.push(effect);
+  node.effects = effects;
+}
+
+function normalizeComponentName(name: string | undefined): string {
+  return String(name || '').toLowerCase().replace(/-/g, '');
+}
+
+function findMatchingInstance(def: any, story: any): any | null {
+  const instances = story && story.instances ? story.instances : [];
+  const defKey = normalizeComponentName(def && def.name);
+  for (let i = 0; i < instances.length; i++) {
+    const instance = instances[i];
+    if (!instance || !instance.componentName) continue;
+    if (normalizeComponentName(instance.componentName) === defKey) return instance;
+  }
+  return null;
+}
+
+function buildStatePreviewLabel(def: any, instance: any): string {
+  const props = instance && instance.props ? instance.props : {};
+  if (instance && instance.children) return String(instance.children);
+  if (props.children) return String(props.children);
+  if (props.placeholder) return String(props.placeholder);
+  if (props.defaultValue) return String(props.defaultValue);
+  return def && def.name ? String(def.name) : 'Component';
+}
+
+function buildStoryStateClasses(def: any, instance: any): string[] {
+  const props = instance && instance.props ? instance.props : {};
+  const classes: string[] = [];
+
+  if (def && def.baseClasses) {
+    for (let i = 0; i < def.baseClasses.length; i++) classes.push(def.baseClasses[i]);
+  }
+
+  if (def && def.type === 'cva') {
+    const variantKeys = Object.keys(def.variants || {});
+    for (let i = 0; i < variantKeys.length; i++) {
+      const key = variantKeys[i];
+      const value = props[key] || (def.defaultVariants && def.defaultVariants[key]) || (def.variants[key] && def.variants[key][0]);
+      if (value && def.variantClasses && def.variantClasses[key] && def.variantClasses[key][value]) {
+        const variantClasses = def.variantClasses[key][value];
+        for (let j = 0; j < variantClasses.length; j++) classes.push(variantClasses[j]);
+      }
+    }
+  }
+
+  const extra = splitClassName(props.className);
+  for (let i = 0; i < extra.length; i++) classes.push(extra[i]);
+  return classes;
+}
+
+function getPreviewTypography(classes: string[]): { fontSize: number; bold: boolean } {
+  const sizeMap: Record<string, number> = {
+    'text-xs': 12,
+    'text-sm': 14,
+    'text-base': 16,
+    'text-lg': 18,
+    'text-xl': 20,
+    'text-2xl': 24,
+    'text-3xl': 30,
+    'text-4xl': 36,
+    'text-5xl': 48,
+  };
+  let fontSize = 14;
+  let bold = false;
+  for (let i = 0; i < classes.length; i++) {
+    const atom = parseUtilityClass(classes[i]);
+    const utility = atom.utility || '';
+    if (sizeMap[utility] != null) fontSize = sizeMap[utility];
+    if (utility === 'font-bold' || utility === 'font-semibold') bold = true;
+    if (utility === 'font-normal' || utility === 'font-light' || utility === 'font-extralight') bold = false;
+  }
+  return { fontSize: fontSize, bold: bold };
+}
+
+function measureTextWidth(label: string, options?: any): number {
+  const node = createTextNode(label, options);
+  const width = node.width;
+  try {
+    node.remove();
+  } catch (_err) {
+    // ignore
+  }
+  return width;
+}
+
+function createPreviewLabelNode(label: string, classes: string[], colorGroup: Record<string, string>): TextNode {
+  const style = tailwindClassesToStyle(classes, 'default', colorGroup);
+  const textColor = style.text ? parseColor(style.text) :
+    (colorGroup.foreground ? parseColor(colorGroup.foreground) : { r: 0, g: 0, b: 0 });
+  const typography = getPreviewTypography(classes);
+  const text = createTextNode(label, { bold: typography.bold, fontSize: typography.fontSize, fill: textColor });
+  if (style.underline && text.textDecoration !== undefined) {
+    text.textDecoration = 'UNDERLINE';
+  }
+  return text;
+}
+
+function buildStoryInstanceClasses(def: any, instance: any): string[] {
+  const props = instance && instance.props ? instance.props : {};
+  let classes: string[] = def && def.baseClasses ? def.baseClasses.slice() : [];
+
+  if (def && def.type === 'cva') {
+    const variantKeys = Object.keys(def.variants || {});
+    for (let i = 0; i < variantKeys.length; i++) {
+      const key = variantKeys[i];
+      const value = props[key]
+        || (def.defaultVariants && def.defaultVariants[key])
+        || (def.variants && def.variants[key] && def.variants[key][0]);
+      if (value && def.variantClasses && def.variantClasses[key] && def.variantClasses[key][value]) {
+        classes = classes.concat(def.variantClasses[key][value]);
+      }
+    }
+  }
+
+  const extra = splitClassName(props.className);
+  if (extra.length > 0) {
+    classes = classes.concat(extra);
+  }
+
+  return classes;
+}
+
+function collectTreeClasses(node: JsxNode | undefined, output: string[]): void {
+  if (!node) return;
+  if (node.type === 'element') {
+    const el = node as any;
+    const className = el.props && el.props.className ? String(el.props.className) : '';
+    if (className) {
+      const list = splitClassName(className);
+      for (let i = 0; i < list.length; i++) output.push(list[i]);
+    }
+    const children = el.children || [];
+    for (let i = 0; i < children.length; i++) {
+      collectTreeClasses(children[i], output);
+    }
+  }
+}
+
+function treeHasResponsiveClasses(node: JsxNode | undefined): boolean {
+  const list: string[] = [];
+  collectTreeClasses(node, list);
+  return list.length > 0 && hasSignificantResponsiveChanges(list);
+}
+
+function mapClassNameForBreakpoint(value: string | undefined, breakpoint: string): string | undefined {
+  if (!value) return value;
+  const list = splitClassName(value);
+  if (list.length === 0) return value;
+  const mapped = getClassesForBreakpoint(list, breakpoint);
+  let hasGrid = false;
+  let hasGridCols = false;
+  for (let i = 0; i < mapped.length; i++) {
+    const cls = mapped[i];
+    if (cls === 'grid' || cls === 'inline-grid') hasGrid = true;
+    if (cls.startsWith('grid-cols-')) hasGridCols = true;
+  }
+  if (hasGrid && !hasGridCols) mapped.push('grid-cols-1');
+  return mapped.join(' ');
+}
+
+function cloneJsxNodeForBreakpoint(node: JsxNode, breakpoint: string): JsxNode {
+  if (!node || node.type !== 'element') return node;
+  const el: any = node;
+  const nextProps = el.props ? Object.assign({}, el.props) : {};
+  if (nextProps.className) {
+    nextProps.className = mapClassNameForBreakpoint(String(nextProps.className), breakpoint);
+  }
+  const nextChildren: any[] = [];
+  const children = el.children || [];
+  for (let i = 0; i < children.length; i++) {
+    nextChildren.push(cloneJsxNodeForBreakpoint(children[i], breakpoint));
+  }
+  return Object.assign({}, el, { props: nextProps, children: nextChildren });
+}
+
+function extractGridColsFromTree(node: JsxNode | undefined): number | null {
+  if (!node || node.type !== 'element') return null;
+  const el = node as any;
+  const className = el.props && el.props.className ? String(el.props.className) : '';
+  const list = className ? splitClassName(className) : [];
+  let hasGrid = false;
+  for (let i = 0; i < list.length; i++) {
+    const cls = list[i];
+    if (cls === 'grid' || cls === 'inline-grid') hasGrid = true;
+    const match = cls.match(/^grid-cols-(\d+)$/);
+    if (match) return parseInt(match[1], 10);
+  }
+  const children = el.children || [];
+  for (let i = 0; i < children.length; i++) {
+    const found = extractGridColsFromTree(children[i]);
+    if (found != null) return found;
+  }
+  return hasGrid ? 1 : null;
+}
+
+function extractLeadingContainerMaxWidthFromTree(node: JsxNode | undefined): number | null {
+  let current: JsxNode | undefined = node;
+  let constrainedWidth: number | null = null;
+
+  while (current && current.type === 'element') {
+    const element = current as any;
+    const className = element.props && element.props.className ? String(element.props.className) : '';
+    const classes = className ? splitClassName(className) : [];
+    const hasFullWidth = classes.indexOf('w-full') !== -1;
+    const maxWidth = extractMaxWidth(classes);
+
+    if (hasFullWidth && maxWidth != null) {
+      constrainedWidth = constrainedWidth == null ? maxWidth : Math.min(constrainedWidth, maxWidth);
+    }
+
+    const children = element.children || [];
+    if (children.length !== 1 || !children[0] || children[0].type !== 'element') {
+      break;
+    }
+    current = children[0];
+  }
+
+  return constrainedWidth;
+}
+
+function uniqueClassSignature(classes: string[] | undefined): string {
+  const seen: Record<string, boolean> = {};
+  const output: string[] = [];
+  const list = classes || [];
+  for (let i = 0; i < list.length; i++) {
+    const cls = list[i];
+    if (!cls || seen[cls]) continue;
+    seen[cls] = true;
+    output.push(cls);
+  }
+  return output.join(' ');
+}
+
+function treeClassSignature(node: JsxNode | undefined): string {
+  const classes: string[] = [];
+  collectTreeClasses(node, classes);
+  return uniqueClassSignature(classes);
+}
+
+function buildCvaClassesForVariant(def: any, props: Record<string, any>, primaryKey: string, primaryValue: string): string[] {
+  const classes: string[] = [];
+  if (def && def.baseClasses) {
+    for (let i = 0; i < def.baseClasses.length; i++) classes.push(def.baseClasses[i]);
+  }
+  const variants = def && def.variants ? def.variants : {};
+  const variantKeys = Object.keys(variants);
+  for (let i = 0; i < variantKeys.length; i++) {
+    const key = variantKeys[i];
+    let value: string | null = null;
+    if (key === primaryKey) {
+      value = primaryValue;
+    } else if (props && props[key]) {
+      value = props[key];
+    } else if (def && def.defaultVariants && def.defaultVariants[key]) {
+      value = def.defaultVariants[key];
+    } else if (variants[key] && variants[key][0]) {
+      value = variants[key][0];
+    }
+    if (value && def.variantClasses && def.variantClasses[key] && def.variantClasses[key][value]) {
+      const variantClasses = def.variantClasses[key][value];
+      for (let j = 0; j < variantClasses.length; j++) classes.push(variantClasses[j]);
+    }
+  }
+  const extra = splitClassName(props && props.className);
+  for (let i = 0; i < extra.length; i++) classes.push(extra[i]);
+  return classes;
+}
+
+function createStatePreviewBlock(
+  def: any,
+  story: any,
+  theme: string,
+  ctx: StoryBuilderContext
+): FrameNode | null {
+  if (!def || (def.type !== 'cva' && def.type !== 'state')) return null;
+  if (shouldSkipStatePreview(def)) return null;
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const instance = findMatchingInstance(def, story);
+  const props = instance && instance.props ? instance.props : {};
+
+  const block = figma.createFrame();
+  block.name = 'States';
+  block.layoutMode = 'VERTICAL';
+  block.itemSpacing = 16;
+  block.primaryAxisSizingMode = 'AUTO';
+  block.counterAxisSizingMode = 'AUTO';
+  block.fills = [];
+  ctx.applyClipBehavior(block, []);
+
+  const matrixTitleStyle = { fontSize: 18, bold: true, opacity: 0.95 };
+  const axisLabelStyle = { fontSize: 13, bold: true, opacity: 0.78 };
+  const itemLabelStyle = { fontSize: 13, bold: true, opacity: 0.72 };
+
+  block.appendChild(createTextNode('State Matrix', matrixTitleStyle));
+
+  const label = buildStatePreviewLabel(def, instance);
+
+  function createStateCell(stateName: string, classes: string[], columnLabel: string): FrameNode {
+    const comp = figma.createFrame();
+    comp.name = def.name + '/' + columnLabel + '/' + stateName;
+    comp.primaryAxisSizingMode = 'AUTO';
+    comp.counterAxisSizingMode = 'AUTO';
+    comp.counterAxisAlignItems = 'CENTER';
+    comp.primaryAxisAlignItems = 'CENTER';
+    comp.itemSpacing = 8;
+    comp.fills = [];
+    comp.strokes = [];
+    ctx.applyClipBehavior(comp, classes);
+
+    applyTailwindStylesToFrame(comp, classes, colorGroup, radiusGroup, theme);
+    comp.appendChild(createPreviewLabelNode(label, classes, colorGroup));
+    applyRingEffect(comp, classes, colorGroup);
+
+    return comp;
+  }
+
+  type VariantColumn = { label: string; states: StateInfo[] };
+  const columns: VariantColumn[] = [];
+
+  if (def.type === 'cva' && def.variants && Object.keys(def.variants).length > 0) {
+    const variantKeys = Object.keys(def.variants);
+    const primaryKey = def.variants.variant ? 'variant' : variantKeys[0];
+    const primaryValues = def.variants[primaryKey] || [];
+    for (let i = 0; i < primaryValues.length; i++) {
+      const value = primaryValues[i];
+      const classes = buildCvaClassesForVariant(def, props, primaryKey, value);
+      const states = mergeStatesWithDefinition(extractStatesFromClasses(classes), def);
+      const labelText = value ? value.charAt(0).toUpperCase() + value.slice(1) : '';
+      columns.push({ label: labelText, states: states });
+    }
+  } else {
+    const classes = buildStoryStateClasses(def, instance);
+    if (classes.length === 0) return null;
+    const states = mergeStatesWithDefinition(extractStatesFromClasses(classes), def);
+    columns.push({ label: def.name || 'Component', states: states });
+  }
+
+  if (columns.length === 0) return null;
+
+  const stateNames: string[] = columns.length > 0 ? getStateNames(columns[0].states) : [];
+  for (let i = 1; i < columns.length; i++) {
+    const names = getStateNames(columns[i].states);
+    for (let j = 0; j < names.length; j++) {
+      const name = names[j];
+      if (stateNames.indexOf(name) === -1) {
+        stateNames.push(name);
+      }
+    }
+  }
+  if (stateNames.length <= 1) return null;
+
+  const cellMatrix: FrameNode[][] = [];
+  const columnWidths: number[] = [];
+  for (let ci = 0; ci < columns.length; ci++) {
+    const column = columns[ci];
+    let maxWidth = measureTextWidth(column.label, itemLabelStyle);
+    const cells: FrameNode[] = [];
+    for (let si = 0; si < stateNames.length; si++) {
+      const stateName = stateNames[si];
+      const classes = buildStateClasses(column.states, stateName);
+      const cell = createStateCell(stateName, classes, column.label || def.name);
+      if (cell.width > maxWidth) maxWidth = cell.width;
+      cells.push(cell);
+    }
+    cellMatrix.push(cells);
+    columnWidths.push(maxWidth);
+  }
+
+  let legendWidth = measureTextWidth('State', itemLabelStyle);
+  for (let i = 0; i < stateNames.length; i++) {
+    const width = measureTextWidth(stateNames[i], itemLabelStyle);
+    if (width > legendWidth) legendWidth = width;
+  }
+  legendWidth += 24;
+
+  function createLegendCell(textValue: string, style: any): FrameNode {
+    const cell = figma.createFrame();
+    cell.layoutMode = 'VERTICAL';
+    cell.primaryAxisSizingMode = 'AUTO';
+    cell.counterAxisSizingMode = 'AUTO';
+    cell.fills = [];
+    cell.appendChild(createTextNode(textValue, style));
+    try {
+      cell.resize(legendWidth, cell.height);
+      cell.counterAxisSizingMode = 'FIXED';
+    } catch (_err) {
+      // ignore
+    }
+    return cell;
+  }
+
+  const axesRow = figma.createFrame();
+  axesRow.name = 'State Axes';
+  axesRow.layoutMode = 'HORIZONTAL';
+  axesRow.itemSpacing = 28;
+  axesRow.primaryAxisSizingMode = 'AUTO';
+  axesRow.counterAxisSizingMode = 'AUTO';
+  axesRow.fills = [];
+  ctx.applyClipBehavior(axesRow, []);
+  axesRow.appendChild(createLegendCell('States', axisLabelStyle));
+  axesRow.appendChild(createTextNode('Variants', axisLabelStyle));
+  block.appendChild(axesRow);
+
+  const table = figma.createFrame();
+  table.name = 'State Table';
+  table.layoutMode = 'VERTICAL';
+  table.itemSpacing = 12;
+  table.primaryAxisSizingMode = 'AUTO';
+  table.counterAxisSizingMode = 'AUTO';
+  table.fills = [];
+  ctx.applyClipBehavior(table, []);
+
+  const tableHeader = figma.createFrame();
+  tableHeader.name = 'State Table Header';
+  tableHeader.layoutMode = 'HORIZONTAL';
+  tableHeader.itemSpacing = 28;
+  tableHeader.primaryAxisSizingMode = 'AUTO';
+  tableHeader.counterAxisSizingMode = 'AUTO';
+  tableHeader.fills = [];
+  tableHeader.appendChild(createLegendCell('State', itemLabelStyle));
+  for (let ci = 0; ci < columns.length; ci++) {
+    const headerCell = figma.createFrame();
+    headerCell.layoutMode = 'VERTICAL';
+    headerCell.primaryAxisSizingMode = 'AUTO';
+    headerCell.counterAxisSizingMode = 'AUTO';
+    headerCell.fills = [];
+    headerCell.appendChild(createTextNode(columns[ci].label, itemLabelStyle));
+    try {
+      headerCell.resize(columnWidths[ci], headerCell.height);
+      headerCell.counterAxisSizingMode = 'FIXED';
+    } catch (_err) {
+      // ignore
+    }
+    tableHeader.appendChild(headerCell);
+  }
+  table.appendChild(tableHeader);
+
+  for (let si = 0; si < stateNames.length; si++) {
+    const row = figma.createFrame();
+    row.name = 'State Row/' + stateNames[si];
+    row.layoutMode = 'HORIZONTAL';
+    row.itemSpacing = 28;
+    row.primaryAxisSizingMode = 'AUTO';
+    row.counterAxisSizingMode = 'AUTO';
+    row.counterAxisAlignItems = 'CENTER';
+    row.fills = [];
+    row.appendChild(createLegendCell(stateNames[si], itemLabelStyle));
+    for (let ci = 0; ci < columns.length; ci++) {
+      const cell = cellMatrix[ci][si];
+      try {
+        cell.resize(columnWidths[ci], cell.height);
+        if (cell.layoutMode === 'HORIZONTAL') {
+          cell.primaryAxisSizingMode = 'FIXED';
+        } else if (cell.layoutMode === 'VERTICAL') {
+          cell.counterAxisSizingMode = 'FIXED';
+        }
+      } catch (_err) {
+        // ignore
+      }
+      row.appendChild(cell);
+    }
+    table.appendChild(row);
+  }
+
+  block.appendChild(table);
+  return block;
+}
+
+function createResponsivePreviewBlock(
+  def: any,
+  story: any,
+  theme: string,
+  ctx: StoryBuilderContext
+): FrameNode | null {
+  if (!def) return null;
+  const instance = findMatchingInstance(def, story);
+  const layoutClasses = normalizeLayoutClasses(story && story.layoutClasses);
+  const layoutHasResponsive = hasSignificantResponsiveChanges(layoutClasses);
+  const treeHasResponsive = story && story.jsxTree ? treeHasResponsiveClasses(story.jsxTree as any) : false;
+  const instanceClasses = buildStoryInstanceClasses(def, instance);
+  const instanceHasResponsive = hasSignificantResponsiveChanges(instanceClasses);
+  if (!layoutHasResponsive && !treeHasResponsive && !instanceHasResponsive) return null;
+
+  const sourceClasses: string[] = [];
+  if (layoutHasResponsive && layoutClasses.length > 0) {
+    for (let i = 0; i < layoutClasses.length; i++) sourceClasses.push(layoutClasses[i]);
+  }
+  if (treeHasResponsive && story && story.jsxTree) {
+    collectTreeClasses(story.jsxTree as any, sourceClasses);
+  }
+  if (sourceClasses.length === 0) {
+    for (let i = 0; i < instanceClasses.length; i++) sourceClasses.push(instanceClasses[i]);
+  }
+  const breakpoints = extractBreakpointsFromClasses(sourceClasses);
+  if (breakpoints.length <= 1) return null;
+  const entries: Array<{
+    bp: { name: string; minWidth: number };
+    layoutOverride: string[];
+    treeOverride: any;
+    instanceOverride: string[];
+    signature: string;
+  }> = [];
+  for (let i = 0; i < breakpoints.length; i++) {
+    const bp = breakpoints[i];
+    const layoutOverride = layoutClasses.length > 0 ? getClassesForBreakpoint(layoutClasses, bp.name) : layoutClasses;
+    let treeOverride: any = story && story.jsxTree ? story.jsxTree : null;
+    if (treeHasResponsive && story && story.jsxTree) {
+      treeOverride = cloneJsxNodeForBreakpoint(story.jsxTree as any, bp.name);
+    }
+    const instanceOverride = getClassesForBreakpoint(instanceClasses, bp.name);
+    let signature = 'I:' + uniqueClassSignature(instanceOverride);
+    if (layoutHasResponsive || treeHasResponsive) {
+      signature = 'L:' + uniqueClassSignature(layoutOverride) + '|T:' + treeClassSignature(treeOverride as any);
+    }
+    entries.push({
+      bp: { name: bp.name, minWidth: bp.minWidth },
+      layoutOverride: layoutOverride,
+      treeOverride: treeOverride,
+      instanceOverride: instanceOverride,
+      signature: signature,
+    });
+  }
+  if (entries.length <= 1) return null;
+  const filteredEntries: typeof entries = [];
+  const baseSignature = entries[0].signature;
+  const seenSignatures: Record<string, boolean> = {};
+  seenSignatures[baseSignature] = true;
+  filteredEntries.push(entries[0]);
+  for (let i = 1; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.signature === baseSignature) continue;
+    if (seenSignatures[entry.signature]) continue;
+    seenSignatures[entry.signature] = true;
+    filteredEntries.push(entry);
+  }
+  if (filteredEntries.length <= 1) return null;
+
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const label = buildStatePreviewLabel(def, instance);
+
+  const block = figma.createFrame();
+  block.name = 'Responsive';
+  block.layoutMode = 'VERTICAL';
+  block.itemSpacing = 8;
+  block.primaryAxisSizingMode = 'AUTO';
+  block.counterAxisSizingMode = 'AUTO';
+  block.fills = [];
+  ctx.applyClipBehavior(block, []);
+
+  block.appendChild(createTextNode('Responsive', { fontSize: 12, bold: true, opacity: 0.7 }));
+
+  const row = figma.createFrame();
+  row.name = 'Responsive Strip';
+  row.layoutMode = 'HORIZONTAL';
+  row.itemSpacing = 16;
+  row.primaryAxisSizingMode = 'AUTO';
+  row.counterAxisSizingMode = 'AUTO';
+  row.fills = [];
+  ctx.applyClipBehavior(row, []);
+
+  for (let i = 0; i < filteredEntries.length; i++) {
+    const entry = filteredEntries[i];
+    const bp = entry.bp;
+    const viewportWidth = getResponsivePreviewWidth(bp.name, bp.minWidth);
+
+    const col = figma.createFrame();
+    col.name = getBreakpointLabel(bp.name, bp.minWidth);
+    col.layoutMode = 'VERTICAL';
+    col.itemSpacing = 6;
+    col.primaryAxisSizingMode = 'AUTO';
+    col.counterAxisSizingMode = 'AUTO';
+    col.fills = [];
+
+    col.appendChild(createTextNode(getBreakpointLabel(bp.name, bp.minWidth), { fontSize: 12, bold: true, opacity: 0.6 }));
+    const viewport = figma.createFrame();
+    viewport.name = 'Viewport';
+    viewport.layoutMode = 'VERTICAL';
+    viewport.itemSpacing = 0;
+    viewport.primaryAxisSizingMode = 'AUTO';
+    viewport.counterAxisSizingMode = 'FIXED';
+    viewport.fills = [];
+    viewport.strokes = [];
+    viewport.clipsContent = true;
+    viewport.resize(viewportWidth, viewport.height);
+
+    if (layoutHasResponsive || treeHasResponsive) {
+      const layoutOverride = entry.layoutOverride;
+      const treeOverride = entry.treeOverride;
+      const storyOverride = Object.assign({}, story, { layoutClasses: layoutOverride, jsxTree: treeOverride });
+      const preview = renderStandaloneStory(storyOverride, theme, ctx, viewportWidth);
+      if (preview) {
+        const colsOverride = treeOverride ? extractGridColsFromTree(treeOverride as any) : null;
+        if (colsOverride != null && colsOverride > 0 && preview.children.length === 1) {
+          const target = preview.children[0];
+          if ('layoutMode' in target) {
+            const previewPadding = (preview.paddingLeft || 0) + (preview.paddingRight || 0);
+            const minWidth = defaultGridWidth(colsOverride);
+            let previewWidth = Number.isFinite(preview.width) ? preview.width - previewPadding : undefined;
+            if (!Number.isFinite(previewWidth) || (previewWidth != null && previewWidth < minWidth)) {
+              previewWidth = minWidth;
+            }
+            ctx.applyGridColumnsWithReflow(target as FrameNode, previewWidth, colsOverride);
+          }
+        }
+        if ('layoutAlign' in preview) {
+          (preview as any).layoutAlign = 'STRETCH';
+        }
+        viewport.appendChild(preview);
+      }
+    } else {
+      const bpClasses = entry.instanceOverride;
+      const comp = figma.createFrame();
+      comp.name = def.name + '/' + bp.name;
+      comp.primaryAxisSizingMode = 'AUTO';
+      comp.counterAxisSizingMode = 'AUTO';
+      comp.counterAxisAlignItems = 'CENTER';
+      comp.primaryAxisAlignItems = 'CENTER';
+      comp.itemSpacing = 8;
+      comp.fills = [];
+      comp.strokes = [];
+      ctx.applyClipBehavior(comp, bpClasses);
+
+      applyTailwindStylesToFrame(comp, bpClasses, colorGroup, radiusGroup, theme);
+      comp.appendChild(createPreviewLabelNode(label, bpClasses, colorGroup));
+
+      if ('layoutAlign' in comp) {
+        (comp as any).layoutAlign = 'STRETCH';
+      }
+      viewport.appendChild(comp);
+    }
+    col.appendChild(viewport);
+    row.appendChild(col);
+  }
+
+  block.appendChild(row);
+  return block;
+}
+
+function getResponsivePreviewWidth(breakpointName: string, minWidth: number): number {
+  if (breakpointName === 'base') return 390;
+  if (Number.isFinite(minWidth) && minWidth > 0) return minWidth;
+  return 390;
+}
+
+function shouldRenderStatesForStory(def: any, story: any, storyIndex: number): boolean {
+  const name = String(story && story.name ? story.name : '').toLowerCase();
+  if (name && (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;
+}
+
+function shouldRenderResponsiveForStory(def: any, story: any, storyIndex: number): boolean {
+  const layoutClasses = normalizeLayoutClasses(story && story.layoutClasses);
+  if (hasSignificantResponsiveChanges(layoutClasses)) return true;
+  if (story && story.jsxTree && treeHasResponsiveClasses(story.jsxTree as any)) return true;
+  const instance = findMatchingInstance(def, story);
+  const instanceClasses = buildStoryInstanceClasses(def, instance);
+  if (hasSignificantResponsiveChanges(instanceClasses)) return true;
+
+  const name = String(story && story.name ? story.name : '').toLowerCase();
+  if (name && (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;
+}
+
+export function createCVAStoryInstance(def: any, instance: any, theme: string, ctx: StoryBuilderContext): any {
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const props = instance.props || {};
+
+  let classes = def.baseClasses ? def.baseClasses.slice() : [];
+  const variantKeys = Object.keys(def.variants || {});
+  for (const key of variantKeys) {
+    const value = props[key] || (def.defaultVariants && def.defaultVariants[key]) || (def.variants[key] && def.variants[key][0]);
+    if (value && def.variantClasses && def.variantClasses[key] && def.variantClasses[key][value]) {
+      classes = classes.concat(def.variantClasses[key][value]);
+    }
+  }
+  classes = classes.concat(splitClassName(props.className));
+
+  const comp = figma.createFrame();
+  comp.name = def.name;
+  comp.primaryAxisSizingMode = 'AUTO';
+  comp.counterAxisSizingMode = 'AUTO';
+  comp.counterAxisAlignItems = 'CENTER';
+  comp.primaryAxisAlignItems = 'CENTER';
+  comp.itemSpacing = 8;
+  comp.fills = [];
+  comp.strokes = [];
+  ctx.applyClipBehavior(comp, classes);
+
+  applyTailwindStylesToFrame(comp, classes, colorGroup, radiusGroup, theme);
+
+  const state = props.disabled === 'true' ? 'disabled' : 'default';
+  const style = tailwindClassesToStyle(classes, state, colorGroup);
+  applyStyleToFrame(comp, style, theme);
+
+  const label = instance.children || props.children || def.name;
+  const typography = getPreviewTypography(classes);
+  const textColor = style.text ? parseColor(style.text) :
+    (colorGroup.foreground ? parseColor(colorGroup.foreground) : { r: 0, g: 0, b: 0 });
+  const text = createTextNode(label, { bold: typography.bold, fontSize: typography.fontSize, fill: textColor });
+  if (style.underline && text.textDecoration !== undefined) {
+    text.textDecoration = 'UNDERLINE';
+  }
+  comp.appendChild(text);
+
+  return comp;
+}
+
+export function createStateStoryInstance(def: any, instance: any, theme: string, ctx: StoryBuilderContext): any {
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const props = instance.props || {};
+
+  let classes = def.baseClasses ? def.baseClasses.slice() : [];
+  classes = classes.concat(splitClassName(props.className));
+
+  const comp = figma.createFrame();
+  comp.name = def.name;
+  comp.primaryAxisSizingMode = 'AUTO';
+  comp.counterAxisSizingMode = 'AUTO';
+  comp.counterAxisAlignItems = 'CENTER';
+  comp.itemSpacing = 8;
+  comp.fills = [];
+  comp.strokes = [];
+  ctx.applyClipBehavior(comp, classes);
+
+  applyTailwindStylesToFrame(comp, classes, colorGroup, radiusGroup, theme);
+
+  let stateName = 'default';
+  if (props['aria-invalid'] === 'true') stateName = 'error';
+  if (props.disabled === 'true') stateName = 'disabled';
+
+  if (stateName !== 'default' && def.states && def.states[stateName]) {
+    applyTailwindStylesToFrame(comp, def.states[stateName].classes || [], colorGroup, radiusGroup, theme);
+  }
+
+  const label = instance.children || props.placeholder || props.defaultValue || def.name;
+  const textColor = colorGroup['muted-foreground'] ? parseColor(colorGroup['muted-foreground']) : { r: 0.4, g: 0.4, b: 0.4 };
+  const text = createTextNode(label, { fontSize: 14, fill: textColor });
+  comp.appendChild(text);
+
+  return comp;
+}
+
+export function createSimpleStoryInstance(def: any, instance: any, theme: string, ctx: StoryBuilderContext): any {
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const props = instance.props || {};
+
+  let classes = def.classes ? def.classes.slice() : [];
+  classes = classes.concat(splitClassName(props.className));
+
+  const frame = figma.createFrame();
+  frame.name = def.name;
+  frame.primaryAxisSizingMode = 'AUTO';
+  frame.counterAxisSizingMode = 'AUTO';
+  frame.fills = [];
+  ctx.applyClipBehavior(frame, classes);
+
+  applyTailwindStylesToFrame(frame, classes, colorGroup, radiusGroup, theme);
+
+  const label = instance.children || props.children;
+  if (label) {
+    frame.appendChild(createTextNode(label, { fontSize: 12 }));
+  }
+
+  return frame;
+}
+
+function renderStoryInstances(
+  layout: any,
+  story: any,
+  theme: string,
+  colorGroup: Record<string, string>,
+  radiusGroup: Record<string, string> | null,
+  ctx: StoryBuilderContext
+): number {
+  let added = 0;
+  for (const instance of story.instances || []) {
+    if (!instance || !instance.componentName) continue;
+    const compDef = ctx.getComponentDefByName(instance.componentName);
+    if (compDef) {
+      const analysis = ctx.normalizeComponentDef(compDef);
+      if (analysis.type === 'cva') {
+        layout.appendChild(createCVAStoryInstance(analysis, instance, theme, ctx));
+        added++;
+        continue;
+      }
+      if (analysis.type === 'state') {
+        layout.appendChild(createStateStoryInstance(analysis, instance, theme, ctx));
+        added++;
+        continue;
+      }
+      if (analysis.type === 'simple') {
+        layout.appendChild(createSimpleStoryInstance(analysis, instance, theme, ctx));
+        added++;
+        continue;
+      }
+      if (analysis.type === 'compound') {
+        const comp = createCompoundComponent(layout, analysis, theme);
+        const extra = splitClassName(instance.props && instance.props.className);
+        if (comp && extra.length > 0) {
+          applyTailwindStylesToFrame(comp, extra, colorGroup, radiusGroup, theme);
+        }
+        added++;
+        continue;
+      }
+    }
+
+    const fallback = figma.createFrame();
+    fallback.name = instance.componentName || 'Component';
+    fallback.layoutMode = 'VERTICAL';
+    fallback.primaryAxisSizingMode = 'AUTO';
+    fallback.counterAxisSizingMode = 'AUTO';
+    fallback.fills = [];
+    const extra = splitClassName(instance.props && instance.props.className);
+    ctx.applyClipBehavior(fallback, extra);
+    if (extra.length > 0) {
+      applyTailwindStylesToFrame(fallback, extra, colorGroup, radiusGroup, theme);
+    }
+    const label = instance.children || instance.props?.children || instance.componentName;
+    if (label) {
+      fallback.appendChild(createTextNode(String(label), { fontSize: 12, opacity: 0.7 }));
+    }
+    layout.appendChild(fallback);
+    added++;
+  }
+  return added;
+}
+
+export function renderStandaloneStory(
+  story: any,
+  theme: string,
+  ctx: StoryBuilderContext,
+  viewportWidth?: number
+): any {
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const layoutClasses = normalizeLayoutClasses(story.layoutClasses);
+  const skipLayoutFullWidth = shouldSkipFullWidthForClasses(layoutClasses);
+
+  const layout = figma.createFrame();
+  layout.name = 'Story Layout';
+  layout.primaryAxisSizingMode = 'AUTO';
+  layout.counterAxisSizingMode = 'AUTO';
+  layout.fills = [];
+  ctx.applyClipBehavior(layout, layoutClasses);
+
+  ctx.applyLayoutClasses(layout, layoutClasses, colorGroup, radiusGroup, theme);
+
+  const fixedWidth = extractFixedWidth(layoutClasses);
+  const maxWidthFromLayout = extractMaxWidth(layoutClasses);
+  const maxWidthFromTree = extractLeadingContainerMaxWidthFromTree(story.jsxTree);
+  const constrainedMaxWidth = (
+    maxWidthFromLayout != null && maxWidthFromTree != null
+      ? Math.min(maxWidthFromLayout, maxWidthFromTree)
+      : (maxWidthFromTree != null ? maxWidthFromTree : maxWidthFromLayout)
+  );
+  const fallbackWidth = !fixedWidth && story.jsxTree && treeHasFullWidth(story.jsxTree, null, {
+    getComponentDefByName: ctx.getComponentDefByName,
+    normalizeComponentDef: ctx.normalizeComponentDef,
+    hasWidthHintInClasses: ctx.hasWidthHintInClasses,
+    propsContainWidthHint: ctx.propsContainWidthHint,
+  })
+    ? (constrainedMaxWidth || 900)
+    : null;
+  let effectiveWidth = fixedWidth || fallbackWidth;
+  const treeGridCols = story.jsxTree ? extractGridColumnsFromTree(story.jsxTree) : null;
+  const treeGridMinWidth = story.jsxTree ? extractGridBreakpointWidthFromTree(story.jsxTree) : null;
+  const layoutGridCols = extractGridColumns(layoutClasses);
+  const layoutGridMinWidth = extractGridBreakpointWidth(layoutClasses);
+  const gridCols = layoutGridCols || treeGridCols;
+  if (!effectiveWidth && gridCols) {
+    effectiveWidth = defaultGridWidth(gridCols);
+  } else if (effectiveWidth && layoutGridCols) {
+    // Only let root-level grid-cols override effectiveWidth — not deeply nested grid-cols inside the story tree
+    const minGridWidth = defaultGridWidth(layoutGridCols);
+    if (effectiveWidth < minGridWidth) {
+      effectiveWidth = minGridWidth;
+    }
+  }
+  const gridMinWidth = Math.max(layoutGridMinWidth || 0, treeGridMinWidth || 0);
+  if (gridMinWidth > 0) {
+    if (!effectiveWidth || effectiveWidth < gridMinWidth) {
+      effectiveWidth = gridMinWidth;
+    }
+  }
+  // Universal default: give stories without a detected width a sensible canvas size
+  if (!effectiveWidth) {
+    effectiveWidth = 900;
+  }
+  if (viewportWidth != null && Number.isFinite(viewportWidth) && viewportWidth > 0) {
+    effectiveWidth = viewportWidth;
+  }
+  if (effectiveWidth) {
+    layout.resize(effectiveWidth, layout.height);
+    if (layout.layoutMode === 'HORIZONTAL') {
+      layout.primaryAxisSizingMode = 'FIXED';
+    } else {
+      layout.counterAxisSizingMode = 'FIXED';
+    }
+    if (!ctx.hasExplicitHeight(layoutClasses)) {
+      layout.resize(effectiveWidth, 1);
+      if (layout.layoutMode === 'HORIZONTAL') {
+        layout.counterAxisSizingMode = 'AUTO';
+      } else {
+        layout.primaryAxisSizingMode = 'AUTO';
+      }
+    }
+  }
+
+  const layoutPadding = (layout.paddingLeft || 0) + (layout.paddingRight || 0);
+  const treeContentWidth = effectiveWidth ? effectiveWidth - layoutPadding : undefined;
+  const treeContext: StoryRenderContext = {
+    maxWidth: treeContentWidth,
+    parentLayout: layout.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+  };
+
+  let added = 0;
+  const allowAbsolute = ctx.hasExplicitHeight(layoutClasses);
+  if (story.jsxTree) {
+    let rendered = false;
+    const rootNode = story.jsxTree as any;
+    if (layoutClasses.length > 0 && rootNode && rootNode.type === 'element' && rootNode.tagName === 'div') {
+      const rootClasses = splitClassName(rootNode.props && rootNode.props.className);
+      const sameClasses = rootClasses.length > 0 && rootClasses.join(' ') === layoutClasses.join(' ');
+      if (sameClasses) {
+        const rootStyle = tailwindClassesToStyle(rootClasses, 'default', colorGroup);
+        const rootTextToken = rootStyle.textToken || extractTextColorToken(rootClasses) || undefined;
+        const rootTextColor = resolveTextColorValue(rootStyle.text, rootTextToken, colorGroup, theme) || undefined;
+        let gridChildWidth: number | undefined;
+        const rootGridCols = extractGridColumns(rootClasses, treeContentWidth);
+        const gridColsForChildren = layoutGridCols || rootGridCols;
+        if (gridColsForChildren && treeContentWidth != null && treeContentWidth > 0) {
+          const gap = layout.itemSpacing || 0;
+          const available = treeContentWidth - gap * Math.max(0, gridColsForChildren - 1);
+          if (available > 0) {
+            gridChildWidth = Math.max(0, available / gridColsForChildren);
+          }
+        }
+        const rootContext: StoryRenderContext = {
+          textColor: rootTextColor,
+          textColorToken: rootTextToken,
+          parentLayout: layout.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+          maxWidth: gridChildWidth != null ? gridChildWidth : treeContentWidth,
+        };
+        for (let i = 0; i < (rootNode.children || []).length; i++) {
+          const child = rootNode.children[i];
+          const childNode = ctx.renderJsxTree(child, colorGroup, radiusGroup, theme, 0, rootContext);
+          if (!childNode) continue;
+          layout.appendChild(childNode);
+          ctx.applyAbsoluteIfAllowed(childNode, layout, allowAbsolute);
+          const fullWidthOptions = (skipLayoutFullWidth || treeContentWidth != null)
+            ? { skipFullWidth: skipLayoutFullWidth, widthOverride: treeContentWidth }
+            : undefined;
+          applyFullWidthIfPossible(childNode, layout, fullWidthOptions);
+          if ('layoutMode' in childNode) {
+            ctx.applyGridColumnsWithReflow(childNode as FrameNode, treeContentWidth);
+          }
+          rendered = true;
+        }
+      }
+    }
+    if (!rendered) {
+      const treeNode = ctx.renderJsxTree(story.jsxTree, colorGroup, radiusGroup, theme, 0, treeContext);
+      if (treeNode) {
+        layout.appendChild(treeNode);
+        ctx.applyAbsoluteIfAllowed(treeNode, layout, allowAbsolute);
+        const fullWidthOptions = (skipLayoutFullWidth || treeContentWidth != null)
+          ? { skipFullWidth: skipLayoutFullWidth, widthOverride: treeContentWidth }
+          : undefined;
+        applyFullWidthIfPossible(treeNode, layout, fullWidthOptions);
+        if ('layoutMode' in treeNode) {
+          ctx.applyGridColumnsWithReflow(treeNode as FrameNode, treeContentWidth);
+        }
+        added++;
+      }
+    } else {
+      added++;
+    }
+  }
+  if (layoutGridCols) {
+    ctx.applyGridColumnsWithReflow(layout, effectiveWidth || layout.width, layoutGridCols);
+  }
+
+  if (added === 0 && story.instances && story.instances.length > 0) {
+    added = renderStoryInstances(layout, story, theme, colorGroup, radiusGroup, ctx);
+  }
+
+  if (added === 0) {
+    layout.appendChild(createTextNode(story.name || 'Story', { fontSize: 12, opacity: 0.6 }));
+  }
+
+  return layout;
+}
+
+export function createUIComponents(parent: any, opts: any, ctx: StoryBuilderContext): any {
+  const options = {
+    primary: true,
+    secondary: true,
+    themeNames: getThemeNames(TOKENS),
+    ...(opts || {}),
+  };
+  debug('createUIComponents start', { opts: options });
+  const section = figma.createFrame();
+  const sectionTitle: string = options.sectionTitle || 'UI Components';
+  section.name = sectionTitle;
+  section.layoutMode = 'VERTICAL';
+  section.itemSpacing = 32;
+  section.primaryAxisSizingMode = 'AUTO';
+  section.counterAxisSizingMode = 'AUTO';
+  section.paddingLeft = section.paddingRight = 24;
+  section.paddingTop = section.paddingBottom = 24;
+  section.fills = [];
+  ctx.applyClipBehavior(section, []);
+  const offsetY = typeof options.yOffset === 'number' ? options.yOffset : 0;
+  const offsetX = typeof options.xOffset === 'number' ? options.xOffset : 0;
+  section.x = offsetX;
+  section.y = offsetY;
+  parent.appendChild(section);
+
+  section.appendChild(createTextNode(sectionTitle, { fontSize: 28, bold: true }));
+
+  function formatThemeLabel(theme: string): string {
+    if (!theme) return 'Theme';
+    return theme.charAt(0).toUpperCase() + theme.slice(1);
+  }
+
+  function addColumn(label: string, theme: string): any {
+    const colFrame = figma.createFrame();
+    colFrame.name = label + ' Column';
+    colFrame.layoutMode = 'VERTICAL';
+    colFrame.itemSpacing = 24;
+    colFrame.primaryAxisSizingMode = 'AUTO';
+    colFrame.counterAxisSizingMode = 'AUTO';
+    colFrame.fills = [];
+    ctx.applyClipBehavior(colFrame, []);
+
+    const header = createTextNode(label + ' Theme', { fontSize: 18, bold: true });
+    colFrame.appendChild(header);
+
+    const pack = getActivePack();
+    const packStories = pack && pack.stories ? pack.stories : [];
+    const storyTagFilter = options && options.storyTagFilter ? String(options.storyTagFilter) : '';
+    for (const story of packStories) {
+      if (storyTagFilter) {
+        const tags = story.tags || [];
+        if (tags.indexOf(storyTagFilter) === -1) continue;
+      }
+      const storyBlock = figma.createFrame();
+      storyBlock.name = story.name || 'Story';
+      storyBlock.layoutMode = 'VERTICAL';
+      storyBlock.itemSpacing = 12;
+      storyBlock.primaryAxisSizingMode = 'AUTO';
+      storyBlock.counterAxisSizingMode = 'AUTO';
+      storyBlock.fills = [];
+      ctx.applyClipBehavior(storyBlock, []);
+      storyBlock.appendChild(createTextNode(story.name || 'Story', { fontSize: 16, bold: true }));
+      storyBlock.appendChild(renderStandaloneStory(story, theme, ctx));
+      colFrame.appendChild(storyBlock);
+    }
+
+    const componentList = figma.createFrame();
+    componentList.name = 'Component Blocks';
+    componentList.layoutMode = 'VERTICAL';
+    componentList.primaryAxisSizingMode = 'AUTO';
+    componentList.counterAxisSizingMode = 'AUTO';
+    componentList.itemSpacing = colFrame.itemSpacing * 6;
+    componentList.fills = [];
+    ctx.applyClipBehavior(componentList, []);
+
+    const defsRaw = (COMPONENT_DEFS && COMPONENT_DEFS.components) ? COMPONENT_DEFS.components : [];
+    const onlyComponents: string[] | undefined = options.onlyComponents;
+    const excludeComponents: string[] | undefined = options.excludeComponents;
+    const defs = defsRaw
+      .map(ctx.normalizeComponentDef)
+      .filter((d: any) => {
+        if (!d || !d.stories || d.stories.length === 0) return false;
+        if (onlyComponents && onlyComponents.length > 0) return onlyComponents.includes(d.name);
+        if (excludeComponents && excludeComponents.length > 0) return !excludeComponents.includes(d.name);
+        return true;
+      })
+      .sort((a: any, b: any) => a.name.localeCompare(b.name));
+
+    for (const def of defs) {
+      const block = figma.createFrame();
+      block.name = def.name;
+      block.layoutMode = 'VERTICAL';
+      block.itemSpacing = 12;
+      block.primaryAxisSizingMode = 'AUTO';
+      block.counterAxisSizingMode = 'AUTO';
+      block.fills = [];
+      ctx.applyClipBehavior(block, []);
+
+      block.appendChild(createTextNode(def.name, { fontSize: 16, bold: true }));
+
+      const storyList = def.stories || [];
+      for (let storyIndex = 0; storyIndex < storyList.length; storyIndex++) {
+        const story = storyList[storyIndex];
+        const storyWrap = figma.createFrame();
+        storyWrap.name = story.name;
+        storyWrap.layoutMode = 'VERTICAL';
+        storyWrap.itemSpacing = 8;
+        storyWrap.primaryAxisSizingMode = 'AUTO';
+        storyWrap.counterAxisSizingMode = 'AUTO';
+        storyWrap.counterAxisAlignItems = 'MIN';
+        storyWrap.fills = [];
+        ctx.applyClipBehavior(storyWrap, []);
+
+        storyWrap.appendChild(createTextNode(story.name, { fontSize: 12, opacity: 0.6, textAlignHorizontal: 'LEFT' }));
+
+        const layout = figma.createFrame();
+        layout.name = 'Story Layout';
+        layout.primaryAxisSizingMode = 'AUTO';
+        layout.counterAxisSizingMode = 'AUTO';
+        layout.fills = [];
+
+        const themeContext = getThemeContext(theme);
+        const colorGroup = themeContext.colorGroup;
+        const radiusGroup = themeContext.radiusGroup;
+        const layoutClasses = normalizeLayoutClasses(story.layoutClasses);
+        const skipLayoutFullWidth = shouldSkipFullWidthForClasses(layoutClasses);
+        ctx.applyClipBehavior(layout, layoutClasses);
+        ctx.applyLayoutClasses(layout, layoutClasses, colorGroup, radiusGroup, theme);
+
+        const fixedWidth = extractFixedWidth(layoutClasses);
+        const maxWidthFromLayout = extractMaxWidth(layoutClasses);
+        const maxWidthFromTree = extractLeadingContainerMaxWidthFromTree(story.jsxTree);
+        const constrainedMaxWidth = (
+          maxWidthFromLayout != null && maxWidthFromTree != null
+            ? Math.min(maxWidthFromLayout, maxWidthFromTree)
+            : (maxWidthFromTree != null ? maxWidthFromTree : maxWidthFromLayout)
+        );
+        const fallbackWidth = !fixedWidth && story.jsxTree && treeHasFullWidth(story.jsxTree, null, {
+          getComponentDefByName: ctx.getComponentDefByName,
+          normalizeComponentDef: ctx.normalizeComponentDef,
+          hasWidthHintInClasses: ctx.hasWidthHintInClasses,
+          propsContainWidthHint: ctx.propsContainWidthHint,
+        })
+          ? (constrainedMaxWidth || 900)
+          : null;
+        let effectiveWidth = fixedWidth || fallbackWidth;
+        const treeGridCols = story.jsxTree ? extractGridColumnsFromTree(story.jsxTree) : null;
+        const treeGridMinWidth = story.jsxTree ? extractGridBreakpointWidthFromTree(story.jsxTree) : null;
+        const layoutGridCols = extractGridColumns(layoutClasses);
+        const layoutGridMinWidth = extractGridBreakpointWidth(layoutClasses);
+        const gridCols = layoutGridCols || treeGridCols;
+        if (!effectiveWidth && gridCols) {
+          effectiveWidth = defaultGridWidth(gridCols);
+        } else if (effectiveWidth && layoutGridCols) {
+          // Only let root-level grid-cols override effectiveWidth — not deeply nested grid-cols inside the story tree
+          const minGridWidth = defaultGridWidth(layoutGridCols);
+          if (effectiveWidth < minGridWidth) {
+            effectiveWidth = minGridWidth;
+          }
+        }
+        const gridMinWidth = Math.max(layoutGridMinWidth || 0, treeGridMinWidth || 0);
+        if (gridMinWidth > 0) {
+          if (!effectiveWidth || effectiveWidth < gridMinWidth) {
+            effectiveWidth = gridMinWidth;
+          }
+        }
+        // Universal default: give stories without a detected width a sensible canvas size
+        if (!effectiveWidth) {
+          effectiveWidth = 900;
+        }
+        if (effectiveWidth) {
+          layout.resize(effectiveWidth, layout.height);
+          if (layout.layoutMode === 'HORIZONTAL') {
+            layout.primaryAxisSizingMode = 'FIXED';
+          } else {
+            layout.counterAxisSizingMode = 'FIXED';
+          }
+          if (!ctx.hasExplicitHeight(layoutClasses)) {
+            layout.resize(effectiveWidth, 1);
+            if (layout.layoutMode === 'HORIZONTAL') {
+              layout.counterAxisSizingMode = 'AUTO';
+            } else {
+              layout.primaryAxisSizingMode = 'AUTO';
+            }
+          }
+        } else {
+          layout.primaryAxisSizingMode = 'AUTO';
+          layout.counterAxisSizingMode = 'AUTO';
+        }
+
+        let added = 0;
+
+        // For compound/simple components with jsxTree, render the full tree
+        if ((def.type === 'compound' || def.type === 'simple') && story.jsxTree) {
+          let rendered = false;
+          const allowAbsolute = ctx.hasExplicitHeight(layoutClasses);
+          const rootNode = story.jsxTree as any;
+          if (layoutClasses.length > 0 && rootNode && rootNode.type === 'element' && rootNode.tagName === 'div') {
+            const rootClasses = splitClassName(rootNode.props && rootNode.props.className);
+            const sameClasses = rootClasses.length > 0 && rootClasses.join(' ') === layoutClasses.join(' ');
+            if (sameClasses) {
+              const rootStyle = tailwindClassesToStyle(rootClasses, 'default', colorGroup);
+              const rootTextToken = rootStyle.textToken || extractTextColorToken(rootClasses) || undefined;
+              const rootTextColor = resolveTextColorValue(rootStyle.text, rootTextToken, colorGroup, theme) || undefined;
+              // Calculate content width accounting for padding
+              const layoutPadding = (layout.paddingLeft || 0) + (layout.paddingRight || 0);
+              const contentWidth = effectiveWidth ? effectiveWidth - layoutPadding : undefined;
+              let gridChildWidth: number | undefined;
+              const rootGridCols = extractGridColumns(rootClasses, contentWidth);
+              const gridColsForChildren = layoutGridCols || rootGridCols;
+              if (gridColsForChildren && contentWidth != null && contentWidth > 0) {
+                const gap = layout.itemSpacing || 0;
+                const available = contentWidth - gap * Math.max(0, gridColsForChildren - 1);
+                if (available > 0) {
+                  gridChildWidth = Math.max(0, available / gridColsForChildren);
+                }
+              }
+              const rootContext: StoryRenderContext = {
+                textColor: rootTextColor,
+                textColorToken: rootTextToken,
+                parentLayout: layout.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+                maxWidth: gridChildWidth != null ? gridChildWidth : contentWidth,
+              };
+              for (const child of rootNode.children || []) {
+                const childNode = ctx.renderJsxTree(child, colorGroup, radiusGroup, theme, 0, rootContext);
+                if (childNode) {
+                  layout.appendChild(childNode);
+                  ctx.applyAbsoluteIfAllowed(childNode, layout, allowAbsolute);
+                  const fullWidthOptions = (skipLayoutFullWidth || contentWidth != null)
+                    ? { skipFullWidth: skipLayoutFullWidth, widthOverride: contentWidth }
+                    : undefined;
+                  applyFullWidthIfPossible(childNode, layout, fullWidthOptions);
+                  if ('layoutMode' in childNode) {
+                    ctx.applyGridColumnsWithReflow(childNode as FrameNode, contentWidth);
+                  }
+                  rendered = true;
+                }
+              }
+              if (rendered && layoutGridCols) {
+                ctx.applyGridColumnsWithReflow(layout, effectiveWidth || layout.width, layoutGridCols);
+              }
+            }
+          }
+
+          if (!rendered) {
+            // Calculate content width for the tree context
+            const layoutPadding = (layout.paddingLeft || 0) + (layout.paddingRight || 0);
+            const treeContentWidth = effectiveWidth ? effectiveWidth - layoutPadding : undefined;
+            const treeContext: StoryRenderContext = {
+              maxWidth: treeContentWidth,
+              parentLayout: layout.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+            };
+            const treeNode = ctx.renderJsxTree(story.jsxTree, colorGroup, radiusGroup, theme, 0, treeContext);
+            if (treeNode) {
+              layout.appendChild(treeNode);
+              ctx.applyAbsoluteIfAllowed(treeNode, layout, allowAbsolute);
+              const fullWidthOptions = (skipLayoutFullWidth || treeContentWidth != null)
+                ? { skipFullWidth: skipLayoutFullWidth, widthOverride: treeContentWidth }
+                : undefined;
+              applyFullWidthIfPossible(treeNode, layout, fullWidthOptions);
+              if ('layoutMode' in treeNode) {
+                ctx.applyGridColumnsWithReflow(treeNode as FrameNode, treeContentWidth);
+              }
+
+              if (effectiveWidth && rootNode && rootNode.type === 'element') {
+                const rootClasses = splitClassName(rootNode.props && rootNode.props.className);
+                const wantsFullWidth = rootClasses.includes('w-full');
+                if (wantsFullWidth && 'resize' in treeNode) {
+                  try {
+                    (treeNode as any).resize(layout.width, (treeNode as any).height);
+                    const treeLayout = ('layoutMode' in treeNode) ? (treeNode as any).layoutMode : 'VERTICAL';
+                    if (treeLayout === 'HORIZONTAL' && 'primaryAxisSizingMode' in treeNode) {
+                      (treeNode as any).primaryAxisSizingMode = 'FIXED';
+                    } else if (treeLayout === 'VERTICAL' && 'counterAxisSizingMode' in treeNode) {
+                      (treeNode as any).counterAxisSizingMode = 'FIXED';
+                    }
+                  } catch (_err) {
+                    // ignore resize errors
+                  }
+                }
+              }
+              added++;
+            }
+          } else {
+            added++;
+          }
+        }
+        if (added > 0) {
+        }
+
+        // For CVA/state components OR when no jsxTree, use flat instance rendering
+        if (added === 0) {
+          for (const instance of story.instances || []) {
+            if (!instance || !instance.componentName) continue;
+            // Normalize names for comparison: lowercase and remove hyphens
+            // This handles cases like "Mobile-nav" (from filename) vs "MobileNav" (from JS identifier)
+            const normalizedInstanceName = instance.componentName.toLowerCase().replace(/-/g, '');
+            const normalizedDefName = def.name.toLowerCase().replace(/-/g, '');
+            if (normalizedInstanceName !== normalizedDefName) continue;
+
+            if (def.type === 'cva') {
+              layout.appendChild(createCVAStoryInstance(def, instance, theme, ctx));
+              added++;
+            } else if (def.type === 'state') {
+              layout.appendChild(createStateStoryInstance(def, instance, theme, ctx));
+              added++;
+            } else if (def.type === 'compound') {
+              const comp = createCompoundComponent(layout, def, theme);
+              const extra = splitClassName(instance.props && instance.props.className);
+              if (comp && extra.length > 0) {
+                applyTailwindStylesToFrame(comp, extra, colorGroup, radiusGroup, theme);
+              }
+              added++;
+            } else if (def.type === 'simple') {
+              layout.appendChild(createSimpleStoryInstance(def, instance, theme, ctx));
+              added++;
+            }
+          }
+        }
+
+        // Fallback if nothing was rendered
+        if (added === 0) {
+          if (def.type === 'compound') {
+            createCompoundComponent(layout, def, theme);
+          } else if (def.type === 'simple') {
+            layout.appendChild(createSimpleStoryInstance(def, { props: {} }, theme, ctx));
+          } else if (def.type === 'cva') {
+            layout.appendChild(createCVAStoryInstance(def, { props: {} }, theme, ctx));
+          } else if (def.type === 'state') {
+            layout.appendChild(createStateStoryInstance(def, { props: {} }, theme, ctx));
+          }
+        }
+
+        storyWrap.appendChild(layout);
+        if (shouldRenderStatesForStory(def, story, storyIndex)) {
+          const statesBlock = createStatePreviewBlock(def, story, theme, ctx);
+          if (statesBlock) {
+            storyWrap.appendChild(statesBlock);
+          }
+        }
+        if (shouldRenderResponsiveForStory(def, story, storyIndex)) {
+          const responsiveBlock = createResponsivePreviewBlock(def, story, theme, ctx);
+          if (responsiveBlock) {
+            storyWrap.appendChild(responsiveBlock);
+          }
+        }
+        block.appendChild(storyWrap);
+      }
+
+      componentList.appendChild(block);
+    }
+
+    if (componentList.children.length > 0) {
+      colFrame.appendChild(componentList);
+    }
+
+    return colFrame;
+  }
+
+  const columns = figma.createFrame();
+  columns.layoutMode = 'HORIZONTAL';
+  columns.itemSpacing = 32;
+  columns.primaryAxisSizingMode = 'AUTO';
+  columns.counterAxisSizingMode = 'AUTO';
+  columns.fills = [];
+  ctx.applyClipBehavior(columns, []);
+  const requestedThemes = Array.isArray(options.themeNames)
+    ? options.themeNames.filter((theme: any, index: number, list: any[]) =>
+      typeof theme === 'string' &&
+      theme.trim().length > 0 &&
+      list.indexOf(theme) === index)
+    : [];
+  if (requestedThemes.length === 0) {
+    if (options.primary) requestedThemes.push('primary');
+    if (options.secondary) requestedThemes.push('secondary');
+  }
+  const multiMode = isMultiModeEnabled();
+  if (multiMode) {
+    const activeTheme = requestedThemes[0] || 'primary';
+    const singleCol = addColumn('Theme', activeTheme);
+    setThemeMode(singleCol, activeTheme);
+    columns.appendChild(singleCol);
+  } else {
+    for (const themeName of requestedThemes) {
+      const themeCol = addColumn(formatThemeLabel(themeName), themeName);
+      setThemeMode(themeCol, themeName);
+      columns.appendChild(themeCol);
+    }
+  }
+  section.appendChild(columns);
+  debug("UI section built", { columns: columns.children.length });
+  return section;
+}