perf(css): audit :has() selectors and add stylelint guard for Safari (#7708)

hectahertz · primer[bot] · jonrohan · web-flow · commit d0fa0ff2301b · 2026-04-28T20:35:43.000Z
Co-authored-by: hectahertz &lt;24622853+hectahertz@users.noreply.github.com&gt;
Co-authored-by: primer[bot] &lt;119360173+primer[bot]@users.noreply.github.com&gt;
Co-authored-by: Jon Rohan &lt;yes@jonrohan.codes&gt;
diff --git a/.changeset/perf-css-has-safari-audit.md b/.changeset/perf-css-has-safari-audit.md
@@ -0,0 +1,6 @@
+---
+'@primer/react': patch
+'@primer/styled-react': patch
+---
+
+perf(css): audit :has() selectors and add stylelint guard for Safari
diff --git a/.github/instructions/css.instructions.md b/.github/instructions/css.instructions.md
@@ -11,3 +11,16 @@ If the file ends with `*.module.css`, it is a CSS Module.
 ## General Conventions
 
 - After making a change to a file, use `npx stylelint -q --rd --fix` with a path to the file changed to make sure the code lints
+
+## `:has()` Selectors and Safari Performance
+
+`:has()` selectors are blocked by stylelint (`selector-pseudo-class-disallowed-list`) because they can cause catastrophic Safari performance regressions. In Aug 2025, a single `:has()` selector on a broadly-present component froze the entire GitHub UI for 10-20+ seconds on Safari. See [github/github-ui#17224](https://github.com/github/github-ui/issues/17224) for the full audit.
+
+**When you need `:has()`:**
+
+1. Ensure it's scoped to a CSS Module class (`&:has(...)` inside a `.Component` rule). Never use `:has()` on `body`, `html`, `*`, or other high-cardinality selectors.
+2. Keep the argument simple. Avoid deeply-nested descendant selectors inside `:has()`.
+3. Add a scoped stylelint disable with justification. Use `stylelint-disable-next-line` for individual selectors, or a `stylelint-disable`/`stylelint-enable` block around a group of related selectors. Avoid file-level disables so new `:has()` selectors in the same file still trigger review. Example: `/* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */`
+4. Consider alternatives first: data attributes set via JS, `:where()`, or restructuring the DOM so the parent already has the information it needs.
+
+**Why CSS Modules help:** CSS Module class names are unique hashed identifiers, so the browser only evaluates `:has()` on elements matching that specific class, not the entire DOM. This limits the invalidation blast radius. Unscoped selectors like `body:has(...)` force the browser to scan all descendants of `body` on every DOM mutation, which is where WebKit's quadratic invalidation triggers.
diff --git a/packages/react/src/ActionList/ActionList.module.css b/packages/react/src/ActionList/ActionList.module.css
@@ -103,6 +103,7 @@
   border-radius: var(--borderRadius-medium);
 
   /* apply flex if trailing action exists as an immediate child */
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:has(> .TrailingAction) {
     display: flex;
     flex-wrap: nowrap;
@@ -371,6 +372,7 @@
   }
 
   /* When TrailingAction is in loading state, keep labels and descriptions accessible */
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:has(.TrailingAction [data-loading='true']):not([data-is-disabled]) {
     /* Ensure labels and descriptions maintain accessibility contrast */
     & .ItemLabel {
@@ -546,6 +548,7 @@
     }
 
     /* show active indicator on parent collapse if child is active */
+    /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
     &:has(~ .SubGroup [data-active='true']) {
       background: var(--control-transparent-bgColor-selected);
 
@@ -642,6 +645,7 @@ default block */
       word-break: normal;
     }
 
+    /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
     &:has([data-truncate='true']) {
       & .ItemLabel {
         flex: 1 0 auto;
@@ -715,6 +719,7 @@ span wrapping svg or text */
   height: 100%;
 
   /* Preserve width consistency when loading state is active for text buttons only */
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &[data-loading='true']:has([data-component='buttonContent']) {
     /* Double the left padding to compensate for missing right padding */
     padding: 0 0 0 calc(var(--base-size-12) * 2);
@@ -734,10 +739,12 @@ span wrapping svg or text */
 }
 
 .InactiveButtonWrap {
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:has(.TrailingVisual) {
     grid-area: trailingVisual;
   }
 
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:has(.LeadingVisual) {
     grid-area: leadingVisual;
   }
diff --git a/packages/react/src/ActionList/Group.module.css b/packages/react/src/ActionList/Group.module.css
@@ -5,7 +5,7 @@
     margin-block-start: var(--base-size-8);
 
     /* If somebody tries to pass the `title` prop AND a `NavList.GroupHeading` as a child, hide the `ActionList.GroupHeading */
-    /* stylelint-disable-next-line selector-max-specificity */
+    /* stylelint-disable-next-line selector-max-specificity, selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
     &:has(.GroupHeadingWrap + ul > .GroupHeadingWrap) {
       /* stylelint-disable-next-line selector-max-specificity */
       & > .GroupHeadingWrap {
diff --git a/packages/react/src/AvatarStack/AvatarStack.module.css b/packages/react/src/AvatarStack/AvatarStack.module.css
@@ -144,6 +144,7 @@
     box-shadow: 0 0 0 var(--avatar-border-width) transparent;
   }
 
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:not([data-component='Avatar']):not(:has([data-square])) {
     border-radius: 50%;
   }
diff --git a/packages/react/src/Breadcrumbs/Breadcrumbs.module.css b/packages/react/src/Breadcrumbs/Breadcrumbs.module.css
@@ -117,6 +117,7 @@
   list-style: none;
 
   /* allow menu items to wrap line */
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:has(.MenuOverlay) {
     white-space: normal;
   }
diff --git a/packages/react/src/Button/ButtonBase.module.css b/packages/react/src/Button/ButtonBase.module.css
@@ -24,6 +24,7 @@
   justify-content: space-between;
   gap: var(--base-size-8);
 
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:has([data-kbd-chord]) {
     padding-inline-end: var(--base-size-6);
   }
@@ -173,6 +174,7 @@
       margin-right: var(--control-large-gap);
     }
 
+    /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
     &:has([data-kbd-chord]) {
       padding-inline-end: var(--base-size-8);
     }
@@ -638,6 +640,7 @@
 
   /* Icon-only + Counter */
 
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:where([data-has-count]):has([data-component='leadingVisual']):not(:has([data-component='text'])) {
     /* stylelint-disable-next-line primer/spacing */
     padding-inline: var(--control-medium-paddingInline-condensed);
diff --git a/packages/react/src/ButtonGroup/ButtonGroup.module.css b/packages/react/src/ButtonGroup/ButtonGroup.module.css
@@ -38,6 +38,7 @@
   }
 
   /* this is a workaround until portal based tooltips are fully removed from dotcom */
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:has(div:last-child:empty) {
     button,
     a {
diff --git a/packages/react/src/PageHeader/PageHeader.module.css b/packages/react/src/PageHeader/PageHeader.module.css
@@ -34,6 +34,7 @@
     --custom-font-size, --custom-line-height, --custom-font-weight are custom properties that can be used to override the below values.
     We don't want these values to be overridden but still want to allow consumers to override them if needed.
   */
+  /* stylelint-disable selector-pseudo-class-disallowed-list -- :has() scoped to CSS Module, audited (github/github-ui#17224) */
   &:has([data-component='TitleArea'][data-size-variant='large']) {
     font-size: var(--custom-font-size, var(--text-title-size-large, 2rem));
     font-weight: var(--custom-font-weight, var(--base-text-weight-normal, 400));
@@ -163,6 +164,7 @@
       padding-block-end: var(--base-size-8);
     }
   }
+  /* stylelint-enable selector-pseudo-class-disallowed-list */
 
   & [data-component='PH_LeadingAction'],
   & [data-component='PH_TrailingAction'],
diff --git a/packages/react/src/SegmentedControl/SegmentedControl.module.css b/packages/react/src/SegmentedControl/SegmentedControl.module.css
@@ -181,12 +181,14 @@
       background-color: var(--borderColor-default);
     }
 
+    /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
     &:has(+ [data-selected])::after,
     &:where([data-selected])::after {
       background-color: transparent;
     }
   }
 
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:focus-within:has(:focus-visible) {
     background-color: transparent;
   }
diff --git a/packages/react/src/Timeline/Timeline.module.css b/packages/react/src/Timeline/Timeline.module.css
@@ -151,6 +151,7 @@
   border: 0;
   border-top: var(--borderWidth-thicker) solid var(--borderColor-default);
 
+  /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
   &:has(+ [data-condensed]) {
     margin-bottom: calc(-1 * var(--base-size-12));
   }
diff --git a/packages/react/src/TreeView/TreeView.module.css b/packages/react/src/TreeView/TreeView.module.css
@@ -72,6 +72,7 @@
      * TreeViewItemContent > TreeViewItemContentText, not a direct child.
      * This is acceptable as the search is scoped to this element's subtree.
      */
+    /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
     &:has(.TreeViewItemSkeleton):hover {
       cursor: default;
       background-color: transparent;
diff --git a/packages/react/src/experimental/SelectPanel2/SelectPanel.module.css b/packages/react/src/experimental/SelectPanel2/SelectPanel.module.css
@@ -121,7 +121,7 @@
 .TextInput {
   padding-left: var(--base-size-8) !important;
 
-  /* stylelint-disable-next-line selector-class-pattern, selector-no-qualifying-type */
+  /* stylelint-disable-next-line selector-class-pattern, selector-no-qualifying-type, selector-pseudo-class-disallowed-list -- :has() scoped to CSS Module, audited (github/github-ui#17224) */
   &:has(input:placeholder-shown) :global(.TextInput-action) {
     display: none;
   }
diff --git a/packages/styled-react/src/components/BaseStyles.tsx b/packages/styled-react/src/components/BaseStyles.tsx
@@ -74,19 +74,12 @@ const GlobalStyle = createGlobalStyle<{colorScheme?: 'light' | 'dark'}>`
     /* stylelint-disable-next-line primer/colors */
     color: var(--BaseStyles-fgColor, var(--fgColor-default));
 
-    /* Global styles for light mode */
-    &:has([data-color-mode='light']) {
-      input & {
-        color-scheme: light;
-      }
-    }
-
-    /* Global styles for dark mode */
-    &:has([data-color-mode='dark']) {
-      input & {
-        color-scheme: dark;
-      }
-    }
+    /*
+     * PERFORMANCE: Removed :has([data-color-mode]) selectors that scanned entire DOM.
+     * Input color-scheme is already handled by global selectors above:
+     *   [data-color-mode='light'] input { color-scheme: light; }
+     *   [data-color-mode='dark'] input { color-scheme: dark; }
+     */
 
     /* Low-specificity default link styling */
     :where(a:not([class*='prc-']):not([class*='PRC-']):not([class*='Primer_Brand__'])) {
diff --git a/stylelint.config.mjs b/stylelint.config.mjs
@@ -14,6 +14,17 @@ export default {
       },
     ],
     'layer-name-pattern': '^[a-z][a-zA-Z0-9.-]*$',
+    // :has() can cause severe perf issues in Safari (quadratic style invalidation).
+    // See github/github-ui#17224 for audit. Existing usages are audited and scoped.
+    // New usages must be explicitly approved and marked with a stylelint-disable comment.
+    'selector-pseudo-class-disallowed-list': [
+      ['has'],
+      {
+        severity: 'error',
+        message:
+          ':has() selectors can cause severe Safari performance issues (github/github-ui#17224). Verify the selector is scoped (CSS Modules) and does not match broadly, then add a scoped stylelint disable (e.g. "stylelint-disable-next-line" or a minimal "stylelint-disable"/"stylelint-enable" block), not a file-level disable.',
+      },
+    ],
   },
   overrides: [
     {

Original file line number	Diff line number	Diff line change
`@@ -144,6 +144,7 @@`
`144`	`144`	`box-shadow: 0 0 0 var(--avatar-border-width) transparent;`
`145`	`145`	`}`
`146`	`146`
	`147`	`+ /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */`
`147`	`148`	`&:not([data-component='Avatar']):not(:has([data-square])) {`
`148`	`149`	`border-radius: 50%;`
`149`	`150`	`}`
Original file line number	Diff line number	Diff line change
`@@ -117,6 +117,7 @@`
`117`	`117`	`list-style: none;`
`118`	`118`
`119`	`119`	`/* allow menu items to wrap line */`
	`120`	`+ /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */`
`120`	`121`	`&:has(.MenuOverlay) {`
`121`	`122`	`white-space: normal;`
`122`	`123`	`}`
Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,7 @@`
`24`	`24`	`justify-content: space-between;`
`25`	`25`	`gap: var(--base-size-8);`
`26`	`26`
	`27`	`+ /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */`
`27`	`28`	`&:has([data-kbd-chord]) {`
`28`	`29`	`padding-inline-end: var(--base-size-6);`
`29`	`30`	`}`
`@@ -173,6 +174,7 @@`
`173`	`174`	`margin-right: var(--control-large-gap);`
`174`	`175`	`}`
`175`	`176`
	`177`	`+ /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */`
`176`	`178`	`&:has([data-kbd-chord]) {`
`177`	`179`	`padding-inline-end: var(--base-size-8);`
`178`	`180`	`}`
`@@ -638,6 +640,7 @@`
`638`	`640`
`639`	`641`	`/* Icon-only + Counter */`
`640`	`642`
	`643`	`+ /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */`
`641`	`644`	`&:where([data-has-count]):has([data-component='leadingVisual']):not(:has([data-component='text'])) {`
`642`	`645`	`/* stylelint-disable-next-line primer/spacing */`
`643`	`646`	`padding-inline: var(--control-medium-paddingInline-condensed);`
Original file line number	Diff line number	Diff line change
`@@ -38,6 +38,7 @@`
`38`	`38`	`}`
`39`	`39`
`40`	`40`	`/* this is a workaround until portal based tooltips are fully removed from dotcom */`
	`41`	`+ /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */`
`41`	`42`	`&:has(div:last-child:empty) {`
`42`	`43`	`button,`
`43`	`44`	`a {`
Original file line number	Diff line number	Diff line change
`@@ -34,6 +34,7 @@`
`34`	`34`	`--custom-font-size, --custom-line-height, --custom-font-weight are custom properties that can be used to override the below values.`
`35`	`35`	`We don't want these values to be overridden but still want to allow consumers to override them if needed.`
`36`	`36`	`*/`
	`37`	`+ /* stylelint-disable selector-pseudo-class-disallowed-list -- :has() scoped to CSS Module, audited (github/github-ui#17224) */`
`37`	`38`	`&:has([data-component='TitleArea'][data-size-variant='large']) {`
`38`	`39`	`font-size: var(--custom-font-size, var(--text-title-size-large, 2rem));`
`39`	`40`	`font-weight: var(--custom-font-weight, var(--base-text-weight-normal, 400));`
`@@ -163,6 +164,7 @@`
`163`	`164`	`padding-block-end: var(--base-size-8);`
`164`	`165`	`}`
`165`	`166`	`}`
	`167`	`+ /* stylelint-enable selector-pseudo-class-disallowed-list */`
`166`	`168`
`167`	`169`	`& [data-component='PH_LeadingAction'],`
`168`	`170`	`& [data-component='PH_TrailingAction'],`
Original file line number	Diff line number	Diff line change
`@@ -181,12 +181,14 @@`
`181`	`181`	`background-color: var(--borderColor-default);`
`182`	`182`	`}`
`183`	`183`
	`184`	`+ /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */`
`184`	`185`	`&:has(+ [data-selected])::after,`
`185`	`186`	`&:where([data-selected])::after {`
`186`	`187`	`background-color: transparent;`
`187`	`188`	`}`
`188`	`189`	`}`
`189`	`190`
	`191`	`+ /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */`
`190`	`192`	`&:focus-within:has(:focus-visible) {`
`191`	`193`	`background-color: transparent;`
`192`	`194`	`}`