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

package/scanner/tailwind-parser.ts

@@ -166,7 +166,22 @@ export function resolveSpacing(value: string): number | undefined {
 // State Modifiers
 // ============================================================================
 
-export const STATE_MODIFIERS = [
+/**
+ * Modifiers that imply the component has its OWN interactive/aria state
+ * (it receives focus, can be disabled directly, etc.). These are the
+ * trigger set for state-component classification — if a root className
+ * uses any of these, the component participates in a state-variant matrix
+ * and the plugin renders it via the state-master path.
+ *
+ * Deliberately excludes `group-*:` and `peer-*:` modifiers — those are
+ * *passive reactions* to a parent's or sibling's state (e.g. Label
+ * dimming when its `<input>` peer is `:disabled`). They don't justify
+ * promoting the component to a state primitive. A Label that only
+ * carries `peer-disabled:opacity-50` should stay `simple`, render its
+ * text children normally, and not get hoisted into a state-master that
+ * wipes its content.
+ */
+export const OWN_STATE_MODIFIERS = [
   'hover:',
   'focus:',
   'focus-visible:',
@@ -182,6 +197,16 @@ export const STATE_MODIFIERS = [
   'data-[state=active]:',
   'data-[checked]:',
   'data-[disabled]:',
+];
+
+/**
+ * All recognized state modifiers — used during state-grouping after a
+ * component has been classified, so passive `group-*` / `peer-*`
+ * variants still get their classes captured even though they don't
+ * trigger classification on their own.
+ */
+export const STATE_MODIFIERS = [
+  ...OWN_STATE_MODIFIERS,
   'group-data-[checked]:',
   'group-data-[disabled]:',
   'peer-data-[checked]:',
@@ -512,7 +537,18 @@ export function groupClassesByState(classes: string[]): Record<string, string[]>
       if (!groups[stateName]) {
         groups[stateName] = [];
       }
-      groups[stateName].push(parsed.utility);
+      // Reconstitute the utility with its opacity suffix when one was
+      // parsed off — without this, `focus-visible:ring-ring/50` and
+      // `aria-invalid:ring-destructive/20` get stripped to plain
+      // `ring-ring` / `ring-destructive` (full opacity), losing the
+      // translucent look shadcn uses for soft focus / invalid rings.
+      // Symptom: State Matrix focus/error variants render solid bright
+      // rings instead of the brand-tinted, semi-transparent look the
+      // browser shows.
+      const utilityWithOpacity = parsed.opacity != null
+        ? parsed.utility + '/' + parsed.opacity
+        : parsed.utility;
+      groups[stateName].push(utilityWithOpacity);
     } else if (!parsed.modifier) {
       groups.default.push(cls);
     } else {

package/src/components/component-gen.ts

@@ -7,9 +7,7 @@ import { tailwindClassesToStyle, applyTailwindStylesToFrame } from '../tailwind'
 import { bindColorVariable, pxFromSizeToken } from '../tokens';
 import { createTextNode } from '../text';
 import { extractStatesFromClasses, mergeStatesWithDefinition, type StateInfo } from '../tailwind';
-import { extractArbitraryValue, parseLength } from '../tailwind';
-
-type RingInfo = { width: number; color: { r: number; g: number; b: number; a?: number } };
+import { getRingInfoFromClasses, markRingNode, applyRingIfPossible } from '../layout';
 
 function getStateEntry(states: StateInfo[], name: string): StateInfo | null {
   for (let i = 0; i < states.length; i++) {
@@ -37,152 +35,6 @@ function buildStateClasses(states: StateInfo[], name: string): string[] {
   return baseClasses.concat(entry.classes);
 }
 
-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;
-  let colorToken = token;
-  let opacityMultiplier: number | null = null;
-  const slashIndex = token.lastIndexOf('/');
-  if (slashIndex > 0 && slashIndex < token.length - 1) {
-    colorToken = token.substring(0, slashIndex);
-    const opacityRaw = token.substring(slashIndex + 1).trim();
-    const opacityNum = parseFloat(opacityRaw);
-    if (!Number.isNaN(opacityNum)) {
-      opacityMultiplier = Math.max(0, Math.min(1, opacityNum / 100));
-    }
-  }
-  const resolved = colorGroup[colorToken];
-  if (!resolved) return null;
-  const parsed = parseColor(resolved);
-  if (opacityMultiplier == null) return parsed;
-  const baseAlpha = parsed.a == null ? 1 : parsed.a;
-  return {
-    r: parsed.r,
-    g: parsed.g,
-    b: parsed.b,
-    a: Math.max(0, Math.min(1, baseAlpha * opacityMultiplier)),
-  };
-}
-
-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 applyRingOverlay(node: FrameNode, ring: RingInfo): boolean {
-  const width = typeof node.width === 'number' ? node.width : 0;
-  const height = typeof node.height === 'number' ? node.height : 0;
-  if (!(width > 0) || !(height > 0)) return false;
-
-  const children = node.children;
-  if (Array.isArray(children) && children.length > 0) {
-    for (let i = children.length - 1; i >= 0; i--) {
-      const child = children[i];
-      if (!child || child.name !== '__inkbridge-ring__') continue;
-      try {
-        child.remove();
-      } catch (_err) {}
-    }
-  }
-
-  const overlay = figma.createFrame();
-  overlay.name = '__inkbridge-ring__';
-  overlay.resize(width + ring.width * 2, height + ring.width * 2);
-  overlay.fills = [];
-  overlay.strokes = [{
-    type: 'SOLID',
-    color: { r: ring.color.r, g: ring.color.g, b: ring.color.b },
-    opacity: ring.color.a == null ? 1 : ring.color.a,
-  }];
-  overlay.strokeWeight = ring.width;
-  try {
-    overlay.strokeAlign = 'INSIDE';
-  } catch (_err) {}
-
-  const nodeRadius = node.cornerRadius;
-  if (typeof nodeRadius === 'number') {
-    overlay.cornerRadius = Math.max(0, nodeRadius + ring.width);
-  } else {
-    const tl = typeof node.topLeftRadius === 'number' ? node.topLeftRadius : null;
-    const tr = typeof node.topRightRadius === 'number' ? node.topRightRadius : null;
-    const br = typeof node.bottomRightRadius === 'number' ? node.bottomRightRadius : null;
-    const bl = typeof node.bottomLeftRadius === 'number' ? node.bottomLeftRadius : null;
-    if (tl != null && tr != null && br != null && bl != null) {
-      overlay.topLeftRadius = Math.max(0, tl + ring.width);
-      overlay.topRightRadius = Math.max(0, tr + ring.width);
-      overlay.bottomRightRadius = Math.max(0, br + ring.width);
-      overlay.bottomLeftRadius = Math.max(0, bl + ring.width);
-    }
-  }
-
-  node.appendChild(overlay);
-  try {
-    overlay.layoutPositioning = 'ABSOLUTE';
-  } catch (_err) {}
-  overlay.x = -ring.width;
-  overlay.y = -ring.width;
-  try {
-    node.clipsContent = false;
-  } catch (_err) {}
-  try {
-    node.insertChild(0, overlay);
-  } catch (_err) {}
-  return true;
-}
-
-function applyRingEffect(node: FrameNode, classes: string[], colorGroup: Record<string, string>): void {
-  const ring = getRingInfoFromClasses(classes, colorGroup);
-  if (!ring) return;
-  if (applyRingOverlay(node, ring)) return;
-  const strokeWeight = typeof node.strokeWeight === 'number' ? node.strokeWeight : 0;
-  node.strokes = [{
-    type: 'SOLID',
-    color: { r: ring.color.r, g: ring.color.g, b: ring.color.b },
-    opacity: ring.color.a == null ? 1 : ring.color.a,
-  }];
-  node.strokeWeight = Math.max(strokeWeight, ring.width);
-  try {
-    node.strokeAlign = 'INSIDE';
-  } catch (_err) {}
-}
-
 export function createCVAComponentSet(parent: FrameNode | PageNode, def: ComponentDef, theme: string): SceneNode | null {
   const colorGroup = getThemeColors(TOKENS, theme);
   const radiusGroup = getThemeRadius(TOKENS, theme);
@@ -303,8 +155,14 @@ export function createCVAComponentSet(parent: FrameNode | PageNode, def: Compone
       }
 
       comp.appendChild(text);
-      applyRingEffect(comp, stateClasses, colorGroup);
+      const ringInfo = getRingInfoFromClasses(stateClasses, colorGroup);
+      if (ringInfo) markRingNode(comp, ringInfo);
       stateRow.appendChild(comp);
+      // Comp's children are in place and it's now in the parent's auto-layout
+      // — apply ring (no-op if not marked). `applyRingIfPossible` locks the
+      // comp's sizing modes during the overlay append so inflation is
+      // impossible.
+      applyRingIfPossible(comp, stateRow);
     }
 
     variantSection.appendChild(stateRow);
@@ -416,9 +274,11 @@ export function createStateComponentSet(parent: FrameNode | PageNode, def: Compo
       fill: { r: placeholderColor.r, g: placeholderColor.g, b: placeholderColor.b }
     });
     comp.appendChild(placeholder);
-    applyRingEffect(comp, stateClasses, colorGroup);
+    const ringInfo = getRingInfoFromClasses(stateClasses, colorGroup);
+    if (ringInfo) markRingNode(comp, ringInfo);
 
     stateRow.appendChild(comp);
+    applyRingIfPossible(comp, stateRow);
   }
 
   container.appendChild(stateRow);

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

@@ -1,7 +1,7 @@
 import { splitClassName, applyTailwindStylesToFrame, tailwindClassesToStyle, type TailwindStyle } from '../tailwind';
 import { parseColor, bindColorVariable } from '../tokens';
 import { createTextNode } from '../text';
-import { applyRingEffect, enforceFixedBoxSizingAfterLayout } from '../layout';
+import { getRingInfoFromClasses, markRingNode, applyRingIfPossible, enforceFixedBoxSizingAfterLayout } from '../layout';
 import { MASTER_ICON_NAME_KEY } from '../components/component-instance';
 import { findChildByName, getFrameHash, setFrameHash, hashString, hashDef } from '../cache';
 import { RENDER_ENGINE_VERSION } from '../render-engine-version';
@@ -359,7 +359,7 @@ export function ensureCvaComponentSet(
         // ignore if plugin runtime rejects the assignment
       }
     } else {
-      // applyTailwindStylesToFrame / applyRingEffect / applyStyleToFrame all
+      // applyTailwindStylesToFrame / markRingNode / applyStyleToFrame all
       // touch the shared frame mixins (fills, strokes, opacity, layout). Cast
       // ComponentNode → FrameNode at the boundary; no `any`.
       const compFrame = comp as unknown as FrameNode;
@@ -386,13 +386,17 @@ export function ensureCvaComponentSet(
         text.textDecoration = 'UNDERLINE';
       }
       comp.appendChild(text);
-      applyRingEffect(compFrame, classes, colorGroup);
+      const ringInfo = getRingInfoFromClasses(classes, colorGroup);
+      if (ringInfo) markRingNode(compFrame, ringInfo);
     }
 
     enforceFixedBoxSizingAfterLayout(comp, classes);
 
     // combineAsVariants expects components to exist in the document tree.
     themeLibrary.appendChild(comp);
+    // Comp is now in the theme library and its sizing has been finalised by
+    // `enforceFixedBoxSizingAfterLayout` — apply the (marked) ring overlay.
+    applyRingIfPossible(comp as unknown as FrameNode, themeLibrary);
     components.push(comp);
   }
 

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

@@ -323,4 +323,12 @@ export async function buildDesignSystemSinglePage(
   // top-level sections.
   removeDuplicateTopLevelSections(ds);
   removeOrphanedTopLevelNodes(ds);
+
+  // Frame the freshly-built page so the user lands on the result instead of
+  // wherever the viewport was before the run. Filter out invisible children
+  // defensively — scrollAndZoomIntoView throws on an empty selection.
+  const visibleChildren = ds.children.filter((node) => node.visible);
+  if (visibleChildren.length > 0) {
+    figma.viewport.scrollAndZoomIntoView(visibleChildren);
+  }
 }

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

@@ -1,7 +1,12 @@
 import { getBaseClass, mergeClasses, parseUtilityClass } from '../tailwind';
 import { parseSquareSizeToken } from '../layout';
 import { getComponentDefByName } from '../components';
-import { isAccordionRootTag, isAccordionItemTag } from './tag-predicates';
+import {
+  isAccordionRootTag,
+  isAccordionItemTag,
+  isSelectItemIndicatorTag,
+  isRadioGroupIndicatorTag,
+} from './tag-predicates';
 import type { NodeIR } from '../tailwind';
 import type { RenderContext } from './render-context';
 
@@ -30,6 +35,15 @@ export function unwrapTransparentWrapper(node: NodeIR): NodeIR {
     if (!current.children || current.children.length !== 1) return current;
     if (current.tagName.toLowerCase().endsWith('trigger')) return current;
     if (getComponentDefByName(current.tagName)) return current;
+    // Context-sensitive indicator wrappers (Select/RadioGroup item indicators)
+    // gate their child's visibility on the parent Item being selected/checked.
+    // The gating check lives in `buildFigmaNode` and only runs when this
+    // function preserves the wrapper — without this guard, the wrapper was
+    // unwrapped to its check/dot icon BEFORE the suppression could fire, and
+    // every non-selected item rendered a stale indicator (the recurring
+    // "checkmarks on every Select item" bug).
+    if (isSelectItemIndicatorTag(current.tagName)) return current;
+    if (isRadioGroupIndicatorTag(current.tagName)) return current;
     current = current.children[0];
   }
   return current;

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

@@ -27,7 +27,7 @@ import {
 } from '../tailwind';
 import { parseColor } from '../tokens';
 import { createTextNode, type CreateTextOptions } from '../text';
-import { applyRingEffect, getRingInfoFromClasses } from '../layout';
+import { getRingInfoFromClasses, markRingNode, applyRingIfPossible } from '../layout';
 import type {
   ComponentDef,
   ComponentStory,
@@ -194,8 +194,6 @@ export function createStatePreviewBlock(
   const label = buildStatePreviewLabel(def, instance);
 
   function createStateCell(stateName: string, classes: string[], columnLabel: string): FrameNode {
-    const ringInfo = getRingInfoFromClasses(classes, colorGroup);
-    const ringPadding = ringInfo && ringInfo.width > 0 ? Math.ceil(ringInfo.width) : 0;
     if (String(def && def.type ? def.type : '').toLowerCase() === 'state') {
       const baseProps = Object.assign({}, props || {});
       const originalExtraClasses = splitClassName(props && props.className);
@@ -256,12 +254,6 @@ export function createStatePreviewBlock(
       cell.fills = [];
       cell.strokes = [];
       ctx.applyClipBehavior(cell, []);
-      if (ringPadding > 0) {
-        cell.paddingTop = ringPadding;
-        cell.paddingRight = ringPadding;
-        cell.paddingBottom = ringPadding;
-        cell.paddingLeft = ringPadding;
-      }
       cell.appendChild(stateNode);
       return cell;
     }
@@ -306,7 +298,8 @@ export function createStatePreviewBlock(
       }
       break; // one sample is enough
     }
-    applyRingEffect(comp, classes, colorGroup);
+    const ringInfo = getRingInfoFromClasses(classes, colorGroup);
+    if (ringInfo) markRingNode(comp, ringInfo);
 
     const cell = figma.createFrame();
     cell.name = def.name + '/' + columnLabel + '/' + stateName + '/Cell';
@@ -318,13 +311,11 @@ export function createStatePreviewBlock(
     cell.fills = [];
     cell.strokes = [];
     ctx.applyClipBehavior(cell, []);
-    if (ringPadding > 0) {
-      cell.paddingTop = ringPadding;
-      cell.paddingRight = ringPadding;
-      cell.paddingBottom = ringPadding;
-      cell.paddingLeft = ringPadding;
-    }
     cell.appendChild(comp);
+    // Comp is now in the cell — its dimensions are final, so we can safely
+    // apply the marked ring overlay. The host-FIXED-toggle inside
+    // applyRingIfPossible ensures appending the overlay can't inflate comp.
+    applyRingIfPossible(comp, cell);
     return cell;
   }
 
@@ -661,11 +652,13 @@ export function createResponsivePreviewBlock(
       const preview = renderStandaloneStory(storyOverride, theme, ctx, viewportWidth);
       if (preview) {
         const colsOverride = treeOverride ? extractRootGridColsFromTree(treeOverride as JsxNode) : null;
-        // Only reflow for actual multi-column grids (cols > 1). A bare `grid` without an
-        // explicit grid-cols-N returns cols=1 from extractRootGridColsFromTree, but that
-        // represents a single-column vertical stack — applying applyGridColumnsWithReflow
-        // for it would incorrectly flip the frame to HORIZONTAL-WRAP and corrupt child layout.
-        if (colsOverride != null && colsOverride > 1 && preview.children.length === 1) {
+        // The `cols > 1` part of the gate now lives in
+        // `applyGridColumnsIfPossible`, so a `cols === 1` forward is a
+        // safe no-op. Keep the `preview.children.length === 1` check —
+        // that's preview-builder-specific (only reflow when the
+        // standalone-story render produced a single root frame to
+        // re-grid).
+        if (colsOverride != null && preview.children.length === 1) {
           const target = preview.children[0];
           if ('layoutMode' in target) {
             const previewPadding = (preview.paddingLeft || 0) + (preview.paddingRight || 0);
@@ -743,27 +736,3 @@ export function shouldRenderStatesForStory(def: ComponentDef, story: ComponentSt
   return storyIndex === 0;
 }
 
-export function shouldRenderResponsiveForStory(def: ComponentDef, story: ComponentStory, storyIndex: number): boolean {
-  const layoutClasses = normalizeLayoutClasses(story && story.layoutClasses);
-  if (hasSignificantResponsiveChanges(layoutClasses)) return true;
-  if (story && story.jsxTree && treeHasResponsiveClasses(story.jsxTree as JsxNode)) 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;
-}

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

@@ -1,5 +1,5 @@
 import { findChildByName, getFrameHash, setFrameHash, hashString, hashDef } from '../cache';
-import { enforceFixedBoxSizingAfterLayout } from '../layout';
+import { enforceFixedBoxSizingAfterLayout, applyRingIfPossible, getRingNode, markRingNode } from '../layout';
 import { splitClassName } from '../tailwind';
 import { RENDER_ENGINE_VERSION } from '../render-engine-version';
 import { tagGeneratedNode } from './generated-node';
@@ -187,6 +187,18 @@ export function ensureStateComponentSet(
       );
       themeLibrary.appendChild(sourceNode);
 
+      // `createStateStoryFrame` → `applyTailwindStylesToFrame` calls
+      // `markRingNode(sourceNode, ringInfo)` for ring classes. We must
+      // capture that ring info BEFORE `createComponentFromNode` — it
+      // creates a NEW node identity, so the `RING_NODES` WeakMap entry
+      // keyed on `sourceNode` is unreachable from the resulting component.
+      // Without this transfer the focus / error variants of state masters
+      // (Input, Textarea) render with no ring overlay — only the host's
+      // 1px border shows. Confirmed 2026-05-17 from a side-by-side
+      // Storybook (correct: 1px border + 3px halo) vs Figma (broken: 1px
+      // border alone) comparison.
+      const ringInfo = getRingNode(sourceNode);
+
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       let component: any = null;
       try {
@@ -200,10 +212,20 @@ export function ensureStateComponentSet(
         continue;
       }
       if (!component) continue;
+      // Transfer the captured ring mark onto the new component identity.
+      if (ringInfo) {
+        markRingNode(component, ringInfo);
+      }
       enforceFixedBoxSizingAfterLayout(
         component,
         splitClassName(stateVariantProps && stateVariantProps.className ? String(stateVariantProps.className) : '')
       );
+      // Now that the component's dimensions are finalised by
+      // `enforceFixedBoxSizingAfterLayout`, build the ring overlay against
+      // those final dimensions. Idempotent: if the comp already has an
+      // `__inkbridge-ring__` child from an earlier pass, it's removed and
+      // recreated at the correct size.
+      applyRingIfPossible(component as unknown as FrameNode, themeLibrary);
 
       const nameParts = [
         toFigmaVariantPropertyName('state') + '=' + toFigmaVariantPropertyValue(stateName),

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

@@ -39,6 +39,7 @@ import {
 import {
   applyAspectRatioIfPossible,
   applyFullWidthIfPossible,
+  applyRingIfPossible,
   applyVerticalFlexGrowIfPossible,
   enforceGrowChildPrimaryFixed,
   extractGridColumns,
@@ -70,7 +71,7 @@ import { getActivePack } from '../plugin';
 import { normalizeLayoutClasses } from './story-layout';
 import { isGeneratedDesignSystemNode, setGeneratedFallbackReason, tagGeneratedNode } from './generated-node';
 import { type StoryBuilderContext, type StoryRenderContext } from './story-builder-context';
-import { createStatePreviewBlock, createResponsivePreviewBlock, shouldRenderStatesForStory, shouldRenderResponsiveForStory } from './preview-builder';
+import { createStatePreviewBlock, createResponsivePreviewBlock, shouldRenderStatesForStory } from './preview-builder';
 import {
   getComponentSectionName,
   groupComponentDefs,
@@ -308,6 +309,45 @@ function populateStoryLayout(
   const useStoryTree = !!effectiveJsxTree
     && !shouldPreferInstanceRendering(def, story)
     && !shouldSkipStoryJsxTree(def, story);
+  // The scanner extracts `story.layoutClasses` from the root JSX node's
+  // className regardless of whether the root is a plain <div> wrapper or a
+  // real component (`<ScrollArea className="rounded-md border bg-background
+  // h-48 w-60 p-3">…`). For div roots the unwrap path below replaces the
+  // wrapper with the bench, so applying the visual classes to the bench
+  // matches the consumer's intent. For component roots the component
+  // renders ITS OWN visual styling — so leaving the same `rounded-md border
+  // bg-background` on the bench paints a phantom rounded rectangle behind
+  // the real component (the symptom: two overlapping bordered boxes, the
+  // bench's padding shifting the component out of register). Reset the
+  // bench's visual styling here when we detect this overlap; the bench's
+  // sizing was already pinned by resolveStoryLayoutWidth via the layout
+  // classes, so the responsive math is unaffected.
+  const rootIsOverpaintingComponent =
+    !!effectiveJsxTree
+    && (effectiveJsxTree as JsxElement).type === 'element'
+    && !!(effectiveJsxTree as JsxElement).isComponent
+    && layoutClasses.length > 0
+    && (() => {
+      const rootClasses = splitClassName(
+        (effectiveJsxTree as JsxElement).props && (effectiveJsxTree as JsxElement).props.className
+      );
+      if (rootClasses.length === 0) return false;
+      const set: Record<string, true> = {};
+      for (const c of rootClasses) set[c] = true;
+      for (const c of layoutClasses) if (!set[c]) return false;
+      return true;
+    })();
+  if (rootIsOverpaintingComponent) {
+    try { layout.fills = []; } catch { /* ignore */ }
+    try { layout.strokes = []; } catch { /* ignore */ }
+    try { layout.cornerRadius = 0; } catch { /* ignore */ }
+    try {
+      layout.paddingLeft = 0;
+      layout.paddingRight = 0;
+      layout.paddingTop = 0;
+      layout.paddingBottom = 0;
+    } catch { /* ignore */ }
+  }
   const layoutPadding = (layout.paddingLeft || 0) + (layout.paddingRight || 0);
   const contentWidth = effectiveWidth ? effectiveWidth - layoutPadding : undefined;
   let added = 0;
@@ -349,6 +389,7 @@ function populateStoryLayout(
             ? { skipFullWidth: skipLayoutFullWidth, widthOverride: contentWidth }
             : undefined;
           applyFullWidthIfPossible(childNode, layout, fullWidthOptions);
+          applyRingIfPossible(childNode, layout);
           applyAspectRatioIfPossible(childNode);
           enforceGrowChildPrimaryFixed(childNode, layout);
           const childRootGridCols = extractRootGridColsFromTree(child);
@@ -387,6 +428,7 @@ function populateStoryLayout(
           ? { skipFullWidth: skipLayoutFullWidth, widthOverride: contentWidth }
           : undefined;
         applyFullWidthIfPossible(childNode, layout, fullWidthOptions);
+        applyRingIfPossible(childNode, layout);
         applyAspectRatioIfPossible(childNode);
         enforceGrowChildPrimaryFixed(childNode, layout);
         rendered = true;
@@ -411,6 +453,7 @@ function populateStoryLayout(
           ? { skipFullWidth: skipLayoutFullWidth, widthOverride: contentWidth }
           : undefined;
         applyFullWidthIfPossible(treeNode, layout, fullWidthOptions);
+        applyRingIfPossible(treeNode, layout);
         applyAspectRatioIfPossible(treeNode);
         enforceGrowChildPrimaryFixed(treeNode, layout);
         const treeRootGridCols = extractRootGridColsFromTree(effectiveJsxTree);
@@ -448,6 +491,10 @@ function populateStoryLayout(
     }
   }
 
+  // `applyGridColumnsIfPossible` guards on `cols <= 1` internally, so
+  // forwarding `layoutGridCols === 1` (the Tailwind default for plain
+  // `grid` with no `grid-cols-N`) is a no-op. The truthiness check
+  // here just avoids a function call when there's no grid at all.
   if (layoutGridCols) {
     ctx.applyGridColumnsWithReflow(layout, effectiveWidth || layout.width, layoutGridCols);
   }
@@ -809,10 +856,13 @@ export async function createUIComponents(parent: FrameNode | PageNode, opts: Cre
         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);
-      }
+      // No pre-flight gate — `createResponsivePreviewBlock` already
+      // returns null when the story has no responsive signals (layout /
+      // tree / instance classes all lack `sm:`/`md:`/`lg:` etc.) or when
+      // the breakpoint set collapses to one, so the gate would have been
+      // a strict subset of the renderer's existing check.
+      const responsiveBlock = createResponsivePreviewBlock(def, story, theme, ctx);
+      if (responsiveBlock) storyWrap.appendChild(responsiveBlock);
       block.appendChild(storyWrap);
     }