stablekit.ts 0.6.3 → 0.6.5

package/dist/eslint.cjs

@@ -23,6 +23,81 @@ __export(eslint_exports, {
   createArchitectureLint: () => createArchitectureLint
 });
 module.exports = __toCommonJS(eslint_exports);
+var noHiddenSwapRule = {
+  meta: {
+    type: "problem",
+    schema: [],
+    messages: {
+      swap: "Sibling elements test the same variable in hidden to swap visibility \u2014 neither reserves space when hidden, causing layout shift. Use <StateSwap> for two states, <StateMap> for inline multi-state, or <LayoutMap> for block-level multi-state."
+    }
+  },
+  create(context) {
+    function getHiddenExpr(node) {
+      if (node.type !== "JSXElement") return null;
+      const attrs = node.openingElement?.attributes ?? [];
+      for (const attr of attrs) {
+        if (attr.type === "JSXAttribute" && attr.name?.name === "hidden" && attr.value?.type === "JSXExpressionContainer" && attr.value.expression?.type !== "Literal") {
+          return attr.value.expression;
+        }
+      }
+      return null;
+    }
+    function unwrapOrUndefined(expr) {
+      if (expr.type === "LogicalExpression" && expr.operator === "||" && expr.right.type === "Identifier" && expr.right.name === "undefined") {
+        return expr.left;
+      }
+      return expr;
+    }
+    function getSubject(rawExpr) {
+      const expr = unwrapOrUndefined(rawExpr);
+      if (expr.type === "Identifier") return expr.name;
+      if (expr.type === "UnaryExpression" && expr.operator === "!" && expr.argument.type === "Identifier") {
+        return expr.argument.name;
+      }
+      if (expr.type === "BinaryExpression" && (expr.operator === "!==" || expr.operator === "===")) {
+        if (expr.left.type === "Identifier") return expr.left.name;
+        if (expr.right.type === "Identifier") return expr.right.name;
+      }
+      if (expr.type === "BinaryExpression" && (expr.operator === "==" || expr.operator === "!=")) {
+        if (expr.left.type === "Identifier") return expr.left.name;
+        if (expr.right.type === "Identifier") return expr.right.name;
+      }
+      return null;
+    }
+    function checkChildren(children) {
+      const entries = [];
+      for (const child of children) {
+        const expr = getHiddenExpr(child);
+        if (expr) {
+          entries.push({ node: child, subject: getSubject(expr) });
+        }
+      }
+      const bySubject = /* @__PURE__ */ new Map();
+      for (const entry of entries) {
+        if (entry.subject) {
+          const group = bySubject.get(entry.subject) ?? [];
+          group.push(entry.node);
+          bySubject.set(entry.subject, group);
+        }
+      }
+      for (const [, group] of bySubject) {
+        if (group.length >= 2) {
+          for (let i = 1; i < group.length; i++) {
+            context.report({ node: group[i], messageId: "swap" });
+          }
+        }
+      }
+    }
+    return {
+      JSXElement(node) {
+        checkChildren(node.children ?? []);
+      },
+      JSXFragment(node) {
+        checkChildren(node.children ?? []);
+      }
+    };
+  }
+};
 function findVariable(scope, name) {
   let current = scope;
   while (current) {
@@ -45,7 +120,7 @@ var noLoadingConflictRule = {
       }
     ],
     messages: {
-      conflict: "Conditional variable as children of a component with a loading prop. The loading prop triggers an internal content swap \u2014 if children also change, both sides shrink simultaneously and pre-allocation is defeated. Use static children with the loading prop, or handle the entire swap explicitly with <StateSwap> in the caller."
+      conflict: "Conditional variable as children of a component with a loading prop (e.g. <Button loading={x}>{label}</Button> where label = x ? 'A' : 'B'). The loading prop triggers an internal content swap \u2014 if children also change, both sides shrink simultaneously and pre-allocation is defeated. Fix: use static children (e.g. 'Submit'), or move the entire swap to the caller with <StateSwap>/<StateMap>."
     }
   },
   create(context) {
@@ -102,135 +177,129 @@ function createArchitectureLint(options) {
         // --- 1. Hardcoded design tokens (universal) ---
         {
           selector: "Literal[value=/text-\\[\\d+/]",
-          message: "Hardcoded font size. Define a named token in @theme."
+          message: "Hardcoded font size in className (e.g. text-[14px]). Add a named size to @theme and use it instead \u2014 hardcoded sizes can't be updated globally."
         },
         {
           selector: "Literal[value=/\\[.*(?:#[0-9a-fA-F]|rgba?).*\\]/]",
-          message: "Hardcoded color value. Define a CSS custom property."
+          message: "Hardcoded color in Tailwind bracket syntax (e.g. bg-[#f00]). Define a CSS custom property in your tokens and reference it \u2014 colors in JS can't be themed or audited."
         },
         {
           selector: "JSXAttribute[name.name='style'] Property > Literal[value=/(?:#[0-9a-fA-F]{3,8}|rgba?\\()/]",
-          message: "Hardcoded color value in style object. Define a CSS custom property."
+          message: "Hardcoded color in style prop. Move this to a CSS custom property \u2014 style={{ color: '#f00' }} can't be themed, overridden by cascade layers, or found by grep."
         },
         {
           selector: "Literal[value=/^#[0-9a-fA-F]{3}([0-9a-fA-F]([0-9a-fA-F]{2}([0-9a-fA-F]{2})?)?)?$/]",
-          message: "Hardcoded hex color. Define a CSS custom property."
+          message: "Hardcoded hex color (e.g. '#5865F2'). Define a CSS custom property and reference it \u2014 colors in JS bypass the cascade and can't be themed."
         },
         {
           selector: "Literal[value=/(?:^|[^a-zA-Z])(?:rgba?|hsla?|oklch|lab|lch)\\(/]",
-          message: "Hardcoded color function. Define a CSS custom property."
+          message: "Hardcoded color function (e.g. rgba(), hsl()). Define a CSS custom property and reference it \u2014 color functions in JS bypass the cascade and can't be themed."
         },
         // --- 1b. Color properties in style props ---
         {
           selector: "JSXAttribute[name.name='style'] Property[key.name=/^(color|backgroundColor|background|borderColor|outlineColor|fill|stroke|accentColor|caretColor)$/]",
-          message: "Visual color property in style prop. Use a data-attribute and CSS selector."
+          message: "Color property in style prop (e.g. style={{ backgroundColor: x }}). CSS owns color \u2014 use a className or data-attribute with a CSS rule instead. If the color is data-driven, set a data-attribute and handle it in your exceptions CSS."
         },
         // --- 1c. Visual state properties in style props ---
         {
           selector: "JSXAttribute[name.name='style'] Property[key.name=/^(opacity|visibility|transition|pointerEvents)$/]",
-          message: "Visual state property in style prop. Use a data-attribute and CSS selector."
+          message: "Visual state property in style prop (e.g. style={{ opacity }}). These are presentation concerns \u2014 use a data-attribute and CSS selector so the visual logic lives in CSS, not JS."
         },
         // --- 1d. Hardcoded magic numbers ---
         {
           selector: "Literal[value=/z-\\[\\d/]",
-          message: "Hardcoded z-index. Define a named z-index token in @theme."
+          message: "Hardcoded z-index (e.g. z-[999]). Define a named z-index token in @theme (e.g. --z-dropdown, --z-modal) \u2014 magic z-indices create stacking conflicts that are impossible to debug."
         },
         {
           selector: "Literal[value=/-m\\w?-\\[|m\\w?-\\[-/]",
-          message: "Negative margin with magic number. This usually fights the layout \u2014 fix the spacing structure instead."
+          message: "Negative margin with magic number (e.g. -mt-[8px]). Negative margins fight the layout \u2014 fix the spacing structure (padding, gap) instead of compensating with negative offsets."
         },
         {
           selector: "Literal[value=/(?:min-|max-)?(?:w|h)-\\[\\d+px\\]/]",
-          message: "Hardcoded pixel dimension. Define a named size token in @theme or use a relative unit."
+          message: "Hardcoded pixel dimension (e.g. w-[347px]). Define a named size token in @theme or use a relative unit \u2014 pixel dimensions break at different viewport sizes and can't be updated globally."
         },
         {
           selector: "Literal[value=/\\w-\\[(?!calc).*?\\d+(?![\\d%]|[dsl]?v[hw]|fr)/]",
-          message: "Hardcoded magic number in arbitrary value. Define a named token in @theme or use a standard utility."
+          message: "Hardcoded magic number in arbitrary value (e.g. rounded-[3px], gap-[12px]). Define a named token in @theme \u2014 magic numbers scattered across components can't be updated globally."
         },
         // --- 2. Data-dependent visual decisions (project-specific) ---
         ...tokenPattern ? [
           {
             selector: `Literal[value=/\\b(bg|text|border)-(${tokenPattern})/]`,
-            message: "Data-dependent visual property. Use a data-attribute and CSS selector."
+            message: "State color token in className (e.g. bg-success, text-warning). State-driven colors belong in CSS \u2014 set a data-attribute (data-status, data-variant) on the element and write a CSS selector that maps the attribute to the color."
           }
         ] : [],
         {
           selector: "JSXAttribute[name.name='style'] ConditionalExpression",
-          message: "Conditional style object. Use a data-state attribute and CSS selector."
+          message: "Conditional style prop (e.g. style={x ? {...} : {...}}). JS is deciding what the component looks like \u2014 set a data-attribute and let CSS handle the visual change."
         },
         {
           selector: "JSXAttribute[name.name='className'] ConditionalExpression",
-          message: "Conditional className. Use a data-attribute and CSS selector instead of switching classes with a ternary."
+          message: "Ternary in className (e.g. className={x ? 'a' : 'b'}). JS is picking the visual treatment \u2014 set a data-attribute and write CSS selectors for each state instead."
         },
         {
           selector: "JSXAttribute[name.name='className'] LogicalExpression[operator='&&']",
-          message: "Conditional className. Use a data-attribute and CSS selector instead of conditionally applying classes."
+          message: "Conditional className (e.g. isActive && 'bold'). JS is toggling visual properties \u2014 set a data-attribute and write a CSS selector instead."
         },
         {
           selector: "JSXAttribute[name.name='className'] ObjectExpression",
-          message: "Conditional className via object syntax. Use a data-attribute and CSS selector instead of cx/cn({ class: condition })."
+          message: "Object syntax in className (e.g. cx({ 'text-red': isError })). This is conditional visual logic in JS \u2014 set a data-attribute and write CSS selectors instead."
         },
         // --- 2c. !important in className ---
         {
           selector: "JSXAttribute[name.name='className'] Literal[value=/(?:^|\\s)![a-z]/]",
-          message: "Tailwind !important modifier in className. !important breaks the cascade \u2014 use specificity or data-attributes."
+          message: "!important modifier in className (e.g. !font-bold). !important breaks cascade layers and makes overrides unpredictable \u2014 use a more specific selector or data-attribute instead."
         },
         // --- 2d. Tailwind color utilities in className ---
         ...banColorUtilities ? [
           {
             selector: `Literal[value=/(?:^|\\s)(?:${twPrefixes})-(?:${twColors})(?:-\\d+)?(?:\\/\\d+)?(?:\\s|$)/]`,
-            message: "Tailwind color utility in className. Colors belong in CSS \u2014 use a CSS class with a custom property or data-attribute selector."
+            message: "Tailwind palette color in className (e.g. bg-red-500, text-green-600). Colors belong in CSS \u2014 use a semantic CSS class or data-attribute selector. If you put colors in JSX, changing a color requires editing every component that uses it."
           }
         ] : [],
         // --- 3. Ternaries on variant props (from createPrimitive) ---
         ...variantProps.map((prop) => ({
           selector: `JSXAttribute[name.name='${prop}'] ConditionalExpression`,
-          message: `Data-dependent ${prop}. Use a data-attribute and CSS selector instead of switching ${prop} with a ternary.`
+          message: `Ternary on ${prop} prop (e.g. ${prop}={x ? 'a' : 'b'}). This component uses createPrimitive \u2014 set a data-attribute and let CSS map data to visual treatment instead of switching ${prop} in JS.`
         })),
         // --- 4. Geometric instability (conditional content) ---
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > ConditionalExpression",
-          message: "Conditional content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT replace with the hidden attribute. For state-driven swaps, use <StateSwap> for text, <StateMap> for keyed views, or <LoadingBoundary> for async states."
+          message: "Ternary in JSX children (e.g. {x ? <A/> : <B/>}). This causes layout shift \u2014 the container resizes when the content swaps. Quick fix: extract to a const above the return. Proper fix: <StateSwap> for two states, <StateMap> for inline multi-state, <LayoutMap> for block-level multi-state, or <LoadingBoundary> for async data."
         },
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='&&']",
-          message: "Conditional mount in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT use the hidden attribute \u2014 it renders children unconditionally and will crash on null data. For state-driven mounts, use <FadeTransition> for enter/exit, <StableField> for form errors, or <LayoutGroup> for pre-rendered views."
+          message: "Conditional mount in JSX children (e.g. {show && <Panel/>}). When this mounts/unmounts, the container resizes. Quick fix: extract to a const above the return. Proper fix: <FadeTransition> for enter/exit animation, <StableField> for form error messages, or <LayoutGroup>/<LayoutMap> for pre-rendered views. Do NOT replace with hidden \u2014 it renders children unconditionally and will crash on null data."
         },
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='||']",
-          message: "Fallback content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven fallbacks, use <StateSwap> to pre-allocate space for both states."
+          message: "Fallback content in JSX children (e.g. {name || 'Unknown'}). When the value changes length, the container resizes. Quick fix: extract to a const above the return. Proper fix: <StateSwap> to pre-allocate space for both states."
         },
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='??']",
-          message: "Nullish fallback in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven fallbacks, use <StateSwap> to pre-allocate space for both states."
+          message: "Nullish fallback in JSX children (e.g. {title ?? 'Loading...'}). When the value arrives, the container resizes. Quick fix: extract to a const above the return. Proper fix: <StateSwap> to pre-allocate space for both states, or <LoadingBoundary> if waiting for async data."
         },
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > TemplateLiteral",
-          message: "Interpolated text in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven values, use <StableCounter> for numbers or <StateSwap> for text variants."
-        },
-        // --- 4b. Sibling hidden swap (geometric instability) ---
-        // Two sibling elements both using conditional hidden to swap
-        // visibility — neither reserves space for the other.
-        // A single hidden={condition} (e.g. error message at bottom of
-        // layout) is fine and intentionally not flagged.
-        {
-          selector: "JSXElement:has(JSXOpeningElement JSXAttribute[name.name='hidden'] > JSXExpressionContainer > :not(Literal)) ~ JSXElement:has(JSXOpeningElement JSXAttribute[name.name='hidden'] > JSXExpressionContainer > :not(Literal))",
-          message: "Sibling elements swap visibility with conditional hidden \u2014 neither reserves space for the other, causing layout shift. Use <StateSwap> for two states or <LayoutMap> for multiple states."
+          message: "Interpolated text in JSX children (e.g. {`${count} items`}). When the value changes (especially digit count), the container resizes. Quick fix: extract to a const above the return. Proper fix: <StableCounter> for numbers that change digit count, or <StateSwap> for text that changes between known variants."
         },
+        // --- 4b removed: sibling hidden swap is now a custom rule ---
         // --- 5. className on firewalled components ---
         ...classNameBlocked.length ? [
           {
             selector: `JSXOpeningElement[name.name=/^(${classNameBlocked.join("|")})$/] > JSXAttribute[name.name='className']`,
-            message: "className on a firewalled component. This component owns its own styling \u2014 use a data-attribute, variant prop, or CSS class internally instead of passing Tailwind utilities from the consumer."
+            message: "className passed to a firewalled component (built with createPrimitive). This component owns its styling \u2014 pass a data-attribute or variant prop instead. The component maps those to visuals internally via CSS."
           }
         ] : []
       ],
-      "stablekit/no-loading-conflict": ["error", { passthrough: loadingPassthrough }]
+      "stablekit/no-loading-conflict": ["error", { passthrough: loadingPassthrough }],
+      "stablekit/no-hidden-swap": "error"
     },
     plugins: {
       stablekit: {
         rules: {
-          "no-loading-conflict": noLoadingConflictRule
+          "no-loading-conflict": noLoadingConflictRule,
+          "no-hidden-swap": noHiddenSwapRule
         }
       }
     }

package/dist/eslint.d.cts

@@ -74,11 +74,13 @@ declare function createArchitectureLint(options: ArchitectureLintOptions): {
         "stablekit/no-loading-conflict": (string | {
             passthrough: string[];
         })[];
+        "stablekit/no-hidden-swap": string;
     };
     plugins: {
         stablekit: {
             rules: {
                 "no-loading-conflict": any;
+                "no-hidden-swap": any;
             };
         };
     };

package/dist/eslint.d.ts

@@ -74,11 +74,13 @@ declare function createArchitectureLint(options: ArchitectureLintOptions): {
         "stablekit/no-loading-conflict": (string | {
             passthrough: string[];
         })[];
+        "stablekit/no-hidden-swap": string;
     };
     plugins: {
         stablekit: {
             rules: {
                 "no-loading-conflict": any;
+                "no-hidden-swap": any;
             };
         };
     };

package/dist/eslint.js

@@ -1,6 +1,81 @@
 import "./chunk-MCKGQKYU.js";
 
 // src/eslint.ts
+var noHiddenSwapRule = {
+  meta: {
+    type: "problem",
+    schema: [],
+    messages: {
+      swap: "Sibling elements test the same variable in hidden to swap visibility \u2014 neither reserves space when hidden, causing layout shift. Use <StateSwap> for two states, <StateMap> for inline multi-state, or <LayoutMap> for block-level multi-state."
+    }
+  },
+  create(context) {
+    function getHiddenExpr(node) {
+      if (node.type !== "JSXElement") return null;
+      const attrs = node.openingElement?.attributes ?? [];
+      for (const attr of attrs) {
+        if (attr.type === "JSXAttribute" && attr.name?.name === "hidden" && attr.value?.type === "JSXExpressionContainer" && attr.value.expression?.type !== "Literal") {
+          return attr.value.expression;
+        }
+      }
+      return null;
+    }
+    function unwrapOrUndefined(expr) {
+      if (expr.type === "LogicalExpression" && expr.operator === "||" && expr.right.type === "Identifier" && expr.right.name === "undefined") {
+        return expr.left;
+      }
+      return expr;
+    }
+    function getSubject(rawExpr) {
+      const expr = unwrapOrUndefined(rawExpr);
+      if (expr.type === "Identifier") return expr.name;
+      if (expr.type === "UnaryExpression" && expr.operator === "!" && expr.argument.type === "Identifier") {
+        return expr.argument.name;
+      }
+      if (expr.type === "BinaryExpression" && (expr.operator === "!==" || expr.operator === "===")) {
+        if (expr.left.type === "Identifier") return expr.left.name;
+        if (expr.right.type === "Identifier") return expr.right.name;
+      }
+      if (expr.type === "BinaryExpression" && (expr.operator === "==" || expr.operator === "!=")) {
+        if (expr.left.type === "Identifier") return expr.left.name;
+        if (expr.right.type === "Identifier") return expr.right.name;
+      }
+      return null;
+    }
+    function checkChildren(children) {
+      const entries = [];
+      for (const child of children) {
+        const expr = getHiddenExpr(child);
+        if (expr) {
+          entries.push({ node: child, subject: getSubject(expr) });
+        }
+      }
+      const bySubject = /* @__PURE__ */ new Map();
+      for (const entry of entries) {
+        if (entry.subject) {
+          const group = bySubject.get(entry.subject) ?? [];
+          group.push(entry.node);
+          bySubject.set(entry.subject, group);
+        }
+      }
+      for (const [, group] of bySubject) {
+        if (group.length >= 2) {
+          for (let i = 1; i < group.length; i++) {
+            context.report({ node: group[i], messageId: "swap" });
+          }
+        }
+      }
+    }
+    return {
+      JSXElement(node) {
+        checkChildren(node.children ?? []);
+      },
+      JSXFragment(node) {
+        checkChildren(node.children ?? []);
+      }
+    };
+  }
+};
 function findVariable(scope, name) {
   let current = scope;
   while (current) {
@@ -23,7 +98,7 @@ var noLoadingConflictRule = {
       }
     ],
     messages: {
-      conflict: "Conditional variable as children of a component with a loading prop. The loading prop triggers an internal content swap \u2014 if children also change, both sides shrink simultaneously and pre-allocation is defeated. Use static children with the loading prop, or handle the entire swap explicitly with <StateSwap> in the caller."
+      conflict: "Conditional variable as children of a component with a loading prop (e.g. <Button loading={x}>{label}</Button> where label = x ? 'A' : 'B'). The loading prop triggers an internal content swap \u2014 if children also change, both sides shrink simultaneously and pre-allocation is defeated. Fix: use static children (e.g. 'Submit'), or move the entire swap to the caller with <StateSwap>/<StateMap>."
     }
   },
   create(context) {
@@ -80,135 +155,129 @@ function createArchitectureLint(options) {
         // --- 1. Hardcoded design tokens (universal) ---
         {
           selector: "Literal[value=/text-\\[\\d+/]",
-          message: "Hardcoded font size. Define a named token in @theme."
+          message: "Hardcoded font size in className (e.g. text-[14px]). Add a named size to @theme and use it instead \u2014 hardcoded sizes can't be updated globally."
         },
         {
           selector: "Literal[value=/\\[.*(?:#[0-9a-fA-F]|rgba?).*\\]/]",
-          message: "Hardcoded color value. Define a CSS custom property."
+          message: "Hardcoded color in Tailwind bracket syntax (e.g. bg-[#f00]). Define a CSS custom property in your tokens and reference it \u2014 colors in JS can't be themed or audited."
         },
         {
           selector: "JSXAttribute[name.name='style'] Property > Literal[value=/(?:#[0-9a-fA-F]{3,8}|rgba?\\()/]",
-          message: "Hardcoded color value in style object. Define a CSS custom property."
+          message: "Hardcoded color in style prop. Move this to a CSS custom property \u2014 style={{ color: '#f00' }} can't be themed, overridden by cascade layers, or found by grep."
         },
         {
           selector: "Literal[value=/^#[0-9a-fA-F]{3}([0-9a-fA-F]([0-9a-fA-F]{2}([0-9a-fA-F]{2})?)?)?$/]",
-          message: "Hardcoded hex color. Define a CSS custom property."
+          message: "Hardcoded hex color (e.g. '#5865F2'). Define a CSS custom property and reference it \u2014 colors in JS bypass the cascade and can't be themed."
         },
         {
           selector: "Literal[value=/(?:^|[^a-zA-Z])(?:rgba?|hsla?|oklch|lab|lch)\\(/]",
-          message: "Hardcoded color function. Define a CSS custom property."
+          message: "Hardcoded color function (e.g. rgba(), hsl()). Define a CSS custom property and reference it \u2014 color functions in JS bypass the cascade and can't be themed."
         },
         // --- 1b. Color properties in style props ---
         {
           selector: "JSXAttribute[name.name='style'] Property[key.name=/^(color|backgroundColor|background|borderColor|outlineColor|fill|stroke|accentColor|caretColor)$/]",
-          message: "Visual color property in style prop. Use a data-attribute and CSS selector."
+          message: "Color property in style prop (e.g. style={{ backgroundColor: x }}). CSS owns color \u2014 use a className or data-attribute with a CSS rule instead. If the color is data-driven, set a data-attribute and handle it in your exceptions CSS."
         },
         // --- 1c. Visual state properties in style props ---
         {
           selector: "JSXAttribute[name.name='style'] Property[key.name=/^(opacity|visibility|transition|pointerEvents)$/]",
-          message: "Visual state property in style prop. Use a data-attribute and CSS selector."
+          message: "Visual state property in style prop (e.g. style={{ opacity }}). These are presentation concerns \u2014 use a data-attribute and CSS selector so the visual logic lives in CSS, not JS."
         },
         // --- 1d. Hardcoded magic numbers ---
         {
           selector: "Literal[value=/z-\\[\\d/]",
-          message: "Hardcoded z-index. Define a named z-index token in @theme."
+          message: "Hardcoded z-index (e.g. z-[999]). Define a named z-index token in @theme (e.g. --z-dropdown, --z-modal) \u2014 magic z-indices create stacking conflicts that are impossible to debug."
         },
         {
           selector: "Literal[value=/-m\\w?-\\[|m\\w?-\\[-/]",
-          message: "Negative margin with magic number. This usually fights the layout \u2014 fix the spacing structure instead."
+          message: "Negative margin with magic number (e.g. -mt-[8px]). Negative margins fight the layout \u2014 fix the spacing structure (padding, gap) instead of compensating with negative offsets."
         },
         {
           selector: "Literal[value=/(?:min-|max-)?(?:w|h)-\\[\\d+px\\]/]",
-          message: "Hardcoded pixel dimension. Define a named size token in @theme or use a relative unit."
+          message: "Hardcoded pixel dimension (e.g. w-[347px]). Define a named size token in @theme or use a relative unit \u2014 pixel dimensions break at different viewport sizes and can't be updated globally."
         },
         {
           selector: "Literal[value=/\\w-\\[(?!calc).*?\\d+(?![\\d%]|[dsl]?v[hw]|fr)/]",
-          message: "Hardcoded magic number in arbitrary value. Define a named token in @theme or use a standard utility."
+          message: "Hardcoded magic number in arbitrary value (e.g. rounded-[3px], gap-[12px]). Define a named token in @theme \u2014 magic numbers scattered across components can't be updated globally."
         },
         // --- 2. Data-dependent visual decisions (project-specific) ---
         ...tokenPattern ? [
           {
             selector: `Literal[value=/\\b(bg|text|border)-(${tokenPattern})/]`,
-            message: "Data-dependent visual property. Use a data-attribute and CSS selector."
+            message: "State color token in className (e.g. bg-success, text-warning). State-driven colors belong in CSS \u2014 set a data-attribute (data-status, data-variant) on the element and write a CSS selector that maps the attribute to the color."
           }
         ] : [],
         {
           selector: "JSXAttribute[name.name='style'] ConditionalExpression",
-          message: "Conditional style object. Use a data-state attribute and CSS selector."
+          message: "Conditional style prop (e.g. style={x ? {...} : {...}}). JS is deciding what the component looks like \u2014 set a data-attribute and let CSS handle the visual change."
         },
         {
           selector: "JSXAttribute[name.name='className'] ConditionalExpression",
-          message: "Conditional className. Use a data-attribute and CSS selector instead of switching classes with a ternary."
+          message: "Ternary in className (e.g. className={x ? 'a' : 'b'}). JS is picking the visual treatment \u2014 set a data-attribute and write CSS selectors for each state instead."
         },
         {
           selector: "JSXAttribute[name.name='className'] LogicalExpression[operator='&&']",
-          message: "Conditional className. Use a data-attribute and CSS selector instead of conditionally applying classes."
+          message: "Conditional className (e.g. isActive && 'bold'). JS is toggling visual properties \u2014 set a data-attribute and write a CSS selector instead."
         },
         {
           selector: "JSXAttribute[name.name='className'] ObjectExpression",
-          message: "Conditional className via object syntax. Use a data-attribute and CSS selector instead of cx/cn({ class: condition })."
+          message: "Object syntax in className (e.g. cx({ 'text-red': isError })). This is conditional visual logic in JS \u2014 set a data-attribute and write CSS selectors instead."
         },
         // --- 2c. !important in className ---
         {
           selector: "JSXAttribute[name.name='className'] Literal[value=/(?:^|\\s)![a-z]/]",
-          message: "Tailwind !important modifier in className. !important breaks the cascade \u2014 use specificity or data-attributes."
+          message: "!important modifier in className (e.g. !font-bold). !important breaks cascade layers and makes overrides unpredictable \u2014 use a more specific selector or data-attribute instead."
         },
         // --- 2d. Tailwind color utilities in className ---
         ...banColorUtilities ? [
           {
             selector: `Literal[value=/(?:^|\\s)(?:${twPrefixes})-(?:${twColors})(?:-\\d+)?(?:\\/\\d+)?(?:\\s|$)/]`,
-            message: "Tailwind color utility in className. Colors belong in CSS \u2014 use a CSS class with a custom property or data-attribute selector."
+            message: "Tailwind palette color in className (e.g. bg-red-500, text-green-600). Colors belong in CSS \u2014 use a semantic CSS class or data-attribute selector. If you put colors in JSX, changing a color requires editing every component that uses it."
           }
         ] : [],
         // --- 3. Ternaries on variant props (from createPrimitive) ---
         ...variantProps.map((prop) => ({
           selector: `JSXAttribute[name.name='${prop}'] ConditionalExpression`,
-          message: `Data-dependent ${prop}. Use a data-attribute and CSS selector instead of switching ${prop} with a ternary.`
+          message: `Ternary on ${prop} prop (e.g. ${prop}={x ? 'a' : 'b'}). This component uses createPrimitive \u2014 set a data-attribute and let CSS map data to visual treatment instead of switching ${prop} in JS.`
         })),
         // --- 4. Geometric instability (conditional content) ---
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > ConditionalExpression",
-          message: "Conditional content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT replace with the hidden attribute. For state-driven swaps, use <StateSwap> for text, <StateMap> for keyed views, or <LoadingBoundary> for async states."
+          message: "Ternary in JSX children (e.g. {x ? <A/> : <B/>}). This causes layout shift \u2014 the container resizes when the content swaps. Quick fix: extract to a const above the return. Proper fix: <StateSwap> for two states, <StateMap> for inline multi-state, <LayoutMap> for block-level multi-state, or <LoadingBoundary> for async data."
         },
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='&&']",
-          message: "Conditional mount in JSX children. Extract to a const above the return (the linter won't flag a plain variable). Do NOT use the hidden attribute \u2014 it renders children unconditionally and will crash on null data. For state-driven mounts, use <FadeTransition> for enter/exit, <StableField> for form errors, or <LayoutGroup> for pre-rendered views."
+          message: "Conditional mount in JSX children (e.g. {show && <Panel/>}). When this mounts/unmounts, the container resizes. Quick fix: extract to a const above the return. Proper fix: <FadeTransition> for enter/exit animation, <StableField> for form error messages, or <LayoutGroup>/<LayoutMap> for pre-rendered views. Do NOT replace with hidden \u2014 it renders children unconditionally and will crash on null data."
         },
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='||']",
-          message: "Fallback content in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven fallbacks, use <StateSwap> to pre-allocate space for both states."
+          message: "Fallback content in JSX children (e.g. {name || 'Unknown'}). When the value changes length, the container resizes. Quick fix: extract to a const above the return. Proper fix: <StateSwap> to pre-allocate space for both states."
         },
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='??']",
-          message: "Nullish fallback in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven fallbacks, use <StateSwap> to pre-allocate space for both states."
+          message: "Nullish fallback in JSX children (e.g. {title ?? 'Loading...'}). When the value arrives, the container resizes. Quick fix: extract to a const above the return. Proper fix: <StateSwap> to pre-allocate space for both states, or <LoadingBoundary> if waiting for async data."
         },
         {
           selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > TemplateLiteral",
-          message: "Interpolated text in JSX children. Extract to a const above the return (the linter won't flag a plain variable). For state-driven values, use <StableCounter> for numbers or <StateSwap> for text variants."
-        },
-        // --- 4b. Sibling hidden swap (geometric instability) ---
-        // Two sibling elements both using conditional hidden to swap
-        // visibility — neither reserves space for the other.
-        // A single hidden={condition} (e.g. error message at bottom of
-        // layout) is fine and intentionally not flagged.
-        {
-          selector: "JSXElement:has(JSXOpeningElement JSXAttribute[name.name='hidden'] > JSXExpressionContainer > :not(Literal)) ~ JSXElement:has(JSXOpeningElement JSXAttribute[name.name='hidden'] > JSXExpressionContainer > :not(Literal))",
-          message: "Sibling elements swap visibility with conditional hidden \u2014 neither reserves space for the other, causing layout shift. Use <StateSwap> for two states or <LayoutMap> for multiple states."
+          message: "Interpolated text in JSX children (e.g. {`${count} items`}). When the value changes (especially digit count), the container resizes. Quick fix: extract to a const above the return. Proper fix: <StableCounter> for numbers that change digit count, or <StateSwap> for text that changes between known variants."
         },
+        // --- 4b removed: sibling hidden swap is now a custom rule ---
         // --- 5. className on firewalled components ---
         ...classNameBlocked.length ? [
           {
             selector: `JSXOpeningElement[name.name=/^(${classNameBlocked.join("|")})$/] > JSXAttribute[name.name='className']`,
-            message: "className on a firewalled component. This component owns its own styling \u2014 use a data-attribute, variant prop, or CSS class internally instead of passing Tailwind utilities from the consumer."
+            message: "className passed to a firewalled component (built with createPrimitive). This component owns its styling \u2014 pass a data-attribute or variant prop instead. The component maps those to visuals internally via CSS."
           }
         ] : []
       ],
-      "stablekit/no-loading-conflict": ["error", { passthrough: loadingPassthrough }]
+      "stablekit/no-loading-conflict": ["error", { passthrough: loadingPassthrough }],
+      "stablekit/no-hidden-swap": "error"
     },
     plugins: {
       stablekit: {
         rules: {
-          "no-loading-conflict": noLoadingConflictRule
+          "no-loading-conflict": noLoadingConflictRule,
+          "no-hidden-swap": noHiddenSwapRule
         }
       }
     }

package/dist/index.cjs

@@ -44,7 +44,7 @@ module.exports = __toCommonJS(index_exports);
 var import_react = require("react");
 
 // src/styles.css
-var styles_default = '/* stablekit \u2014 layout stability toolkit for React\n *\n * CSS class prefix: sk-\n * All animations use CSS custom properties for themability.\n * Styles are auto-injected at import time (opt-out via meta tag).\n */\n\n/* \u2500\u2500 LayoutGroup / LayoutView \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* All children overlap in the same grid cell.\n   Grid auto-sizes to the largest child.\n   Views use flex-column so their content stretches to fill\n   the reserved width \u2014 the visual footprint is constant.\n   Inline groups (StateSwap) use inline-grid for inline contexts. */\n.sk-layout-group {\n  display: grid;\n}\n.sk-layout-group[data-inline] {\n  display: inline-grid;\n}\n.sk-layout-group > * {\n  grid-area: 1 / 1;\n  display: flex;\n  flex-direction: column;\n}\n.sk-layout-group[data-inline] > * {\n  display: inline-flex;\n  flex-direction: row;\n  align-items: center;\n}\n.sk-layout-group[data-inline] > * > * {\n  width: 100%;\n}\n\n/* Inactive LayoutView hiding \u2014 CSS-driven via data-state attribute.\n   LayoutView sets data-state="active"|"inactive" so consumers can\n   override transitions on .sk-layout-view without specificity fights.\n   [inert] handles accessibility (non-focusable, non-interactive). */\n.sk-layout-view[data-state="inactive"] {\n  opacity: 0;\n  visibility: hidden;\n}\n\n/* \u2500\u2500 SizeRatchet \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* contain isolates internal reflow from ancestors. */\n.sk-size-ratchet {\n  contain: layout style;\n}\n\n/* \u2500\u2500 Shimmer / Skeleton \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n.sk-skeleton-grid {\n  display: grid;\n  gap: var(--sk-skeleton-gap, 0.75rem);\n  contain: layout style;\n}\n\n.sk-skeleton-bone {\n  display: flex;\n  flex-direction: column;\n  gap: var(--sk-skeleton-bone-gap, 0.125rem);\n  padding: var(--sk-skeleton-bone-padding, 0.375rem 0.5rem);\n}\n\n.sk-shimmer-line {\n  height: 1lh;\n  border-radius: var(--sk-shimmer-radius, 0.125rem);\n  background: linear-gradient(\n    90deg,\n    var(--sk-shimmer-color, #e5e7eb) 25%,\n    var(--sk-shimmer-highlight, #f3f4f6) 50%,\n    var(--sk-shimmer-color, #e5e7eb) 75%\n  );\n  background-size: 200% 100%;\n  animation: sk-shimmer var(--sk-shimmer-duration, 1.5s) ease-in-out infinite;\n}\n\n/* Inert ghost inside a shimmer-line \u2014 sizes the shimmer to match\n   content width exactly. Invisible and non-interactive via [inert]. */\n.sk-shimmer-line > [inert] {\n  visibility: hidden;\n}\n\n@keyframes sk-shimmer {\n  0% { background-position: 200% 0; }\n  100% { background-position: -200% 0; }\n}\n\n/* \u2500\u2500 MediaSkeleton \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Loading-aware media container.\n   Reserves space via aspect-ratio (set inline by the component).\n   Child constraints enforced via React.cloneElement inline styles. */\n.sk-media {\n  overflow: hidden;\n}\n.sk-media-shimmer {\n  position: absolute;\n  inset: 0;\n  border-radius: var(--sk-shimmer-radius, 0.125rem);\n  background: linear-gradient(\n    90deg,\n    var(--sk-shimmer-color, #e5e7eb) 25%,\n    var(--sk-shimmer-highlight, #f3f4f6) 50%,\n    var(--sk-shimmer-color, #e5e7eb) 75%\n  );\n  background-size: 200% 100%;\n  animation: sk-shimmer var(--sk-shimmer-duration, 1.5s) ease-in-out infinite;\n  transition: opacity var(--sk-loading-exit-duration, 400ms) var(--sk-ease-decelerate);\n}\n\n/* \u2500\u2500 Shared easing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Decelerate: fast start, gentle finish \u2014 for elements entering view. */\n/* Standard: balanced ease \u2014 for general-purpose transitions. */\n/* Accelerate: gentle start, fast finish \u2014 for elements leaving view. */\n:root {\n  --sk-ease-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1.0);\n  --sk-ease-standard: cubic-bezier(0.4, 0, 0.2, 1);\n  --sk-ease-accelerate: cubic-bezier(0.4, 0, 1, 1);\n}\n\n/* \u2500\u2500 FadeTransition \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n.sk-fade {\n  --sk-fade-duration: 400ms;\n}\n\n.sk-fade-entering {\n  animation: sk-emerge var(--sk-fade-duration) var(--sk-ease-decelerate) forwards;\n}\n\n.sk-fade-exiting {\n  animation: sk-collapse var(--sk-fade-duration) var(--sk-ease-accelerate) forwards;\n}\n\n@keyframes sk-emerge {\n  from {\n    opacity: 0;\n    transform: translateY(var(--sk-fade-offset-y, -12px)) scale(var(--sk-fade-offset-scale, 0.98));\n  }\n  to {\n    opacity: 1;\n    transform: translateY(0) scale(1);\n  }\n}\n\n@keyframes sk-collapse {\n  from { opacity: 1; transform: scaleY(1); transform-origin: top; }\n  to   { opacity: 0; transform: scaleY(0); transform-origin: top; }\n}\n\n/* \u2500\u2500 Loading layers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Shared by shimmer and content layers inside skeleton components.\n   Both layers permanently occupy the same grid cell; only opacity\n   and interactivity change. CSS transitions handle the crossfade. */\n.sk-loading-layer {\n  grid-area: 1 / 1;\n  transition: opacity var(--sk-loading-exit-duration, 400ms) var(--sk-ease-decelerate);\n}\n\n/* \u2500\u2500 Reduced motion \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Disables all animations \u2014 shimmer, fade, and loading exit.\n   Layout changes still happen instantly so functionality is preserved. */\n@media (prefers-reduced-motion: reduce) {\n  .sk-fade-entering,\n  .sk-fade-exiting,\n  .sk-shimmer-line,\n  .sk-media-shimmer {\n    animation-duration: 0s !important;\n  }\n  .sk-loading-layer,\n  .sk-media-shimmer {\n    transition-duration: 0s !important;\n  }\n}\n';
+var styles_default = '/* stablekit \u2014 layout stability toolkit for React\n *\n * CSS class prefix: sk-\n * All animations use CSS custom properties for themability.\n * Styles are auto-injected at import time (opt-out via meta tag).\n */\n\n/* \u2500\u2500 LayoutGroup / LayoutView \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* All children overlap in the same grid cell.\n   Grid auto-sizes to the largest child.\n   Views use flex-column so their content stretches to fill\n   the reserved width \u2014 the visual footprint is constant.\n   Inline groups (StateSwap) use inline-grid for inline contexts. */\n.sk-layout-group {\n  display: grid;\n}\n.sk-layout-group[data-inline] {\n  display: inline-grid;\n}\n.sk-layout-group > * {\n  grid-area: 1 / 1;\n  display: flex;\n  flex-direction: column;\n}\n.sk-layout-group[data-inline] > * {\n  display: inline-flex;\n  flex-direction: row;\n  align-items: center;\n  width: 100%;\n}\n\n/* Inactive LayoutView hiding \u2014 CSS-driven via data-state attribute.\n   LayoutView sets data-state="active"|"inactive" so consumers can\n   override transitions on .sk-layout-view without specificity fights.\n   [inert] handles accessibility (non-focusable, non-interactive). */\n.sk-layout-view[data-state="inactive"] {\n  opacity: 0;\n  visibility: hidden;\n}\n\n/* \u2500\u2500 SizeRatchet \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* contain isolates internal reflow from ancestors. */\n.sk-size-ratchet {\n  contain: layout style;\n}\n\n/* \u2500\u2500 Shimmer / Skeleton \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n.sk-skeleton-grid {\n  display: grid;\n  gap: var(--sk-skeleton-gap, 0.75rem);\n  contain: layout style;\n}\n\n.sk-skeleton-bone {\n  display: flex;\n  flex-direction: column;\n  gap: var(--sk-skeleton-bone-gap, 0.125rem);\n  padding: var(--sk-skeleton-bone-padding, 0.375rem 0.5rem);\n}\n\n.sk-shimmer-line {\n  height: 1lh;\n  border-radius: var(--sk-shimmer-radius, 0.125rem);\n  background: linear-gradient(\n    90deg,\n    var(--sk-shimmer-color, #e5e7eb) 25%,\n    var(--sk-shimmer-highlight, #f3f4f6) 50%,\n    var(--sk-shimmer-color, #e5e7eb) 75%\n  );\n  background-size: 200% 100%;\n  animation: sk-shimmer var(--sk-shimmer-duration, 1.5s) ease-in-out infinite;\n}\n\n/* Inert ghost inside a shimmer-line \u2014 sizes the shimmer to match\n   content width exactly. Invisible and non-interactive via [inert]. */\n.sk-shimmer-line > [inert] {\n  visibility: hidden;\n}\n\n@keyframes sk-shimmer {\n  0% { background-position: 200% 0; }\n  100% { background-position: -200% 0; }\n}\n\n/* \u2500\u2500 MediaSkeleton \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Loading-aware media container.\n   Reserves space via aspect-ratio (set inline by the component).\n   Child constraints enforced via React.cloneElement inline styles. */\n.sk-media {\n  overflow: hidden;\n}\n.sk-media-shimmer {\n  position: absolute;\n  inset: 0;\n  border-radius: var(--sk-shimmer-radius, 0.125rem);\n  background: linear-gradient(\n    90deg,\n    var(--sk-shimmer-color, #e5e7eb) 25%,\n    var(--sk-shimmer-highlight, #f3f4f6) 50%,\n    var(--sk-shimmer-color, #e5e7eb) 75%\n  );\n  background-size: 200% 100%;\n  animation: sk-shimmer var(--sk-shimmer-duration, 1.5s) ease-in-out infinite;\n  transition: opacity var(--sk-loading-exit-duration, 400ms) var(--sk-ease-decelerate);\n}\n\n/* \u2500\u2500 Shared easing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Decelerate: fast start, gentle finish \u2014 for elements entering view. */\n/* Standard: balanced ease \u2014 for general-purpose transitions. */\n/* Accelerate: gentle start, fast finish \u2014 for elements leaving view. */\n:root {\n  --sk-ease-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1.0);\n  --sk-ease-standard: cubic-bezier(0.4, 0, 0.2, 1);\n  --sk-ease-accelerate: cubic-bezier(0.4, 0, 1, 1);\n}\n\n/* \u2500\u2500 FadeTransition \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n.sk-fade {\n  --sk-fade-duration: 400ms;\n}\n\n.sk-fade-entering {\n  animation: sk-emerge var(--sk-fade-duration) var(--sk-ease-decelerate) forwards;\n}\n\n.sk-fade-exiting {\n  animation: sk-collapse var(--sk-fade-duration) var(--sk-ease-accelerate) forwards;\n}\n\n@keyframes sk-emerge {\n  from {\n    opacity: 0;\n    transform: translateY(var(--sk-fade-offset-y, -12px)) scale(var(--sk-fade-offset-scale, 0.98));\n  }\n  to {\n    opacity: 1;\n    transform: translateY(0) scale(1);\n  }\n}\n\n@keyframes sk-collapse {\n  from { opacity: 1; transform: scaleY(1); transform-origin: top; }\n  to   { opacity: 0; transform: scaleY(0); transform-origin: top; }\n}\n\n/* \u2500\u2500 Loading layers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Shared by shimmer and content layers inside skeleton components.\n   Both layers permanently occupy the same grid cell; only opacity\n   and interactivity change. CSS transitions handle the crossfade. */\n.sk-loading-layer {\n  grid-area: 1 / 1;\n  transition: opacity var(--sk-loading-exit-duration, 400ms) var(--sk-ease-decelerate);\n}\n\n/* \u2500\u2500 Reduced motion \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Disables all animations \u2014 shimmer, fade, and loading exit.\n   Layout changes still happen instantly so functionality is preserved. */\n@media (prefers-reduced-motion: reduce) {\n  .sk-fade-entering,\n  .sk-fade-exiting,\n  .sk-shimmer-line,\n  .sk-media-shimmer {\n    animation-duration: 0s !important;\n  }\n  .sk-loading-layer,\n  .sk-media-shimmer {\n    transition-duration: 0s !important;\n  }\n}\n';
 
 // src/internal/inject-styles.ts
 var injected = false;

package/dist/index.js

@@ -11,7 +11,7 @@ import {
 } from "react";
 
 // src/styles.css
-var styles_default = '/* stablekit \u2014 layout stability toolkit for React\n *\n * CSS class prefix: sk-\n * All animations use CSS custom properties for themability.\n * Styles are auto-injected at import time (opt-out via meta tag).\n */\n\n/* \u2500\u2500 LayoutGroup / LayoutView \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* All children overlap in the same grid cell.\n   Grid auto-sizes to the largest child.\n   Views use flex-column so their content stretches to fill\n   the reserved width \u2014 the visual footprint is constant.\n   Inline groups (StateSwap) use inline-grid for inline contexts. */\n.sk-layout-group {\n  display: grid;\n}\n.sk-layout-group[data-inline] {\n  display: inline-grid;\n}\n.sk-layout-group > * {\n  grid-area: 1 / 1;\n  display: flex;\n  flex-direction: column;\n}\n.sk-layout-group[data-inline] > * {\n  display: inline-flex;\n  flex-direction: row;\n  align-items: center;\n}\n.sk-layout-group[data-inline] > * > * {\n  width: 100%;\n}\n\n/* Inactive LayoutView hiding \u2014 CSS-driven via data-state attribute.\n   LayoutView sets data-state="active"|"inactive" so consumers can\n   override transitions on .sk-layout-view without specificity fights.\n   [inert] handles accessibility (non-focusable, non-interactive). */\n.sk-layout-view[data-state="inactive"] {\n  opacity: 0;\n  visibility: hidden;\n}\n\n/* \u2500\u2500 SizeRatchet \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* contain isolates internal reflow from ancestors. */\n.sk-size-ratchet {\n  contain: layout style;\n}\n\n/* \u2500\u2500 Shimmer / Skeleton \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n.sk-skeleton-grid {\n  display: grid;\n  gap: var(--sk-skeleton-gap, 0.75rem);\n  contain: layout style;\n}\n\n.sk-skeleton-bone {\n  display: flex;\n  flex-direction: column;\n  gap: var(--sk-skeleton-bone-gap, 0.125rem);\n  padding: var(--sk-skeleton-bone-padding, 0.375rem 0.5rem);\n}\n\n.sk-shimmer-line {\n  height: 1lh;\n  border-radius: var(--sk-shimmer-radius, 0.125rem);\n  background: linear-gradient(\n    90deg,\n    var(--sk-shimmer-color, #e5e7eb) 25%,\n    var(--sk-shimmer-highlight, #f3f4f6) 50%,\n    var(--sk-shimmer-color, #e5e7eb) 75%\n  );\n  background-size: 200% 100%;\n  animation: sk-shimmer var(--sk-shimmer-duration, 1.5s) ease-in-out infinite;\n}\n\n/* Inert ghost inside a shimmer-line \u2014 sizes the shimmer to match\n   content width exactly. Invisible and non-interactive via [inert]. */\n.sk-shimmer-line > [inert] {\n  visibility: hidden;\n}\n\n@keyframes sk-shimmer {\n  0% { background-position: 200% 0; }\n  100% { background-position: -200% 0; }\n}\n\n/* \u2500\u2500 MediaSkeleton \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Loading-aware media container.\n   Reserves space via aspect-ratio (set inline by the component).\n   Child constraints enforced via React.cloneElement inline styles. */\n.sk-media {\n  overflow: hidden;\n}\n.sk-media-shimmer {\n  position: absolute;\n  inset: 0;\n  border-radius: var(--sk-shimmer-radius, 0.125rem);\n  background: linear-gradient(\n    90deg,\n    var(--sk-shimmer-color, #e5e7eb) 25%,\n    var(--sk-shimmer-highlight, #f3f4f6) 50%,\n    var(--sk-shimmer-color, #e5e7eb) 75%\n  );\n  background-size: 200% 100%;\n  animation: sk-shimmer var(--sk-shimmer-duration, 1.5s) ease-in-out infinite;\n  transition: opacity var(--sk-loading-exit-duration, 400ms) var(--sk-ease-decelerate);\n}\n\n/* \u2500\u2500 Shared easing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Decelerate: fast start, gentle finish \u2014 for elements entering view. */\n/* Standard: balanced ease \u2014 for general-purpose transitions. */\n/* Accelerate: gentle start, fast finish \u2014 for elements leaving view. */\n:root {\n  --sk-ease-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1.0);\n  --sk-ease-standard: cubic-bezier(0.4, 0, 0.2, 1);\n  --sk-ease-accelerate: cubic-bezier(0.4, 0, 1, 1);\n}\n\n/* \u2500\u2500 FadeTransition \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n.sk-fade {\n  --sk-fade-duration: 400ms;\n}\n\n.sk-fade-entering {\n  animation: sk-emerge var(--sk-fade-duration) var(--sk-ease-decelerate) forwards;\n}\n\n.sk-fade-exiting {\n  animation: sk-collapse var(--sk-fade-duration) var(--sk-ease-accelerate) forwards;\n}\n\n@keyframes sk-emerge {\n  from {\n    opacity: 0;\n    transform: translateY(var(--sk-fade-offset-y, -12px)) scale(var(--sk-fade-offset-scale, 0.98));\n  }\n  to {\n    opacity: 1;\n    transform: translateY(0) scale(1);\n  }\n}\n\n@keyframes sk-collapse {\n  from { opacity: 1; transform: scaleY(1); transform-origin: top; }\n  to   { opacity: 0; transform: scaleY(0); transform-origin: top; }\n}\n\n/* \u2500\u2500 Loading layers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Shared by shimmer and content layers inside skeleton components.\n   Both layers permanently occupy the same grid cell; only opacity\n   and interactivity change. CSS transitions handle the crossfade. */\n.sk-loading-layer {\n  grid-area: 1 / 1;\n  transition: opacity var(--sk-loading-exit-duration, 400ms) var(--sk-ease-decelerate);\n}\n\n/* \u2500\u2500 Reduced motion \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Disables all animations \u2014 shimmer, fade, and loading exit.\n   Layout changes still happen instantly so functionality is preserved. */\n@media (prefers-reduced-motion: reduce) {\n  .sk-fade-entering,\n  .sk-fade-exiting,\n  .sk-shimmer-line,\n  .sk-media-shimmer {\n    animation-duration: 0s !important;\n  }\n  .sk-loading-layer,\n  .sk-media-shimmer {\n    transition-duration: 0s !important;\n  }\n}\n';
+var styles_default = '/* stablekit \u2014 layout stability toolkit for React\n *\n * CSS class prefix: sk-\n * All animations use CSS custom properties for themability.\n * Styles are auto-injected at import time (opt-out via meta tag).\n */\n\n/* \u2500\u2500 LayoutGroup / LayoutView \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* All children overlap in the same grid cell.\n   Grid auto-sizes to the largest child.\n   Views use flex-column so their content stretches to fill\n   the reserved width \u2014 the visual footprint is constant.\n   Inline groups (StateSwap) use inline-grid for inline contexts. */\n.sk-layout-group {\n  display: grid;\n}\n.sk-layout-group[data-inline] {\n  display: inline-grid;\n}\n.sk-layout-group > * {\n  grid-area: 1 / 1;\n  display: flex;\n  flex-direction: column;\n}\n.sk-layout-group[data-inline] > * {\n  display: inline-flex;\n  flex-direction: row;\n  align-items: center;\n  width: 100%;\n}\n\n/* Inactive LayoutView hiding \u2014 CSS-driven via data-state attribute.\n   LayoutView sets data-state="active"|"inactive" so consumers can\n   override transitions on .sk-layout-view without specificity fights.\n   [inert] handles accessibility (non-focusable, non-interactive). */\n.sk-layout-view[data-state="inactive"] {\n  opacity: 0;\n  visibility: hidden;\n}\n\n/* \u2500\u2500 SizeRatchet \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* contain isolates internal reflow from ancestors. */\n.sk-size-ratchet {\n  contain: layout style;\n}\n\n/* \u2500\u2500 Shimmer / Skeleton \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n.sk-skeleton-grid {\n  display: grid;\n  gap: var(--sk-skeleton-gap, 0.75rem);\n  contain: layout style;\n}\n\n.sk-skeleton-bone {\n  display: flex;\n  flex-direction: column;\n  gap: var(--sk-skeleton-bone-gap, 0.125rem);\n  padding: var(--sk-skeleton-bone-padding, 0.375rem 0.5rem);\n}\n\n.sk-shimmer-line {\n  height: 1lh;\n  border-radius: var(--sk-shimmer-radius, 0.125rem);\n  background: linear-gradient(\n    90deg,\n    var(--sk-shimmer-color, #e5e7eb) 25%,\n    var(--sk-shimmer-highlight, #f3f4f6) 50%,\n    var(--sk-shimmer-color, #e5e7eb) 75%\n  );\n  background-size: 200% 100%;\n  animation: sk-shimmer var(--sk-shimmer-duration, 1.5s) ease-in-out infinite;\n}\n\n/* Inert ghost inside a shimmer-line \u2014 sizes the shimmer to match\n   content width exactly. Invisible and non-interactive via [inert]. */\n.sk-shimmer-line > [inert] {\n  visibility: hidden;\n}\n\n@keyframes sk-shimmer {\n  0% { background-position: 200% 0; }\n  100% { background-position: -200% 0; }\n}\n\n/* \u2500\u2500 MediaSkeleton \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Loading-aware media container.\n   Reserves space via aspect-ratio (set inline by the component).\n   Child constraints enforced via React.cloneElement inline styles. */\n.sk-media {\n  overflow: hidden;\n}\n.sk-media-shimmer {\n  position: absolute;\n  inset: 0;\n  border-radius: var(--sk-shimmer-radius, 0.125rem);\n  background: linear-gradient(\n    90deg,\n    var(--sk-shimmer-color, #e5e7eb) 25%,\n    var(--sk-shimmer-highlight, #f3f4f6) 50%,\n    var(--sk-shimmer-color, #e5e7eb) 75%\n  );\n  background-size: 200% 100%;\n  animation: sk-shimmer var(--sk-shimmer-duration, 1.5s) ease-in-out infinite;\n  transition: opacity var(--sk-loading-exit-duration, 400ms) var(--sk-ease-decelerate);\n}\n\n/* \u2500\u2500 Shared easing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Decelerate: fast start, gentle finish \u2014 for elements entering view. */\n/* Standard: balanced ease \u2014 for general-purpose transitions. */\n/* Accelerate: gentle start, fast finish \u2014 for elements leaving view. */\n:root {\n  --sk-ease-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1.0);\n  --sk-ease-standard: cubic-bezier(0.4, 0, 0.2, 1);\n  --sk-ease-accelerate: cubic-bezier(0.4, 0, 1, 1);\n}\n\n/* \u2500\u2500 FadeTransition \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n.sk-fade {\n  --sk-fade-duration: 400ms;\n}\n\n.sk-fade-entering {\n  animation: sk-emerge var(--sk-fade-duration) var(--sk-ease-decelerate) forwards;\n}\n\n.sk-fade-exiting {\n  animation: sk-collapse var(--sk-fade-duration) var(--sk-ease-accelerate) forwards;\n}\n\n@keyframes sk-emerge {\n  from {\n    opacity: 0;\n    transform: translateY(var(--sk-fade-offset-y, -12px)) scale(var(--sk-fade-offset-scale, 0.98));\n  }\n  to {\n    opacity: 1;\n    transform: translateY(0) scale(1);\n  }\n}\n\n@keyframes sk-collapse {\n  from { opacity: 1; transform: scaleY(1); transform-origin: top; }\n  to   { opacity: 0; transform: scaleY(0); transform-origin: top; }\n}\n\n/* \u2500\u2500 Loading layers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Shared by shimmer and content layers inside skeleton components.\n   Both layers permanently occupy the same grid cell; only opacity\n   and interactivity change. CSS transitions handle the crossfade. */\n.sk-loading-layer {\n  grid-area: 1 / 1;\n  transition: opacity var(--sk-loading-exit-duration, 400ms) var(--sk-ease-decelerate);\n}\n\n/* \u2500\u2500 Reduced motion \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n\n/* Disables all animations \u2014 shimmer, fade, and loading exit.\n   Layout changes still happen instantly so functionality is preserved. */\n@media (prefers-reduced-motion: reduce) {\n  .sk-fade-entering,\n  .sk-fade-exiting,\n  .sk-shimmer-line,\n  .sk-media-shimmer {\n    animation-duration: 0s !important;\n  }\n  .sk-loading-layer,\n  .sk-media-shimmer {\n    transition-duration: 0s !important;\n  }\n}\n';
 
 // src/internal/inject-styles.ts
 var injected = false;

package/dist/stylelint.cjs

@@ -5856,7 +5856,6 @@ module.exports = __toCommonJS(stylelint_exports);
 var pluginRuleName = "stablekit/no-functional-in-utility";
 var descendantColorRuleName = "stablekit/no-descendant-color-in-state";
 var duplicateRulesetRuleName = "stablekit/no-duplicate-ruleset";
-var nearDuplicateRuleName = "stablekit/no-near-duplicate-ruleset";
 var undefinedTokenRuleName = "stablekit/no-undefined-token";
 function createFunctionalTokenPlugin(prefixes) {
   const rule = (enabled) => {
@@ -5950,65 +5949,6 @@ Declarations: ${fingerprint}`,
     rule
   };
 }
-function createNearDuplicatePlugin() {
-  function collectDirectDecls(ruleNode) {
-    const map = /* @__PURE__ */ new Map();
-    for (const child of ruleNode.nodes ?? []) {
-      if (child.type === "decl") {
-        map.set(child.prop, child.value);
-      } else if (child.type === "atrule" && child.name === "apply") {
-        map.set(`@apply`, child.params);
-      }
-    }
-    return map;
-  }
-  const rule = (enabled) => {
-    return (root, result) => {
-      if (!enabled) return;
-      const groups = /* @__PURE__ */ new Map();
-      root.walkRules((ruleNode) => {
-        if (ruleNode.parent?.type === "atrule" && ruleNode.parent.name === "keyframes") return;
-        const propMap = collectDirectDecls(ruleNode);
-        if (propMap.size < 2) return;
-        const propKey = [...propMap.keys()].sort().join(", ");
-        const entry = { selector: ruleNode.selector, propKey, propMap, node: ruleNode };
-        const group = groups.get(propKey);
-        if (group) {
-          for (const existing of group) {
-            let diffCount = 0;
-            let diffProp = "";
-            let diffOld = "";
-            let diffNew = "";
-            for (const [prop, value] of entry.propMap) {
-              const existingValue = existing.propMap.get(prop);
-              if (existingValue !== value) {
-                diffCount++;
-                diffProp = prop;
-                diffOld = existingValue ?? "(missing)";
-                diffNew = value;
-              }
-            }
-            if (diffCount === 0) continue;
-            if (diffCount === 1 && diffProp !== "@apply") {
-              result.warn(
-                `Near-duplicate ruleset \u2014 "${ruleNode.selector}" differs from "${existing.selector}" only in ${diffProp} (${diffOld} \u2192 ${diffNew}). Consider consolidating to a single class.`,
-                { node: ruleNode }
-              );
-              break;
-            }
-          }
-          group.push(entry);
-        } else {
-          groups.set(propKey, [entry]);
-        }
-      });
-    };
-  };
-  return {
-    ruleName: nearDuplicateRuleName,
-    rule
-  };
-}
 function createUndefinedTokenPlugin(runtimePrefixes) {
   const varPattern = /var\(--([a-zA-Z0-9_-]+)/g;
   const rule = (enabled) => {
@@ -6055,7 +5995,7 @@ function createStyleLint(options = {}) {
     runtimeTokens = [],
     files = ["src/**/*.css"]
   } = options;
-  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin(), createNearDuplicatePlugin(), createUndefinedTokenPlugin(runtimeTokens)];
+  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin(), createUndefinedTokenPlugin(runtimeTokens)];
   if (functionalTokens.length > 0) {
     plugins.push(createFunctionalTokenPlugin(functionalTokens));
   }
@@ -6073,8 +6013,6 @@ function createStyleLint(options = {}) {
     [descendantColorRuleName]: true,
     // Flag selectors with identical declarations for consolidation.
     [duplicateRulesetRuleName]: true,
-    // Flag near-duplicate rulesets (same props, differ by 1 value).
-    [nearDuplicateRuleName]: true,
     // Flag var() references to custom properties not defined in this file.
     [undefinedTokenRuleName]: true,
     // Ban animating layout properties — causes reflow on every frame.

package/dist/stylelint.d.cts

@@ -27,7 +27,7 @@
  *    top/right/bottom/left). These trigger reflow on every frame.
  *    Use transform (scaleY, translateY) or opacity instead.
  *
- * 6. Don't duplicate rulesets — two selectors with byte-identical
+ * 6. Don't duplicate rulesets — two selectors with identical
  *    declarations (after sorting) should be consolidated under one
  *    shared class name. The warning includes the matched declarations
  *    so the developer can see why they were flagged.

package/dist/stylelint.d.ts

@@ -27,7 +27,7 @@
  *    top/right/bottom/left). These trigger reflow on every frame.
  *    Use transform (scaleY, translateY) or opacity instead.
  *
- * 6. Don't duplicate rulesets — two selectors with byte-identical
+ * 6. Don't duplicate rulesets — two selectors with identical
  *    declarations (after sorting) should be consolidated under one
  *    shared class name. The warning includes the matched declarations
  *    so the developer can see why they were flagged.

package/dist/stylelint.js

@@ -5833,7 +5833,6 @@ var require_postcss = __commonJS({
 var pluginRuleName = "stablekit/no-functional-in-utility";
 var descendantColorRuleName = "stablekit/no-descendant-color-in-state";
 var duplicateRulesetRuleName = "stablekit/no-duplicate-ruleset";
-var nearDuplicateRuleName = "stablekit/no-near-duplicate-ruleset";
 var undefinedTokenRuleName = "stablekit/no-undefined-token";
 function createFunctionalTokenPlugin(prefixes) {
   const rule = (enabled) => {
@@ -5927,65 +5926,6 @@ Declarations: ${fingerprint}`,
     rule
   };
 }
-function createNearDuplicatePlugin() {
-  function collectDirectDecls(ruleNode) {
-    const map = /* @__PURE__ */ new Map();
-    for (const child of ruleNode.nodes ?? []) {
-      if (child.type === "decl") {
-        map.set(child.prop, child.value);
-      } else if (child.type === "atrule" && child.name === "apply") {
-        map.set(`@apply`, child.params);
-      }
-    }
-    return map;
-  }
-  const rule = (enabled) => {
-    return (root, result) => {
-      if (!enabled) return;
-      const groups = /* @__PURE__ */ new Map();
-      root.walkRules((ruleNode) => {
-        if (ruleNode.parent?.type === "atrule" && ruleNode.parent.name === "keyframes") return;
-        const propMap = collectDirectDecls(ruleNode);
-        if (propMap.size < 2) return;
-        const propKey = [...propMap.keys()].sort().join(", ");
-        const entry = { selector: ruleNode.selector, propKey, propMap, node: ruleNode };
-        const group = groups.get(propKey);
-        if (group) {
-          for (const existing of group) {
-            let diffCount = 0;
-            let diffProp = "";
-            let diffOld = "";
-            let diffNew = "";
-            for (const [prop, value] of entry.propMap) {
-              const existingValue = existing.propMap.get(prop);
-              if (existingValue !== value) {
-                diffCount++;
-                diffProp = prop;
-                diffOld = existingValue ?? "(missing)";
-                diffNew = value;
-              }
-            }
-            if (diffCount === 0) continue;
-            if (diffCount === 1 && diffProp !== "@apply") {
-              result.warn(
-                `Near-duplicate ruleset \u2014 "${ruleNode.selector}" differs from "${existing.selector}" only in ${diffProp} (${diffOld} \u2192 ${diffNew}). Consider consolidating to a single class.`,
-                { node: ruleNode }
-              );
-              break;
-            }
-          }
-          group.push(entry);
-        } else {
-          groups.set(propKey, [entry]);
-        }
-      });
-    };
-  };
-  return {
-    ruleName: nearDuplicateRuleName,
-    rule
-  };
-}
 function createUndefinedTokenPlugin(runtimePrefixes) {
   const varPattern = /var\(--([a-zA-Z0-9_-]+)/g;
   const rule = (enabled) => {
@@ -6032,7 +5972,7 @@ function createStyleLint(options = {}) {
     runtimeTokens = [],
     files = ["src/**/*.css"]
   } = options;
-  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin(), createNearDuplicatePlugin(), createUndefinedTokenPlugin(runtimeTokens)];
+  const plugins = [createDescendantColorPlugin(), createDuplicateRulesetPlugin(), createUndefinedTokenPlugin(runtimeTokens)];
   if (functionalTokens.length > 0) {
     plugins.push(createFunctionalTokenPlugin(functionalTokens));
   }
@@ -6050,8 +5990,6 @@ function createStyleLint(options = {}) {
     [descendantColorRuleName]: true,
     // Flag selectors with identical declarations for consolidation.
     [duplicateRulesetRuleName]: true,
-    // Flag near-duplicate rulesets (same props, differ by 1 value).
-    [nearDuplicateRuleName]: true,
     // Flag var() references to custom properties not defined in this file.
     [undefinedTokenRuleName]: true,
     // Ban animating layout properties — causes reflow on every frame.

package/dist/styles.css

@@ -27,8 +27,6 @@
   display: inline-flex;
   flex-direction: row;
   align-items: center;
-}
-.sk-layout-group[data-inline] > * > * {
   width: 100%;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stablekit.ts",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "React toolkit for layout stability — zero-shift components for loading states, content swaps, and spatial containers.",
   "type": "module",
   "main": "./dist/index.cjs",