inkhouse 0.1.0-beta.0

package/src/ui-builder.ts

@@ -0,0 +1,1996 @@
+import { parseColor, type RGB } from './colors';
+import { pxFromSizeToken } from './variables';
+import { applyTailwindStylesToFrame, applyBorderWidthUtilities, applyAbsoluteIfPossible, applyFullWidthIfPossible, markFullWidthNode, applyDeferredBottomPositioning, applyDeferredCenterYPositioning } from './tailwind';
+import { createCompoundComponent } from './component-gen';
+import { LayoutParser } from './layout-parser';
+import { extractTextColorToken, resolveTextColorFallback, resolveTextColorValue } from './color-resolver';
+import { TAG_TYPOGRAPHY, createTextNode, getLineHeightFromClasses, getNodeTextStyle, getTextAlignFromClasses } from './text-builder';
+import { defaultGridWidth } from './story-layout';
+import { getCompoundClasses, mergeClasses } from './class-utils';
+import { getClassesForBreakpoint } from './responsive-analyzer';
+import {
+  type StoryBuilderContext,
+  createCVAStoryInstance,
+  createStateStoryInstance,
+  createUIComponents as createUIComponentsFromStory,
+} from './story-builder';
+import { applyClipBehavior, shouldClipContent, applyGridColumnsWithReflow, maybeWrapMxAuto, resolveGridWidthOverride } from './layout-utils';
+import { getComponentDefByName, getIconRegistryEntry, getReactIconKey } from './component-lookup';
+import {
+  type RenderContext,
+  hasWidthHintInClasses,
+  propsContainWidthHint,
+  hasExplicitHeight,
+} from './render-context';
+import { createInlineTextNode, isInlineTextNode } from './inline-text';
+import { maybeExpandTextLineComponent } from './text-line';
+import {
+  extractGridColumns,
+  getBaseClass,
+  getNodeLayoutComputed,
+  shouldSkipFullWidthForClasses,
+  shouldStretchToParentWidth,
+  solveLayoutWidths,
+} from './width-solver';
+import { parseUtilityClass } from './utility-resolver';
+import { getImageHash, getSvgString } from './image-cache';
+import { buildDecorativeClipPathNode, parseClipPathFromStyle } from './clip-path-decorative';
+import {
+  type JsxNode,
+  type JsxElement,
+  type JsxText,
+  type NodeIR,
+  type NodeIRElement,
+  type NodeIRHelpers,
+  resolveNodeIR,
+  applyNodeTransforms,
+  isElementLikeNode,
+} from './node-ir';
+// Icon handling extracted to separate module
+import {
+  ICON_PATHS,
+  createIcon,
+  createIconFromSvg,
+  nodeIrToSvg,
+  resizeSvgNodeTo,
+  wrapIconNode,
+  resolveIconSizeFromClasses,
+  getVectorPaintUsage,
+} from './icon-builder';
+
+declare const figma: any;
+
+const RESPONSIVE_BREAKPOINT_ORDER = ['sm', 'md', 'lg', 'xl', '2xl'] as const;
+const RESPONSIVE_BREAKPOINT_MIN_WIDTH: Record<typeof RESPONSIVE_BREAKPOINT_ORDER[number], number> = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  '2xl': 1536,
+};
+
+function resolveBreakpointIndexForWidth(width?: number): number {
+  if (!Number.isFinite(width) || (width as number) <= 0) return -1;
+  let idx = -1;
+  for (let i = 0; i < RESPONSIVE_BREAKPOINT_ORDER.length; i++) {
+    const bp = RESPONSIVE_BREAKPOINT_ORDER[i];
+    if ((width as number) >= RESPONSIVE_BREAKPOINT_MIN_WIDTH[bp]) {
+      idx = i;
+    }
+  }
+  return idx;
+}
+
+function isAccordionRootTag(tagName: string): boolean {
+  return tagName === 'Accordion' || tagName === 'AccordionPrimitive.Root';
+}
+
+function isAccordionItemTag(tagName: string): boolean {
+  return tagName === 'AccordionItem' || tagName === 'AccordionPrimitive.Item';
+}
+
+function isAccordionContentTag(tagName: string): boolean {
+  return tagName === 'AccordionContent' || tagName === 'AccordionPrimitive.Content';
+}
+
+function isAccordionHeaderTag(tagName: string): boolean {
+  return tagName === 'AccordionHeader' || tagName === 'AccordionPrimitive.Header';
+}
+
+function isAccordionChevronTag(tagName: string): boolean {
+  return tagName === 'ChevronDownIcon' || tagName === 'ChevronDown';
+}
+
+function normalizeAccordionDefaultValue(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed || trimmed === 'defaultValue' || trimmed === 'undefined' || trimmed === 'null') {
+    return null;
+  }
+  return trimmed;
+}
+
+function resolveAccordionItemValue(value: unknown, itemIndex?: number): string | null {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (trimmed) {
+      if (trimmed.includes('${i}')) {
+        return Number.isFinite(itemIndex) ? `item-${itemIndex}` : null;
+      }
+      return trimmed;
+    }
+  }
+  return Number.isFinite(itemIndex) ? `item-${itemIndex}` : null;
+}
+
+function createPerChildRenderContext(
+  baseContext: RenderContext,
+  parentNode: NodeIR,
+  child: NodeIR,
+  accordionItemOrdinal: { value: number }
+): RenderContext {
+  const childContext: RenderContext = { ...baseContext };
+  if (
+    (parentNode.kind === 'element' || parentNode.kind === 'component') &&
+    isAccordionRootTag(parentNode.tagName) &&
+    (child.kind === 'element' || child.kind === 'component') &&
+    isAccordionItemTag(child.tagName)
+  ) {
+    childContext.accordionItemIndex = accordionItemOrdinal.value++;
+  }
+  return childContext;
+}
+
+function getRenderableChildren(node: NodeIR, classes: string[]): NodeIR[] {
+  if (node.kind !== 'element' && node.kind !== 'component') return [];
+  const children = node.children.slice();
+  if (node.kind !== 'element' || node.tagLower !== 'table') return children;
+  if (!classes.includes('caption-bottom')) return children;
+
+  const captions: NodeIR[] = [];
+  const others: NodeIR[] = [];
+  for (const child of children) {
+    if ((child.kind === 'element' || child.kind === 'component') && child.tagLower === 'caption') captions.push(child);
+    else others.push(child);
+  }
+  return captions.length > 0 ? [...others, ...captions] : children;
+}
+
+function hasTableCellSizeOverride(classes: string[]): boolean {
+  for (const cls of classes) {
+    const base = getBaseClass(cls);
+    if (!base) continue;
+    if (base === 'flex-1' || base === 'grow' || base === 'grow-0') return true;
+    if (base.startsWith('w-') || base.startsWith('min-w-') || base.startsWith('max-w-')) return true;
+  }
+  return false;
+}
+
+function getNumericColSpan(value: unknown): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return Math.max(1, Math.floor(value));
+  if (typeof value === 'string') {
+    const parsed = parseInt(value, 10);
+    if (Number.isFinite(parsed)) return Math.max(1, parsed);
+  }
+  return 1;
+}
+
+function isSemanticTableContainer(node: NodeIR): boolean {
+  if (node.kind !== 'element' && node.kind !== 'component') return false;
+  return node.tagLower === 'table' || node.tagLower === 'thead' || node.tagLower === 'tbody' || node.tagLower === 'tfoot';
+}
+
+function clearTopBorder(node: SceneNode): void {
+  try {
+    (node as any).strokeTopWeight = 0;
+  } catch (_err) {
+    // ignore if unsupported
+  }
+}
+
+function clearBottomBorder(node: SceneNode): void {
+  try {
+    (node as any).strokeBottomWeight = 0;
+  } catch (_err) {
+    // ignore if unsupported
+  }
+}
+
+function constrainSingleHorizontalTextChild(frame: any): void {
+  if (
+    frame.layoutMode !== 'HORIZONTAL'
+    || !Array.isArray(frame.children)
+    || frame.children.length < 2
+  ) {
+    return;
+  }
+
+  // Keep naturally centered CTA/action rows intact.
+  // Constraining text width in CENTER rows makes one text child consume the
+  // remaining width, which shifts sibling controls off-center.
+  if (frame.primaryAxisAlignItems === 'CENTER') {
+    return;
+  }
+
+  // Width constraints only make sense once the row width is fixed.
+  if (frame.primaryAxisSizingMode !== 'FIXED') {
+    return;
+  }
+
+  const textChildren = frame.children.filter((child: any) => child?.type === 'TEXT');
+  if (textChildren.length !== 1) return;
+
+  const nonTextWidth = frame.children
+    .filter((child: any) => child?.type !== 'TEXT')
+    .reduce((sum: number, child: any) => sum + (child?.width || 0), 0);
+
+  const availableWidth = Math.max(
+    0,
+    frame.width
+      - (frame.paddingLeft || 0)
+      - (frame.paddingRight || 0)
+      - (frame.itemSpacing || 0) * Math.max(0, frame.children.length - 1)
+      - nonTextWidth,
+  );
+
+  if (availableWidth <= 0) return;
+
+  const textChild = textChildren[0];
+  try {
+    textChild.textAutoResize = 'HEIGHT';
+    textChild.resize(availableWidth, textChild.height);
+  } catch (_err) {
+    // ignore resize errors
+  }
+}
+
+function stabilizeHorizontalStretchChild(child: any, parent: any): void {
+  if (
+    !child
+    || child.type !== 'FRAME'
+    || child.layoutMode !== 'HORIZONTAL'
+    || child.layoutAlign !== 'STRETCH'
+    || child.primaryAxisSizingMode === 'FIXED'
+    || !parent
+    || parent.layoutMode !== 'VERTICAL'
+  ) {
+    return;
+  }
+
+  const parentContentWidth = Math.max(
+    0,
+    (parent.width || 0) - (parent.paddingLeft || 0) - (parent.paddingRight || 0),
+  );
+  if (parentContentWidth <= 0) return;
+
+  try {
+    child.resize(parentContentWidth, Math.max(1, child.height || 1));
+    child.primaryAxisSizingMode = 'FIXED';
+  } catch (_err) {
+    // ignore resize errors
+  }
+}
+
+const TEXT_SIZE_PX: 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,
+};
+
+const FONT_WEIGHT_RANK: Record<string, number> = {
+  'font-thin': 1,
+  'font-extralight': 2,
+  'font-light': 3,
+  'font-normal': 4,
+  'font-medium': 5,
+  'font-semibold': 6,
+  'font-bold': 7,
+  'font-extrabold': 8,
+  'font-black': 9,
+};
+
+const FONT_WEIGHT_TO_STYLE: Record<string, string> = {
+  'font-thin': 'Thin',
+  'font-extralight': 'ExtraLight',
+  'font-light': 'Light',
+  'font-normal': 'Regular',
+  'font-medium': 'Medium',
+  'font-semibold': 'SemiBold',
+  'font-bold': 'Bold',
+  'font-extrabold': 'ExtraBold',
+  'font-black': 'Black',
+};
+
+function getFontStyleFromClasses(classes: string[], fallback?: string): string | undefined {
+  let found: string | undefined;
+  for (const cls of classes) {
+    const style = FONT_WEIGHT_TO_STYLE[cls];
+    if (style) { found = style; }
+  }
+  if (found == null && fallback == null) return undefined;
+  return found != null ? found : fallback;
+}
+
+function getResolvedTextSizeFromClasses(classes: string[], fallback?: number): number | undefined {
+  let resolved = fallback;
+  for (const cls of classes) {
+    if (TEXT_SIZE_PX[cls] != null) resolved = TEXT_SIZE_PX[cls];
+  }
+  return resolved;
+}
+
+function getResolvedBoldFromClasses(classes: string[], fallback?: boolean): boolean | undefined {
+  let rank = fallback ? 7 : 4;
+  let seenWeight = false;
+  for (const cls of classes) {
+    if (FONT_WEIGHT_RANK[cls] != null) {
+      rank = FONT_WEIGHT_RANK[cls];
+      seenWeight = true;
+    }
+  }
+  if (!seenWeight && fallback == null) return undefined;
+  return rank >= FONT_WEIGHT_RANK['font-semibold'];
+}
+
+function getResponsiveConflictGroup(utility: string): string | null {
+  if (
+    utility === 'flex-row' ||
+    utility === 'flex-row-reverse' ||
+    utility === 'flex-col' ||
+    utility === 'flex-col-reverse'
+  ) {
+    return 'layout-direction';
+  }
+
+  if (
+    utility === 'justify-start' ||
+    utility === 'justify-center' ||
+    utility === 'justify-end' ||
+    utility === 'justify-between' ||
+    utility === 'justify-around' ||
+    utility === 'justify-evenly'
+  ) {
+    return 'main-align';
+  }
+
+  if (
+    utility === 'items-start' ||
+    utility === 'items-center' ||
+    utility === 'items-end' ||
+    utility === 'items-stretch' ||
+    utility === 'items-baseline'
+  ) {
+    return 'cross-align';
+  }
+
+  if (
+    utility === 'text-left' ||
+    utility === 'text-center' ||
+    utility === 'text-right' ||
+    utility === 'text-justify'
+  ) {
+    return 'text-align';
+  }
+
+  return null;
+}
+
+function resolveClassesForBreakpoint(classes: string[], breakpointIndex: number): string[] {
+  if (!classes || classes.length === 0) return classes || [];
+
+  const out: string[] = [];
+  const conflictIndex = new Map<string, number>();
+  for (let i = 0; i < classes.length; i++) {
+    const atom = parseUtilityClass(classes[i]);
+    if (!atom.utility) continue;
+
+    let requiredBreakpoint = -1;
+    const remainingVariants: string[] = [];
+    for (let j = 0; j < atom.variants.length; j++) {
+      const variant = atom.variants[j];
+      const responsiveIdx = RESPONSIVE_BREAKPOINT_ORDER.indexOf(variant as any);
+      if (responsiveIdx !== -1) {
+        if (responsiveIdx > requiredBreakpoint) requiredBreakpoint = responsiveIdx;
+      } else {
+        remainingVariants.push(variant);
+      }
+    }
+
+    if (requiredBreakpoint !== -1 && breakpointIndex < requiredBreakpoint) {
+      continue;
+    }
+
+    const rebuilt = remainingVariants.length > 0
+      ? remainingVariants.join(':') + ':' + atom.utility
+      : atom.utility;
+    const finalClass = atom.important ? '!' + rebuilt : rebuilt;
+    const conflictGroup = getResponsiveConflictGroup(atom.utility);
+    if (conflictGroup) {
+      const variantScope = remainingVariants.join(':');
+      const conflictKey = `${variantScope}|${conflictGroup}`;
+      const existingIndex = conflictIndex.get(conflictKey);
+      if (existingIndex !== undefined) {
+        out[existingIndex] = finalClass;
+      } else {
+        conflictIndex.set(conflictKey, out.length);
+        out.push(finalClass);
+      }
+      continue;
+    }
+
+    out.push(finalClass);
+  }
+  return out;
+}
+
+function resolveNodeResponsiveClasses(node: NodeIR, width?: number): NodeIR {
+  const breakpointIndex = resolveBreakpointIndexForWidth(width);
+  if (breakpointIndex === -1) return node;
+
+  if (node.kind === 'text' || node.kind === 'divider') return node;
+
+  if (node.kind === 'fragment') {
+    return Object.assign({}, node, {
+      children: node.children.map(child => resolveNodeResponsiveClasses(child, width)),
+    });
+  }
+
+  if (node.kind === 'ring') {
+    return Object.assign({}, node, {
+      classes: resolveClassesForBreakpoint(node.classes, breakpointIndex),
+      child: resolveNodeResponsiveClasses(node.child, width),
+    });
+  }
+
+  return Object.assign({}, node, {
+    classes: resolveClassesForBreakpoint(node.classes, breakpointIndex),
+    children: node.children.map(child => resolveNodeResponsiveClasses(child, width)),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Constants (Icon code moved to icon-builder.ts)
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Functions
+// ---------------------------------------------------------------------------
+
+function resolveContextTextColorValue(
+  context: RenderContext,
+  colorGroup: Record<string, string>,
+  theme: string
+): string | RGB | null {
+  return resolveTextColorValue(context.textColor, context.textColorToken, colorGroup, theme);
+}
+
+// SVG/icon functions moved to icon-builder.ts
+
+function resolveIconForegroundColor(
+  context: RenderContext,
+  colorGroup: Record<string, string>,
+  theme: string
+): RGB {
+  const resolvedTextColor = resolveContextTextColorValue(context, colorGroup, theme);
+  if (resolvedTextColor) return parseColor(resolvedTextColor);
+  if (colorGroup.foreground) return parseColor(colorGroup.foreground);
+  return { r: 0.1, g: 0.1, b: 0.1 };
+}
+
+function wrapSvgIcon(
+  icon: SceneNode,
+  classes: string[],
+  props: Record<string, string>,
+  name: string
+): FrameNode {
+  const size = resolveIconSizeFromClasses(classes, props);
+  resizeSvgNodeTo(icon, size.width, size.height);
+  const usage = getVectorPaintUsage(icon);
+  const pad = usage.hasStrokes ? 1 : 0;
+  return wrapIconNode(icon, size.width, size.height, pad, name);
+}
+
+function wrapMappedIcon(
+  icon: SceneNode,
+  iconKey: string,
+  tagName: string,
+  classes: string[],
+  props: Record<string, string>,
+  rotateAccordionChevron: boolean
+): FrameNode {
+  const size = resolveIconSizeFromClasses(classes, props);
+  resizeSvgNodeTo(icon, size.width, size.height);
+  const pad = ICON_PATHS[iconKey].stroke
+    ? Math.max(1, Math.ceil((ICON_PATHS[iconKey].strokeWidth || 1.5) / 2))
+    : 0;
+  const wrapped = wrapIconNode(icon, size.width, size.height, pad, `icon/${iconKey}`);
+  if (rotateAccordionChevron && isAccordionChevronTag(tagName)) {
+    wrapped.rotation = 180;
+  }
+  return wrapped;
+}
+
+function renderRegistryIcon(
+  tagName: string,
+  classes: string[],
+  props: Record<string, string>,
+  fgColor: RGB
+): FrameNode | null {
+  const iconEntry = getIconRegistryEntry(tagName);
+  if (!iconEntry || !iconEntry.svg) return null;
+  const icon = createIconFromSvg(iconEntry.svg, fgColor);
+  if (!icon) return null;
+  return wrapSvgIcon(icon, classes, props, `icon/${tagName}`);
+}
+
+function renderMappedIcon(
+  tagName: string,
+  classes: string[],
+  props: Record<string, string>,
+  fgColor: RGB,
+  rotateAccordionChevron: boolean
+): FrameNode | null {
+  const iconKey = getReactIconKey(tagName);
+  if (!iconKey || !ICON_PATHS[iconKey]) return null;
+  const icon = createIcon(iconKey, fgColor);
+  if (!icon) return null;
+  return wrapMappedIcon(icon, iconKey, tagName, classes, props, rotateAccordionChevron);
+}
+
+function normalizeComponentDef(raw: any): any {
+  if (!raw || !raw.analysis) return raw;
+
+  // Scanner output stores component metadata (stories, layout, responsive, colorScheme)
+  // alongside the nested `analysis`. Many render paths want the analysis shape but still
+  // need the attached metadata, so preserve it when normalizing.
+  return {
+    ...raw.analysis,
+    stories: Array.isArray(raw.analysis.stories)
+      ? raw.analysis.stories
+      : (Array.isArray(raw.stories) ? raw.stories : []),
+    hasStory: typeof raw.analysis.hasStory === 'boolean'
+      ? raw.analysis.hasStory
+      : !!raw.hasStory,
+    layout: raw.layout,
+    responsive: raw.responsive,
+    colorScheme: raw.colorScheme,
+  };
+}
+
+function nodeHasClipPathDescendant(node: NodeIR): boolean {
+  if (node.kind === 'text' || node.kind === 'divider') return false;
+  if (node.kind === 'ring') return nodeHasClipPathDescendant(node.child);
+  if (node.kind === 'fragment') {
+    for (let i = 0; i < node.children.length; i++) {
+      if (nodeHasClipPathDescendant(node.children[i])) return true;
+    }
+    return false;
+  }
+  if (node.kind === 'element') {
+    if (parseClipPathFromStyle(node.props.style)) return true;
+  }
+  for (let i = 0; i < node.children.length; i++) {
+    if (nodeHasClipPathDescendant(node.children[i])) return true;
+  }
+  return false;
+}
+
+/**
+ * Render a component using its internal jsxTree structure.
+ * This handles components with decorative elements (gradient backgrounds, blurred shapes, etc.)
+ * by rendering the component's actual DOM structure instead of a simple wrapper.
+ */
+function renderComponentWithJsxTree(
+  jsxTree: JsxNode,
+  actualChildren: NodeIR[],
+  colorGroup: Record<string, string>,
+  radiusGroup: Record<string, string> | null,
+  theme: string,
+  depth: number,
+  context: RenderContext
+): SceneNode | null {
+  // Convert the component's jsxTree to NodeIR and render it
+  // When we encounter {children} text, substitute with actualChildren
+  const substitutedTree = substituteChildrenInJsxTree(jsxTree, actualChildren);
+  if (!substitutedTree) return null;
+
+  // Resolve and render the substituted tree
+  const resolved = resolveNodeIR(substitutedTree);
+  if (!resolved) return null;
+
+  const nodeHelpers: NodeIRHelpers = {
+    getComponentDefByName: getComponentDefByName,
+    normalizeComponentDef: normalizeComponentDef,
+    getCompoundClasses: getCompoundClasses,
+    mergeClasses: mergeClasses,
+  };
+  const transformed = applyNodeTransforms(resolved, colorGroup, nodeHelpers);
+  const responsiveResolved = resolveNodeResponsiveClasses(transformed, context.maxWidth);
+  const solved = solveLayoutWidths(responsiveResolved, context.maxWidth);
+  return buildFigmaNode(solved, colorGroup, radiusGroup, theme, depth, context);
+}
+
+/**
+ * Recursively substitute {children} text nodes with actual children from the story.
+ */
+function substituteChildrenInJsxTree(
+  jsxNode: JsxNode,
+  actualChildren: NodeIR[]
+): JsxNode | null {
+  if (jsxNode.type === 'text') {
+    const textNode = jsxNode as JsxText;
+    // Check if this is a {children} placeholder
+    if (textNode.content.trim() === '{children}') {
+      // Return a fragment-like structure - we'll handle this in element processing
+      return null; // Will be handled specially in element processing
+    }
+    return jsxNode;
+  }
+
+  const element = jsxNode as JsxElement;
+  const newChildren: JsxNode[] = [];
+
+  for (const child of element.children || []) {
+    if (child.type === 'text') {
+      const textChild = child as JsxText;
+      if (textChild.content.trim() === '{children}') {
+        // Convert NodeIR children back to JsxNode format for consistency
+        for (const actualChild of actualChildren) {
+          const jsxChild = nodeIRToJsxNode(actualChild);
+          if (jsxChild) {
+            newChildren.push(jsxChild);
+          }
+        }
+        continue;
+      }
+    }
+    const substituted = substituteChildrenInJsxTree(child, actualChildren);
+    if (substituted) {
+      newChildren.push(substituted);
+    }
+  }
+
+  return {
+    type: 'element',
+    tagName: element.tagName,
+    isComponent: element.isComponent,
+    props: element.props,
+    children: newChildren,
+  } as JsxElement;
+}
+
+/**
+ * Check whether a component jsxTree explicitly exposes a {children} slot.
+ * If it does not, rendering the tree for an instance with children would drop
+ * those children, so callers should use the wrapper fallback instead.
+ */
+function jsxTreeHasChildrenSlot(jsxNode: JsxNode | null | undefined): boolean {
+  if (!jsxNode) return false;
+  if (jsxNode.type === 'text') {
+    const content = (jsxNode as JsxText).content.trim();
+    return /^\{\s*children\s*\}$/.test(content);
+  }
+  const element = jsxNode as JsxElement;
+  for (const child of element.children || []) {
+    if (jsxTreeHasChildrenSlot(child)) return true;
+  }
+  return false;
+}
+
+/**
+ * Convert a NodeIR node back to JsxNode format.
+ */
+function nodeIRToJsxNode(node: NodeIR): JsxNode | null {
+  if (node.kind === 'text') {
+    return { type: 'text', content: node.text } as JsxText;
+  }
+
+  if (node.kind === 'element' || node.kind === 'component') {
+    const children: JsxNode[] = [];
+    for (const child of node.children || []) {
+      const jsxChild = nodeIRToJsxNode(child);
+      if (jsxChild) {
+        children.push(jsxChild);
+      }
+    }
+    return {
+      type: 'element',
+      tagName: node.tagName,
+      isComponent: node.kind === 'component',
+      props: Object.assign({}, node.props, { className: node.classes.join(' ') }),
+      children,
+    } as JsxElement;
+  }
+
+  if (node.kind === 'fragment') {
+    // Wrap fragment children in a div
+    const children: JsxNode[] = [];
+    for (const child of node.children || []) {
+      const jsxChild = nodeIRToJsxNode(child);
+      if (jsxChild) {
+        children.push(jsxChild);
+      }
+    }
+    return {
+      type: 'element',
+      tagName: 'div',
+      isComponent: false,
+      props: {},
+      children,
+    } as JsxElement;
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// JSX Tree Rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a separator node for divide-y/divide-x
+ */
+function createDivideSeparator(
+  direction: 'HORIZONTAL' | 'VERTICAL',
+  color: RGB,
+  parentWidth: number
+): FrameNode {
+  const sep = figma.createFrame();
+  sep.name = 'divider';
+  applyClipBehavior(sep, []);
+
+  if (direction === 'HORIZONTAL') {
+    // Horizontal line (for divide-y in vertical list)
+    sep.resize(Math.max(parentWidth, 100), 1);
+    sep.layoutAlign = 'STRETCH';
+  } else {
+    // Vertical line (for divide-x in horizontal list)
+    sep.resize(1, 24); // Height will adjust
+    sep.layoutGrow = 0;
+    sep.layoutAlign = 'STRETCH';
+  }
+
+  sep.fills = [{ type: 'SOLID', color: { r: color.r, g: color.g, b: color.b }, opacity: 1 }];
+  return sep;
+}
+function resolveCornerRadiusFromClasses(
+  classes: string[],
+  radiusGroup: Record<string, string> | null
+): number | null {
+  if (classes.includes('rounded-full')) return 9999;
+  if (classes.includes('rounded-none')) return 0;
+
+  for (const cls of classes) {
+    const match = cls.match(/^rounded-\[(\d+(?:\.\d+)?)px\]$/);
+    if (match) return parseFloat(match[1]);
+  }
+
+  const tokenMap: Record<string, string> = {
+    'rounded-sm': 'sm',
+    'rounded': 'base',
+    'rounded-md': 'md',
+    'rounded-lg': 'lg',
+    'rounded-xl': 'xl',
+    'rounded-2xl': '2xl',
+    'rounded-3xl': '3xl',
+  };
+  const fallbackMap: Record<string, number> = {
+    sm: 2,
+    base: 4,
+    md: 6,
+    lg: 8,
+    xl: 12,
+    '2xl': 16,
+    '3xl': 24,
+  };
+
+  for (const cls of classes) {
+    const tokenKey = tokenMap[cls];
+    if (!tokenKey) continue;
+    if (radiusGroup && radiusGroup[tokenKey]) {
+      return pxFromSizeToken(radiusGroup[tokenKey]);
+    }
+    if (fallbackMap[tokenKey] != null) return fallbackMap[tokenKey];
+  }
+
+  return null;
+}
+
+/**
+ * Renders a JSX tree from the scanner into Figma frames
+ */
+function getStoryBuilderContext(): StoryBuilderContext {
+  return {
+    getComponentDefByName: getComponentDefByName,
+    normalizeComponentDef: normalizeComponentDef,
+    applyClipBehavior: applyClipBehavior,
+    applyLayoutClasses: applyLayoutClasses,
+    hasExplicitHeight: hasExplicitHeight,
+    renderJsxTree: renderJsxTree,
+    applyAbsoluteIfAllowed: applyAbsoluteIfAllowed,
+    applyGridColumnsWithReflow: applyGridColumnsWithReflow,
+    hasWidthHintInClasses: hasWidthHintInClasses,
+    propsContainWidthHint: propsContainWidthHint,
+  };
+}
+
+
+export function renderJsxTree(
+  node: JsxNode,
+  colorGroup: Record<string, string>,
+  radiusGroup: Record<string, string> | null,
+  theme: string,
+  depth: number = 0,
+  context: RenderContext = {}
+): SceneNode | null {
+  const resolved = resolveNodeIR(node);
+  if (!resolved) return null;
+  const nodeHelpers: NodeIRHelpers = {
+    getComponentDefByName: getComponentDefByName,
+    normalizeComponentDef: normalizeComponentDef,
+    getCompoundClasses: getCompoundClasses,
+    mergeClasses: mergeClasses,
+  };
+  const transformed = applyNodeTransforms(resolved, colorGroup, nodeHelpers);
+  const responsiveResolved = resolveNodeResponsiveClasses(transformed, context.maxWidth);
+  const solved = solveLayoutWidths(responsiveResolved, context.maxWidth);
+  return buildFigmaNode(solved, colorGroup, radiusGroup, theme, depth, context);
+}
+
+function buildFigmaNode(
+  node: NodeIR,
+  colorGroup: Record<string, string>,
+  radiusGroup: Record<string, string> | null,
+  theme: string,
+  depth: number,
+  context: RenderContext
+): SceneNode | null {
+  if (node.kind === 'text') {
+    const opts: any = { fontSize: context.textFontSize || 14, theme };
+    if (context.textFontStyle != null) {
+      opts.fontStyle = context.textFontStyle;
+    } else if (context.textBold != null) {
+      opts.bold = context.textBold;
+    }
+    if (context.textLineHeight != null) {
+      opts.lineHeight = context.textLineHeight;
+    }
+    if (context.textColor) {
+      opts.fill = context.textColor;
+    }
+    if (context.textAlign) {
+      opts.textAlignHorizontal = context.textAlign;
+    }
+    const textNode = createTextNode(node.text, opts);
+    if (context.textTruncate && context.maxWidth) {
+      try {
+        const maxLines = context.textMaxLines || 1;
+        const fontSize = context.textFontSize || 14;
+        const lineH = context.textLineHeight || Math.ceil(fontSize * 1.5);
+        (textNode as any).textTruncation = 'ENDING';
+        (textNode as any).maxLines = maxLines;
+        textNode.resize(context.maxWidth, Math.max(lineH, lineH * maxLines));
+      } catch (_err) {
+        // ignore — truncation not supported in all plugin contexts
+      }
+    } else if (context.maxWidth && context.parentLayout !== 'HORIZONTAL') {
+      try {
+        textNode.textAutoResize = 'HEIGHT';
+        textNode.resize(context.maxWidth, textNode.height);
+      } catch (_err) {
+        // ignore resize errors
+      }
+    }
+    return textNode;
+  }
+
+  if (node.kind === 'fragment') {
+    if (node.children.length === 0) return null;
+    const wrapper = figma.createFrame();
+    wrapper.name = 'Fragment';
+    wrapper.layoutMode = 'VERTICAL';
+    wrapper.primaryAxisSizingMode = 'AUTO';
+    wrapper.counterAxisSizingMode = 'AUTO';
+    wrapper.fills = [];
+    applyClipBehavior(wrapper, []);
+    for (const child of node.children) {
+      const childNode = buildFigmaNode(child, colorGroup, radiusGroup, theme, depth + 1, context);
+      if (childNode) {
+        wrapper.appendChild(childNode);
+        if (isElementLikeNode(child)) {
+          LayoutParser.applyChildProperties(childNode, child.classes, wrapper);
+        }
+        stabilizeHorizontalStretchChild(childNode, wrapper);
+        constrainSingleHorizontalTextChild(childNode);
+        applyAbsoluteIfPossible(childNode, wrapper);
+        applyFullWidthIfPossible(childNode, wrapper, context.maxWidth != null ? { widthOverride: context.maxWidth } : undefined);
+      }
+    }
+    applyDeferredBottomPositioning(wrapper);
+      applyDeferredCenterYPositioning(wrapper);
+    return wrapper;
+  }
+
+  if (node.kind === 'divider') {
+    const parentWidth = context.maxWidth || 200;
+    return createDivideSeparator(node.direction, node.color, parentWidth);
+  }
+
+  if (node.kind === 'ring') {
+    const ring = figma.createFrame();
+    ring.name = 'ring';
+    ring.layoutMode = 'HORIZONTAL';
+    ring.primaryAxisSizingMode = 'AUTO';
+    ring.counterAxisSizingMode = 'AUTO';
+    applyClipBehavior(ring, []);
+    // Render ring as a stroke (CSS box-shadow equivalent), not a fill.
+    // A fill-based ring bleeds through transparent child backgrounds; strokes match CSS behavior.
+    ring.fills = [];
+    ring.strokes = [{
+      type: 'SOLID',
+      color: { r: node.ringColor.r, g: node.ringColor.g, b: node.ringColor.b },
+      opacity: node.ringOpacity,
+    }];
+    (ring as any).strokeWeight = node.ringWidth;
+    (ring as any).strokeAlign = 'OUTSIDE';
+    // No padding needed — stroke draws on the frame border
+
+    let baseRadius: number | null = null;
+    if (isElementLikeNode(node.child)) {
+      baseRadius = resolveCornerRadiusFromClasses(node.child.classes, radiusGroup);
+    }
+    if (baseRadius == null && radiusGroup && radiusGroup.base) {
+      baseRadius = pxFromSizeToken(radiusGroup.base);
+    }
+    if (baseRadius == null) baseRadius = 0;
+    ring.cornerRadius = baseRadius + node.offsetWidth;
+
+    let innerParent: FrameNode = ring;
+    if (node.offsetWidth > 0 && node.offsetColor) {
+      const offsetFrame = figma.createFrame();
+      offsetFrame.name = 'ring-offset';
+      offsetFrame.layoutMode = 'HORIZONTAL';
+      offsetFrame.primaryAxisSizingMode = 'AUTO';
+      offsetFrame.counterAxisSizingMode = 'AUTO';
+      applyClipBehavior(offsetFrame, []);
+      offsetFrame.fills = [{
+        type: 'SOLID',
+        color: { r: node.offsetColor.r, g: node.offsetColor.g, b: node.offsetColor.b },
+        opacity: 1,
+      }];
+      offsetFrame.strokes = [];
+      offsetFrame.paddingLeft = offsetFrame.paddingRight = offsetFrame.paddingTop = offsetFrame.paddingBottom = node.offsetWidth;
+      offsetFrame.cornerRadius = baseRadius + node.offsetWidth;
+      ring.appendChild(offsetFrame);
+      innerParent = offsetFrame;
+    }
+
+    const childNode = buildFigmaNode(node.child, colorGroup, radiusGroup, theme, depth + 1, context);
+    if (childNode) {
+      innerParent.appendChild(childNode);
+      if (isElementLikeNode(node.child)) {
+        LayoutParser.applyChildProperties(childNode, node.child.classes, innerParent);
+      }
+      stabilizeHorizontalStretchChild(childNode, innerParent);
+      constrainSingleHorizontalTextChild(childNode);
+      applyAbsoluteIfPossible(childNode, innerParent);
+      applyFullWidthIfPossible(childNode, innerParent, context.maxWidth != null ? { widthOverride: context.maxWidth } : undefined);
+      return maybeWrapMxAuto(ring, node.classes, context);
+    }
+
+    return null;
+  }
+
+  const tagLower = node.tagLower;
+  const breakpointIndex = resolveBreakpointIndexForWidth(
+    context.maxWidth != null ? context.maxWidth : defaultGridWidth(3)
+  );
+  let classes = resolveClassesForBreakpoint(node.classes, breakpointIndex);
+  if (isAccordionHeaderTag(node.tagName) && !classes.includes('w-full')) {
+    classes = mergeClasses(classes, ['w-full']);
+  }
+  const layoutComputed = getNodeLayoutComputed(node);
+  const alignFromClasses = getTextAlignFromClasses(classes);
+  const textStyle = getNodeTextStyle(node, colorGroup);
+  const textToken = textStyle.textToken || extractTextColorToken(classes) || context.textColorToken || null;
+  const fallbackTextColor = resolveTextColorFallback(classes, colorGroup, theme);
+  const ownTextColor = resolveTextColorValue(
+    textStyle.text || fallbackTextColor,
+    textToken,
+    colorGroup,
+    theme
+  );
+  const ownTextFontSize = getResolvedTextSizeFromClasses(classes, context.textFontSize);
+  const ownTextBold = getResolvedBoldFromClasses(classes, context.textBold);
+  const ownTextFontStyle = getFontStyleFromClasses(classes, context.textFontStyle);
+  const ownTextLineHeight = ownTextFontSize != null
+    ? (getLineHeightFromClasses(classes, ownTextFontSize) ?? context.textLineHeight)
+    : context.textLineHeight;
+  const inheritedTextColor = resolveTextColorValue(
+    context.textColor,
+    context.textColorToken,
+    colorGroup,
+    theme
+  );
+  const resolvedTextColor = ownTextColor || inheritedTextColor;
+  let contextualMaxWidth = context.maxWidth;
+  if (layoutComputed.explicitWidth != null) {
+    contextualMaxWidth = layoutComputed.explicitWidth;
+  } else if (layoutComputed.maxWidth != null) {
+    contextualMaxWidth = context.maxWidth != null
+      ? Math.min(layoutComputed.maxWidth, context.maxWidth)
+      : layoutComputed.maxWidth;
+  }
+  // Detect text truncation from classes on this element; reset per-element (don't inherit)
+  let _truncate: boolean | undefined;
+  let _maxLines: number | undefined;
+  if (classes.includes('truncate')) {
+    _truncate = true; _maxLines = 1;
+  } else {
+    for (const cls of classes) {
+      const m = cls.match(/^line-clamp-(\d+)$/);
+      if (m) { _truncate = true; _maxLines = parseInt(m[1], 10); break; }
+    }
+  }
+  const nextContext: RenderContext = {
+    ...context,
+    textAlign: alignFromClasses || context.textAlign,
+    maxWidth: contextualMaxWidth,
+    textFontSize: ownTextFontSize,
+    textBold: ownTextBold,
+    textFontStyle: ownTextFontStyle,
+    textLineHeight: ownTextLineHeight,
+    textColor: resolvedTextColor,
+    textColorToken: textToken || context.textColorToken,
+    textTruncate: _truncate,
+    textMaxLines: _maxLines,
+  };
+
+  if (isAccordionRootTag(node.tagName)) {
+    nextContext.accordionOpenValue = normalizeAccordionDefaultValue(node.props?.defaultValue);
+    nextContext.accordionItemIndex = undefined;
+    nextContext.accordionItemValue = null;
+    nextContext.accordionItemIsOpen = false;
+  } else if (isAccordionItemTag(node.tagName)) {
+    const accordionItemValue = resolveAccordionItemValue(node.props?.value, context.accordionItemIndex);
+    nextContext.accordionItemValue = accordionItemValue;
+    nextContext.accordionItemIsOpen = !!accordionItemValue &&
+      !!nextContext.accordionOpenValue &&
+      accordionItemValue === nextContext.accordionOpenValue;
+  }
+
+  if (isAccordionContentTag(node.tagName) && !context.accordionItemIsOpen) {
+    return null;
+  }
+
+  // Check for hidden classes - skip rendering unless overridden by a display class
+  // In responsive contexts "hidden sm:flex" produces ["hidden","flex"]; the last display
+  // class wins (same semantics as CSS), so we must not skip when a display override follows.
+  if (classes.includes('hidden') || classes.includes('sr-only')) {
+    const DISPLAY_OVERRIDES = new Set(['flex','inline-flex','block','inline-block','inline','grid','inline-grid','table','table-cell','table-row','contents','flow-root','list-item']);
+    const hiddenIdx = Math.max(classes.lastIndexOf('hidden'), classes.lastIndexOf('sr-only'));
+    const overridden = classes.slice(hiddenIdx + 1).some(c => DISPLAY_OVERRIDES.has(c));
+    if (!overridden) {
+      return null;
+    }
+  }
+
+  if (node.kind === 'element' && tagLower === 'svg') {
+    const svgString = nodeIrToSvg(node);
+    if (svgString) {
+      const fgColor = resolveIconForegroundColor(nextContext, colorGroup, theme);
+      const icon = createIconFromSvg(svgString, fgColor);
+      if (icon) {
+        const wrapped = wrapSvgIcon(icon, classes, node.props, 'icon/svg');
+        return maybeWrapMxAuto(wrapped, classes, context);
+      }
+    }
+  }
+
+  // Image placeholder: <img> and Next.js <Image>
+  if (tagLower === 'img' || node.tagName === 'Image') {
+    const ir = layoutComputed.layoutIR;
+    // Prefer Tailwind-derived fixed sizes, then explicit width/height props, then defaults
+    const w = ir.fixedWidth
+      ?? (node.props.width != null ? parseFloat(String(node.props.width)) : null)
+      ?? 200;
+    const h = ir.fixedHeight
+      ?? (node.props.height != null ? parseFloat(String(node.props.height)) : null)
+      ?? 150;
+    const imgFrame = figma.createFrame();
+    imgFrame.name = node.props.alt ? String(node.props.alt) : 'image';
+    // layoutMode must stay NONE (fixed-size image frame); don't set sizing mode properties
+    imgFrame.layoutMode = 'NONE';
+    // Apply border radius from Tailwind classes (fills set below)
+    applyTailwindStylesToFrame(imgFrame, classes, colorGroup, radiusGroup, theme);
+    // Resize after applyTailwindStylesToFrame in case it modifies the frame
+    imgFrame.resize(Math.max(1, w), Math.max(1, h));
+
+    const src = node.props.src ? String(node.props.src) : null;
+    const svgString = src ? getSvgString(src) : null;
+    const imageHash = src ? getImageHash(src) : null;
+
+    if (svgString) {
+      // SVG: render as native vector node via createNodeFromSvg
+      try {
+        const svgNode = figma.createNodeFromSvg(svgString);
+        svgNode.name = node.props.alt ? String(node.props.alt) : 'image';
+        svgNode.resize(Math.max(1, w), Math.max(1, h));
+        imgFrame.remove();
+        return maybeWrapMxAuto(svgNode, classes, context);
+      } catch (_e) { /* fall through to placeholder */ }
+    }
+
+    if (imageHash) {
+      imgFrame.fills = [{ type: 'IMAGE', scaleMode: 'FILL', imageHash } as ImagePaint];
+    } else {
+      imgFrame.fills = [{ type: 'SOLID', color: { r: 0.878, g: 0.894, b: 0.914 }, opacity: 1 }];
+      try {
+        const placeholderSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#9ca3af" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><polyline points="21 15 16 10 5 21"/></svg>`;
+        const iconNode = figma.createNodeFromSvg(placeholderSvg);
+        if (iconNode) {
+          iconNode.x = Math.max(0, Math.round((w - 24) / 2));
+          iconNode.y = Math.max(0, Math.round((h - 24) / 2));
+          imgFrame.appendChild(iconNode);
+        }
+      } catch (_e) { /* createNodeFromSvg not available in all contexts */ }
+    }
+    return maybeWrapMxAuto(imgFrame, classes, context);
+  }
+
+  if (node.kind === 'element') {
+    const fgColor = resolveIconForegroundColor(nextContext, colorGroup, theme);
+    const registryIcon = renderRegistryIcon(node.tagName, classes, node.props, fgColor);
+    if (registryIcon) {
+      return maybeWrapMxAuto(registryIcon, classes, context);
+    }
+
+    const mappedIcon = renderMappedIcon(
+      node.tagName,
+      classes,
+      node.props,
+      fgColor,
+      !!nextContext.accordionItemIsOpen
+    );
+    if (mappedIcon) {
+      return maybeWrapMxAuto(mappedIcon, classes, context);
+    }
+  }
+
+  // Check for React component (uppercase) - try to find definition
+  if (node.kind === 'component') {
+    const expanded = maybeExpandTextLineComponent(node);
+    if (expanded) {
+      return buildFigmaNode(expanded, colorGroup, radiusGroup, theme, depth, context);
+    }
+    // Check if this is a React Icon we can render
+    const fgColor = resolveIconForegroundColor(nextContext, colorGroup, theme);
+    const registryIcon = renderRegistryIcon(node.tagName, classes, node.props, fgColor);
+    if (registryIcon) {
+      return maybeWrapMxAuto(registryIcon, classes, context);
+    }
+
+    const mappedIcon = renderMappedIcon(
+      node.tagName,
+      classes,
+      node.props,
+      fgColor,
+      !!nextContext.accordionItemIsOpen
+    );
+    if (mappedIcon) {
+      return maybeWrapMxAuto(mappedIcon, classes, context);
+    }
+
+    const compDef = getComponentDefByName(node.tagName);
+    const storyContext = getStoryBuilderContext();
+
+    if (compDef) {
+      const analysis = normalizeComponentDef(compDef);
+      if (analysis.type === 'cva') {
+        const instance = {
+          props: Object.assign({}, node.props),
+          children: collectTextContent(node),
+        };
+        const cva = createCVAStoryInstance(analysis, instance, theme, storyContext);
+        return maybeWrapMxAuto(cva, classes, context);
+      }
+      if (analysis.type === 'state') {
+        const instance = {
+          props: Object.assign({}, node.props),
+          children: collectTextContent(node),
+        };
+        const state = createStateStoryInstance(analysis, instance, theme, storyContext);
+        return maybeWrapMxAuto(state, classes, context);
+      }
+      if (!node.children || node.children.length === 0) {
+        // For simple components used inline in jsxTree (e.g. <Box className="h-4 w-48" />),
+        // render as a styled frame using the instance's className merged with base visual classes
+        if (analysis.type === 'simple' && node.props.className) {
+          const instanceClasses = node.classes.slice();
+          const compClasses = analysis.classes || [];
+          const baseVisualClasses = compClasses.filter((c: string) =>
+            c.startsWith('bg-') || (c.startsWith('rounded') && !c.includes('/'))
+          );
+          const allClasses = mergeClasses(baseVisualClasses, instanceClasses);
+
+          const simpleFrame = figma.createFrame();
+          simpleFrame.name = node.tagName;
+          simpleFrame.layoutMode = 'VERTICAL';
+          simpleFrame.primaryAxisSizingMode = 'FIXED';
+          simpleFrame.counterAxisSizingMode = 'FIXED';
+          simpleFrame.fills = [];
+          applyClipBehavior(simpleFrame, allClasses);
+          if (allClasses.length > 0) {
+            applyTailwindStylesToFrame(simpleFrame, allClasses, colorGroup, radiusGroup, theme);
+          }
+          return maybeWrapMxAuto(simpleFrame, allClasses, context);
+        }
+
+        // If the component has a jsxTree (from its own implementation), render it directly
+        // (e.g. <HeroSection /> inline with no children expands to the full component structure)
+        if (analysis.type === 'simple' && analysis.jsxTree) {
+          const result = renderComponentWithJsxTree(
+            analysis.jsxTree,
+            [],
+            colorGroup,
+            radiusGroup,
+            theme,
+            depth,
+            context
+          );
+          if (result) {
+            return maybeWrapMxAuto(result, classes, context);
+          }
+        }
+
+        const frame = figma.createFrame();
+        frame.name = node.tagName;
+        frame.layoutMode = 'VERTICAL';
+        frame.primaryAxisSizingMode = 'AUTO';
+        frame.counterAxisSizingMode = 'AUTO';
+        frame.fills = [];
+        applyClipBehavior(frame, classes);
+
+        const comp = createCompoundComponent(frame, analysis, theme);
+        if (comp) return maybeWrapMxAuto(comp, classes, context);
+      }
+    }
+
+    // If this component has children in the jsxTree, render them
+    // (wrapper components should show their content)
+    if (node.children && node.children.length > 0) {
+      // Get compound classes - try own definition first, then parent's subComponents
+      let compoundClasses: string[] = [];
+      let currentCompoundDef: any = null;
+      if (compDef) {
+        const normalizedDef = normalizeComponentDef(compDef);
+        // Get subComponent classes if this is a compound component
+        compoundClasses = getCompoundClasses(normalizedDef, node.tagName);
+        if (normalizedDef.type === 'compound') {
+          currentCompoundDef = normalizedDef;
+        }
+        // Check if this component has a jsxTree structure (for components with decorative elements)
+        if (normalizedDef.type === 'simple' && normalizedDef.jsxTree) {
+          const hasInstanceChildren = (node.children?.length ?? 0) > 0;
+          const canRenderTree = !hasInstanceChildren || jsxTreeHasChildrenSlot(normalizedDef.jsxTree);
+          if (canRenderTree) {
+          // Render the component's internal structure from jsxTree
+          const result = renderComponentWithJsxTree(
+            normalizedDef.jsxTree,
+            node.children,
+            colorGroup,
+            radiusGroup,
+            theme,
+            depth,
+            context
+          );
+          if (result) {
+            return maybeWrapMxAuto(result, classes, context);
+          }
+          }
+        }
+        // Use only container-level classes from the definition
+        const defClasses = normalizedDef.baseClasses || normalizedDef.classes || [];
+        if (defClasses.length > 0) {
+          // Filter to only container classes (no decorative element classes)
+          const containerClasses = defClasses.filter((c: string) =>
+            c === 'relative' || c === 'isolate' ||
+            c.startsWith('py-') || c.startsWith('px-') || c.startsWith('p-') ||
+            c.startsWith('rounded')
+          );
+          compoundClasses = mergeClasses(containerClasses, compoundClasses);
+        }
+      }
+      // If no classes found and we have a parent compound def, look up as subComponent
+      if (compoundClasses.length === 0 && context.parentCompoundDef) {
+        compoundClasses = getCompoundClasses(context.parentCompoundDef, node.tagName);
+      }
+
+      const mergedClasses = compoundClasses.length > 0
+        ? mergeClasses(compoundClasses, classes)
+        : classes;
+      const activeMergedClasses = mergedClasses === classes
+        ? classes
+        : resolveClassesForBreakpoint(mergedClasses, breakpointIndex);
+
+      const wrapperFrame = figma.createFrame();
+      wrapperFrame.name = node.tagName;
+      wrapperFrame.fills = [];
+
+      // Apply layout using LayoutParser IR
+      const wrapperIR = activeMergedClasses === classes ? layoutComputed.layoutIR : LayoutParser.parseToIR(activeMergedClasses);
+      LayoutParser.applyToFrame(wrapperFrame, wrapperIR);
+
+      // Apply styles to the frame
+      if (activeMergedClasses.length > 0) {
+        applyTailwindStylesToFrame(wrapperFrame, activeMergedClasses, colorGroup, radiusGroup, theme);
+      }
+      applyClipBehavior(wrapperFrame, activeMergedClasses);
+      // Calculate content width for children (accounting for padding)
+      // This is needed for justify-between to work in Figma SPACE_BETWEEN mode
+      const wrapperPadding = (wrapperFrame.paddingLeft || 0) + (wrapperFrame.paddingRight || 0);
+      const hasFixedWidth = wrapperFrame.layoutMode === 'HORIZONTAL'
+        ? wrapperFrame.primaryAxisSizingMode === 'FIXED'
+        : wrapperFrame.counterAxisSizingMode === 'FIXED';
+      const wrapperContentWidth = hasFixedWidth && wrapperFrame.width > 0
+        ? wrapperFrame.width - wrapperPadding
+        : undefined;
+      const childCtx: RenderContext = Object.assign({}, nextContext, {
+        parentLayout: wrapperFrame.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+        textColor: nextContext.textColor,
+        textColorToken: nextContext.textColorToken,
+        maxWidth: wrapperContentWidth || context.maxWidth,
+        parentCompoundDef: currentCompoundDef || nextContext.parentCompoundDef,
+      });
+      const skipWrapperFullWidth = shouldSkipFullWidthForClasses(activeMergedClasses);
+      const accordionItemOrdinal = { value: 0 };
+
+      for (const child of node.children) {
+        const perChildCtx = createPerChildRenderContext(childCtx, node, child, accordionItemOrdinal);
+        const childNode = buildFigmaNode(child, colorGroup, radiusGroup, theme, depth + 1, perChildCtx);
+        if (childNode) {
+          wrapperFrame.appendChild(childNode);
+
+          // Apply child-specific layout properties
+          if (isElementLikeNode(child)) {
+            LayoutParser.applyChildProperties(childNode, child.classes, wrapperFrame);
+          }
+          stabilizeHorizontalStretchChild(childNode, wrapperFrame);
+          constrainSingleHorizontalTextChild(childNode);
+
+          applyAbsoluteIfPossible(childNode, wrapperFrame);
+          const fullWidthOptions = (skipWrapperFullWidth || childCtx.maxWidth != null)
+            ? { skipFullWidth: skipWrapperFullWidth, widthOverride: childCtx.maxWidth }
+            : undefined;
+          applyFullWidthIfPossible(childNode, wrapperFrame, fullWidthOptions);
+        }
+      }
+      applyDeferredBottomPositioning(wrapperFrame);
+      applyDeferredCenterYPositioning(wrapperFrame);
+      // Apply grid columns after all children are added
+      const wrapperGridWidth = resolveGridWidthOverride(wrapperFrame, childCtx.maxWidth);
+      applyGridColumnsWithReflow(wrapperFrame, wrapperGridWidth);
+
+      return maybeWrapMxAuto(wrapperFrame, activeMergedClasses, context);
+    }
+
+    // Components like SelectValue, Input etc. that expose a placeholder prop but have no
+    // renderable children — render the placeholder as muted text so triggers show content.
+    if ((!node.children || node.children.length === 0) && node.props && node.props.placeholder) {
+      const phOpts: any = { fontSize: context.textFontSize || 14, theme, opacity: 0.4 };
+      if (context.textFontStyle != null) phOpts.fontStyle = context.textFontStyle;
+      else if (context.textBold != null) phOpts.bold = context.textBold;
+      if (context.textColor) phOpts.fill = context.textColor;
+      return createTextNode(node.props.placeholder, phOpts);
+    }
+
+    // Unknown component without children - render styled frame
+    const compFrame = figma.createFrame();
+    compFrame.name = node.tagName;
+    compFrame.layoutMode = 'VERTICAL';
+    compFrame.primaryAxisSizingMode = 'AUTO';
+    compFrame.counterAxisSizingMode = 'AUTO';
+    compFrame.fills = [];
+    applyClipBehavior(compFrame, classes);
+    if (classes.length > 0) {
+      applyTailwindStylesToFrame(compFrame, classes, colorGroup, radiusGroup, theme);
+    }
+    const compChildCtx: RenderContext = Object.assign({}, nextContext, {
+      textColor: nextContext.textColor,
+      textColorToken: nextContext.textColorToken,
+      maxWidth: compFrame.layoutMode === 'HORIZONTAL' ? undefined : context.maxWidth,
+      parentLayout: compFrame.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+    });
+    const skipCompFullWidth = shouldSkipFullWidthForClasses(classes);
+    const accordionItemOrdinal = { value: 0 };
+    for (const child of node.children || []) {
+      const perChildCtx = createPerChildRenderContext(compChildCtx, node, child, accordionItemOrdinal);
+      const childNode = buildFigmaNode(child, colorGroup, radiusGroup, theme, depth + 1, perChildCtx);
+      if (childNode) {
+        compFrame.appendChild(childNode);
+        // Apply child layout properties based on parent context
+        if (isElementLikeNode(child)) {
+          LayoutParser.applyChildProperties(childNode, child.classes, compFrame);
+        }
+        stabilizeHorizontalStretchChild(childNode, compFrame);
+        constrainSingleHorizontalTextChild(childNode);
+        applyAbsoluteIfPossible(childNode, compFrame);
+        const fullWidthOptions = (skipCompFullWidth || compChildCtx.maxWidth != null)
+          ? { skipFullWidth: skipCompFullWidth, widthOverride: compChildCtx.maxWidth }
+          : undefined;
+        applyFullWidthIfPossible(childNode, compFrame, fullWidthOptions);
+      }
+    }
+    applyDeferredBottomPositioning(compFrame);
+      applyDeferredCenterYPositioning(compFrame);
+    // Apply grid columns after all children are added
+    applyGridColumnsWithReflow(compFrame);
+    return maybeWrapMxAuto(compFrame, classes, context);
+  }
+
+  // HTML elements - create frame or text
+  if (['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'span', 'a', 'label', 'li', 'small'].includes(tagLower)) {
+    const hasElementChildren = (node.children || []).some(child => isElementLikeNode(child));
+    const hasLayoutClass = layoutComputed.hasLayoutClass;
+    const hasFlexChildClass = layoutComputed.hasFlexChildClass;
+    const hasExplicitSize = layoutComputed.hasExplicitSize;
+    const inlineOnlyChildren = hasElementChildren && (node.children || []).every(isInlineTextNode);
+    // Any solid background on a text-category element requires a frame to be visible
+    const hasBgClass = classes.some(cls => {
+      if (!cls.startsWith('bg-')) return false;
+      const rest = cls.slice(3);
+      return !rest.startsWith('gradient') && !rest.startsWith('linear') && !rest.startsWith('radial') && rest !== 'transparent';
+    });
+
+    if (inlineOnlyChildren && !hasLayoutClass && !hasFlexChildClass && !hasBgClass) {
+      const inlineText = createInlineTextNode(node as NodeIRElement, textStyle, nextContext, colorGroup, theme, layoutComputed);
+      if (inlineText) return maybeWrapMxAuto(inlineText, classes, context);
+    }
+
+    // Create a frame container for elements with layout, explicit sizing, flex child classes, or a background fill
+    if (hasElementChildren || hasLayoutClass || hasFlexChildClass || hasExplicitSize || hasBgClass) {
+      const frame = figma.createFrame();
+      frame.name = node.tagName;
+      frame.fills = [];
+
+      // Apply layout using LayoutParser IR
+      LayoutParser.applyToFrame(frame, layoutComputed.layoutIR);
+
+      // Apply visual styles
+      if (classes.length > 0) {
+        applyTailwindStylesToFrame(frame, classes, colorGroup, radiusGroup, theme);
+      }
+      applyClipBehavior(frame, classes);
+      if (
+        context.parentLayout === 'VERTICAL'
+        && shouldStretchToParentWidth(tagLower, classes)
+      ) {
+        (frame as any).layoutAlign = 'STRETCH';
+      } else if (context.parentLayout === 'VERTICAL') {
+        // Inline display elements (inline-flex, inline-block, etc.) must not stretch to parent width.
+        // Figma's default layoutAlign 'INHERIT' = STRETCH in a VERTICAL parent — override it.
+        const hasInlineDisplay = classes.some(c => {
+          const base = getBaseClass(c);
+          return base === 'inline' || base === 'inline-flex' || base === 'inline-block' || base === 'inline-grid';
+        });
+        if (hasInlineDisplay) {
+          try { (frame as any).layoutSizingHorizontal = 'HUG'; } catch (_e) { /* ignore if frame has no auto-layout */ }
+        }
+      }
+      if (
+        frame.layoutMode === 'HORIZONTAL'
+        && context.maxWidth
+        && (frame as any).layoutAlign === 'STRETCH'
+        && frame.primaryAxisSizingMode !== 'FIXED'
+      ) {
+        frame.resize(context.maxWidth, frame.height);
+        frame.primaryAxisSizingMode = 'FIXED';
+      }
+      // Handle text content or children
+      if (hasElementChildren) {
+        const frameHasFixedWidth = frame.layoutMode === 'HORIZONTAL'
+          ? frame.primaryAxisSizingMode === 'FIXED'
+          : frame.counterAxisSizingMode === 'FIXED';
+        const resolvedMaxWidth = frameHasFixedWidth
+          ? (nextContext.maxWidth ? Math.min(nextContext.maxWidth, frame.width) : frame.width)
+          : nextContext.maxWidth;
+        const skipElementFullWidth = shouldSkipFullWidthForClasses(classes);
+        const contentWidth = resolvedMaxWidth
+          ? Math.max(0, resolvedMaxWidth - (frame.paddingLeft || 0) - (frame.paddingRight || 0))
+          : undefined;
+        const gridWidthOverride = resolveGridWidthOverride(frame, contentWidth);
+        const inheritedChildMaxWidth = frame.layoutMode === 'HORIZONTAL' ? undefined : contentWidth;
+        const childContext: RenderContext = {
+          ...nextContext,
+          textAlign: nextContext.textAlign,
+          maxWidth: inheritedChildMaxWidth,
+          parentLayout: frame.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+          textColor: nextContext.textColor,
+          textColorToken: nextContext.textColorToken,
+        };
+        const accordionItemOrdinal = { value: 0 };
+        for (const child of node.children || []) {
+          const perChildCtx = createPerChildRenderContext(childContext, node, child, accordionItemOrdinal);
+          const childNode = buildFigmaNode(child, colorGroup, radiusGroup, theme, depth + 1, perChildCtx);
+          if (childNode) {
+            frame.appendChild(childNode);
+            // Apply child layout properties based on parent context
+            if (isElementLikeNode(child)) {
+              LayoutParser.applyChildProperties(childNode, child.classes, frame);
+            }
+            stabilizeHorizontalStretchChild(childNode, frame);
+            constrainSingleHorizontalTextChild(childNode);
+            applyAbsoluteIfPossible(childNode, frame);
+            const fullWidthOptions = (skipElementFullWidth || childContext.maxWidth != null)
+              ? { skipFullWidth: skipElementFullWidth, widthOverride: childContext.maxWidth }
+              : undefined;
+            applyFullWidthIfPossible(childNode, frame, fullWidthOptions);
+          }
+        }
+        applyDeferredBottomPositioning(frame);
+      applyDeferredCenterYPositioning(frame);
+        constrainSingleHorizontalTextChild(frame);
+        // Apply grid columns after all children are added
+        applyGridColumnsWithReflow(frame, gridWidthOverride);
+      } else {
+        // Text-only element with sizing - create text node and append
+        const textContent = collectTextContent(node);
+        if (textContent.trim()) {
+          const typo = TAG_TYPOGRAPHY[tagLower] || { fontSize: 14 };
+          const isHeadingTag = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(tagLower);
+          const textOpts: any = {
+            fontSize: typo.fontSize,
+            bold: typo.bold,
+            lineHeight: typo.lineHeight,
+            theme,
+            fontRole: isHeadingTag ? 'heading' : 'sans',
+          };
+          if (textStyle.text) {
+            textOpts.fill = textStyle.text;
+          } else if (nextContext.textColor) {
+            textOpts.fill = nextContext.textColor;
+          }
+          const resolvedBold = getResolvedBoldFromClasses(classes, textOpts.bold);
+          if (resolvedBold != null) textOpts.bold = resolvedBold;
+          const resolvedFontStyle = getFontStyleFromClasses(classes, nextContext.textFontStyle);
+          if (resolvedFontStyle != null) textOpts.fontStyle = resolvedFontStyle;
+          const resolvedSize = getResolvedTextSizeFromClasses(classes, textOpts.fontSize);
+          if (resolvedSize != null) textOpts.fontSize = resolvedSize;
+          // Apply text-center alignment if present
+          if (classes.includes('text-center')) {
+            textOpts.textAlignHorizontal = 'CENTER';
+          } else if (classes.includes('text-right')) {
+            textOpts.textAlignHorizontal = 'RIGHT';
+          }
+          const textNode = createTextNode(textContent, textOpts);
+          // In a HORIZONTAL frame with CENTER alignment, don't force the text node
+          // to a fixed width — let it stay HUG-sized so the frame's CENTER alignment
+          // can position it (e.g. a numbered circle with justify-center).
+          const isHorizontalCentered = frame.layoutMode === 'HORIZONTAL'
+            && (frame as any).primaryAxisAlignItems === 'CENTER';
+          const textContentWidth = (!isHorizontalCentered && nextContext.maxWidth)
+            ? Math.max(0, nextContext.maxWidth - (frame.paddingLeft || 0) - (frame.paddingRight || 0))
+            : undefined;
+          if (textContentWidth && textContentWidth > 0) {
+            try {
+              textNode.textAutoResize = 'HEIGHT';
+              textNode.resize(textContentWidth, textNode.height);
+            } catch (_err) {
+              // ignore resize errors
+            }
+          }
+          frame.appendChild(textNode);
+        }
+      }
+      return maybeWrapMxAuto(frame, classes, context);
+    }
+
+    // Text-like elements - gather all text content
+    const textContent = collectTextContent(node);
+    if (!textContent.trim()) return null;
+
+    const typo = TAG_TYPOGRAPHY[tagLower] || { fontSize: 14 };
+    const isHeadingTag = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(tagLower);
+    const textOpts: any = {
+      fontSize: typo.fontSize,
+      bold: typo.bold,
+      lineHeight: typo.lineHeight,
+      theme,
+      fontRole: isHeadingTag ? 'heading' : 'sans',
+    };
+
+    // Extract text color from classes
+    if (textStyle.text) {
+      textOpts.fill = textStyle.text;
+    } else if (nextContext.textColor) {
+      textOpts.fill = nextContext.textColor;
+    }
+
+    if (nextContext.textAlign) {
+      textOpts.textAlignHorizontal = nextContext.textAlign;
+    }
+
+    // Check for bold/font-weight class
+    const resolvedBold = getResolvedBoldFromClasses(classes, textOpts.bold);
+    if (resolvedBold != null) textOpts.bold = resolvedBold;
+    const resolvedFontStyle = getFontStyleFromClasses(classes, nextContext.textFontStyle);
+    if (resolvedFontStyle != null) textOpts.fontStyle = resolvedFontStyle;
+
+    // Extract font size from classes
+    const resolvedSize = getResolvedTextSizeFromClasses(classes, textOpts.fontSize);
+    if (resolvedSize != null) textOpts.fontSize = resolvedSize;
+
+    const lineHeight = getLineHeightFromClasses(classes, textOpts.fontSize);
+    if (lineHeight) {
+      textOpts.lineHeight = lineHeight;
+    }
+
+    const textNode = createTextNode(textContent, textOpts);
+    const isBlockText = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p'].includes(tagLower);
+    const shouldConstrain = nextContext.maxWidth
+      && nextContext.parentLayout !== 'HORIZONTAL'
+      && (isBlockText || classes.includes('block') || classes.includes('w-full'));
+    const hasTruncateClass = classes.includes('truncate');
+    let lineClampN: number | null = null;
+    for (const cls of classes) {
+      const m = cls.match(/^line-clamp-(\d+)$/);
+      if (m) { lineClampN = parseInt(m[1], 10); break; }
+    }
+    if ((hasTruncateClass || lineClampN != null) && nextContext.maxWidth) {
+      try {
+        const maxLines = lineClampN ?? 1;
+        const fs = textOpts.fontSize || 14;
+        const lh = textOpts.lineHeight || Math.ceil(fs * 1.5);
+        (textNode as any).textTruncation = 'ENDING';
+        (textNode as any).maxLines = maxLines;
+        textNode.resize(nextContext.maxWidth, Math.max(lh, lh * maxLines));
+      } catch (_err) { /* ignore */ }
+    } else if (shouldConstrain) {
+      try {
+        textNode.textAutoResize = 'HEIGHT';
+        textNode.resize(nextContext.maxWidth, textNode.height);
+      } catch (_err) {
+        // ignore resize errors
+      }
+    }
+    return maybeWrapMxAuto(textNode, classes, context);
+  }
+
+  // <hr> - horizontal rule / separator
+  if (tagLower === 'hr') {
+    const hr = figma.createFrame();
+    hr.name = 'hr';
+    hr.layoutMode = 'HORIZONTAL';
+    hr.resize(200, 1);
+    hr.primaryAxisSizingMode = 'FIXED';
+    hr.counterAxisSizingMode = 'FIXED';
+    const borderColor = colorGroup.border ? parseColor(colorGroup.border) : { r: 0.85, g: 0.85, b: 0.85 };
+    hr.fills = [{ type: 'SOLID', color: { r: borderColor.r, g: borderColor.g, b: borderColor.b } }];
+    if (classes.includes('w-full')) {
+      markFullWidthNode(hr);
+    }
+    return maybeWrapMxAuto(hr, classes, context);
+  }
+
+  // Container elements (div, nav, section, header, footer, ul, ol, etc.)
+
+  // Check for clip-path in style prop - create vector shape instead of frame
+  const clipPathPolygon = parseClipPathFromStyle(node.props.style);
+  if (clipPathPolygon && node.children.length === 0) {
+    const decorativeNode = buildDecorativeClipPathNode({
+      clipPathPolygon,
+      classes,
+      contextMaxWidth: context.maxWidth,
+      colorGroup,
+      radiusGroup,
+      theme,
+    });
+    if (decorativeNode) return maybeWrapMxAuto(decorativeNode, classes, context);
+  }
+
+  const frame = figma.createFrame();
+  frame.name = node.tagName;
+  frame.fills = [];
+
+  // Apply layout using LayoutParser IR (handles flex, grid, alignment, spacing, dimensions)
+  LayoutParser.applyToFrame(frame, layoutComputed.layoutIR);
+
+  // Apply visual styles (colors, borders, radius) from Tailwind classes
+  // Resolve sm: breakpoint overrides when container is >= 640px (matches CSS cascade)
+  const effectiveClasses = (context.maxWidth != null && context.maxWidth >= 640)
+    ? getClassesForBreakpoint(classes, 'sm')
+    : classes;
+  if (effectiveClasses.length > 0) {
+    applyTailwindStylesToFrame(frame, effectiveClasses, colorGroup, radiusGroup, theme);
+  }
+  applyClipBehavior(frame, effectiveClasses);
+  // Hero-like containers (`relative isolate`) with decorative clip-path blobs should
+  // clip to their own bounds so gradients never spill outside the component frame.
+  if (effectiveClasses.includes('relative') && effectiveClasses.includes('isolate') && nodeHasClipPathDescendant(node)) {
+    frame.clipsContent = true;
+  }
+
+  // NOTE: text-left/center/right only affects TEXT content in CSS, not block layout.
+  // Do NOT apply alignFromClasses to frame.counterAxisAlignItems here.
+  // The textAlign context is propagated to child text nodes instead.
+
+  const shouldApplyContextWidth = depth === 0 && context.maxWidth;
+  if (shouldApplyContextWidth || (nextContext.maxWidth && nextContext.maxWidth !== context.maxWidth)) {
+    const targetWidth = shouldApplyContextWidth ? context.maxWidth : nextContext.maxWidth;
+    if (targetWidth) {
+      if (frame.layoutMode === 'HORIZONTAL') {
+        frame.resize(targetWidth, frame.height);
+        frame.primaryAxisSizingMode = 'FIXED';
+      } else {
+        frame.resize(targetWidth, frame.height);
+        frame.counterAxisSizingMode = 'FIXED';
+      }
+    }
+    // Clip the story root frame so absolute-positioned children (e.g. gradient blobs)
+    // don't extend visually outside the component's bounds in Figma.
+    if (shouldApplyContextWidth) {
+      frame.clipsContent = true;
+    }
+  }
+
+  // Block-level elements in VERTICAL parents should stretch to fill width
+  // Note: We set layoutAlign even before the frame is appended - Figma will respect it when appended
+  if (
+    context.parentLayout === 'VERTICAL'
+    && shouldStretchToParentWidth(tagLower, classes)
+  ) {
+    (frame as any).layoutAlign = 'STRETCH';
+  } else if (context.parentLayout === 'VERTICAL') {
+    const hasInlineDisplay = classes.some(c => {
+      const base = getBaseClass(c);
+      return base === 'inline' || base === 'inline-flex' || base === 'inline-block' || base === 'inline-grid';
+    });
+    if (hasInlineDisplay) {
+      try { (frame as any).layoutSizingHorizontal = 'HUG'; } catch (_e) { /* ignore if frame has no auto-layout */ }
+    }
+  }
+
+  if (
+    frame.layoutMode === 'HORIZONTAL'
+    && context.maxWidth
+    && (frame as any).layoutAlign === 'STRETCH'
+    && frame.primaryAxisSizingMode !== 'FIXED'
+  ) {
+    frame.resize(context.maxWidth, frame.height);
+    frame.primaryAxisSizingMode = 'FIXED';
+  }
+
+  const frameHasFixedWidth = frame.layoutMode === 'HORIZONTAL'
+    ? frame.primaryAxisSizingMode === 'FIXED'
+    : frame.counterAxisSizingMode === 'FIXED';
+  const resolvedMaxWidth = frameHasFixedWidth
+    ? (nextContext.maxWidth ? Math.min(nextContext.maxWidth, frame.width) : frame.width)
+    : nextContext.maxWidth;
+  const gridCols = extractGridColumns(classes, resolvedMaxWidth || context.maxWidth);
+  const gridWidth = resolvedMaxWidth || context.maxWidth || (gridCols ? defaultGridWidth(gridCols) : undefined);
+  const skipChildFullWidth = !!gridCols || classes.includes('grid') || classes.includes('inline-grid');
+  if (gridCols && gridWidth && 'resize' in frame) {
+    try {
+      if (frame.layoutMode !== 'HORIZONTAL') frame.layoutMode = 'HORIZONTAL';
+      if ((frame as any).layoutWrap !== undefined) {
+        (frame as any).layoutWrap = 'WRAP';
+      }
+      frame.resize(gridWidth, frame.height);
+      frame.primaryAxisSizingMode = 'FIXED';
+      frame.counterAxisSizingMode = 'AUTO';
+    } catch (_err) {
+      // ignore resize errors
+    }
+  }
+
+  // Render children
+  const contentWidth = resolvedMaxWidth
+    ? Math.max(0, resolvedMaxWidth - (frame.paddingLeft || 0) - (frame.paddingRight || 0))
+    : undefined;
+  const inheritedChildMaxWidth = frame.layoutMode === 'HORIZONTAL' ? undefined : contentWidth;
+  const childContext: RenderContext = {
+    ...nextContext,
+    textAlign: nextContext.textAlign,
+    maxWidth: inheritedChildMaxWidth,
+    parentLayout: frame.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+    textColor: nextContext.textColor,
+    textColorToken: nextContext.textColorToken,
+  };
+  const renderChildren = getRenderableChildren(node, classes);
+  const accordionItemOrdinal = { value: 0 };
+
+  // For VERTICAL layouts, extract mt-* (margin-top) from children and use as itemSpacing
+  // This converts CSS margins to Figma auto-layout gaps
+  if (frame.layoutMode === 'VERTICAL' && renderChildren.length > 1 && !isSemanticTableContainer(node)) {
+    let maxMarginTop = 0;
+    for (const child of renderChildren) {
+      if (!isElementLikeNode(child)) continue;
+      const childClasses = child.classes;
+      for (const cls of childClasses) {
+        const mtMatch = cls.match(/^mt-(\d+)$/);
+        if (mtMatch) {
+          const mtValue = parseInt(mtMatch[1], 10) * 4; // Tailwind spacing scale
+          if (mtValue > maxMarginTop) maxMarginTop = mtValue;
+        }
+        // Also handle mt-[Xpx] arbitrary values
+        const mtArbitraryMatch = cls.match(/^mt-\[(\d+)px\]$/);
+        if (mtArbitraryMatch) {
+          const mtValue = parseInt(mtArbitraryMatch[1], 10);
+          if (mtValue > maxMarginTop) maxMarginTop = mtValue;
+        }
+      }
+    }
+    if (maxMarginTop > 0 && (!frame.itemSpacing || frame.itemSpacing < maxMarginTop)) {
+      frame.itemSpacing = maxMarginTop;
+    }
+  }
+
+  // Inline-only div: all children are text/span/a nodes (no block layout).
+  // Collapse into a single text node — like a CSS inline container (e.g. pill labels).
+  const hasOnlyInlineChildren = !layoutComputed.hasLayoutClass
+    && renderChildren.length > 0
+    && renderChildren.every(isInlineTextNode);
+  if (hasOnlyInlineChildren) {
+    const inlineText = createInlineTextNode(node as any, textStyle, nextContext, colorGroup, theme, layoutComputed);
+    if (inlineText) {
+      frame.appendChild(inlineText);
+      return maybeWrapMxAuto(frame, classes, context);
+    }
+  }
+
+  for (const child of renderChildren) {
+    const perChildCtx = createPerChildRenderContext(childContext, node, child, accordionItemOrdinal);
+    const childNode = buildFigmaNode(child, colorGroup, radiusGroup, theme, depth + 1, perChildCtx);
+    if (childNode) {
+      frame.appendChild(childNode);
+
+      // Apply child-specific layout properties (flex-1, self-*, etc.)
+      if (isElementLikeNode(child)) {
+        LayoutParser.applyChildProperties(childNode, child.classes, frame);
+      }
+      stabilizeHorizontalStretchChild(childNode, frame);
+      constrainSingleHorizontalTextChild(childNode);
+
+      applyAbsoluteIfPossible(childNode, frame);
+      const fullWidthOptions = (skipChildFullWidth || contentWidth != null)
+        ? { skipFullWidth: skipChildFullWidth, widthOverride: contentWidth }
+        : undefined;
+      applyFullWidthIfPossible(childNode, frame, fullWidthOptions);
+      if (
+        node.kind === 'element'
+        && node.tagLower === 'table'
+        && child.kind === 'element'
+        && child.tagLower === 'tfoot'
+      ) {
+        // CSS table border-collapse merges adjacent borders to 1px.
+        // In Figma stacked frames accumulate strokes, so clear tfoot top stroke.
+        clearTopBorder(childNode);
+      }
+      if (
+        node.kind === 'element'
+        && node.tagLower === 'tfoot'
+        && child.kind === 'element'
+        && child.tagLower === 'tr'
+      ) {
+        // Matches [&>tr]:last:border-b-0 on TableFooter.
+        clearBottomBorder(childNode);
+      }
+      if (
+        node.kind === 'element'
+        && node.tagLower === 'tr'
+        && (child.kind === 'element' || child.kind === 'component')
+        && (child.tagLower === 'td' || child.tagLower === 'th')
+        && !hasTableCellSizeOverride(child.classes)
+      ) {
+        const colSpan = getNumericColSpan((child.props as any)?.colSpan);
+        try {
+          (childNode as any).layoutGrow = colSpan;
+        } catch (_err) {
+          // ignore if node cannot grow in this parent
+        }
+      }
+    }
+  }
+
+  // For input/textarea elements with no children, render defaultValue or placeholder as text
+  if ((tagLower === 'input' || tagLower === 'textarea') && (!node.children || node.children.length === 0)) {
+    const inputText = node.props.defaultValue || node.props.value;
+    const inputPlaceholder = node.props.placeholder;
+    if (inputText || inputPlaceholder) {
+      const inputTextOpts: any = { fontSize: context.textFontSize || 14, theme };
+      if (inputText) {
+        if (context.textColor) inputTextOpts.fill = context.textColor;
+      } else {
+        inputTextOpts.opacity = 0.4; // placeholder muted
+      }
+      const inputTextNode = createTextNode(inputText || inputPlaceholder, inputTextOpts);
+      frame.appendChild(inputTextNode);
+    }
+  }
+
+  applyDeferredBottomPositioning(frame);
+      applyDeferredCenterYPositioning(frame);
+  applyGridColumnsWithReflow(frame, gridWidth || frame.width, gridCols || undefined);
+
+  // Re-apply clipping after children are added, in case Figma resets it during layout ops.
+  if (shouldClipContent(classes)) {
+    frame.clipsContent = true;
+  }
+  // Re-apply directional border widths after layout/resize passes; Figma may normalize
+  // stroke sides during downstream sizing operations.
+  if (Array.isArray(frame.strokes) && frame.strokes.length > 0) {
+    applyBorderWidthUtilities(frame, classes);
+  }
+
+  return maybeWrapMxAuto(frame, classes, context);
+}
+
+/**
+ * Recursively collect text content from a resolved node tree
+ */
+function collectTextContent(node: NodeIR): string {
+  const parts: string[] = [];
+  const walk = (current: NodeIR): void => {
+    if (current.kind === 'text') {
+      parts.push(current.text);
+      return;
+    }
+    if (current.kind === 'fragment') {
+      for (const child of current.children) {
+        walk(child);
+      }
+      return;
+    }
+    if (current.kind === 'divider') {
+      return;
+    }
+    if (current.kind === 'ring') {
+      walk(current.child);
+      return;
+    }
+    if (current.classes.includes('hidden') || current.classes.includes('sr-only')) {
+      return;
+    }
+    for (const child of current.children || []) {
+      walk(child);
+    }
+  };
+  walk(node);
+  return parts.join(' ').replace(/\s+/g, ' ').trim();
+}
+
+function applyLayoutClasses(
+  frame: any,
+  classes: string[] | undefined,
+  colorGroup: Record<string, string>,
+  radiusGroup: Record<string, string> | null,
+  theme: string
+): void {
+  const list = classes || [];
+  const layoutIR = LayoutParser.parseToIR(list);
+  LayoutParser.applyToFrame(frame, layoutIR);
+  frame.fills = frame.fills || [];
+  if (list.length > 0) {
+    applyTailwindStylesToFrame(frame, list, colorGroup, radiusGroup, theme);
+  }
+  applyClipBehavior(frame, list);
+
+  if (!frame.itemSpacing || frame.itemSpacing === 0) {
+    frame.itemSpacing = 12;
+  }
+}
+
+function applyAbsoluteIfAllowed(child: SceneNode, parent: FrameNode, allowAbsolute: boolean): void {
+  if (!allowAbsolute) return;
+  applyAbsoluteIfPossible(child, parent);
+}
+
+export function createUIComponents(parent: any, opts?: any): any {
+  return createUIComponentsFromStory(parent, opts, getStoryBuilderContext());
+}