feat(selector): support universal selector with inherited CSS properties

skovhus · claude · skovhus · commit 5e847c476f89 · 2026-03-25T22:30:17.000+01:00
Lift `&amp; *` and bare `*` declarations to the parent element when all
properties are CSS-inherited (color, font-family, cursor, etc.).
Non-inherited properties or complex patterns (&amp; &gt; *, &amp;:hover *, &amp; * *)
still bail as before.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/internal/collect-styled-decls.ts b/src/internal/collect-styled-decls.ts
@@ -4,9 +4,10 @@
  */
 import type { Collection } from "jscodeshift";
 import {
+  type CssRuleIR,
   computeUniversalSelectorLoc,
-  hasUniversalSelectorInRules,
   normalizeStylisAstToIR,
+  rewriteInheritedUniversalRules,
 } from "./css-ir.js";
 import {
   cloneAstNode,
@@ -62,6 +63,19 @@ function collectStyledDeclsImpl(args: {
     universalSelectorLoc = computeUniversalSelectorLoc(getNodeLocStart(template), rawCss);
   };
 
+  /** Rewrite inherited-only `& *` rules to base and note any remaining universals. */
+  const rewriteUniversalRules = (
+    rules: CssRuleIR[],
+    template: any,
+    rawCss: string,
+  ): CssRuleIR[] => {
+    const rewritten = rewriteInheritedUniversalRules(rules);
+    if (rewritten.hasRemainingUniversal) {
+      noteUniversalSelector(template, rawCss);
+    }
+    return rewritten.rules;
+  };
+
   /**
    * Convert a MemberExpression AST node to a string like "animated.div".
    * Returns null if the expression doesn't match the expected pattern.
@@ -811,12 +825,11 @@ function collectStyledDeclsImpl(args: {
         const template = init.quasi;
         const templateLoc = getNodeLocStart(template);
         const parsed = parseStyledTemplateLiteral(template);
-        const rules = normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, {
-          rawCss: parsed.rawCss,
-        });
-        if (hasUniversalSelectorInRules(rules)) {
-          noteUniversalSelector(template, parsed.rawCss);
-        }
+        const rules = rewriteUniversalRules(
+          normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, { rawCss: parsed.rawCss }),
+          template,
+          parsed.rawCss,
+        );
 
         styledDecls.push({
           ...placementHints,
@@ -845,12 +858,11 @@ function collectStyledDeclsImpl(args: {
           const template = init.quasi;
           const templateLoc = getNodeLocStart(template);
           const parsed = parseStyledTemplateLiteral(template);
-          const rules = normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, {
-            rawCss: parsed.rawCss,
-          });
-          if (hasUniversalSelectorInRules(rules)) {
-            noteUniversalSelector(template, parsed.rawCss);
-          }
+          const rules = rewriteUniversalRules(
+            normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, { rawCss: parsed.rawCss }),
+            template,
+            parsed.rawCss,
+          );
 
           const attrsInfo = peeled.attrsArg != null ? parseAttrsArg(peeled.attrsArg) : undefined;
           const sfpResult =
@@ -897,12 +909,11 @@ function collectStyledDeclsImpl(args: {
         const template = init.quasi;
         const templateLoc = getNodeLocStart(template);
         const parsed = parseStyledTemplateLiteral(template);
-        const rules = normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, {
-          rawCss: parsed.rawCss,
-        });
-        if (hasUniversalSelectorInRules(rules)) {
-          noteUniversalSelector(template, parsed.rawCss);
-        }
+        const rules = rewriteUniversalRules(
+          normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, { rawCss: parsed.rawCss }),
+          template,
+          parsed.rawCss,
+        );
 
         styledDecls.push({
           ...placementHints,
@@ -934,12 +945,11 @@ function collectStyledDeclsImpl(args: {
         const template = init.quasi;
         const templateLoc = getNodeLocStart(template);
         const parsed = parseStyledTemplateLiteral(template);
-        const rules = normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, {
-          rawCss: parsed.rawCss,
-        });
-        if (hasUniversalSelectorInRules(rules)) {
-          noteUniversalSelector(template, parsed.rawCss);
-        }
+        const rules = rewriteUniversalRules(
+          normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, { rawCss: parsed.rawCss }),
+          template,
+          parsed.rawCss,
+        );
 
         styledDecls.push({
           ...placementHints,
@@ -971,12 +981,11 @@ function collectStyledDeclsImpl(args: {
         const template = init.quasi;
         const templateLoc = getNodeLocStart(template);
         const parsed = parseStyledTemplateLiteral(template);
-        const rules = normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, {
-          rawCss: parsed.rawCss,
-        });
-        if (hasUniversalSelectorInRules(rules)) {
-          noteUniversalSelector(template, parsed.rawCss);
-        }
+        const rules = rewriteUniversalRules(
+          normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, { rawCss: parsed.rawCss }),
+          template,
+          parsed.rawCss,
+        );
 
         styledDecls.push({
           ...placementHints,
@@ -1281,12 +1290,11 @@ function collectStyledDeclsImpl(args: {
           // Handle styled.div(props => css`...`) pattern
           const templateLoc = getNodeLocStart(cssTemplate);
           const parsed = parseStyledTemplateLiteral(cssTemplate);
-          const rules = normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, {
-            rawCss: parsed.rawCss,
-          });
-          if (hasUniversalSelectorInRules(rules)) {
-            noteUniversalSelector(cssTemplate, parsed.rawCss);
-          }
+          const rules = rewriteUniversalRules(
+            normalizeStylisAstToIR(parsed.stylisAst, parsed.slots, { rawCss: parsed.rawCss }),
+            cssTemplate,
+            parsed.rawCss,
+          );
 
           // Extract destructured params and transform expressions
           const destructuredParams = extractDestructuredParams(arg0);
diff --git a/src/internal/css-inherited-properties.ts b/src/internal/css-inherited-properties.ts
@@ -0,0 +1,79 @@
+/**
+ * CSS properties that are inherited by default.
+ * Setting these on a parent element propagates the value to all descendants,
+ * making `& * { prop: value }` equivalent to setting the property on the parent.
+ *
+ * Source of truth: W3C CSS2 full property table (https://www.w3.org/TR/CSS2/propidx.html)
+ * plus CSS3+ properties verified against MDN formal definitions ("Inherited: yes").
+ * Excludes deprecated aural CSS properties (azimuth, speak, voice-family, etc.).
+ */
+
+const CSS_INHERITED_PROPERTIES: ReadonlySet<string> = new Set([
+  // Text and font
+  "color",
+  "font",
+  "font-family",
+  "font-size",
+  "font-style",
+  "font-weight",
+  "font-variant",
+  "font-stretch",
+  "font-size-adjust",
+  "font-optical-sizing",
+  "font-kerning",
+  "font-feature-settings",
+  "font-variation-settings",
+  "line-height",
+  "letter-spacing",
+  "word-spacing",
+  "text-align",
+  "text-indent",
+  "text-transform",
+  "text-wrap",
+  "white-space",
+  "word-break",
+  "overflow-wrap",
+  "word-wrap",
+  "hyphens",
+  "tab-size",
+  "text-shadow",
+  "text-decoration-skip-ink",
+  "text-underline-offset",
+  "text-underline-position",
+
+  // List
+  "list-style",
+  "list-style-type",
+  "list-style-position",
+  "list-style-image",
+
+  // Table
+  "border-collapse",
+  "border-spacing",
+  "caption-side",
+  "empty-cells",
+
+  // UI and interaction
+  "cursor",
+  "visibility",
+  "pointer-events",
+  "accent-color",
+  "caret-color",
+  "color-scheme",
+
+  // Writing and direction
+  "direction",
+  "writing-mode",
+  "text-orientation",
+  "quotes",
+  "orphans",
+  "widows",
+]);
+
+/**
+ * Check if a CSS property is inherited by default.
+ * Custom properties (--*) are also inherited.
+ */
+export function isCssInheritedProperty(property: string): boolean {
+  return property.startsWith("--") || CSS_INHERITED_PROPERTIES.has(property);
+}
diff --git a/src/internal/css-ir.ts b/src/internal/css-ir.ts
@@ -3,6 +3,7 @@
  * Core concepts: declaration/value modeling and selector normalization.
  */
 import type { Element } from "stylis";
+import { isCssInheritedProperty } from "./css-inherited-properties.js";
 import { PLACEHOLDER_RE, type StyledInterpolationSlot } from "./styled-css.js";
 import { isPrettierIgnoreComment } from "./utilities/string-utils.js";
 
@@ -545,10 +546,63 @@ function sameArray(a: readonly string[], b: readonly string[]): boolean {
 }
 
 /**
- * Check if any rule has a universal selector (`*`) in its selector string.
+ * Selector pattern for a simple descendant universal selector.
+ * Stylis normalizes `& * { ... }` to selector `"& *"`, and
+ * bare `* { ... }` to selector `"*"`. Both are equivalent.
  */
-export function hasUniversalSelectorInRules(rules: CssRuleIR[]): boolean {
-  return rules.some((r) => typeof r.selector === "string" && r.selector.includes("*"));
+const SIMPLE_DESCENDANT_UNIVERSAL_RE = /^(&\s+\*|\*)$/;
+
+/**
+ * Rewrite `& *` rules whose declarations are ALL inherited CSS properties
+ * into base `&` rules (lifting them to the parent element).
+ *
+ * Returns the (possibly modified) rules and whether any un-rewritable
+ * universal selectors remain (which should still trigger a bail).
+ */
+export function rewriteInheritedUniversalRules(rules: CssRuleIR[]): {
+  rules: CssRuleIR[];
+  hasRemainingUniversal: boolean;
+} {
+  // Quick check: if no rule contains `*` at all, skip detailed analysis
+  if (!rules.some((r) => typeof r.selector === "string" && r.selector.includes("*"))) {
+    return { rules, hasRemainingUniversal: false };
+  }
+
+  let hasRemainingUniversal = false;
+  const result: CssRuleIR[] = [];
+
+  for (const rule of rules) {
+    if (typeof rule.selector !== "string" || !rule.selector.includes("*")) {
+      result.push(rule);
+      continue;
+    }
+
+    // Only handle simple `& *` (descendant universal) with no at-rules
+    if (!SIMPLE_DESCENDANT_UNIVERSAL_RE.test(rule.selector) || rule.atRuleStack.length > 0) {
+      hasRemainingUniversal = true;
+      result.push(rule);
+      continue;
+    }
+
+    // Check if ALL declarations use inherited properties
+    const allInherited = rule.declarations.every((d) => isCssInheritedProperty(d.property));
+
+    if (!allInherited) {
+      hasRemainingUniversal = true;
+      result.push(rule);
+      continue;
+    }
+
+    // Rewrite: merge declarations into the base `&` rule
+    const baseRule = result.find((r) => r.selector === "&" && r.atRuleStack.length === 0);
+    if (baseRule) {
+      baseRule.declarations.push(...rule.declarations);
+    } else {
+      result.push({ selector: "&", atRuleStack: [], declarations: [...rule.declarations] });
+    }
+  }
+
+  return { rules: result, hasRemainingUniversal };
 }
 
 /**
diff --git a/src/internal/transform/css-helpers.ts b/src/internal/transform/css-helpers.ts
@@ -9,8 +9,8 @@ import type { CssRuleIR } from "../css-ir.js";
 import { getNodeLocStart } from "../utilities/jscodeshift-utils.js";
 import {
   computeUniversalSelectorLoc,
-  hasUniversalSelectorInRules,
   normalizeStylisAstToIR,
+  rewriteInheritedUniversalRules,
 } from "../css-ir.js";
 import { parseStyledTemplateLiteral } from "../styled-css.js";
 import type { StyledDecl } from "../transform-types.js";
@@ -130,6 +130,15 @@ export function isIdentifierReference(p: any): boolean {
   return true;
 }
 
+/** Rewrite inherited-only `& *` rules to base and notify via callback if universals remain. */
+function applyUniversalRewrite(rules: CssRuleIR[], onRemaining: () => void): CssRuleIR[] {
+  const rewritten = rewriteInheritedUniversalRules(rules);
+  if (rewritten.hasRemainingUniversal) {
+    onRemaining();
+  }
+  return rewritten.rules;
+}
+
 function buildExportedLocalNames(root: any, j: JSCodeshift): Set<string> {
   const exportedLocalNames = new Set<string>();
   root.find(j.ExportNamedDeclaration).forEach((p: any) => {
@@ -246,10 +255,10 @@ function parseCssHelperTemplate(args: {
   const parsed = parseStyledTemplateLiteral(template);
   const rawCss = `& { ${parsed.rawCss} }`;
   const stylisAst = compile(rawCss);
-  const rules = normalizeStylisAstToIR(stylisAst, parsed.slots, { rawCss });
-  if (hasUniversalSelectorInRules(rules)) {
-    noteUniversalSelector(template, parsed.rawCss);
-  }
+  const rules = applyUniversalRewrite(
+    normalizeStylisAstToIR(stylisAst, parsed.slots, { rawCss }),
+    () => noteUniversalSelector(template, parsed.rawCss),
+  );
   return {
     rules,
     rawCss,
@@ -1144,11 +1153,10 @@ export function extractAndRemoveCssHelpers(args: {
 
         const rawCss = `& { ${parsed.rawCss} }`;
         const stylisAst = compile(rawCss);
-        const rules = normalizeStylisAstToIR(stylisAst, parsed.slots, { rawCss });
-
-        if (hasUniversalSelectorInRules(rules)) {
-          noteCssHelperUniversalSelector(template, parsed.rawCss);
-        }
+        const rules = applyUniversalRewrite(
+          normalizeStylisAstToIR(stylisAst, parsed.slots, { rawCss }),
+          () => noteCssHelperUniversalSelector(template, parsed.rawCss),
+        );
 
         // Create a qualified name for the style key: objectName + PropName
         const qualifiedName = `${objectName}.${propName}`;
diff --git a/test-cases/selector-universalInherited.input.tsx b/test-cases/selector-universalInherited.input.tsx
diff --git a/test-cases/selector-universalInherited.output.tsx b/test-cases/selector-universalInherited.output.tsx
