From 263c25cf47f78402a8842818a0b8b0bd21df5edc Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 28 Jul 2026 20:09:02 +0000
Subject: [PATCH 01/39] Document prop merging conventions

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 contributor-docs/style.md | 53 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/contributor-docs/style.md b/contributor-docs/style.md
index c9dabb0db1a..8d71f6905d4 100644
--- a/contributor-docs/style.md
+++ b/contributor-docs/style.md
@@ -68,6 +68,7 @@ row before the </tbody></table> line.
     - [Utilities](#utilities)
   - [Props](#props)
     - [Prefer applying component rest parameters to the root element rendered by a component](#prefer-applying-component-rest-parameters-to-the-root-element-rendered-by-a-component)
+    - [Merge shared props intentionally](#merge-shared-props-intentionally)
     - [Prefer authoring callback prop types with arguments that can be extended](#prefer-authoring-callback-prop-types-with-arguments-that-can-be-extended)
   - [Hooks](#hooks)
     - [Prefer authoring hooks that accept a `ref` instead of returning a `ref` to apply](#prefer-authoring-hooks-that-accept-a-ref-instead-of-returning-a-ref-to-apply)
@@ -299,6 +300,58 @@ function Example({children, ...rest}: Props) {
 </td></tr>
 </tbody></table>
 
+#### Merge shared props intentionally
+
+When a component and a consumer can both provide a prop, define how those values
+are merged instead of allowing the order of prop spreads to decide accidentally.
+Use the following conventions:
+
+- Event handlers run the component's handler first, then the consumer's handler
+  if the event has not been prevented.
+- Class names are merged with `clsx`.
+- Style objects apply the component's styles first and the consumer's styles
+  second so that the consumer can override them.
+- Other attributes use the consumer's value. If an attribute must be controlled
+  by the component, do not expose it as a prop, or use types that only offer it
+  in the scenarios where the consumer can control it.
+
+For example:
+
+```tsx
+type Props = React.ComponentPropsWithoutRef<'button'>
+
+function Example({className, onClick, style, ...rest}: Props) {
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    performInternalAction(event)
+
+    if (!event.defaultPrevented) {
+      onClick?.(event)
+    }
+  }
+
+  return (
+    <button
+      data-component="Example"
+      {...rest}
+      className={clsx(classes.Example, className)}
+      onClick={handleClick}
+      style={{...defaultStyle, ...style}}
+    />
+  )
+}
+```
+
+When a component requires an attribute for correct behavior, remove it from the
+consumer-facing type instead of silently overriding a value the API accepts:
+
+```tsx
+type Props = Omit<React.ComponentPropsWithoutRef<'button'>, 'type'>
+
+function Example(props: Props) {
+  return <button {...props} type="button" />
+}
+```
+
 #### Prefer authoring callback prop types with arguments that can be extended
 
 When authoring callback props, it is helpful to structure the types for these

From d404b2bd72129fcd02d0524984339eedcb44ae71 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 28 Jul 2026 21:21:08 +0000
Subject: [PATCH 02/39] Add prop merging utility and ADR

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 contributor-docs/adrs/adr-025-prop-merging.md | 114 ++++++++++++++++++
 contributor-docs/style.md                     |  26 ++--
 .../src/utils/__tests__/mergeProps.test.ts    |  84 +++++++++++++
 packages/react/src/utils/mergeProps.ts        |  61 ++++++++++
 4 files changed, 274 insertions(+), 11 deletions(-)
 create mode 100644 contributor-docs/adrs/adr-025-prop-merging.md
 create mode 100644 packages/react/src/utils/__tests__/mergeProps.test.ts
 create mode 100644 packages/react/src/utils/mergeProps.ts

diff --git a/contributor-docs/adrs/adr-025-prop-merging.md b/contributor-docs/adrs/adr-025-prop-merging.md
new file mode 100644
index 00000000000..3b1ff57fd6c
--- /dev/null
+++ b/contributor-docs/adrs/adr-025-prop-merging.md
@@ -0,0 +1,114 @@
+# Prop merging conventions
+
+📆 Date: 2026-07-28
+
+## Status
+
+| Stage          | State       |
+| -------------- | ----------- |
+| Status         | Accepted ✅ |
+| Implementation | Adopted ✅  |
+
+## Context
+
+Primer components often set props on an element while also accepting those same
+props from consumers. Relying on object spread order alone either replaces
+component behavior and styling or prevents consumers from customizing supported
+props. Inconsistent precedence also makes component APIs difficult to predict.
+
+We need one convention for combining component-authored and consumer-authored
+props, plus an implementation that applies it consistently.
+
+## Decision
+
+Components must intentionally merge any prop that both the component and
+consumer can provide. Pass component props first and consumer props second to the
+`mergeProps` utility:
+
+```tsx
+<button
+  {...mergeProps(
+    {
+      className: classes.Example,
+      onClick: handleClick,
+      style: defaultStyle,
+    },
+    props,
+  )}
+/>
+```
+
+`mergeProps(componentProps, consumerProps)` applies these rules:
+
+- Event handlers are composed in argument order. The component handler runs
+  first. The consumer handler runs only if the component handler does not set
+  `event.defaultPrevented`.
+- `className` values are combined with `clsx`, with the component value first.
+- `style` objects are shallowly merged, with the consumer value taking
+  precedence for duplicate properties.
+- All other duplicate props use the consumer value.
+
+If a component must control an attribute for correct behavior, it must not
+expose that attribute unconditionally. Omit it from the public prop type, or use
+a discriminated union that only exposes it in supported scenarios, rather than
+accepting and silently overriding the consumer value.
+
+The utility is an implementation detail for building Primer React components
+and is not part of the package's public API.
+
+### Scenarios requiring separate handling
+
+The general rules do not cover every form of composition:
+
+- **Refs are not composed.** Use `useMergedRefs` when both the component and
+  consumer need the same element reference.
+- **Styles are not deeply merged.** Nested objects and values such as CSS custom
+  property maps are replaced at the first duplicate property.
+- **Cancellation is based on `defaultPrevented`.** The consumer handler is
+  skipped when the first argument's `defaultPrevented` value is truthy after the
+  component handler runs. Calling `stopPropagation()` alone does not stop the
+  consumer handler because both handlers run for the same React event.
+- **Cancellation is synchronous and one-way.** The consumer cannot prevent the
+  component handler because it runs second, and an asynchronous call to
+  `preventDefault()` occurs too late. APIs that require consumer veto before
+  internal behavior need a separate cancellable callback design.
+- **Errors stop composition.** If the component handler throws, the consumer
+  handler does not run.
+- **`on*` callback props are treated as event handlers.** A callback whose name
+  starts with `on` and whose value is a function is composed with the same
+  cancellation behavior, even if it is not a DOM event handler.
+- **Cancellation only considers the first argument.** All callback arguments
+  are forwarded, but only a `defaultPrevented` value on the first argument can
+  cancel the second callback. Zero-argument callbacks run both handlers.
+- **Ordinary prop precedence includes `undefined`.** An explicitly present
+  consumer prop with an `undefined` value replaces the component value unless
+  the prop has special class name, style, or event-handler behavior.
+
+## Consequences
+
+Component behavior and base styling are preserved while consumers retain
+predictable override points. A shared utility reduces hand-written merging logic
+and makes precedence consistent across components.
+
+The convention requires component authors to distinguish supported overrides
+from attributes that the component must own. Event ordering also means consumer
+handlers cannot cancel component work that has already happened.
+
+## Alternatives
+
+### Use prop spread order for every prop
+
+This is concise, but replaces event handlers, class names, and complete style
+objects instead of composing them.
+
+### Always give component props precedence
+
+This preserves implementation details but makes accepted consumer props
+ineffective and creates a misleading API.
+
+### Let consumers run event handlers first
+
+This would let consumers prevent component behavior, but gives consumers control
+over invariants and accessibility behavior that the component owns. APIs that
+need a consumer veto should model it explicitly instead of changing the default
+ordering for all handlers.
diff --git a/contributor-docs/style.md b/contributor-docs/style.md
index 8d71f6905d4..b5a4873dfae 100644
--- a/contributor-docs/style.md
+++ b/contributor-docs/style.md
@@ -315,32 +315,36 @@ Use the following conventions:
   by the component, do not expose it as a prop, or use types that only offer it
   in the scenarios where the consumer can control it.
 
-For example:
+Use the `mergeProps` utility with component props first and consumer props
+second:
 
 ```tsx
 type Props = React.ComponentPropsWithoutRef<'button'>
 
-function Example({className, onClick, style, ...rest}: Props) {
+function Example(props: Props) {
   const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
     performInternalAction(event)
-
-    if (!event.defaultPrevented) {
-      onClick?.(event)
-    }
   }
 
   return (
     <button
-      data-component="Example"
-      {...rest}
-      className={clsx(classes.Example, className)}
-      onClick={handleClick}
-      style={{...defaultStyle, ...style}}
+      {...mergeProps(
+        {
+          'data-component': 'Example',
+          className: classes.Example,
+          onClick: handleClick,
+          style: defaultStyle,
+        },
+        props,
+      )}
     />
   )
 }
 ```
 
+See [ADR-025](./adrs/adr-025-prop-merging.md) for the full decision and
+additional scenarios that require separate handling.
+
 When a component requires an attribute for correct behavior, remove it from the
 consumer-facing type instead of silently overriding a value the API accepts:
 
diff --git a/packages/react/src/utils/__tests__/mergeProps.test.ts b/packages/react/src/utils/__tests__/mergeProps.test.ts
new file mode 100644
index 00000000000..abf87ea9b18
--- /dev/null
+++ b/packages/react/src/utils/__tests__/mergeProps.test.ts
@@ -0,0 +1,84 @@
+import {describe, expect, test, vi} from 'vitest'
+import {mergeProps} from '../mergeProps'
+
+describe('mergeProps', () => {
+  test('combines props and gives the second value precedence', () => {
+    expect(
+      mergeProps(
+        {
+          id: 'component-id',
+          role: 'button',
+        },
+        {
+          id: 'consumer-id',
+          'aria-label': 'Example',
+        },
+      ),
+    ).toEqual({
+      id: 'consumer-id',
+      role: 'button',
+      'aria-label': 'Example',
+    })
+  })
+
+  test('merges class names with clsx', () => {
+    expect(mergeProps({className: 'component'}, {className: ['consumer', {active: true}]})).toEqual({
+      className: 'component consumer active',
+    })
+  })
+
+  test('shallowly merges styles and gives the second value precedence', () => {
+    const componentStyle = {color: 'red', padding: 4}
+    const consumerStyle = {color: 'blue'}
+
+    const merged = mergeProps({style: componentStyle}, {style: consumerStyle})
+
+    expect(merged.style).toEqual({color: 'blue', padding: 4})
+    expect(componentStyle).toEqual({color: 'red', padding: 4})
+    expect(consumerStyle).toEqual({color: 'blue'})
+  })
+
+  test('runs event handlers in order', () => {
+    const calls: string[] = []
+    const event = {defaultPrevented: false}
+    const componentHandler = vi.fn((_event: typeof event, _value: string) => calls.push('component'))
+    const consumerHandler = vi.fn((_event: typeof event, _value: string) => calls.push('consumer'))
+
+    const merged = mergeProps({onClick: componentHandler}, {onClick: consumerHandler})
+    merged.onClick(event, 'value')
+
+    expect(calls).toEqual(['component', 'consumer'])
+    expect(componentHandler).toHaveBeenCalledWith(event, 'value')
+    expect(consumerHandler).toHaveBeenCalledWith(event, 'value')
+  })
+
+  test('does not run the second event handler when the first prevents the event', () => {
+    const event = {
+      defaultPrevented: false,
+      preventDefault() {
+        this.defaultPrevented = true
+      },
+    }
+    const componentHandler = vi.fn((currentEvent: typeof event) => {
+      currentEvent.preventDefault()
+    })
+    const consumerHandler = vi.fn()
+
+    const merged = mergeProps({onClick: componentHandler}, {onClick: consumerHandler})
+    merged.onClick(event)
+
+    expect(componentHandler).toHaveBeenCalledWith(event)
+    expect(consumerHandler).not.toHaveBeenCalled()
+  })
+
+  test('composes zero-argument callbacks', () => {
+    const componentHandler = vi.fn()
+    const consumerHandler = vi.fn()
+
+    const merged = mergeProps({onDismiss: componentHandler}, {onDismiss: consumerHandler})
+    merged.onDismiss()
+
+    expect(componentHandler).toHaveBeenCalledOnce()
+    expect(consumerHandler).toHaveBeenCalledOnce()
+  })
+})
diff --git a/packages/react/src/utils/mergeProps.ts b/packages/react/src/utils/mergeProps.ts
new file mode 100644
index 00000000000..53ab175d6d2
--- /dev/null
+++ b/packages/react/src/utils/mergeProps.ts
@@ -0,0 +1,61 @@
+import {clsx} from 'clsx'
+import type {Merge} from './types'
+
+type EventHandler = (...args: unknown[]) => void
+type ClassValue = Parameters<typeof clsx>[number]
+
+function mergeProps<A extends object, B extends object = A>(a: A, b: B): Merge<A, B> {
+  const merged = {...a} as Record<string, unknown>
+
+  for (const [key, value] of Object.entries(b)) {
+    if (key in merged) {
+      const existing = merged[key]
+
+      if (key === 'className') {
+        merged[key] = clsx(existing as ClassValue, value as ClassValue)
+      } else if (isEventHandlerKey(key) && isEventHandler(existing) && isEventHandler(value)) {
+        merged[key] = composeEventHandlers(existing, value)
+      } else if (key === 'style') {
+        merged[key] = mergeStyle(existing, value)
+      } else {
+        merged[key] = value
+      }
+    } else {
+      merged[key] = value
+    }
+  }
+
+  return merged as Merge<A, B>
+}
+
+function composeEventHandlers(a: EventHandler, b: EventHandler) {
+  return (...args: Parameters<EventHandler>) => {
+    a(...args)
+
+    const event = args[0] as {defaultPrevented?: boolean} | undefined
+    if (!event?.defaultPrevented) {
+      b(...args)
+    }
+  }
+}
+
+function isEventHandlerKey(key: string) {
+  return key.startsWith('on')
+}
+
+function isEventHandler(value: unknown): value is EventHandler {
+  return typeof value === 'function'
+}
+
+function mergeStyle(a: unknown, b: unknown) {
+  return {
+    ...(isObject(a) ? a : {}),
+    ...(isObject(b) ? b : {}),
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+export {mergeProps}

From bc5e845c723e9706fb39b3af934dbdfc807e04d7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 28 Jul 2026 21:31:02 +0000
Subject: [PATCH 03/39] Remove ADR reference from style guide

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 contributor-docs/style.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/contributor-docs/style.md b/contributor-docs/style.md
index b5a4873dfae..8bffb03f3fd 100644
--- a/contributor-docs/style.md
+++ b/contributor-docs/style.md
@@ -342,9 +342,6 @@ function Example(props: Props) {
 }
 ```
 
-See [ADR-025](./adrs/adr-025-prop-merging.md) for the full decision and
-additional scenarios that require separate handling.
-
 When a component requires an attribute for correct behavior, remove it from the
 consumer-facing type instead of silently overriding a value the API accepts:
 

From 7c0ad501373f506c27ae49fa2e46eb7d8968774a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 28 Jul 2026 21:35:50 +0000
Subject: [PATCH 04/39] Mark prop merging ADR as proposed

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 contributor-docs/adrs/adr-025-prop-merging.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/contributor-docs/adrs/adr-025-prop-merging.md b/contributor-docs/adrs/adr-025-prop-merging.md
index 3b1ff57fd6c..b12a6a6ceb2 100644
--- a/contributor-docs/adrs/adr-025-prop-merging.md
+++ b/contributor-docs/adrs/adr-025-prop-merging.md
@@ -6,8 +6,8 @@
 
 | Stage          | State       |
 | -------------- | ----------- |
-| Status         | Accepted ✅ |
-| Implementation | Adopted ✅  |
+| Status         | Proposed ⚠️ |
+| Implementation | Pending ⚠️  |
 
 ## Context
 

From ff2f94a4dc7770b4e185dcfa892dc9e18e3c0b9a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Jul 2026 15:21:48 +0000
Subject: [PATCH 05/39] Document React 19 ref prop behavior

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 contributor-docs/adrs/adr-025-prop-merging.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/contributor-docs/adrs/adr-025-prop-merging.md b/contributor-docs/adrs/adr-025-prop-merging.md
index b12a6a6ceb2..1061e370636 100644
--- a/contributor-docs/adrs/adr-025-prop-merging.md
+++ b/contributor-docs/adrs/adr-025-prop-merging.md
@@ -60,8 +60,9 @@ and is not part of the package's public API.
 
 The general rules do not cover every form of composition:
 
-- **Refs are not composed.** Use `useMergedRefs` when both the component and
-  consumer need the same element reference.
+- **Refs are not composed.** In React 19, `ref` is passed as a prop, but it still
+  requires separate composition. Use `useMergedRefs` when both the component
+  and consumer need the same element reference.
 - **Styles are not deeply merged.** Nested objects and values such as CSS custom
   property maps are replaced at the first duplicate property.
 - **Cancellation is based on `defaultPrevented`.** The consumer handler is

From 2c2a9ca77259539cd497d2b36ef608e1e259423a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 30 Jul 2026 16:10:43 +0000
Subject: [PATCH 06/39] docs: add typed prop-gating examples to ADR-025

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 contributor-docs/adrs/adr-025-prop-merging.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/contributor-docs/adrs/adr-025-prop-merging.md b/contributor-docs/adrs/adr-025-prop-merging.md
index 1061e370636..497888f448d 100644
--- a/contributor-docs/adrs/adr-025-prop-merging.md
+++ b/contributor-docs/adrs/adr-025-prop-merging.md
@@ -53,6 +53,24 @@ expose that attribute unconditionally. Omit it from the public prop type, or use
 a discriminated union that only exposes it in supported scenarios, rather than
 accepting and silently overriding the consumer value.
 
+For example:
+
+```tsx
+// Component-owned attribute: `type` is fixed internally and is not public API.
+type IconButtonProps = Omit<React.ComponentPropsWithoutRef<'button'>, 'type'>
+```
+
+```tsx
+// Conditional attributes: only expose anchor-only props when `as: 'a'`.
+type ButtonLikeProps =
+  | ({
+      as?: 'button'
+    } & Omit<React.ComponentPropsWithoutRef<'button'>, 'href' | 'target' | 'rel'>)
+  | ({
+      as: 'a'
+    } & React.ComponentPropsWithoutRef<'a'>)
+```
+
 The utility is an implementation detail for building Primer React components
 and is not part of the package's public API.
 

From e2d6bd3f32c5812c9de5c8601d127cbc02fa9038 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 4 Aug 2026 15:50:11 -0500
Subject: [PATCH 07/39] Document mergeProps function behavior

Add documentation for mergeProps utility function.
---
 packages/react/src/utils/mergeProps.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/packages/react/src/utils/mergeProps.ts b/packages/react/src/utils/mergeProps.ts
index 53ab175d6d2..90fcad03a01 100644
--- a/packages/react/src/utils/mergeProps.ts
+++ b/packages/react/src/utils/mergeProps.ts
@@ -4,6 +4,15 @@ import type {Merge} from './types'
 type EventHandler = (...args: unknown[]) => void
 type ClassValue = Parameters<typeof clsx>[number]
 
+/**
+ * Applies our rules for merging props between two objects. This utility handles the following scenarios:
+ * 
+ * - Merging `className` values
+ * - Merging event handlers
+ * - Merging `style` values
+ *
+ * In other cases, if a key exists in both `A` and `B` then the value in `B` will be used in the final result
+ */
 function mergeProps<A extends object, B extends object = A>(a: A, b: B): Merge<A, B> {
   const merged = {...a} as Record<string, unknown>
 

From 7bd1b5283569fac5bcb080a1ee2be6313fbd1591 Mon Sep 17 00:00:00 2001
From: joshblack <3901764+joshblack@users.noreply.github.com>
Date: Tue, 4 Aug 2026 20:57:19 +0000
Subject: [PATCH 08/39] chore: auto-fix lint and formatting issues

---
 packages/react/src/utils/mergeProps.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/utils/mergeProps.ts b/packages/react/src/utils/mergeProps.ts
index 90fcad03a01..8d71428d719 100644
--- a/packages/react/src/utils/mergeProps.ts
+++ b/packages/react/src/utils/mergeProps.ts
@@ -6,7 +6,7 @@ type ClassValue = Parameters<typeof clsx>[number]
 
 /**
  * Applies our rules for merging props between two objects. This utility handles the following scenarios:
- * 
+ *
  * - Merging `className` values
  * - Merging event handlers
  * - Merging `style` values

From a069b88bce476f3bc0ff67f1b26737490ac4e738 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Mon, 10 Aug 2026 16:10:16 -0500
Subject: [PATCH 09/39] Handle undefined consumer event handlers

Treat undefined consumer handlers as absent so call sites can pass forwardable props directly to mergeProps.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: faa7e8da-1bd6-4c1c-831d-50b021ccc03b
---
 contributor-docs/adrs/adr-025-prop-merging.md | 23 ++++++++++++++++++-
 .../src/utils/__tests__/mergeProps.test.ts    |  8 +++++++
 packages/react/src/utils/mergeProps.ts        |  8 +++++--
 3 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/contributor-docs/adrs/adr-025-prop-merging.md b/contributor-docs/adrs/adr-025-prop-merging.md
index 497888f448d..bfe3df3ecf1 100644
--- a/contributor-docs/adrs/adr-025-prop-merging.md
+++ b/contributor-docs/adrs/adr-025-prop-merging.md
@@ -42,12 +42,33 @@ consumer can provide. Pass component props first and consumer props second to th
 
 - Event handlers are composed in argument order. The component handler runs
   first. The consumer handler runs only if the component handler does not set
-  `event.defaultPrevented`.
+  `event.defaultPrevented`. An `undefined` consumer handler is treated as absent
+  and does not replace the component handler.
 - `className` values are combined with `clsx`, with the component value first.
 - `style` objects are shallowly merged, with the consumer value taking
   precedence for duplicate properties.
 - All other duplicate props use the consumer value.
 
+Keep forwardable consumer props together and pass them directly as the second
+argument. Do not conditionally add optional event handlers before calling
+`mergeProps`; the utility handles omitted handlers:
+
+```tsx
+function Example({componentOnlyProp, ...rest}: Props) {
+  return (
+    <button
+      {...mergeProps(
+        {
+          className: classes.Example,
+          onClick: handleClick,
+        },
+        rest,
+      )}
+    />
+  )
+}
+```
+
 If a component must control an attribute for correct behavior, it must not
 expose that attribute unconditionally. Omit it from the public prop type, or use
 a discriminated union that only exposes it in supported scenarios, rather than
diff --git a/packages/react/src/utils/__tests__/mergeProps.test.ts b/packages/react/src/utils/__tests__/mergeProps.test.ts
index abf87ea9b18..4d330791ce2 100644
--- a/packages/react/src/utils/__tests__/mergeProps.test.ts
+++ b/packages/react/src/utils/__tests__/mergeProps.test.ts
@@ -52,6 +52,14 @@ describe('mergeProps', () => {
     expect(consumerHandler).toHaveBeenCalledWith(event, 'value')
   })
 
+  test('preserves the first event handler when the second is undefined', () => {
+    const componentHandler = vi.fn()
+
+    const merged = mergeProps({onClick: componentHandler}, {onClick: undefined})
+
+    expect(merged.onClick).toBe(componentHandler)
+  })
+
   test('does not run the second event handler when the first prevents the event', () => {
     const event = {
       defaultPrevented: false,
diff --git a/packages/react/src/utils/mergeProps.ts b/packages/react/src/utils/mergeProps.ts
index 8d71428d719..a7d6df5de9b 100644
--- a/packages/react/src/utils/mergeProps.ts
+++ b/packages/react/src/utils/mergeProps.ts
@@ -22,8 +22,12 @@ function mergeProps<A extends object, B extends object = A>(a: A, b: B): Merge<A
 
       if (key === 'className') {
         merged[key] = clsx(existing as ClassValue, value as ClassValue)
-      } else if (isEventHandlerKey(key) && isEventHandler(existing) && isEventHandler(value)) {
-        merged[key] = composeEventHandlers(existing, value)
+      } else if (isEventHandlerKey(key) && isEventHandler(existing)) {
+        if (isEventHandler(value)) {
+          merged[key] = composeEventHandlers(existing, value)
+        } else if (value !== undefined) {
+          merged[key] = value
+        }
       } else if (key === 'style') {
         merged[key] = mergeStyle(existing, value)
       } else {

From 1913ffbb39d3ea58f9b7fcccd8dc1e042376e6f3 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Mon, 10 Aug 2026 16:18:59 -0500
Subject: [PATCH 10/39] Clarify mergeProps call site conventions

Document how to forward destructured consumer props without rebuilding the second argument and prefer conventional internal prop values.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: faa7e8da-1bd6-4c1c-831d-50b021ccc03b
---
 contributor-docs/adrs/adr-025-prop-merging.md | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/contributor-docs/adrs/adr-025-prop-merging.md b/contributor-docs/adrs/adr-025-prop-merging.md
index bfe3df3ecf1..962660e41d0 100644
--- a/contributor-docs/adrs/adr-025-prop-merging.md
+++ b/contributor-docs/adrs/adr-025-prop-merging.md
@@ -51,16 +51,24 @@ consumer can provide. Pass component props first and consumer props second to th
 
 Keep forwardable consumer props together and pass them directly as the second
 argument. Do not conditionally add optional event handlers before calling
-`mergeProps`; the utility handles omitted handlers:
+`mergeProps`; the utility handles omitted handlers. If a component must read or
+normalize a consumer prop, destructure it and include the forwarded or derived
+value in the first object instead of reconstructing the second object.
+
+Use conventional prop values in the first object. For example, combine multiple
+internal class names with `clsx` before calling `mergeProps` instead of passing
+array or object shorthand:
 
 ```tsx
-function Example({componentOnlyProp, ...rest}: Props) {
+function Example({checked, ...rest}: Props) {
   return (
-    <button
+    <input
       {...mergeProps(
         {
-          className: classes.Example,
-          onClick: handleClick,
+          className: clsx(classes.Control, classes.Example),
+          onChange: handleChange,
+          'aria-checked': checked ? 'true' : 'false',
+          checked,
         },
         rest,
       )}

From cd253a03e3be96337a3bb930f2d1715bb3ba4a14 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 16:48:42 -0500
Subject: [PATCH 11/39] Clarify inline class name merging

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 contributor-docs/style.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/contributor-docs/style.md b/contributor-docs/style.md
index 8bffb03f3fd..b76f56d6a98 100644
--- a/contributor-docs/style.md
+++ b/contributor-docs/style.md
@@ -308,7 +308,7 @@ Use the following conventions:
 
 - Event handlers run the component's handler first, then the consumer's handler
   if the event has not been prevented.
-- Class names are merged with `clsx`.
+- Class names are merged inline by the component with `clsx`.
 - Style objects apply the component's styles first and the consumer's styles
   second so that the consumer can override them.
 - Other attributes use the consumer's value. If an attribute must be controlled
@@ -321,7 +321,7 @@ second:
 ```tsx
 type Props = React.ComponentPropsWithoutRef<'button'>
 
-function Example(props: Props) {
+function Example({className, ...props}: Props) {
   const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
     performInternalAction(event)
   }
@@ -331,7 +331,7 @@ function Example(props: Props) {
       {...mergeProps(
         {
           'data-component': 'Example',
-          className: classes.Example,
+          className: clsx(classes.Example, className),
           onClick: handleClick,
           style: defaultStyle,
         },
@@ -342,6 +342,9 @@ function Example(props: Props) {
 }
 ```
 
+Destructure the consumer's `className` and keep the `clsx` call at the component
+call site. Do not rely on `mergeProps` to add the consumer class name later.
+
 When a component requires an attribute for correct behavior, remove it from the
 consumer-facing type instead of silently overriding a value the API accepts:
 
@@ -353,6 +356,10 @@ function Example(props: Props) {
 }
 ```
 
+Only move an attribute after the merged spread when the component already owns
+that attribute. Preserve existing consumer precedence when the attribute has
+historically been overridable.
+
 #### Prefer authoring callback prop types with arguments that can be extended
 
 When authoring callback props, it is helpful to structure the types for these

From 4274bec1efc5529d6a8e1702586e7735f9d5880d Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 16:50:25 -0500
Subject: [PATCH 12/39] Document ref ordering with mergeProps

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 contributor-docs/adrs/adr-025-prop-merging.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/contributor-docs/adrs/adr-025-prop-merging.md b/contributor-docs/adrs/adr-025-prop-merging.md
index 962660e41d0..023994dfe79 100644
--- a/contributor-docs/adrs/adr-025-prop-merging.md
+++ b/contributor-docs/adrs/adr-025-prop-merging.md
@@ -109,7 +109,14 @@ The general rules do not cover every form of composition:
 
 - **Refs are not composed.** In React 19, `ref` is passed as a prop, but it still
   requires separate composition. Use `useMergedRefs` when both the component
-  and consumer need the same element reference.
+  and consumer need the same element reference. Keep `ref` before the
+  `mergeProps` spread so ref handling is visibly separate and merged props are
+  applied last:
+
+  ```tsx
+  <button ref={mergedRef} {...mergeProps(componentProps, consumerProps)} />
+  ```
+
 - **Styles are not deeply merged.** Nested objects and values such as CSS custom
   property maps are replaced at the first duplicate property.
 - **Cancellation is based on `defaultPrevented`.** The consumer handler is

From a63333a118eff53e7caecca2e1f24cc9df904d51 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Jul 2026 14:47:58 +0000
Subject: [PATCH 13/39] Add merge props ESLint migration rule

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 .github/workflows/migration-status.yml        | 13 +++
 eslint.config.mjs                             |  2 +
 package-lock.json                             | 20 ++++
 packages/eslint-config/package.json           | 23 +++++
 packages/eslint-config/src/index.test.ts      |  9 ++
 packages/eslint-config/src/index.ts           | 24 +++++
 .../src/rules/preferMergeProps.test.ts        | 68 +++++++++++++
 .../src/rules/preferMergeProps.ts             | 95 +++++++++++++++++++
 packages/eslint-config/tsconfig.json          |  7 ++
 packages/eslint-config/vitest.config.ts       |  7 ++
 script/merge-props-migration-status.mts       | 65 +++++++++++++
 11 files changed, 333 insertions(+)
 create mode 100644 packages/eslint-config/package.json
 create mode 100644 packages/eslint-config/src/index.test.ts
 create mode 100644 packages/eslint-config/src/index.ts
 create mode 100644 packages/eslint-config/src/rules/preferMergeProps.test.ts
 create mode 100644 packages/eslint-config/src/rules/preferMergeProps.ts
 create mode 100644 packages/eslint-config/tsconfig.json
 create mode 100644 packages/eslint-config/vitest.config.ts
 create mode 100644 script/merge-props-migration-status.mts

diff --git a/.github/workflows/migration-status.yml b/.github/workflows/migration-status.yml
index 9b74e5e6f78..d2cf2599c1f 100644
--- a/.github/workflows/migration-status.yml
+++ b/.github/workflows/migration-status.yml
@@ -5,6 +5,19 @@ on:
   workflow_dispatch:
 
 jobs:
+  merge-props:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - name: install dependencies
+        run: npm ci
+      - name: run migration script
+        run: node script/merge-props-migration-status.mts >> $GITHUB_STEP_SUMMARY
+
   react-compiler:
     runs-on: ubuntu-latest
     steps:
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 22647924d8e..7092b2f8d56 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -3,6 +3,7 @@ import {fileURLToPath} from 'node:url'
 import {fixupConfigRules, fixupPluginRules} from '@eslint/compat'
 import {FlatCompat} from '@eslint/eslintrc'
 import js from '@eslint/js'
+import primerConfig from '@primer/eslint-config'
 import eslintReact from '@eslint-react/eslint-plugin'
 import vitest from '@vitest/eslint-plugin'
 import {defineConfig, globalIgnores} from 'eslint/config'
@@ -58,6 +59,7 @@ const config = defineConfig([
   ]),
 
   js.configs.recommended,
+  primerConfig,
 
   ...fixupConfigRules([react.configs.flat.recommended, react.configs.flat['jsx-runtime']]),
   reactHooks.configs.flat['recommended-latest'],
diff --git a/package-lock.json b/package-lock.json
index 055b4792707..27849dc14ae 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -6627,6 +6627,10 @@
       "resolved": "packages/doc-gen",
       "link": true
     },
+    "node_modules/@primer/eslint-config": {
+      "resolved": "packages/eslint-config",
+      "link": true
+    },
     "node_modules/@primer/mcp": {
       "resolved": "packages/mcp",
       "link": true
@@ -28958,6 +28962,22 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "packages/eslint-config": {
+      "name": "@primer/eslint-config",
+      "version": "0.0.0",
+      "dependencies": {
+        "@typescript-eslint/utils": "^8.59.1"
+      },
+      "devDependencies": {
+        "@primer/vitest-config": "^0.0.0",
+        "eslint": "^10.7.0",
+        "typescript": "^6.0.3",
+        "vitest": "^4.1.9"
+      },
+      "peerDependencies": {
+        "eslint": "^10.7.0"
+      }
+    },
     "packages/mcp": {
       "name": "@primer/mcp",
       "version": "1.0.0",
diff --git a/packages/eslint-config/package.json b/packages/eslint-config/package.json
new file mode 100644
index 00000000000..1cdac91ed43
--- /dev/null
+++ b/packages/eslint-config/package.json
@@ -0,0 +1,23 @@
+{
+  "name": "@primer/eslint-config",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": "./src/index.ts",
+  "scripts": {
+    "test": "vitest --run",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "eslint": "^10.7.0"
+  },
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.59.1"
+  },
+  "devDependencies": {
+    "@primer/vitest-config": "^0.0.0",
+    "eslint": "^10.7.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}
diff --git a/packages/eslint-config/src/index.test.ts b/packages/eslint-config/src/index.test.ts
new file mode 100644
index 00000000000..a85314c3b18
--- /dev/null
+++ b/packages/eslint-config/src/index.test.ts
@@ -0,0 +1,9 @@
+import {describe, expect, test} from 'vitest'
+import {config, plugin} from './index.ts'
+
+describe('@primer/eslint-config', () => {
+  test('exports the prefer-merge-props rule disabled by default', () => {
+    expect(plugin.rules?.['prefer-merge-props']).toBeDefined()
+    expect(config.rules?.['primer/prefer-merge-props']).toBe('off')
+  })
+})
diff --git a/packages/eslint-config/src/index.ts b/packages/eslint-config/src/index.ts
new file mode 100644
index 00000000000..c1d31e635e3
--- /dev/null
+++ b/packages/eslint-config/src/index.ts
@@ -0,0 +1,24 @@
+import type {TSESLint} from '@typescript-eslint/utils'
+import {preferMergeProps} from './rules/preferMergeProps.ts'
+
+const plugin: TSESLint.FlatConfig.Plugin = {
+  meta: {
+    name: '@primer/eslint-config',
+  },
+  rules: {
+    'prefer-merge-props': preferMergeProps,
+  },
+}
+
+const config: TSESLint.FlatConfig.Config = {
+  name: '@primer/eslint-config',
+  plugins: {
+    primer: plugin,
+  },
+  rules: {
+    'primer/prefer-merge-props': 'off',
+  },
+}
+
+export {config, plugin, preferMergeProps}
+export default config
diff --git a/packages/eslint-config/src/rules/preferMergeProps.test.ts b/packages/eslint-config/src/rules/preferMergeProps.test.ts
new file mode 100644
index 00000000000..d8cdb28987b
--- /dev/null
+++ b/packages/eslint-config/src/rules/preferMergeProps.test.ts
@@ -0,0 +1,68 @@
+import {RuleTester} from 'eslint'
+import {describe, it} from 'vitest'
+import {preferMergeProps} from './preferMergeProps.ts'
+
+RuleTester.describe = describe
+RuleTester.it = it
+RuleTester.itOnly = it
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    parserOptions: {
+      ecmaFeatures: {
+        jsx: true,
+      },
+    },
+  },
+})
+
+ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<RuleTester['run']>[1], {
+  valid: [
+    {
+      name: 'accepts outermost props merged with mergeProps',
+      code: `const example = <button {...mergeProps(componentProps, props)} />`,
+    },
+    {
+      name: 'accepts a namespaced mergeProps utility',
+      code: `const example = <button {...utils.mergeProps(componentProps, props)} />`,
+    },
+    {
+      name: 'accepts props previously merged with mergeProps',
+      code: `
+        const mergedProps = mergeProps(componentProps, props)
+        const example = <button {...mergedProps} />
+      `,
+    },
+    {
+      name: 'ignores elements without spread props',
+      code: `const example = <button type="button" />`,
+    },
+    {
+      name: 'ignores spread props on nested elements',
+      code: `const example = <div><button {...props} /></div>`,
+    },
+    {
+      name: 'ignores spread props inside an outermost fragment',
+      code: `const example = <><button {...props} /></>`,
+    },
+  ],
+  invalid: [
+    {
+      name: 'reports direct props spread on an outermost element',
+      code: `const example = <button {...props} />`,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports each unmerged spread on an outermost element',
+      code: `const example = <button {...componentProps} {...props} />`,
+      errors: [{messageId: 'preferMergeProps'}, {messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports outermost elements in conditional branches',
+      code: `const example = condition ? <button {...props} /> : <a {...props} />`,
+      errors: [{messageId: 'preferMergeProps'}, {messageId: 'preferMergeProps'}],
+    },
+  ],
+})
diff --git a/packages/eslint-config/src/rules/preferMergeProps.ts b/packages/eslint-config/src/rules/preferMergeProps.ts
new file mode 100644
index 00000000000..944377648eb
--- /dev/null
+++ b/packages/eslint-config/src/rules/preferMergeProps.ts
@@ -0,0 +1,95 @@
+import {ASTUtils, type TSESLint, type TSESTree} from '@typescript-eslint/utils'
+
+type MessageIds = 'preferMergeProps'
+
+const preferMergeProps: TSESLint.RuleModule<MessageIds> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Require spread props on outermost JSX elements to use mergeProps',
+    },
+    messages: {
+      preferMergeProps:
+        'Spread props on an outermost JSX element with mergeProps so component and consumer props are merged intentionally.',
+    },
+    schema: [],
+  },
+  create(context) {
+    const {sourceCode} = context
+
+    return {
+      JSXOpeningElement(node) {
+        if (!isOutermostElement(node.parent)) {
+          return
+        }
+
+        for (const attribute of node.attributes) {
+          if (
+            attribute.type === 'JSXSpreadAttribute' &&
+            !isMergedProps(attribute.argument, sourceCode.getScope(attribute))
+          ) {
+            context.report({
+              node: attribute,
+              messageId: 'preferMergeProps',
+            })
+          }
+        }
+      },
+    }
+  },
+}
+
+function isOutermostElement(element: TSESTree.JSXElement): boolean {
+  let ancestor: TSESTree.Node | undefined = element.parent
+
+  while (ancestor) {
+    if (ancestor.type === 'JSXElement' || ancestor.type === 'JSXFragment') {
+      return false
+    }
+    ancestor = ancestor.parent
+  }
+
+  return true
+}
+
+function isMergedProps(argument: TSESTree.Expression, scope: TSESLint.Scope.Scope): boolean {
+  if (isMergePropsCall(argument)) {
+    return true
+  }
+
+  if (argument.type !== 'Identifier') {
+    return false
+  }
+
+  const variable = ASTUtils.findVariable(scope, argument)
+  return (
+    variable?.defs.some(definition => {
+      return (
+        definition.type === 'Variable' &&
+        definition.parent.kind === 'const' &&
+        definition.node.init !== null &&
+        isMergePropsCall(definition.node.init)
+      )
+    }) ?? false
+  )
+}
+
+function isMergePropsCall(argument: TSESTree.Expression): boolean {
+  if (argument.type !== 'CallExpression') {
+    return false
+  }
+
+  const {callee} = argument
+  if (callee.type === 'Identifier') {
+    return callee.name === 'mergeProps'
+  }
+
+  return (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'mergeProps'
+  )
+}
+
+export {preferMergeProps}
diff --git a/packages/eslint-config/tsconfig.json b/packages/eslint-config/tsconfig.json
new file mode 100644
index 00000000000..02e8975d4d9
--- /dev/null
+++ b/packages/eslint-config/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src", "vitest.config.ts"]
+}
diff --git a/packages/eslint-config/vitest.config.ts b/packages/eslint-config/vitest.config.ts
new file mode 100644
index 00000000000..6c7353fc4e0
--- /dev/null
+++ b/packages/eslint-config/vitest.config.ts
@@ -0,0 +1,7 @@
+import {defineConfig} from '@primer/vitest-config/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+  },
+})
diff --git a/script/merge-props-migration-status.mts b/script/merge-props-migration-status.mts
new file mode 100644
index 00000000000..30280b64501
--- /dev/null
+++ b/script/merge-props-migration-status.mts
@@ -0,0 +1,65 @@
+import path from 'node:path'
+import {ESLint} from 'eslint'
+
+const directory = path.resolve(import.meta.dirname, '..')
+const ruleId = 'primer/prefer-merge-props'
+const eslint = new ESLint({
+  cwd: directory,
+  overrideConfig: [
+    {
+      rules: {
+        [ruleId]: 'error',
+      },
+    },
+  ],
+})
+const results = await eslint.lintFiles(['packages/react/src/**/*.{ts,tsx}'])
+const fatalMessages = results.flatMap(result => {
+  return result.messages
+    .filter(message => message.fatal)
+    .map(message => `${result.filePath}:${message.line} ${message.message}`)
+})
+
+if (fatalMessages.length > 0) {
+  throw new Error(`Unable to generate the mergeProps migration report:\n${fatalMessages.join('\n')}`)
+}
+
+const affectedResults = results.filter(result => {
+  return result.messages.some(message => message.ruleId === ruleId)
+})
+const violationCount = affectedResults.reduce((count, result) => {
+  return count + result.messages.filter(message => message.ruleId === ruleId).length
+}, 0)
+
+write(`
+# mergeProps Migration
+
+This report tracks outermost JSX prop spreads that should migrate to \`mergeProps\`.
+
+## Status
+
+**Outermost prop spreads to migrate:** ${violationCount}
+
+**Affected files:** ${affectedResults.length} of ${results.length}
+`)
+
+write(`
+## Affected Files (${affectedResults.length})
+
+| Filepath | Locations | Violations |
+| :------- | :-------- | :--------- |`)
+
+for (const result of affectedResults) {
+  const relativePath = path.relative(directory, result.filePath)
+  const messages = result.messages.filter(message => message.ruleId === ruleId)
+  const locations = messages.map(
+    message => `[L${message.line}](https://github.com/primer/react/blob/main/${relativePath}#L${message.line})`,
+  )
+  const link = `[\`${relativePath}\`](https://github.com/primer/react/blob/main/${relativePath})`
+
+  write(`| ${link} | ${locations.join(', ')} | ${messages.length} |`)
+}
+
+function write(value: string): void {
+  process.stdout.write(`${value}\n`)
+}

From e3ab7d9423e307b6c9915191c4bed2e17e81dfbd Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Jul 2026 16:06:02 +0000
Subject: [PATCH 14/39] Expand merge props rule coverage

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 .../src/rules/preferMergeProps.test.ts        | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/packages/eslint-config/src/rules/preferMergeProps.test.ts b/packages/eslint-config/src/rules/preferMergeProps.test.ts
index d8cdb28987b..0c0131c86cd 100644
--- a/packages/eslint-config/src/rules/preferMergeProps.test.ts
+++ b/packages/eslint-config/src/rules/preferMergeProps.test.ts
@@ -47,6 +47,25 @@ ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<R
       name: 'ignores spread props inside an outermost fragment',
       code: `const example = <><button {...props} /></>`,
     },
+    {
+      name: 'ignores spread props on elements nested in conditional content',
+      code: `const example = <div>{condition ? <button {...props} /> : null}</div>`,
+    },
+    {
+      name: 'ignores spread props on elements nested in mapped content',
+      code: `const example = <ul>{items.map(item => <li {...item} />)}</ul>`,
+    },
+    {
+      name: 'ignores spread props on elements nested in a render prop',
+      code: `const example = <Component render={() => <button {...props} />} />`,
+    },
+    {
+      name: 'ignores object spread expressions outside JSX',
+      code: `
+        const copiedProps = {...props}
+        const example = <button type="button" />
+      `,
+    },
   ],
   invalid: [
     {
@@ -64,5 +83,35 @@ ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<R
       code: `const example = condition ? <button {...props} /> : <a {...props} />`,
       errors: [{messageId: 'preferMergeProps'}, {messageId: 'preferMergeProps'}],
     },
+    {
+      name: 'reports unmerged props on an outermost custom component',
+      code: `const example = <Button {...props} />`,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports unmerged props on an outermost member component',
+      code: `const example = <ActionList.Item {...props} />`,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports props returned from another utility',
+      code: `const example = <button {...getProps()} />`,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports props copied into an object expression',
+      code: `const example = <button {...{...props}} />`,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports only the unmerged spread alongside merged props',
+      code: `const example = <button {...mergeProps(componentProps, props)} {...otherProps} />`,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports props on outermost elements in logical expressions',
+      code: `const example = condition && <button {...props} />`,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
   ],
 })

From c115012bdcdcc463dea8bfeb4e00e1e875ebd85c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Jul 2026 16:07:02 +0000
Subject: [PATCH 15/39] Clarify function spread test name

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 packages/eslint-config/src/rules/preferMergeProps.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/eslint-config/src/rules/preferMergeProps.test.ts b/packages/eslint-config/src/rules/preferMergeProps.test.ts
index 0c0131c86cd..fadf5fe0e34 100644
--- a/packages/eslint-config/src/rules/preferMergeProps.test.ts
+++ b/packages/eslint-config/src/rules/preferMergeProps.test.ts
@@ -94,7 +94,7 @@ ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<R
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
-      name: 'reports props returned from another utility',
+      name: 'reports spread props returned from a function call',
       code: `const example = <button {...getProps()} />`,
       errors: [{messageId: 'preferMergeProps'}],
     },

From 2c0ac969696b41b071a96035d5f16f9f1bc16942 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Jul 2026 16:41:19 +0000
Subject: [PATCH 16/39] Scope merge props rule to component roots

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 .../src/rules/preferMergeProps.test.ts        | 119 +++++++++---
 .../src/rules/preferMergeProps.ts             | 177 +++++++++++++++++-
 script/merge-props-migration-status.mts       |   4 +-
 3 files changed, 263 insertions(+), 37 deletions(-)

diff --git a/packages/eslint-config/src/rules/preferMergeProps.test.ts b/packages/eslint-config/src/rules/preferMergeProps.test.ts
index fadf5fe0e34..e72c9c1aaad 100644
--- a/packages/eslint-config/src/rules/preferMergeProps.test.ts
+++ b/packages/eslint-config/src/rules/preferMergeProps.test.ts
@@ -21,43 +21,45 @@ const ruleTester = new RuleTester({
 ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<RuleTester['run']>[1], {
   valid: [
     {
-      name: 'accepts outermost props merged with mergeProps',
-      code: `const example = <button {...mergeProps(componentProps, props)} />`,
+      name: 'accepts component root props merged with mergeProps',
+      code: `function Example() { return <button {...mergeProps(componentProps, props)} /> }`,
     },
     {
       name: 'accepts a namespaced mergeProps utility',
-      code: `const example = <button {...utils.mergeProps(componentProps, props)} />`,
+      code: `function Example() { return <button {...utils.mergeProps(componentProps, props)} /> }`,
     },
     {
       name: 'accepts props previously merged with mergeProps',
       code: `
-        const mergedProps = mergeProps(componentProps, props)
-        const example = <button {...mergedProps} />
+        function Example() {
+          const mergedProps = mergeProps(componentProps, props)
+          return <button {...mergedProps} />
+        }
       `,
     },
     {
       name: 'ignores elements without spread props',
-      code: `const example = <button type="button" />`,
+      code: `function Example() { return <button type="button" /> }`,
     },
     {
       name: 'ignores spread props on nested elements',
-      code: `const example = <div><button {...props} /></div>`,
+      code: `function Example() { return <div><button {...props} /></div> }`,
     },
     {
-      name: 'ignores spread props inside an outermost fragment',
-      code: `const example = <><button {...props} /></>`,
+      name: 'ignores spread props inside a root fragment',
+      code: `function Example() { return <><button {...props} /></> }`,
     },
     {
       name: 'ignores spread props on elements nested in conditional content',
-      code: `const example = <div>{condition ? <button {...props} /> : null}</div>`,
+      code: `function Example() { return <div>{condition ? <button {...props} /> : null}</div> }`,
     },
     {
       name: 'ignores spread props on elements nested in mapped content',
-      code: `const example = <ul>{items.map(item => <li {...item} />)}</ul>`,
+      code: `function Example() { return <ul>{items.map(item => <li {...item} />)}</ul> }`,
     },
     {
       name: 'ignores spread props on elements nested in a render prop',
-      code: `const example = <Component render={() => <button {...props} />} />`,
+      code: `function Example() { return <Component render={() => <button {...props} />} /> }`,
     },
     {
       name: 'ignores object spread expressions outside JSX',
@@ -66,51 +68,114 @@ ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<R
         const example = <button type="button" />
       `,
     },
+    {
+      name: 'ignores JSX assigned outside a component',
+      code: `const example = <button {...props} />`,
+    },
+    {
+      name: 'ignores JSX returned by a lowercase helper',
+      code: `function renderButton() { return <button {...props} /> }`,
+    },
+    {
+      name: 'ignores JSX returned by an unrelated callback',
+      code: `const buttons = items.map(props => <button {...props} />)`,
+    },
+    {
+      name: 'ignores component roots in test files',
+      filename: 'Example.test.jsx',
+      code: `function Example() { return <button {...props} /> }`,
+    },
+    {
+      name: 'ignores component roots in story files',
+      filename: 'Example.stories.jsx',
+      code: `function Example() { return <button {...props} /> }`,
+    },
+    {
+      name: 'ignores component roots in test directories',
+      filename: '__tests__/Example.jsx',
+      code: `function Example() { return <button {...props} /> }`,
+    },
   ],
   invalid: [
     {
-      name: 'reports direct props spread on an outermost element',
-      code: `const example = <button {...props} />`,
+      name: 'reports direct props spread on a function component root',
+      code: `function Example(props) { return <button {...props} type="button" /> }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
-      name: 'reports each unmerged spread on an outermost element',
-      code: `const example = <button {...componentProps} {...props} />`,
+      name: 'reports rest props composed with an explicit handler',
+      code: `
+        function Example({onClick, ...rest}) {
+          return <button {...rest} type="button" onClick={event => onClick?.(event)} />
+        }
+      `,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports each unmerged spread on a component root',
+      code: `function Example() { return <button {...componentProps} {...props} /> }`,
+      errors: [{messageId: 'preferMergeProps'}, {messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports component roots in separate return branches',
+      code: `
+        function Example({foo, ...rest}) {
+          if (foo) {
+            return <a {...rest} href="#" />
+          }
+          return <button {...rest} type="button" />
+        }
+      `,
       errors: [{messageId: 'preferMergeProps'}, {messageId: 'preferMergeProps'}],
     },
     {
-      name: 'reports outermost elements in conditional branches',
-      code: `const example = condition ? <button {...props} /> : <a {...props} />`,
+      name: 'reports component roots in conditional expression branches',
+      code: `function Example() { return condition ? <button {...props} /> : <a {...props} /> }`,
       errors: [{messageId: 'preferMergeProps'}, {messageId: 'preferMergeProps'}],
     },
     {
-      name: 'reports unmerged props on an outermost custom component',
-      code: `const example = <Button {...props} />`,
+      name: 'reports unmerged props on a root custom component',
+      code: `function Example() { return <Button {...props} /> }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
-      name: 'reports unmerged props on an outermost member component',
-      code: `const example = <ActionList.Item {...props} />`,
+      name: 'reports unmerged props on a root member component',
+      code: `function Example() { return <ActionList.Item {...props} /> }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports spread props returned from a function call',
-      code: `const example = <button {...getProps()} />`,
+      code: `function Example() { return <button {...getProps()} /> }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports props copied into an object expression',
-      code: `const example = <button {...{...props}} />`,
+      code: `function Example() { return <button {...{...props}} /> }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports only the unmerged spread alongside merged props',
-      code: `const example = <button {...mergeProps(componentProps, props)} {...otherProps} />`,
+      code: `function Example() { return <button {...mergeProps(componentProps, props)} {...otherProps} /> }`,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports props on component roots in logical expressions',
+      code: `function Example() { return condition && <button {...props} /> }`,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports props on a concise arrow component root',
+      code: `const Example = props => <button {...props} />`,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports props on a forwardRef component root',
+      code: `const Example = React.forwardRef((props, ref) => <button {...props} ref={ref} />)`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
-      name: 'reports props on outermost elements in logical expressions',
-      code: `const example = condition && <button {...props} />`,
+      name: 'reports props on a class component root',
+      code: `class Example extends React.Component { render() { return <button {...this.props} /> } }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
   ],
diff --git a/packages/eslint-config/src/rules/preferMergeProps.ts b/packages/eslint-config/src/rules/preferMergeProps.ts
index 944377648eb..d687c3fc680 100644
--- a/packages/eslint-config/src/rules/preferMergeProps.ts
+++ b/packages/eslint-config/src/rules/preferMergeProps.ts
@@ -6,20 +6,24 @@ const preferMergeProps: TSESLint.RuleModule<MessageIds> = {
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'Require spread props on outermost JSX elements to use mergeProps',
+      description: 'Require spread props on component root elements to use mergeProps',
     },
     messages: {
       preferMergeProps:
-        'Spread props on an outermost JSX element with mergeProps so component and consumer props are merged intentionally.',
+        'Spread props on a component root element with mergeProps so component and consumer props are merged intentionally.',
     },
     schema: [],
   },
   create(context) {
     const {sourceCode} = context
 
+    if (isTestOrStoryFile(context.filename)) {
+      return {}
+    }
+
     return {
       JSXOpeningElement(node) {
-        if (!isOutermostElement(node.parent)) {
+        if (!isComponentRoot(node.parent)) {
           return
         }
 
@@ -39,17 +43,174 @@ const preferMergeProps: TSESLint.RuleModule<MessageIds> = {
   },
 }
 
-function isOutermostElement(element: TSESTree.JSXElement): boolean {
-  let ancestor: TSESTree.Node | undefined = element.parent
+function isTestOrStoryFile(filename: string): boolean {
+  const normalizedFilename = filename.replaceAll('\\', '/')
+  return (
+    /(?:^|\/)__(?:tests|stories)__(?:\/|$)/u.test(normalizedFilename) ||
+    /\.(?:spec|test|stories|story)\.[cm]?[jt]sx?$/u.test(normalizedFilename)
+  )
+}
+
+function isComponentRoot(element: TSESTree.JSXElement): boolean {
+  let expression: TSESTree.Node = element
+
+  for (;;) {
+    const parent: TSESTree.Node = expression.parent
 
-  while (ancestor) {
-    if (ancestor.type === 'JSXElement' || ancestor.type === 'JSXFragment') {
+    if (
+      parent.type === 'ConditionalExpression' &&
+      (parent.consequent === expression || parent.alternate === expression)
+    ) {
+      expression = parent
+      continue
+    }
+
+    if (parent.type === 'LogicalExpression' && parent.right === expression) {
+      expression = parent
+      continue
+    }
+
+    if (
+      parent.type === 'TSAsExpression' ||
+      parent.type === 'TSNonNullExpression' ||
+      parent.type === 'TSSatisfiesExpression' ||
+      parent.type === 'TSTypeAssertion'
+    ) {
+      expression = parent
+      continue
+    }
+
+    if (parent.type === 'ReturnStatement' && parent.argument === expression) {
+      return isReturnedByComponent(parent)
+    }
+
+    if (parent.type === 'ArrowFunctionExpression' && parent.body === expression) {
+      return isComponentFunction(parent)
+    }
+
+    if (parent.type === 'JSXElement' || parent.type === 'JSXFragment') {
       return false
     }
+
+    return false
+  }
+}
+
+function isReturnedByComponent(statement: TSESTree.ReturnStatement): boolean {
+  let ancestor = statement.parent
+
+  while (ancestor.type !== 'Program') {
+    if (isFunction(ancestor)) {
+      return isComponentFunction(ancestor)
+    }
     ancestor = ancestor.parent
   }
 
-  return true
+  return false
+}
+
+function isFunction(node: TSESTree.Node): node is ComponentFunction {
+  return (
+    node.type === 'ArrowFunctionExpression' || node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression'
+  )
+}
+
+type ComponentFunction = TSESTree.ArrowFunctionExpression | TSESTree.FunctionDeclaration | TSESTree.FunctionExpression
+
+function isComponentFunction(node: ComponentFunction): boolean {
+  const name = getFunctionName(node)
+  if (name !== null) {
+    return isComponentName(name)
+  }
+
+  if (node.parent.type === 'ExportDefaultDeclaration') {
+    return true
+  }
+
+  return isWrappedComponent(node)
+}
+
+function getFunctionName(node: ComponentFunction): string | null {
+  if (node.parent.type === 'VariableDeclarator' && node.parent.init === node && node.parent.id.type === 'Identifier') {
+    return node.parent.id.name
+  }
+
+  if (
+    node.parent.type === 'AssignmentExpression' &&
+    node.parent.right === node &&
+    node.parent.left.type === 'Identifier'
+  ) {
+    return node.parent.left.name
+  }
+
+  if (node.type !== 'ArrowFunctionExpression' && node.id !== null) {
+    return node.id.name
+  }
+
+  if (
+    node.type === 'FunctionExpression' &&
+    node.parent.type === 'MethodDefinition' &&
+    node.parent.value === node &&
+    node.parent.key.type === 'Identifier' &&
+    node.parent.key.name === 'render'
+  ) {
+    return getClassName(node.parent.parent.parent)
+  }
+
+  return null
+}
+
+function getClassName(node: TSESTree.ClassDeclaration | TSESTree.ClassExpression): string | null {
+  if (node.id !== null) {
+    return node.id.name
+  }
+
+  if (node.parent.type === 'VariableDeclarator' && node.parent.init === node && node.parent.id.type === 'Identifier') {
+    return node.parent.id.name
+  }
+
+  if (node.parent.type === 'ExportDefaultDeclaration') {
+    return 'DefaultExport'
+  }
+
+  return null
+}
+
+function isWrappedComponent(node: ComponentFunction): boolean {
+  let expression: TSESTree.Node = node
+
+  while (
+    expression.parent.type === 'CallExpression' &&
+    expression.parent.arguments.includes(expression as TSESTree.Expression) &&
+    isComponentWrapper(expression.parent.callee)
+  ) {
+    expression = expression.parent
+  }
+
+  return (
+    (expression.parent.type === 'VariableDeclarator' &&
+      expression.parent.init === expression &&
+      expression.parent.id.type === 'Identifier' &&
+      isComponentName(expression.parent.id.name)) ||
+    expression.parent.type === 'ExportDefaultDeclaration'
+  )
+}
+
+function isComponentWrapper(callee: TSESTree.Expression): boolean {
+  if (callee.type === 'Identifier') {
+    return callee.name === 'forwardRef' || callee.name === 'fixedForwardRef' || callee.name === 'memo'
+  }
+
+  return (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.property.type === 'Identifier' &&
+    (callee.property.name === 'forwardRef' || callee.property.name === 'memo')
+  )
+}
+
+function isComponentName(name: string): boolean {
+  return /^[A-Z]/u.test(name)
 }
 
 function isMergedProps(argument: TSESTree.Expression, scope: TSESLint.Scope.Scope): boolean {
diff --git a/script/merge-props-migration-status.mts b/script/merge-props-migration-status.mts
index 30280b64501..37108c021ac 100644
--- a/script/merge-props-migration-status.mts
+++ b/script/merge-props-migration-status.mts
@@ -34,11 +34,11 @@ const violationCount = affectedResults.reduce((count, result) => {
 write(`
 # mergeProps Migration
 
-This report tracks outermost JSX prop spreads that should migrate to \`mergeProps\`.
+This report tracks component root prop spreads that should migrate to \`mergeProps\`.
 
 ## Status
 
-**Outermost prop spreads to migrate:** ${violationCount}
+**Component root prop spreads to migrate:** ${violationCount}
 
 **Affected files:** ${affectedResults.length} of ${results.length}
 `)

From 8c4f47f1ba1405e795b759d245ea6f755e6f1427 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Jul 2026 16:56:37 +0000
Subject: [PATCH 17/39] Handle typed component wrappers

Co-authored-by: joshblack <3901764+joshblack@users.noreply.github.com>
---
 package-lock.json                             |  1 +
 packages/eslint-config/package.json           |  1 +
 .../src/rules/preferMergeProps.test.ts        | 20 ++++++++
 .../src/rules/preferMergeProps.ts             | 46 ++++++++++++++-----
 4 files changed, 56 insertions(+), 12 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 27849dc14ae..b98d8ac49a0 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -28970,6 +28970,7 @@
       },
       "devDependencies": {
         "@primer/vitest-config": "^0.0.0",
+        "@typescript-eslint/parser": "8.59.1",
         "eslint": "^10.7.0",
         "typescript": "^6.0.3",
         "vitest": "^4.1.9"
diff --git a/packages/eslint-config/package.json b/packages/eslint-config/package.json
index 1cdac91ed43..3bfbee50bb4 100644
--- a/packages/eslint-config/package.json
+++ b/packages/eslint-config/package.json
@@ -16,6 +16,7 @@
   },
   "devDependencies": {
     "@primer/vitest-config": "^0.0.0",
+    "@typescript-eslint/parser": "8.59.1",
     "eslint": "^10.7.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
diff --git a/packages/eslint-config/src/rules/preferMergeProps.test.ts b/packages/eslint-config/src/rules/preferMergeProps.test.ts
index e72c9c1aaad..6e1203b5115 100644
--- a/packages/eslint-config/src/rules/preferMergeProps.test.ts
+++ b/packages/eslint-config/src/rules/preferMergeProps.test.ts
@@ -1,4 +1,5 @@
 import {RuleTester} from 'eslint'
+import tsParser from '@typescript-eslint/parser'
 import {describe, it} from 'vitest'
 import {preferMergeProps} from './preferMergeProps.ts'
 
@@ -9,6 +10,7 @@ RuleTester.itOnly = it
 const ruleTester = new RuleTester({
   languageOptions: {
     ecmaVersion: 'latest',
+    parser: tsParser,
     sourceType: 'module',
     parserOptions: {
       ecmaFeatures: {
@@ -173,6 +175,24 @@ ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<R
       code: `const Example = React.forwardRef((props, ref) => <button {...props} ref={ref} />)`,
       errors: [{messageId: 'preferMergeProps'}],
     },
+    {
+      name: 'reports props on an asserted forwardRef component root',
+      code: `
+        const Example = React.forwardRef(
+          (props, ref) => <button {...props} ref={ref} />
+        ) as PolymorphicForwardRefComponent
+      `,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
+    {
+      name: 'reports props on a forwardRef component root using satisfies',
+      code: `
+        const Example = React.forwardRef(
+          (props, ref) => <button {...props} ref={ref} />
+        ) satisfies PolymorphicForwardRefComponent
+      `,
+      errors: [{messageId: 'preferMergeProps'}],
+    },
     {
       name: 'reports props on a class component root',
       code: `class Example extends React.Component { render() { return <button {...this.props} /> } }`,
diff --git a/packages/eslint-config/src/rules/preferMergeProps.ts b/packages/eslint-config/src/rules/preferMergeProps.ts
index d687c3fc680..b208f77143c 100644
--- a/packages/eslint-config/src/rules/preferMergeProps.ts
+++ b/packages/eslint-config/src/rules/preferMergeProps.ts
@@ -70,12 +70,7 @@ function isComponentRoot(element: TSESTree.JSXElement): boolean {
       continue
     }
 
-    if (
-      parent.type === 'TSAsExpression' ||
-      parent.type === 'TSNonNullExpression' ||
-      parent.type === 'TSSatisfiesExpression' ||
-      parent.type === 'TSTypeAssertion'
-    ) {
+    if (isTypeScriptWrapper(parent)) {
       expression = parent
       continue
     }
@@ -96,6 +91,21 @@ function isComponentRoot(element: TSESTree.JSXElement): boolean {
   }
 }
 
+function isTypeScriptWrapper(
+  node: TSESTree.Node,
+): node is
+  | TSESTree.TSAsExpression
+  | TSESTree.TSNonNullExpression
+  | TSESTree.TSSatisfiesExpression
+  | TSESTree.TSTypeAssertion {
+  return (
+    node.type === 'TSAsExpression' ||
+    node.type === 'TSNonNullExpression' ||
+    node.type === 'TSSatisfiesExpression' ||
+    node.type === 'TSTypeAssertion'
+  )
+}
+
 function isReturnedByComponent(statement: TSESTree.ReturnStatement): boolean {
   let ancestor = statement.parent
 
@@ -179,12 +189,24 @@ function getClassName(node: TSESTree.ClassDeclaration | TSESTree.ClassExpression
 function isWrappedComponent(node: ComponentFunction): boolean {
   let expression: TSESTree.Node = node
 
-  while (
-    expression.parent.type === 'CallExpression' &&
-    expression.parent.arguments.includes(expression as TSESTree.Expression) &&
-    isComponentWrapper(expression.parent.callee)
-  ) {
-    expression = expression.parent
+  for (;;) {
+    const parent: TSESTree.Node = expression.parent
+
+    if (isTypeScriptWrapper(parent)) {
+      expression = parent
+      continue
+    }
+
+    if (
+      parent.type === 'CallExpression' &&
+      parent.arguments.includes(expression as TSESTree.Expression) &&
+      isComponentWrapper(parent.callee)
+    ) {
+      expression = parent
+      continue
+    }
+
+    break
   }
 
   return (

From 534acfd022e0307d5643a29c11555300bf83e34b Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Fri, 31 Jul 2026 13:25:36 -0500
Subject: [PATCH 18/39] Refine merge props migration reporting

Ignore pure prop-forwarding wrappers so the adoption report only tracks component roots with props that need intentional merging.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 00bfd295-6ed9-4119-8d63-103a0b3c63e8
---
 .../src/rules/preferMergeProps.test.ts        | 34 +++++++++++++------
 .../src/rules/preferMergeProps.ts             | 18 +++++++++-
 script/merge-props-migration-status.mts       |  4 +--
 3 files changed, 42 insertions(+), 14 deletions(-)

diff --git a/packages/eslint-config/src/rules/preferMergeProps.test.ts b/packages/eslint-config/src/rules/preferMergeProps.test.ts
index 6e1203b5115..7fccc3aa386 100644
--- a/packages/eslint-config/src/rules/preferMergeProps.test.ts
+++ b/packages/eslint-config/src/rules/preferMergeProps.test.ts
@@ -43,6 +43,18 @@ ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<R
       name: 'ignores elements without spread props',
       code: `function Example() { return <button type="button" /> }`,
     },
+    {
+      name: 'ignores a component that only forwards consumer props',
+      code: `function Example(props) { return <button {...props} /> }`,
+    },
+    {
+      name: 'ignores a component that forwards consumer props and composes a ref separately',
+      code: `const Example = React.forwardRef((props, ref) => <button {...props} ref={ref} />)`,
+    },
+    {
+      name: 'ignores a component that only forwards props to a custom component',
+      code: `function Example(props) { return <Button {...props} /> }`,
+    },
     {
       name: 'ignores spread props on nested elements',
       code: `function Example() { return <div><button {...props} /></div> }`,
@@ -132,27 +144,27 @@ ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<R
     },
     {
       name: 'reports component roots in conditional expression branches',
-      code: `function Example() { return condition ? <button {...props} /> : <a {...props} /> }`,
+      code: `function Example() { return condition ? <button type="button" {...props} /> : <a href="#" {...props} /> }`,
       errors: [{messageId: 'preferMergeProps'}, {messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports unmerged props on a root custom component',
-      code: `function Example() { return <Button {...props} /> }`,
+      code: `function Example() { return <Button variant="primary" {...props} /> }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports unmerged props on a root member component',
-      code: `function Example() { return <ActionList.Item {...props} /> }`,
+      code: `function Example() { return <ActionList.Item role="menuitem" {...props} /> }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports spread props returned from a function call',
-      code: `function Example() { return <button {...getProps()} /> }`,
+      code: `function Example() { return <button type="button" {...getProps()} /> }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports props copied into an object expression',
-      code: `function Example() { return <button {...{...props}} /> }`,
+      code: `function Example() { return <button type="button" {...{...props}} /> }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
@@ -162,24 +174,24 @@ ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<R
     },
     {
       name: 'reports props on component roots in logical expressions',
-      code: `function Example() { return condition && <button {...props} /> }`,
+      code: `function Example() { return condition && <button type="button" {...props} /> }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports props on a concise arrow component root',
-      code: `const Example = props => <button {...props} />`,
+      code: `const Example = props => <button type="button" {...props} />`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports props on a forwardRef component root',
-      code: `const Example = React.forwardRef((props, ref) => <button {...props} ref={ref} />)`,
+      code: `const Example = React.forwardRef((props, ref) => <button type="button" {...props} ref={ref} />)`,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports props on an asserted forwardRef component root',
       code: `
         const Example = React.forwardRef(
-          (props, ref) => <button {...props} ref={ref} />
+          (props, ref) => <button type="button" {...props} ref={ref} />
         ) as PolymorphicForwardRefComponent
       `,
       errors: [{messageId: 'preferMergeProps'}],
@@ -188,14 +200,14 @@ ruleTester.run('prefer-merge-props', preferMergeProps as unknown as Parameters<R
       name: 'reports props on a forwardRef component root using satisfies',
       code: `
         const Example = React.forwardRef(
-          (props, ref) => <button {...props} ref={ref} />
+          (props, ref) => <button type="button" {...props} ref={ref} />
         ) satisfies PolymorphicForwardRefComponent
       `,
       errors: [{messageId: 'preferMergeProps'}],
     },
     {
       name: 'reports props on a class component root',
-      code: `class Example extends React.Component { render() { return <button {...this.props} /> } }`,
+      code: `class Example extends React.Component { render() { return <button type="button" {...this.props} /> } }`,
       errors: [{messageId: 'preferMergeProps'}],
     },
   ],
diff --git a/packages/eslint-config/src/rules/preferMergeProps.ts b/packages/eslint-config/src/rules/preferMergeProps.ts
index b208f77143c..34a2a638981 100644
--- a/packages/eslint-config/src/rules/preferMergeProps.ts
+++ b/packages/eslint-config/src/rules/preferMergeProps.ts
@@ -23,7 +23,7 @@ const preferMergeProps: TSESLint.RuleModule<MessageIds> = {
 
     return {
       JSXOpeningElement(node) {
-        if (!isComponentRoot(node.parent)) {
+        if (!isComponentRoot(node.parent) || !hasPropsToMerge(node)) {
           return
         }
 
@@ -43,6 +43,22 @@ const preferMergeProps: TSESLint.RuleModule<MessageIds> = {
   },
 }
 
+function hasPropsToMerge(node: TSESTree.JSXOpeningElement): boolean {
+  const spreadCount = node.attributes.filter(attribute => attribute.type === 'JSXSpreadAttribute').length
+  if (spreadCount > 1) {
+    return true
+  }
+
+  return node.attributes.some(attribute => {
+    return (
+      attribute.type === 'JSXAttribute' &&
+      attribute.name.type === 'JSXIdentifier' &&
+      attribute.name.name !== 'key' &&
+      attribute.name.name !== 'ref'
+    )
+  })
+}
+
 function isTestOrStoryFile(filename: string): boolean {
   const normalizedFilename = filename.replaceAll('\\', '/')
   return (
diff --git a/script/merge-props-migration-status.mts b/script/merge-props-migration-status.mts
index 37108c021ac..5e5d08675be 100644
--- a/script/merge-props-migration-status.mts
+++ b/script/merge-props-migration-status.mts
@@ -34,11 +34,11 @@ const violationCount = affectedResults.reduce((count, result) => {
 write(`
 # mergeProps Migration
 
-This report tracks component root prop spreads that should migrate to \`mergeProps\`.
+This report tracks component roots that combine authored props with unmerged spread props.
 
 ## Status
 
-**Component root prop spreads to migrate:** ${violationCount}
+**Unmerged component root prop spreads to migrate:** ${violationCount}
 
 **Affected files:** ${affectedResults.length} of ${results.length}
 `)

From 56963ebc36a8e8fe0912b5f0fba6b376ed856cce Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Fri, 31 Jul 2026 13:17:04 -0500
Subject: [PATCH 19/39] Add merge props migration driver

Refine the adoption report, add validated migration examples, and introduce the coordinator skill and bounded batch agent for ADR-025.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 00bfd295-6ed9-4119-8d63-103a0b3c63e8
---
 .changeset/clean-radios-merge.md              |   5 +
 .changeset/tidy-token-events.md               |   5 +
 .changeset/visible-class-merging.md           |   5 +
 .../migrate-to-merge-props-batch.agent.md     |  68 ++++++
 .../skills/migrate-to-merge-props/SKILL.md    | 207 ++++++++++++++++++
 packages/react/src/Radio/Radio.test.tsx       |   1 +
 packages/react/src/Radio/Radio.tsx            |  32 ++-
 packages/react/src/Radio/Radio.types.test.tsx |   6 +
 packages/react/src/Token/TokenBase.tsx        |  54 +++--
 .../react/src/Token/__tests__/Token.test.tsx  |  11 +
 .../src/VisuallyHidden/VisuallyHidden.tsx     |  10 +-
 11 files changed, 362 insertions(+), 42 deletions(-)
 create mode 100644 .changeset/clean-radios-merge.md
 create mode 100644 .changeset/tidy-token-events.md
 create mode 100644 .changeset/visible-class-merging.md
 create mode 100644 .github/agents/migrate-to-merge-props-batch.agent.md
 create mode 100644 .github/skills/migrate-to-merge-props/SKILL.md
 create mode 100644 packages/react/src/Radio/Radio.types.test.tsx

diff --git a/.changeset/clean-radios-merge.md b/.changeset/clean-radios-merge.md
new file mode 100644
index 00000000000..5ddb7fd741d
--- /dev/null
+++ b/.changeset/clean-radios-merge.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': major
+---
+
+Radio: Prevent overriding the input type so the component always renders radio semantics.
diff --git a/.changeset/tidy-token-events.md b/.changeset/tidy-token-events.md
new file mode 100644
index 00000000000..7da0e9d015b
--- /dev/null
+++ b/.changeset/tidy-token-events.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Token: Run removal keyboard behavior before consumer keydown handlers.
diff --git a/.changeset/visible-class-merging.md b/.changeset/visible-class-merging.md
new file mode 100644
index 00000000000..4c07d423a18
--- /dev/null
+++ b/.changeset/visible-class-merging.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+VisuallyHidden: Merge consumer class names with component styles consistently.
diff --git a/.github/agents/migrate-to-merge-props-batch.agent.md b/.github/agents/migrate-to-merge-props-batch.agent.md
new file mode 100644
index 00000000000..375d777ce30
--- /dev/null
+++ b/.github/agents/migrate-to-merge-props-batch.agent.md
@@ -0,0 +1,68 @@
+---
+name: migrate-to-merge-props-batch
+description: Performs one bounded ADR-025 mergeProps migration batch and returns validation and migration-report evidence to the coordinator.
+tools:
+  - read
+  - search
+  - edit
+  - execute
+skills:
+  - migrate-to-merge-props
+  - style-guide
+  - changesets
+  - storybook
+---
+
+You implement exactly one batch assigned by the `migrate-to-merge-props`
+coordinator. Use that skill for the ADR, validated patterns, scope, stack
+contract, and validation requirements.
+
+## Required input
+
+Do not begin without:
+
+- The current stack branch.
+- Exact component names, file paths, and report locations.
+- The maximum batch size.
+- Total and affected-file counts before the batch.
+- Targeted validation commands.
+
+Confirm the branch and findings still match the assignment. Stop if the batch
+is too large, overlaps another entry, includes unassigned files, or requires an
+unresolved architecture, accessibility, or public API decision.
+
+## Workflow
+
+1. Read ADR-025, the repository instructions, `mergeProps`, and the validated
+   production examples named by the coordinator skill.
+2. Confirm every assigned finding still appears in the report.
+3. Inspect public props, spread order, handlers, styles, class names, refs,
+   invariant attributes, tests, stories, and nearby prior art.
+4. Implement only the assigned findings and tightly coupled tests, type tests,
+   or changesets.
+5. Pass component props first and consumer props second.
+6. Keep component class names as strings.
+7. Omit absent optional consumer handlers from the second argument.
+8. Compose refs separately.
+9. Omit or gate invariant attributes in public types and apply them after the
+   merged spread.
+10. Format, lint, test, type-check, and run any requested Storybook,
+    accessibility, visual, or build validation.
+11. Regenerate the report and confirm the assigned findings disappeared with
+    no new findings.
+
+Do not disable enforcement, add blanket suppressions, manipulate report output,
+expose `mergeProps` publicly, fix unrelated findings, select another batch,
+create stack entries, commit, or change stack structure.
+
+## Result format
+
+| Field         | Content                                                              |
+| ------------- | -------------------------------------------------------------------- |
+| Branch        | Current stack branch                                                 |
+| Assigned      | Component names, paths, and original locations                       |
+| Resolved      | Findings removed from the regenerated report                         |
+| Files changed | Source, tests, types, stories, and changesets edited                 |
+| Remaining     | Updated finding and affected-file counts                             |
+| Validation    | Failed commands and relevant summaries, or `Passed`                  |
+| Blockers      | Findings requiring an ADR, API, accessibility, or ownership decision |
diff --git a/.github/skills/migrate-to-merge-props/SKILL.md b/.github/skills/migrate-to-merge-props/SKILL.md
new file mode 100644
index 00000000000..e7fb7b75593
--- /dev/null
+++ b/.github/skills/migrate-to-merge-props/SKILL.md
@@ -0,0 +1,207 @@
+---
+name: migrate-to-merge-props
+description: 'Use when: coordinating ADR-025 adoption through measured mergeProps batches in a stacked migration. Plans bounded batches, invokes migrate-to-merge-props-batch, verifies report progress, and removes temporary migration tooling at completion.'
+---
+
+# Migrate to mergeProps
+
+Coordinate adoption of
+[`ADR-025: Prop merging conventions`](../../../contributor-docs/adrs/adr-025-prop-merging.md).
+
+ADR-025 is the source of truth for correctness. The ESLint rule and migration
+report identify likely work, but a finding is not complete until the component
+preserves its behavior, accessibility contract, public types, refs, handlers,
+class names, and styles according to the ADR.
+
+## Sources of truth and migration artifacts
+
+| Artifact          | Location                                                                              | Role                                      | Lifetime  |
+| ----------------- | ------------------------------------------------------------------------------------- | ----------------------------------------- | --------- |
+| ADR               | `contributor-docs/adrs/adr-025-prop-merging.md`                                       | Defines the target prop-merging contract  | Permanent |
+| Style guidance    | `contributor-docs/style.md`, "Merge shared props intentionally"                       | Shows the component-authoring convention  | Permanent |
+| Utility           | `packages/react/src/utils/mergeProps.ts`                                              | Implements shared merge behavior          | Permanent |
+| Adoption rule     | `primer/prefer-merge-props` in `packages/eslint-config/src/rules/preferMergeProps.ts` | Detects unmerged component root props     | Permanent |
+| Migration report  | `node script/merge-props-migration-status.mts`                                        | Measures remaining findings               | Temporary |
+| Batch agent       | `.github/agents/migrate-to-merge-props-batch.agent.md`                                | Implements one assigned migration batch   | Temporary |
+| Coordinator skill | `.github/skills/migrate-to-merge-props/SKILL.md`                                      | Plans, delegates, measures, and cleans up | Temporary |
+
+## Scope
+
+- Included: findings reported in `packages/react/src/**/*.{ts,tsx}` by
+  `primer/prefer-merge-props`.
+- Excluded: tests, stories, nested JSX, generated output, `.agents/**/*`, and
+  pure pass-through roots that have one spread and no component-authored prop
+  other than `ref` or `key`.
+- Refs are always composed separately with `useMergedRefs`.
+- Default maximum batch size: five findings.
+- Default run size: two sequential batches per invocation.
+- Never split one source file across separate batches.
+
+## Validated migration patterns
+
+Use these production examples as prior art:
+
+- `packages/react/src/VisuallyHidden/VisuallyHidden.tsx`: class-name-only
+  merging.
+- `packages/react/src/Token/TokenBase.tsx`: internal behavior first, optional
+  consumer event handler second, and ref composition outside `mergeProps`.
+- `packages/react/src/Radio/Radio.tsx`: a component-owned attribute omitted
+  from the public type and applied after merged props.
+
+Apply these rules:
+
+1. Pass component-authored props first and consumer-authored props second.
+2. Keep the component-authored `className` as a string. Let `mergeProps` use
+   `clsx` to combine it with consumer class values.
+3. Do not add an optional consumer handler to the second argument when it is
+   absent. An explicit `undefined` entry would replace the internal handler
+   instead of composing it.
+4. Keep refs outside `mergeProps`.
+5. Put invariant attributes after the merged spread and omit them from the
+   public prop type. Use a discriminated union when ownership depends on the
+   rendered element.
+6. Preserve intentional consumer `undefined` precedence for ordinary props.
+7. Add tests for event order, cancellation, controlled attributes, type
+   exclusions, or other behavior that is not already covered.
+
+## Stack contract
+
+Use one linear stack:
+
+1. `copilot/update-style-docs-prop-merging`: ADR, utility, adoption rule, and
+   report foundation.
+2. `migrate/merge-props-migrator`: validated examples, tooling refinements,
+   coordinator skill, and batch agent.
+3. `migrate/merge-props-batch-01` through
+   `migrate/merge-props-batch-NN`: one bounded migration batch per entry.
+4. `migrate/merge-props-cleanup`: temporary artifact removal after the report
+   reaches zero.
+
+Use only non-interactive stack commands:
+
+```shell
+gh stack view --json
+gh stack add migrate/merge-props-batch-NN
+gh stack submit --auto
+```
+
+Do not create the cleanup entry while in-scope findings remain.
+
+## Coordinator workflow
+
+### 1. Resume the stack
+
+Inspect:
+
+```shell
+git status --short --branch
+gh stack view --json
+```
+
+Confirm the current branch is the top active entry. If a lower entry changed,
+rebase the upstack before selecting findings. Do not mix unrelated worktree
+changes into a migration entry.
+
+### 2. Establish the baseline
+
+Run:
+
+```shell
+node script/merge-props-migration-status.mts
+```
+
+Record the total finding count, affected-file count, exact paths and locations,
+findings already assigned to stack entries, and blockers. Do not edit generated
+output or exclusions to lower the count.
+
+### 3. Plan non-overlapping batches
+
+Group findings by component family and remediation pattern. Each batch must:
+
+- Contain at most the selected finding limit.
+- Own complete files rather than splitting a file between entries.
+- Be reviewable as one coherent change.
+- Avoid files already assigned to an existing stack entry.
+- Include tightly coupled tests and changesets.
+
+Calculate the remaining batch count using the selected limit.
+
+### 4. Ask how much work to run
+
+Use a structured prompt containing:
+
+| Field       | Default | Constraint                               |
+| ----------- | ------- | ---------------------------------------- |
+| Batch size  | `5`     | Integer greater than or equal to `1`     |
+| Run mode    | Limited | Limited batches or all remaining batches |
+| Batch count | `2`     | Integer greater than or equal to `1`     |
+
+Show the baseline, calculated remaining batches, and exact assignments before
+editing. Prefer a small set of sequential batches over running the full
+migration at once.
+
+### 5. Run each selected batch
+
+For each batch:
+
+1. Create `migrate/merge-props-batch-NN` with `gh stack add`.
+2. Invoke `migrate-to-merge-props-batch` with the branch, exact paths and
+   locations, maximum size, before counts, and targeted validation commands.
+3. Review the returned diff and evidence.
+4. Add or update changesets for consumer-facing behavior or type changes.
+5. Commit only the assigned batch.
+6. Regenerate the report.
+7. Confirm assigned findings disappeared, no new findings appeared, and counts
+   changed by the expected amount.
+8. Stop before another entry if validation or report evidence fails.
+
+Run code-editing batch agents sequentially because every branch depends on the
+previous branch.
+
+### 6. Handle blockers
+
+Do not force a mechanical merge when a finding requires a decision about:
+
+- Consumer veto before internal behavior.
+- Whether an ARIA, semantic, or stable identifier prop is component-owned.
+- A breaking public type change.
+- Polymorphic attribute ownership.
+- Ref composition.
+
+Return the file, component, current behavior, ADR conflict, and smallest
+decision needed.
+
+### 7. Finish or pause
+
+In limited mode, stop after the selected number of entries and leave the stack
+resumable.
+
+When the report reaches zero, add `migrate/merge-props-cleanup` and remove:
+
+- `.github/skills/migrate-to-merge-props/`
+- `.github/agents/migrate-to-merge-props-batch.agent.md`
+- `script/merge-props-migration-status.mts`
+- The `merge-props` job from `.github/workflows/migration-status.yml`
+
+Keep ADR-025, style guidance, `mergeProps`, the ESLint rule, and regression
+tests. Mark ADR-025 adopted and implemented in the cleanup entry after final
+validation.
+
+### 8. Submit and report
+
+Run:
+
+```shell
+gh stack submit --auto
+gh stack view --json
+```
+
+Return completed stack entries, requested/completed/remaining batches, resolved
+paths, updated counts, validation failures, and blockers. Do not claim
+completion before the report is zero and the cleanup entry exists.
+
+## Example invocation
+
+> Use `/migrate-to-merge-props` with at most five findings per entry. Run two
+> batches, regenerate the report after each entry, and stop on unexpected
+> results.
diff --git a/packages/react/src/Radio/Radio.test.tsx b/packages/react/src/Radio/Radio.test.tsx
index 1a7b9756dcd..d20071927db 100644
--- a/packages/react/src/Radio/Radio.test.tsx
+++ b/packages/react/src/Radio/Radio.test.tsx
@@ -21,6 +21,7 @@ describe('Radio', () => {
     const radio = getByRole('radio')
 
     expect(radio).toBeDefined()
+    expect(radio).toHaveAttribute('type', 'radio')
   })
 
   it('renders data-component attribute', () => {
diff --git a/packages/react/src/Radio/Radio.tsx b/packages/react/src/Radio/Radio.tsx
index 5ea79439a9f..d14e073f96e 100644
--- a/packages/react/src/Radio/Radio.tsx
+++ b/packages/react/src/Radio/Radio.tsx
@@ -5,6 +5,7 @@ import {clsx} from 'clsx'
 import sharedClasses from '../Checkbox/shared.module.css'
 import classes from './Radio.module.css'
 import type {WithSlotMarker} from '../utils/types'
+import {mergeProps} from '../utils/mergeProps'
 
 export type RadioProps = {
   /**
@@ -32,7 +33,7 @@ export type RadioProps = {
    * Indicates whether the radio button must be checked before the form can be submitted
    */
   required?: boolean
-} & InputHTMLAttributes<HTMLInputElement>
+} & Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>
 
 /**
  * An accessible, native radio component for selecting one option from a list.
@@ -56,7 +57,6 @@ const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
     const radioGroupContext = useContext(RadioGroupContext)
     const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
       radioGroupContext?.onChange && radioGroupContext.onChange(e)
-      onChange && onChange(e)
     }
     const name = nameProp || radioGroupContext?.name
 
@@ -69,17 +69,25 @@ const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
 
     return (
       <input
-        type="radio"
-        value={value}
-        name={name}
+        {...mergeProps(
+          {
+            onChange: handleOnChange,
+            className: clsx(sharedClasses.Input, classes.Radio),
+            'aria-checked': checked ? ('true' as const) : ('false' as const),
+          },
+          {
+            ...rest,
+            ...(onChange ? {onChange} : {}),
+            value,
+            name,
+            disabled,
+            checked,
+            required,
+            className,
+          },
+        )}
         ref={ref}
-        disabled={disabled}
-        checked={checked}
-        aria-checked={checked ? 'true' : 'false'}
-        required={required}
-        onChange={handleOnChange}
-        className={clsx(className, sharedClasses.Input, classes.Radio)}
-        {...rest}
+        type="radio"
         data-component="Radio"
       />
     )
diff --git a/packages/react/src/Radio/Radio.types.test.tsx b/packages/react/src/Radio/Radio.types.test.tsx
new file mode 100644
index 00000000000..a08856d1c1e
--- /dev/null
+++ b/packages/react/src/Radio/Radio.types.test.tsx
@@ -0,0 +1,6 @@
+import Radio from '.'
+
+export function doesNotAcceptType() {
+  // @ts-expect-error Radio always renders an input with type="radio"
+  return <Radio name="example" value="example" type="checkbox" />
+}
diff --git a/packages/react/src/Token/TokenBase.tsx b/packages/react/src/Token/TokenBase.tsx
index 03202c6f0cb..17025fc667f 100644
--- a/packages/react/src/Token/TokenBase.tsx
+++ b/packages/react/src/Token/TokenBase.tsx
@@ -1,10 +1,10 @@
 import type {KeyboardEvent} from 'react'
 import React from 'react'
-import {clsx} from 'clsx'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import classes from './TokenBase.module.css'
 import {defaultTokenSize, type TokenSizeKeys} from './constants'
 import {isTokenInteractive} from './utils'
+import {mergeProps} from '../utils/mergeProps'
 
 export type {TokenSizeKeys}
 
@@ -55,30 +55,38 @@ const TokenBase = React.forwardRef<HTMLButtonElement | HTMLAnchorElement | HTMLS
     },
     forwardedRef,
   ) => {
+    const handleKeyDown = (event: KeyboardEvent<HTMLSpanElement & HTMLAnchorElement & HTMLButtonElement>) => {
+      if ((event.key === 'Backspace' || event.key === 'Delete') && onRemove) {
+        onRemove()
+      }
+    }
+
     return (
       <Component
-        onKeyDown={(event: KeyboardEvent<HTMLSpanElement & HTMLAnchorElement & HTMLButtonElement>) => {
-          onKeyDown && onKeyDown(event)
-
-          if ((event.key === 'Backspace' || event.key === 'Delete') && onRemove) {
-            onRemove()
-          }
-        }}
-        className={clsx(classes.TokenBase, className)}
-        data-cursor-is-interactive={isTokenInteractive({
-          as: Component,
-          onClick: rest.onClick,
-          onFocus: rest.onFocus,
-          tabIndex: rest.tabIndex,
-          disabled: rest.disabled,
-        })}
-        data-size={size}
-        id={id?.toString()}
-        {...(Component === 'button'
-          ? (rest as React.ButtonHTMLAttributes<HTMLButtonElement>)
-          : Component === 'a'
-            ? (rest as React.AnchorHTMLAttributes<HTMLAnchorElement>)
-            : (rest as React.HTMLAttributes<HTMLSpanElement>))}
+        {...mergeProps(
+          {
+            onKeyDown: handleKeyDown,
+            className: classes.TokenBase,
+            'data-cursor-is-interactive': isTokenInteractive({
+              as: Component,
+              onClick: rest.onClick,
+              onFocus: rest.onFocus,
+              tabIndex: rest.tabIndex,
+              disabled: rest.disabled,
+            }),
+            'data-size': size,
+          },
+          {
+            ...(Component === 'button'
+              ? (rest as React.ButtonHTMLAttributes<HTMLButtonElement>)
+              : Component === 'a'
+                ? (rest as React.AnchorHTMLAttributes<HTMLAnchorElement>)
+                : (rest as React.HTMLAttributes<HTMLSpanElement>)),
+            ...(onKeyDown ? {onKeyDown} : {}),
+            className,
+            id: id?.toString(),
+          },
+        )}
         // TypeScript cannot resolve polymorphic ref types at compile time
         // This assertion is safe because the ref will match the actual rendered element
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
diff --git a/packages/react/src/Token/__tests__/Token.test.tsx b/packages/react/src/Token/__tests__/Token.test.tsx
index 73c01124c2a..ac07bbe22fe 100644
--- a/packages/react/src/Token/__tests__/Token.test.tsx
+++ b/packages/react/src/Token/__tests__/Token.test.tsx
@@ -63,6 +63,17 @@ const testTokenComponent = (Component: React.ComponentType<React.PropsWithChildr
     expect(onRemoveMock).toHaveBeenCalled()
   })
 
+  it('calls onRemove before the consumer onKeyDown handler', () => {
+    const calls: string[] = []
+    const {getByText} = HTMLRender(
+      <Component text="token" onRemove={() => calls.push('remove')} onKeyDown={() => calls.push('consumer')} />,
+    )
+
+    fireEvent.keyDown(getByText('token'), {key: 'Backspace'})
+
+    expect(calls).toEqual(['remove', 'consumer'])
+  })
+
   it('adds className to rendered component', () => {
     const {getByText} = HTMLRender(<Component text="token" className="testing-class" />)
     const domNode = getByText('token')
diff --git a/packages/react/src/VisuallyHidden/VisuallyHidden.tsx b/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
index d05c496352f..d2b8231d952 100644
--- a/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
+++ b/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
@@ -1,6 +1,6 @@
-import {clsx} from 'clsx'
 import type React from 'react'
 import {type HTMLAttributes} from 'react'
+import {mergeProps} from '../utils/mergeProps'
 import classes from './VisuallyHidden.module.css'
 
 /**
@@ -13,12 +13,8 @@ import classes from './VisuallyHidden.module.css'
  *
  * @see https://www.scottohara.me/blog/2023/03/21/visually-hidden-hack.html
  */
-export const VisuallyHidden = ({className, children, ...rest}: VisuallyHiddenProps) => {
-  return (
-    <span className={clsx(className, classes.VisuallyHidden)} {...rest}>
-      {children}
-    </span>
-  )
+export const VisuallyHidden = ({children, ...rest}: VisuallyHiddenProps) => {
+  return <span {...mergeProps({className: classes.VisuallyHidden}, rest)}>{children}</span>
 }
 
 export type VisuallyHiddenProps = React.PropsWithChildren<

From 9475d36ff3c5c2f7e6d8b4bd6724d85521083ab4 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Fri, 31 Jul 2026 13:28:21 -0500
Subject: [PATCH 20/39] Keep migration driver focused on coordination

Move implementation and adoption-tool changes out of the driver entry and document stack ownership for foundation, driver, batch, and cleanup work.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 00bfd295-6ed9-4119-8d63-103a0b3c63e8
---
 .changeset/clean-radios-merge.md              |  5 --
 .changeset/tidy-token-events.md               |  5 --
 .changeset/visible-class-merging.md           |  5 --
 .../migrate-to-merge-props-batch.agent.md     |  9 ++-
 .../skills/migrate-to-merge-props/SKILL.md    | 67 ++++++++++++++-----
 packages/react/src/Radio/Radio.test.tsx       |  1 -
 packages/react/src/Radio/Radio.tsx            | 32 ++++-----
 packages/react/src/Radio/Radio.types.test.tsx |  6 --
 packages/react/src/Token/TokenBase.tsx        | 54 +++++++--------
 .../react/src/Token/__tests__/Token.test.tsx  | 11 ---
 .../src/VisuallyHidden/VisuallyHidden.tsx     | 10 ++-
 11 files changed, 98 insertions(+), 107 deletions(-)
 delete mode 100644 .changeset/clean-radios-merge.md
 delete mode 100644 .changeset/tidy-token-events.md
 delete mode 100644 .changeset/visible-class-merging.md
 delete mode 100644 packages/react/src/Radio/Radio.types.test.tsx

diff --git a/.changeset/clean-radios-merge.md b/.changeset/clean-radios-merge.md
deleted file mode 100644
index 5ddb7fd741d..00000000000
--- a/.changeset/clean-radios-merge.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@primer/react': major
----
-
-Radio: Prevent overriding the input type so the component always renders radio semantics.
diff --git a/.changeset/tidy-token-events.md b/.changeset/tidy-token-events.md
deleted file mode 100644
index 7da0e9d015b..00000000000
--- a/.changeset/tidy-token-events.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@primer/react': patch
----
-
-Token: Run removal keyboard behavior before consumer keydown handlers.
diff --git a/.changeset/visible-class-merging.md b/.changeset/visible-class-merging.md
deleted file mode 100644
index 4c07d423a18..00000000000
--- a/.changeset/visible-class-merging.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@primer/react': patch
----
-
-VisuallyHidden: Merge consumer class names with component styles consistently.
diff --git a/.github/agents/migrate-to-merge-props-batch.agent.md b/.github/agents/migrate-to-merge-props-batch.agent.md
index 375d777ce30..b093977be22 100644
--- a/.github/agents/migrate-to-merge-props-batch.agent.md
+++ b/.github/agents/migrate-to-merge-props-batch.agent.md
@@ -33,8 +33,8 @@ unresolved architecture, accessibility, or public API decision.
 
 ## Workflow
 
-1. Read ADR-025, the repository instructions, `mergeProps`, and the validated
-   production examples named by the coordinator skill.
+1. Read ADR-025, the repository instructions, `mergeProps`, its tests, and any
+   relevant migrated component from a lower batch entry.
 2. Confirm every assigned finding still appears in the report.
 3. Inspect public props, spread order, handlers, styles, class names, refs,
    invariant attributes, tests, stories, and nearby prior art.
@@ -53,7 +53,10 @@ unresolved architecture, accessibility, or public API decision.
 
 Do not disable enforcement, add blanket suppressions, manipulate report output,
 expose `mergeProps` publicly, fix unrelated findings, select another batch,
-create stack entries, commit, or change stack structure.
+create stack entries, commit, or change stack structure. Do not refine the
+adoption rule, report, utility, workflow, coordinator, or agent in a batch
+entry. Return those issues as blockers so the coordinator can update the owning
+lower stack entry and rebase.
 
 ## Result format
 
diff --git a/.github/skills/migrate-to-merge-props/SKILL.md b/.github/skills/migrate-to-merge-props/SKILL.md
index e7fb7b75593..89773b78497 100644
--- a/.github/skills/migrate-to-merge-props/SKILL.md
+++ b/.github/skills/migrate-to-merge-props/SKILL.md
@@ -37,16 +37,17 @@ class names, and styles according to the ADR.
 - Default run size: two sequential batches per invocation.
 - Never split one source file across separate batches.
 
-## Validated migration patterns
+## Migration rules and prior art
 
-Use these production examples as prior art:
+Before the first implementation batch, inspect:
 
-- `packages/react/src/VisuallyHidden/VisuallyHidden.tsx`: class-name-only
-  merging.
-- `packages/react/src/Token/TokenBase.tsx`: internal behavior first, optional
-  consumer event handler second, and ref composition outside `mergeProps`.
-- `packages/react/src/Radio/Radio.tsx`: a component-owned attribute omitted
-  from the public type and applied after merged props.
+- The component example in `contributor-docs/style.md`.
+- `packages/react/src/utils/mergeProps.ts`.
+- `packages/react/src/utils/__tests__/mergeProps.test.ts`.
+
+After implementation batches exist, inspect a relevant migrated component from
+a lower stack entry as prior art. Do not add reference component migrations to
+the driver entry.
 
 Apply these rules:
 
@@ -64,16 +65,44 @@ Apply these rules:
 7. Add tests for event order, cancellation, controlled attributes, type
    exclusions, or other behavior that is not already covered.
 
+## Stack ownership contract
+
+Every change must live in the entry that owns its concern:
+
+- `copilot/update-style-docs-prop-merging` owns ADR-025, `mergeProps`, the
+  adoption rule, rule tests, report script, and migration-status workflow.
+  Refinements to any of those artifacts must be committed to this foundation
+  entry.
+- `migrate/merge-props-migrator` owns only the coordinator skill and batch
+  agent. It must not contain component migrations, migration changesets, or
+  adoption-tool refinements.
+- `migrate/merge-props-batch-NN` owns only its assigned component
+  implementation, tightly coupled tests or stories, and required changesets.
+- `migrate/merge-props-cleanup` owns final temporary-artifact removal and the
+  ADR status update.
+
+If batch work exposes a problem in the adoption rule, report, utility, or
+workflow:
+
+1. Stop the batch without working around the problem.
+2. Navigate to `copilot/update-style-docs-prop-merging`.
+3. Commit the refinement there.
+4. Rebase every upstack entry.
+5. Regenerate the report before resuming the batch.
+
+If the coordinator or agent instructions need refinement, update
+`migrate/merge-props-migrator` and rebase the batch entries above it.
+
 ## Stack contract
 
 Use one linear stack:
 
-1. `copilot/update-style-docs-prop-merging`: ADR, utility, adoption rule, and
-   report foundation.
-2. `migrate/merge-props-migrator`: validated examples, tooling refinements,
-   coordinator skill, and batch agent.
+1. `copilot/update-style-docs-prop-merging`: ADR, utility, adoption mechanism,
+   report, workflow, and all refinements to those artifacts.
+2. `migrate/merge-props-migrator`: coordinator skill and batch agent only.
 3. `migrate/merge-props-batch-01` through
-   `migrate/merge-props-batch-NN`: one bounded migration batch per entry.
+   `migrate/merge-props-batch-NN`: one bounded component implementation batch
+   per entry.
 4. `migrate/merge-props-cleanup`: temporary artifact removal after the report
    reaches zero.
 
@@ -102,6 +131,9 @@ Confirm the current branch is the top active entry. If a lower entry changed,
 rebase the upstack before selecting findings. Do not mix unrelated worktree
 changes into a migration entry.
 
+Inspect the diff for each existing stack entry and confirm it still follows the
+stack ownership contract before creating another batch.
+
 ### 2. Establish the baseline
 
 Run:
@@ -149,11 +181,12 @@ For each batch:
    locations, maximum size, before counts, and targeted validation commands.
 3. Review the returned diff and evidence.
 4. Add or update changesets for consumer-facing behavior or type changes.
-5. Commit only the assigned batch.
-6. Regenerate the report.
-7. Confirm assigned findings disappeared, no new findings appeared, and counts
+5. Confirm the entry contains no adoption-tool or driver changes.
+6. Commit only the assigned batch.
+7. Regenerate the report.
+8. Confirm assigned findings disappeared, no new findings appeared, and counts
    changed by the expected amount.
-8. Stop before another entry if validation or report evidence fails.
+9. Stop before another entry if validation or report evidence fails.
 
 Run code-editing batch agents sequentially because every branch depends on the
 previous branch.
diff --git a/packages/react/src/Radio/Radio.test.tsx b/packages/react/src/Radio/Radio.test.tsx
index d20071927db..1a7b9756dcd 100644
--- a/packages/react/src/Radio/Radio.test.tsx
+++ b/packages/react/src/Radio/Radio.test.tsx
@@ -21,7 +21,6 @@ describe('Radio', () => {
     const radio = getByRole('radio')
 
     expect(radio).toBeDefined()
-    expect(radio).toHaveAttribute('type', 'radio')
   })
 
   it('renders data-component attribute', () => {
diff --git a/packages/react/src/Radio/Radio.tsx b/packages/react/src/Radio/Radio.tsx
index d14e073f96e..5ea79439a9f 100644
--- a/packages/react/src/Radio/Radio.tsx
+++ b/packages/react/src/Radio/Radio.tsx
@@ -5,7 +5,6 @@ import {clsx} from 'clsx'
 import sharedClasses from '../Checkbox/shared.module.css'
 import classes from './Radio.module.css'
 import type {WithSlotMarker} from '../utils/types'
-import {mergeProps} from '../utils/mergeProps'
 
 export type RadioProps = {
   /**
@@ -33,7 +32,7 @@ export type RadioProps = {
    * Indicates whether the radio button must be checked before the form can be submitted
    */
   required?: boolean
-} & Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>
+} & InputHTMLAttributes<HTMLInputElement>
 
 /**
  * An accessible, native radio component for selecting one option from a list.
@@ -57,6 +56,7 @@ const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
     const radioGroupContext = useContext(RadioGroupContext)
     const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
       radioGroupContext?.onChange && radioGroupContext.onChange(e)
+      onChange && onChange(e)
     }
     const name = nameProp || radioGroupContext?.name
 
@@ -69,25 +69,17 @@ const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
 
     return (
       <input
-        {...mergeProps(
-          {
-            onChange: handleOnChange,
-            className: clsx(sharedClasses.Input, classes.Radio),
-            'aria-checked': checked ? ('true' as const) : ('false' as const),
-          },
-          {
-            ...rest,
-            ...(onChange ? {onChange} : {}),
-            value,
-            name,
-            disabled,
-            checked,
-            required,
-            className,
-          },
-        )}
-        ref={ref}
         type="radio"
+        value={value}
+        name={name}
+        ref={ref}
+        disabled={disabled}
+        checked={checked}
+        aria-checked={checked ? 'true' : 'false'}
+        required={required}
+        onChange={handleOnChange}
+        className={clsx(className, sharedClasses.Input, classes.Radio)}
+        {...rest}
         data-component="Radio"
       />
     )
diff --git a/packages/react/src/Radio/Radio.types.test.tsx b/packages/react/src/Radio/Radio.types.test.tsx
deleted file mode 100644
index a08856d1c1e..00000000000
--- a/packages/react/src/Radio/Radio.types.test.tsx
+++ /dev/null
@@ -1,6 +0,0 @@
-import Radio from '.'
-
-export function doesNotAcceptType() {
-  // @ts-expect-error Radio always renders an input with type="radio"
-  return <Radio name="example" value="example" type="checkbox" />
-}
diff --git a/packages/react/src/Token/TokenBase.tsx b/packages/react/src/Token/TokenBase.tsx
index 17025fc667f..03202c6f0cb 100644
--- a/packages/react/src/Token/TokenBase.tsx
+++ b/packages/react/src/Token/TokenBase.tsx
@@ -1,10 +1,10 @@
 import type {KeyboardEvent} from 'react'
 import React from 'react'
+import {clsx} from 'clsx'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import classes from './TokenBase.module.css'
 import {defaultTokenSize, type TokenSizeKeys} from './constants'
 import {isTokenInteractive} from './utils'
-import {mergeProps} from '../utils/mergeProps'
 
 export type {TokenSizeKeys}
 
@@ -55,38 +55,30 @@ const TokenBase = React.forwardRef<HTMLButtonElement | HTMLAnchorElement | HTMLS
     },
     forwardedRef,
   ) => {
-    const handleKeyDown = (event: KeyboardEvent<HTMLSpanElement & HTMLAnchorElement & HTMLButtonElement>) => {
-      if ((event.key === 'Backspace' || event.key === 'Delete') && onRemove) {
-        onRemove()
-      }
-    }
-
     return (
       <Component
-        {...mergeProps(
-          {
-            onKeyDown: handleKeyDown,
-            className: classes.TokenBase,
-            'data-cursor-is-interactive': isTokenInteractive({
-              as: Component,
-              onClick: rest.onClick,
-              onFocus: rest.onFocus,
-              tabIndex: rest.tabIndex,
-              disabled: rest.disabled,
-            }),
-            'data-size': size,
-          },
-          {
-            ...(Component === 'button'
-              ? (rest as React.ButtonHTMLAttributes<HTMLButtonElement>)
-              : Component === 'a'
-                ? (rest as React.AnchorHTMLAttributes<HTMLAnchorElement>)
-                : (rest as React.HTMLAttributes<HTMLSpanElement>)),
-            ...(onKeyDown ? {onKeyDown} : {}),
-            className,
-            id: id?.toString(),
-          },
-        )}
+        onKeyDown={(event: KeyboardEvent<HTMLSpanElement & HTMLAnchorElement & HTMLButtonElement>) => {
+          onKeyDown && onKeyDown(event)
+
+          if ((event.key === 'Backspace' || event.key === 'Delete') && onRemove) {
+            onRemove()
+          }
+        }}
+        className={clsx(classes.TokenBase, className)}
+        data-cursor-is-interactive={isTokenInteractive({
+          as: Component,
+          onClick: rest.onClick,
+          onFocus: rest.onFocus,
+          tabIndex: rest.tabIndex,
+          disabled: rest.disabled,
+        })}
+        data-size={size}
+        id={id?.toString()}
+        {...(Component === 'button'
+          ? (rest as React.ButtonHTMLAttributes<HTMLButtonElement>)
+          : Component === 'a'
+            ? (rest as React.AnchorHTMLAttributes<HTMLAnchorElement>)
+            : (rest as React.HTMLAttributes<HTMLSpanElement>))}
         // TypeScript cannot resolve polymorphic ref types at compile time
         // This assertion is safe because the ref will match the actual rendered element
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
diff --git a/packages/react/src/Token/__tests__/Token.test.tsx b/packages/react/src/Token/__tests__/Token.test.tsx
index ac07bbe22fe..73c01124c2a 100644
--- a/packages/react/src/Token/__tests__/Token.test.tsx
+++ b/packages/react/src/Token/__tests__/Token.test.tsx
@@ -63,17 +63,6 @@ const testTokenComponent = (Component: React.ComponentType<React.PropsWithChildr
     expect(onRemoveMock).toHaveBeenCalled()
   })
 
-  it('calls onRemove before the consumer onKeyDown handler', () => {
-    const calls: string[] = []
-    const {getByText} = HTMLRender(
-      <Component text="token" onRemove={() => calls.push('remove')} onKeyDown={() => calls.push('consumer')} />,
-    )
-
-    fireEvent.keyDown(getByText('token'), {key: 'Backspace'})
-
-    expect(calls).toEqual(['remove', 'consumer'])
-  })
-
   it('adds className to rendered component', () => {
     const {getByText} = HTMLRender(<Component text="token" className="testing-class" />)
     const domNode = getByText('token')
diff --git a/packages/react/src/VisuallyHidden/VisuallyHidden.tsx b/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
index d2b8231d952..d05c496352f 100644
--- a/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
+++ b/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
@@ -1,6 +1,6 @@
+import {clsx} from 'clsx'
 import type React from 'react'
 import {type HTMLAttributes} from 'react'
-import {mergeProps} from '../utils/mergeProps'
 import classes from './VisuallyHidden.module.css'
 
 /**
@@ -13,8 +13,12 @@ import classes from './VisuallyHidden.module.css'
  *
  * @see https://www.scottohara.me/blog/2023/03/21/visually-hidden-hack.html
  */
-export const VisuallyHidden = ({children, ...rest}: VisuallyHiddenProps) => {
-  return <span {...mergeProps({className: classes.VisuallyHidden}, rest)}>{children}</span>
+export const VisuallyHidden = ({className, children, ...rest}: VisuallyHiddenProps) => {
+  return (
+    <span className={clsx(className, classes.VisuallyHidden)} {...rest}>
+      {children}
+    </span>
+  )
 }
 
 export type VisuallyHiddenProps = React.PropsWithChildren<

From 241b8d78c89ec3c441c45b337e42b8fb265d685b Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 16:49:06 -0500
Subject: [PATCH 21/39] Preserve inline class name merging

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 .github/agents/migrate-to-merge-props-batch.agent.md |  6 ++++--
 .github/skills/migrate-to-merge-props/SKILL.md       | 11 +++++++----
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/.github/agents/migrate-to-merge-props-batch.agent.md b/.github/agents/migrate-to-merge-props-batch.agent.md
index b093977be22..17ab40cb4cd 100644
--- a/.github/agents/migrate-to-merge-props-batch.agent.md
+++ b/.github/agents/migrate-to-merge-props-batch.agent.md
@@ -41,11 +41,13 @@ unresolved architecture, accessibility, or public API decision.
 4. Implement only the assigned findings and tightly coupled tests, type tests,
    or changesets.
 5. Pass component props first and consumer props second.
-6. Keep component class names as strings.
+6. Destructure consumer class names and merge them inline with component class
+   names using `clsx`; omit `className` from the second `mergeProps` argument.
 7. Omit absent optional consumer handlers from the second argument.
 8. Compose refs separately.
 9. Omit or gate invariant attributes in public types and apply them after the
-   merged spread.
+   merged spread. Preserve existing consumer precedence for attributes that
+   were historically overridable.
 10. Format, lint, test, type-check, and run any requested Storybook,
     accessibility, visual, or build validation.
 11. Regenerate the report and confirm the assigned findings disappeared with
diff --git a/.github/skills/migrate-to-merge-props/SKILL.md b/.github/skills/migrate-to-merge-props/SKILL.md
index 89773b78497..15ea349a377 100644
--- a/.github/skills/migrate-to-merge-props/SKILL.md
+++ b/.github/skills/migrate-to-merge-props/SKILL.md
@@ -52,15 +52,18 @@ the driver entry.
 Apply these rules:
 
 1. Pass component-authored props first and consumer-authored props second.
-2. Keep the component-authored `className` as a string. Let `mergeProps` use
-   `clsx` to combine it with consumer class values.
+2. Destructure the consumer `className` and combine it with component class
+   names inline using `clsx`. Omit `className` from the consumer props passed to
+   `mergeProps`; do not delegate class-name composition to the utility.
 3. Do not add an optional consumer handler to the second argument when it is
    absent. An explicit `undefined` entry would replace the internal handler
    instead of composing it.
 4. Keep refs outside `mergeProps`.
 5. Put invariant attributes after the merged spread and omit them from the
-   public prop type. Use a discriminated union when ownership depends on the
-   rendered element.
+   public prop type. Only treat an attribute as invariant when the component
+   already owns it; preserve existing consumer precedence for historically
+   overridable attributes. Use a discriminated union when ownership depends on
+   the rendered element.
 6. Preserve intentional consumer `undefined` precedence for ordinary props.
 7. Add tests for event order, cancellation, controlled attributes, type
    exclusions, or other behavior that is not already covered.

From c59c26e54bdffedce730b7951664f9ad56a14936 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 16:49:50 -0500
Subject: [PATCH 22/39] Limit migration changesets to contract changes

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 .../agents/migrate-to-merge-props-batch.agent.md    | 10 +++++++---
 .github/skills/migrate-to-merge-props/SKILL.md      | 13 ++++++++++---
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/.github/agents/migrate-to-merge-props-batch.agent.md b/.github/agents/migrate-to-merge-props-batch.agent.md
index 17ab40cb4cd..c89377ee9f7 100644
--- a/.github/agents/migrate-to-merge-props-batch.agent.md
+++ b/.github/agents/migrate-to-merge-props-batch.agent.md
@@ -39,7 +39,7 @@ unresolved architecture, accessibility, or public API decision.
 3. Inspect public props, spread order, handlers, styles, class names, refs,
    invariant attributes, tests, stories, and nearby prior art.
 4. Implement only the assigned findings and tightly coupled tests, type tests,
-   or changesets.
+   or changesets required by genuine public contract changes.
 5. Pass component props first and consumer props second.
 6. Destructure consumer class names and merge them inline with component class
    names using `clsx`; omit `className` from the second `mergeProps` argument.
@@ -48,9 +48,13 @@ unresolved architecture, accessibility, or public API decision.
 9. Omit or gate invariant attributes in public types and apply them after the
    merged spread. Preserve existing consumer precedence for attributes that
    were historically overridable.
-10. Format, lint, test, type-check, and run any requested Storybook,
+10. Treat the migration as a behavior-preserving refactor and do not add a
+    changeset by default. Add one only when correctness requires a public
+    behavior or type change, such as documenting through types that an accepted
+    prop was never applied.
+11. Format, lint, test, type-check, and run any requested Storybook,
     accessibility, visual, or build validation.
-11. Regenerate the report and confirm the assigned findings disappeared with
+12. Regenerate the report and confirm the assigned findings disappeared with
     no new findings.
 
 Do not disable enforcement, add blanket suppressions, manipulate report output,
diff --git a/.github/skills/migrate-to-merge-props/SKILL.md b/.github/skills/migrate-to-merge-props/SKILL.md
index 15ea349a377..83a6cda8ba1 100644
--- a/.github/skills/migrate-to-merge-props/SKILL.md
+++ b/.github/skills/migrate-to-merge-props/SKILL.md
@@ -67,6 +67,10 @@ Apply these rules:
 6. Preserve intentional consumer `undefined` precedence for ordinary props.
 7. Add tests for event order, cancellation, controlled attributes, type
    exclusions, or other behavior that is not already covered.
+8. Treat component migrations as behavior-preserving refactors and do not add a
+   changeset by default. Add one only when correctness requires a genuine public
+   contract change, such as updating a type to communicate that an accepted prop
+   was never applied.
 
 ## Stack ownership contract
 
@@ -80,7 +84,8 @@ Every change must live in the entry that owns its concern:
   agent. It must not contain component migrations, migration changesets, or
   adoption-tool refinements.
 - `migrate/merge-props-batch-NN` owns only its assigned component
-  implementation, tightly coupled tests or stories, and required changesets.
+  implementation, tightly coupled tests or stories, and changesets required by
+  unavoidable public contract changes.
 - `migrate/merge-props-cleanup` owns final temporary-artifact removal and the
   ADR status update.
 
@@ -157,7 +162,8 @@ Group findings by component family and remediation pattern. Each batch must:
 - Own complete files rather than splitting a file between entries.
 - Be reviewable as one coherent change.
 - Avoid files already assigned to an existing stack entry.
-- Include tightly coupled tests and changesets.
+- Include tightly coupled tests and only the changesets required by genuine
+  public contract changes.
 
 Calculate the remaining batch count using the selected limit.
 
@@ -183,7 +189,8 @@ For each batch:
 2. Invoke `migrate-to-merge-props-batch` with the branch, exact paths and
    locations, maximum size, before counts, and targeted validation commands.
 3. Review the returned diff and evidence.
-4. Add or update changesets for consumer-facing behavior or type changes.
+4. Do not add a changeset for a behavior-preserving migration. Add or update one
+   only when the batch requires a genuine public behavior or type change.
 5. Confirm the entry contains no adoption-tool or driver changes.
 6. Commit only the assigned batch.
 7. Regenerate the report.

From 27384de0a436bfaba67a064195112fe81c75813f Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 16:50:43 -0500
Subject: [PATCH 23/39] Require refs before merged props

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 .github/agents/migrate-to-merge-props-batch.agent.md | 3 ++-
 .github/skills/migrate-to-merge-props/SKILL.md       | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.github/agents/migrate-to-merge-props-batch.agent.md b/.github/agents/migrate-to-merge-props-batch.agent.md
index c89377ee9f7..2b845ebc9ba 100644
--- a/.github/agents/migrate-to-merge-props-batch.agent.md
+++ b/.github/agents/migrate-to-merge-props-batch.agent.md
@@ -44,7 +44,8 @@ unresolved architecture, accessibility, or public API decision.
 6. Destructure consumer class names and merge them inline with component class
    names using `clsx`; omit `className` from the second `mergeProps` argument.
 7. Omit absent optional consumer handlers from the second argument.
-8. Compose refs separately.
+8. Compose refs separately and place the `ref` prop before the `mergeProps`
+   spread.
 9. Omit or gate invariant attributes in public types and apply them after the
    merged spread. Preserve existing consumer precedence for attributes that
    were historically overridable.
diff --git a/.github/skills/migrate-to-merge-props/SKILL.md b/.github/skills/migrate-to-merge-props/SKILL.md
index 83a6cda8ba1..0449df63a71 100644
--- a/.github/skills/migrate-to-merge-props/SKILL.md
+++ b/.github/skills/migrate-to-merge-props/SKILL.md
@@ -58,7 +58,8 @@ Apply these rules:
 3. Do not add an optional consumer handler to the second argument when it is
    absent. An explicit `undefined` entry would replace the internal handler
    instead of composing it.
-4. Keep refs outside `mergeProps`.
+4. Keep refs outside `mergeProps` and place the `ref` prop before the merged
+   spread.
 5. Put invariant attributes after the merged spread and omit them from the
    public prop type. Only treat an attribute as invariant when the component
    already owns it; preserve existing consumer precedence for historically

From 69589940097297206c173fb55eac4740e1b456d7 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 17:00:16 -0500
Subject: [PATCH 24/39] Plan migration batches by component volume

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 .../migrate-to-merge-props-batch.agent.md     | 10 ++--
 .../skills/migrate-to-merge-props/SKILL.md    | 46 +++++++++++++------
 2 files changed, 39 insertions(+), 17 deletions(-)

diff --git a/.github/agents/migrate-to-merge-props-batch.agent.md b/.github/agents/migrate-to-merge-props-batch.agent.md
index 2b845ebc9ba..24f570057b9 100644
--- a/.github/agents/migrate-to-merge-props-batch.agent.md
+++ b/.github/agents/migrate-to-merge-props-batch.agent.md
@@ -23,13 +23,14 @@ Do not begin without:
 
 - The current stack branch.
 - Exact component names, file paths, and report locations.
-- The maximum batch size.
+- The target changed LOC and acceptable fuzz.
 - Total and affected-file counts before the batch.
 - Targeted validation commands.
 
 Confirm the branch and findings still match the assignment. Stop if the batch
-is too large, overlaps another entry, includes unassigned files, or requires an
-unresolved architecture, accessibility, or public API decision.
+is materially larger than the target, overlaps another entry, splits an
+assigned component family without justification, includes unassigned files, or
+requires an unresolved architecture, accessibility, or public API decision.
 
 ## Workflow
 
@@ -57,6 +58,9 @@ unresolved architecture, accessibility, or public API decision.
     accessibility, visual, or build validation.
 12. Regenerate the report and confirm the assigned findings disappeared with
     no new findings.
+13. Measure additions plus deletions relative to the preceding entry. Treat the
+    LOC target as a planning guide rather than a hard cap when the assigned
+    component-family boundary is coherent.
 
 Do not disable enforcement, add blanket suppressions, manipulate report output,
 expose `mergeProps` publicly, fix unrelated findings, select another batch,
diff --git a/.github/skills/migrate-to-merge-props/SKILL.md b/.github/skills/migrate-to-merge-props/SKILL.md
index 0449df63a71..7b0aaf774c3 100644
--- a/.github/skills/migrate-to-merge-props/SKILL.md
+++ b/.github/skills/migrate-to-merge-props/SKILL.md
@@ -33,7 +33,10 @@ class names, and styles according to the ADR.
   pure pass-through roots that have one spread and no component-authored prop
   other than `ref` or `key`.
 - Refs are always composed separately with `useMergedRefs`.
-- Default maximum batch size: five findings.
+- Default batch target: roughly 500 changed lines, measured as additions plus
+  deletions relative to the preceding stack entry.
+- The LOC target is intentionally fuzzy. Component families are the dominant
+  boundary, so a coherent batch may land below or moderately above 500 lines.
 - Default run size: two sequential batches per invocation.
 - Never split one source file across separate batches.
 
@@ -157,30 +160,41 @@ output or exclusions to lower the count.
 
 ### 3. Plan non-overlapping batches
 
-Group findings by component family and remediation pattern. Each batch must:
+Use the `/primer-query` skill to query current `@primer/react` JSX usage for the
+affected component families before assigning batches. Give a high-volume
+component its own entry so review and rollout risk remain isolated. As a
+default, treat 500 or more JSX uses as high volume, but adjust at an obvious
+break in the current usage distribution.
+
+Group the remaining findings by component family and remediation pattern. Pack
+multiple lower-volume component families into an entry until its estimated diff
+approaches the selected changed-LOC target. Prefer keeping a family together
+over hitting the target exactly. Each batch must:
 
-- Contain at most the selected finding limit.
 - Own complete files rather than splitting a file between entries.
+- Keep a component family together unless the family is independently too large
+  or contains distinct remediation risks.
 - Be reviewable as one coherent change.
 - Avoid files already assigned to an existing stack entry.
 - Include tightly coupled tests and only the changesets required by genuine
   public contract changes.
 
-Calculate the remaining batch count using the selected limit.
+Estimate the remaining batch count from the planned family groupings and changed
+LOC target. Recalculate after each completed entry using its actual diff size.
 
 ### 4. Ask how much work to run
 
 Use a structured prompt containing:
 
-| Field       | Default | Constraint                               |
-| ----------- | ------- | ---------------------------------------- |
-| Batch size  | `5`     | Integer greater than or equal to `1`     |
-| Run mode    | Limited | Limited batches or all remaining batches |
-| Batch count | `2`     | Integer greater than or equal to `1`     |
+| Field              | Default | Constraint                               |
+| ------------------ | ------- | ---------------------------------------- |
+| Target changed LOC | `500`   | Integer greater than or equal to `1`     |
+| Run mode           | Limited | Limited batches or all remaining batches |
+| Batch count        | `2`     | Integer greater than or equal to `1`     |
 
-Show the baseline, calculated remaining batches, and exact assignments before
-editing. Prefer a small set of sequential batches over running the full
-migration at once.
+Show the baseline, usage-based high-volume classification, estimated remaining
+batches, and exact assignments before editing. Prefer a small set of sequential
+batches over running the full migration at once.
 
 ### 5. Run each selected batch
 
@@ -188,7 +202,8 @@ For each batch:
 
 1. Create `migrate/merge-props-batch-NN` with `gh stack add`.
 2. Invoke `migrate-to-merge-props-batch` with the branch, exact paths and
-   locations, maximum size, before counts, and targeted validation commands.
+   locations, target changed LOC and acceptable fuzz, before counts, and
+   targeted validation commands.
 3. Review the returned diff and evidence.
 4. Do not add a changeset for a behavior-preserving migration. Add or update one
    only when the batch requires a genuine public behavior or type change.
@@ -197,7 +212,10 @@ For each batch:
 7. Regenerate the report.
 8. Confirm assigned findings disappeared, no new findings appeared, and counts
    changed by the expected amount.
-9. Stop before another entry if validation or report evidence fails.
+9. Measure additions plus deletions relative to the preceding entry. Accept
+   moderate variance from the target when the component boundary is coherent;
+   stop and re-plan if the batch is materially larger than estimated.
+10. Stop before another entry if validation or report evidence fails.
 
 Run code-editing batch agents sequentially because every branch depends on the
 previous branch.

From 273dcf3969d3b5a7b1c09ba8f8cc5ee3fa190dc8 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Wed, 12 Aug 2026 11:20:06 -0500
Subject: [PATCH 25/39] Avoid clsx for single class names

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 84a0d8ca-13d3-4cb2-ab24-18fa2d9a8a14
---
 .github/agents/migrate-to-merge-props-batch.agent.md | 6 ++++--
 .github/skills/migrate-to-merge-props/SKILL.md       | 8 +++++---
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/.github/agents/migrate-to-merge-props-batch.agent.md b/.github/agents/migrate-to-merge-props-batch.agent.md
index 24f570057b9..acd11e4110d 100644
--- a/.github/agents/migrate-to-merge-props-batch.agent.md
+++ b/.github/agents/migrate-to-merge-props-batch.agent.md
@@ -42,8 +42,10 @@ requires an unresolved architecture, accessibility, or public API decision.
 4. Implement only the assigned findings and tightly coupled tests, type tests,
    or changesets required by genuine public contract changes.
 5. Pass component props first and consumer props second.
-6. Destructure consumer class names and merge them inline with component class
-   names using `clsx`; omit `className` from the second `mergeProps` argument.
+6. Destructure consumer class names. Merge component and consumer class names
+   inline using `clsx` only when there are multiple values to combine; pass a
+   single class name directly. Omit `className` from the second `mergeProps`
+   argument.
 7. Omit absent optional consumer handlers from the second argument.
 8. Compose refs separately and place the `ref` prop before the `mergeProps`
    spread.
diff --git a/.github/skills/migrate-to-merge-props/SKILL.md b/.github/skills/migrate-to-merge-props/SKILL.md
index 7b0aaf774c3..a1fc4a16344 100644
--- a/.github/skills/migrate-to-merge-props/SKILL.md
+++ b/.github/skills/migrate-to-merge-props/SKILL.md
@@ -55,9 +55,11 @@ the driver entry.
 Apply these rules:
 
 1. Pass component-authored props first and consumer-authored props second.
-2. Destructure the consumer `className` and combine it with component class
-   names inline using `clsx`. Omit `className` from the consumer props passed to
-   `mergeProps`; do not delegate class-name composition to the utility.
+2. Destructure the consumer `className`. Combine component and consumer class
+   names inline using `clsx` only when there are multiple values to combine. If
+   only one class name remains, pass it directly instead of wrapping it in
+   `clsx`. Omit `className` from the consumer props passed to `mergeProps`; do
+   not delegate class-name composition to the utility.
 3. Do not add an optional consumer handler to the second argument when it is
    absent. An explicit `undefined` entry would replace the internal handler
    instead of composing it.

From 38e9ea5e1b023e786b0dadd68ad1c714eba35c36 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Fri, 31 Jul 2026 13:35:31 -0500
Subject: [PATCH 26/39] Migrate initial components to mergeProps

Apply the validated class name, event handler, ref, and component-owned prop patterns in a dedicated implementation batch.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 00bfd295-6ed9-4119-8d63-103a0b3c63e8
---
 packages/react/src/Radio/Radio.test.tsx       |  1 +
 packages/react/src/Radio/Radio.tsx            | 32 ++++++-----
 packages/react/src/Radio/Radio.types.test.tsx |  6 +++
 packages/react/src/Token/TokenBase.tsx        | 54 +++++++++++--------
 .../react/src/Token/__tests__/Token.test.tsx  | 11 ++++
 .../src/VisuallyHidden/VisuallyHidden.tsx     | 10 ++--
 6 files changed, 72 insertions(+), 42 deletions(-)
 create mode 100644 packages/react/src/Radio/Radio.types.test.tsx

diff --git a/packages/react/src/Radio/Radio.test.tsx b/packages/react/src/Radio/Radio.test.tsx
index 1a7b9756dcd..d20071927db 100644
--- a/packages/react/src/Radio/Radio.test.tsx
+++ b/packages/react/src/Radio/Radio.test.tsx
@@ -21,6 +21,7 @@ describe('Radio', () => {
     const radio = getByRole('radio')
 
     expect(radio).toBeDefined()
+    expect(radio).toHaveAttribute('type', 'radio')
   })
 
   it('renders data-component attribute', () => {
diff --git a/packages/react/src/Radio/Radio.tsx b/packages/react/src/Radio/Radio.tsx
index 5ea79439a9f..d14e073f96e 100644
--- a/packages/react/src/Radio/Radio.tsx
+++ b/packages/react/src/Radio/Radio.tsx
@@ -5,6 +5,7 @@ import {clsx} from 'clsx'
 import sharedClasses from '../Checkbox/shared.module.css'
 import classes from './Radio.module.css'
 import type {WithSlotMarker} from '../utils/types'
+import {mergeProps} from '../utils/mergeProps'
 
 export type RadioProps = {
   /**
@@ -32,7 +33,7 @@ export type RadioProps = {
    * Indicates whether the radio button must be checked before the form can be submitted
    */
   required?: boolean
-} & InputHTMLAttributes<HTMLInputElement>
+} & Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>
 
 /**
  * An accessible, native radio component for selecting one option from a list.
@@ -56,7 +57,6 @@ const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
     const radioGroupContext = useContext(RadioGroupContext)
     const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
       radioGroupContext?.onChange && radioGroupContext.onChange(e)
-      onChange && onChange(e)
     }
     const name = nameProp || radioGroupContext?.name
 
@@ -69,17 +69,25 @@ const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
 
     return (
       <input
-        type="radio"
-        value={value}
-        name={name}
+        {...mergeProps(
+          {
+            onChange: handleOnChange,
+            className: clsx(sharedClasses.Input, classes.Radio),
+            'aria-checked': checked ? ('true' as const) : ('false' as const),
+          },
+          {
+            ...rest,
+            ...(onChange ? {onChange} : {}),
+            value,
+            name,
+            disabled,
+            checked,
+            required,
+            className,
+          },
+        )}
         ref={ref}
-        disabled={disabled}
-        checked={checked}
-        aria-checked={checked ? 'true' : 'false'}
-        required={required}
-        onChange={handleOnChange}
-        className={clsx(className, sharedClasses.Input, classes.Radio)}
-        {...rest}
+        type="radio"
         data-component="Radio"
       />
     )
diff --git a/packages/react/src/Radio/Radio.types.test.tsx b/packages/react/src/Radio/Radio.types.test.tsx
new file mode 100644
index 00000000000..a08856d1c1e
--- /dev/null
+++ b/packages/react/src/Radio/Radio.types.test.tsx
@@ -0,0 +1,6 @@
+import Radio from '.'
+
+export function doesNotAcceptType() {
+  // @ts-expect-error Radio always renders an input with type="radio"
+  return <Radio name="example" value="example" type="checkbox" />
+}
diff --git a/packages/react/src/Token/TokenBase.tsx b/packages/react/src/Token/TokenBase.tsx
index 03202c6f0cb..17025fc667f 100644
--- a/packages/react/src/Token/TokenBase.tsx
+++ b/packages/react/src/Token/TokenBase.tsx
@@ -1,10 +1,10 @@
 import type {KeyboardEvent} from 'react'
 import React from 'react'
-import {clsx} from 'clsx'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import classes from './TokenBase.module.css'
 import {defaultTokenSize, type TokenSizeKeys} from './constants'
 import {isTokenInteractive} from './utils'
+import {mergeProps} from '../utils/mergeProps'
 
 export type {TokenSizeKeys}
 
@@ -55,30 +55,38 @@ const TokenBase = React.forwardRef<HTMLButtonElement | HTMLAnchorElement | HTMLS
     },
     forwardedRef,
   ) => {
+    const handleKeyDown = (event: KeyboardEvent<HTMLSpanElement & HTMLAnchorElement & HTMLButtonElement>) => {
+      if ((event.key === 'Backspace' || event.key === 'Delete') && onRemove) {
+        onRemove()
+      }
+    }
+
     return (
       <Component
-        onKeyDown={(event: KeyboardEvent<HTMLSpanElement & HTMLAnchorElement & HTMLButtonElement>) => {
-          onKeyDown && onKeyDown(event)
-
-          if ((event.key === 'Backspace' || event.key === 'Delete') && onRemove) {
-            onRemove()
-          }
-        }}
-        className={clsx(classes.TokenBase, className)}
-        data-cursor-is-interactive={isTokenInteractive({
-          as: Component,
-          onClick: rest.onClick,
-          onFocus: rest.onFocus,
-          tabIndex: rest.tabIndex,
-          disabled: rest.disabled,
-        })}
-        data-size={size}
-        id={id?.toString()}
-        {...(Component === 'button'
-          ? (rest as React.ButtonHTMLAttributes<HTMLButtonElement>)
-          : Component === 'a'
-            ? (rest as React.AnchorHTMLAttributes<HTMLAnchorElement>)
-            : (rest as React.HTMLAttributes<HTMLSpanElement>))}
+        {...mergeProps(
+          {
+            onKeyDown: handleKeyDown,
+            className: classes.TokenBase,
+            'data-cursor-is-interactive': isTokenInteractive({
+              as: Component,
+              onClick: rest.onClick,
+              onFocus: rest.onFocus,
+              tabIndex: rest.tabIndex,
+              disabled: rest.disabled,
+            }),
+            'data-size': size,
+          },
+          {
+            ...(Component === 'button'
+              ? (rest as React.ButtonHTMLAttributes<HTMLButtonElement>)
+              : Component === 'a'
+                ? (rest as React.AnchorHTMLAttributes<HTMLAnchorElement>)
+                : (rest as React.HTMLAttributes<HTMLSpanElement>)),
+            ...(onKeyDown ? {onKeyDown} : {}),
+            className,
+            id: id?.toString(),
+          },
+        )}
         // TypeScript cannot resolve polymorphic ref types at compile time
         // This assertion is safe because the ref will match the actual rendered element
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
diff --git a/packages/react/src/Token/__tests__/Token.test.tsx b/packages/react/src/Token/__tests__/Token.test.tsx
index 73c01124c2a..ac07bbe22fe 100644
--- a/packages/react/src/Token/__tests__/Token.test.tsx
+++ b/packages/react/src/Token/__tests__/Token.test.tsx
@@ -63,6 +63,17 @@ const testTokenComponent = (Component: React.ComponentType<React.PropsWithChildr
     expect(onRemoveMock).toHaveBeenCalled()
   })
 
+  it('calls onRemove before the consumer onKeyDown handler', () => {
+    const calls: string[] = []
+    const {getByText} = HTMLRender(
+      <Component text="token" onRemove={() => calls.push('remove')} onKeyDown={() => calls.push('consumer')} />,
+    )
+
+    fireEvent.keyDown(getByText('token'), {key: 'Backspace'})
+
+    expect(calls).toEqual(['remove', 'consumer'])
+  })
+
   it('adds className to rendered component', () => {
     const {getByText} = HTMLRender(<Component text="token" className="testing-class" />)
     const domNode = getByText('token')
diff --git a/packages/react/src/VisuallyHidden/VisuallyHidden.tsx b/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
index d05c496352f..d2b8231d952 100644
--- a/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
+++ b/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
@@ -1,6 +1,6 @@
-import {clsx} from 'clsx'
 import type React from 'react'
 import {type HTMLAttributes} from 'react'
+import {mergeProps} from '../utils/mergeProps'
 import classes from './VisuallyHidden.module.css'
 
 /**
@@ -13,12 +13,8 @@ import classes from './VisuallyHidden.module.css'
  *
  * @see https://www.scottohara.me/blog/2023/03/21/visually-hidden-hack.html
  */
-export const VisuallyHidden = ({className, children, ...rest}: VisuallyHiddenProps) => {
-  return (
-    <span className={clsx(className, classes.VisuallyHidden)} {...rest}>
-      {children}
-    </span>
-  )
+export const VisuallyHidden = ({children, ...rest}: VisuallyHiddenProps) => {
+  return <span {...mergeProps({className: classes.VisuallyHidden}, rest)}>{children}</span>
 }
 
 export type VisuallyHiddenProps = React.PropsWithChildren<

From 2dba46fc026a516d30559abbb729c90c45c37ae2 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Mon, 10 Aug 2026 16:19:52 -0500
Subject: [PATCH 27/39] refactor: update based on ADR guidance

---
 packages/react/src/Radio/Radio.tsx     | 24 ++++-----------------
 packages/react/src/Token/TokenBase.tsx | 30 +++++++-------------------
 2 files changed, 12 insertions(+), 42 deletions(-)

diff --git a/packages/react/src/Radio/Radio.tsx b/packages/react/src/Radio/Radio.tsx
index d14e073f96e..243eca17644 100644
--- a/packages/react/src/Radio/Radio.tsx
+++ b/packages/react/src/Radio/Radio.tsx
@@ -40,17 +40,7 @@ export type RadioProps = {
  */
 const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
   (
-    {
-      checked,
-      disabled,
-      name: nameProp,
-      onChange,
-      required,
-      value,
-      className,
-      'aria-hidden': ariaHidden = false,
-      ...rest
-    }: RadioProps,
+    {checked, name: nameProp, 'aria-hidden': ariaHidden, ...rest}: RadioProps,
     ref,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): ReactElement<any> => {
@@ -74,17 +64,11 @@ const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
             onChange: handleOnChange,
             className: clsx(sharedClasses.Input, classes.Radio),
             'aria-checked': checked ? ('true' as const) : ('false' as const),
-          },
-          {
-            ...rest,
-            ...(onChange ? {onChange} : {}),
-            value,
-            name,
-            disabled,
+            'aria-hidden': ariaHidden,
             checked,
-            required,
-            className,
+            name,
           },
+          rest,
         )}
         ref={ref}
         type="radio"
diff --git a/packages/react/src/Token/TokenBase.tsx b/packages/react/src/Token/TokenBase.tsx
index 17025fc667f..8132c9ff3cd 100644
--- a/packages/react/src/Token/TokenBase.tsx
+++ b/packages/react/src/Token/TokenBase.tsx
@@ -42,24 +42,18 @@ export interface TokenBaseProps
 }
 
 const TokenBase = React.forwardRef<HTMLButtonElement | HTMLAnchorElement | HTMLSpanElement | undefined, TokenBaseProps>(
-  (
-    {
-      onRemove,
-      onKeyDown,
-      id,
-      className,
-      size = defaultTokenSize,
-      isSelected: _isSelected,
-      as: Component = 'span',
-      ...rest
-    },
-    forwardedRef,
-  ) => {
+  ({onRemove, id, size = defaultTokenSize, isSelected: _isSelected, as: Component = 'span', ...rest}, forwardedRef) => {
     const handleKeyDown = (event: KeyboardEvent<HTMLSpanElement & HTMLAnchorElement & HTMLButtonElement>) => {
       if ((event.key === 'Backspace' || event.key === 'Delete') && onRemove) {
         onRemove()
       }
     }
+    const consumerProps =
+      Component === 'button'
+        ? (rest as React.ButtonHTMLAttributes<HTMLButtonElement>)
+        : Component === 'a'
+          ? (rest as React.AnchorHTMLAttributes<HTMLAnchorElement>)
+          : (rest as React.HTMLAttributes<HTMLSpanElement>)
 
     return (
       <Component
@@ -75,17 +69,9 @@ const TokenBase = React.forwardRef<HTMLButtonElement | HTMLAnchorElement | HTMLS
               disabled: rest.disabled,
             }),
             'data-size': size,
-          },
-          {
-            ...(Component === 'button'
-              ? (rest as React.ButtonHTMLAttributes<HTMLButtonElement>)
-              : Component === 'a'
-                ? (rest as React.AnchorHTMLAttributes<HTMLAnchorElement>)
-                : (rest as React.HTMLAttributes<HTMLSpanElement>)),
-            ...(onKeyDown ? {onKeyDown} : {}),
-            className,
             id: id?.toString(),
           },
+          consumerProps,
         )}
         // TypeScript cannot resolve polymorphic ref types at compile time
         // This assertion is safe because the ref will match the actual rendered element

From 972770cd392d429496da369e5f012285c54cafd4 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 16:52:36 -0500
Subject: [PATCH 28/39] Keep component class name merging inline

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 packages/react/src/Radio/Radio.tsx               |  6 +++---
 packages/react/src/Token/TokenBase.tsx           | 16 ++++++++++------
 .../react/src/VisuallyHidden/VisuallyHidden.tsx  |  5 +++--
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/packages/react/src/Radio/Radio.tsx b/packages/react/src/Radio/Radio.tsx
index 243eca17644..78bb48abc89 100644
--- a/packages/react/src/Radio/Radio.tsx
+++ b/packages/react/src/Radio/Radio.tsx
@@ -40,7 +40,7 @@ export type RadioProps = {
  */
 const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
   (
-    {checked, name: nameProp, 'aria-hidden': ariaHidden, ...rest}: RadioProps,
+    {checked, name: nameProp, className, 'aria-hidden': ariaHidden, ...rest}: RadioProps,
     ref,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): ReactElement<any> => {
@@ -59,10 +59,11 @@ const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
 
     return (
       <input
+        ref={ref}
         {...mergeProps(
           {
             onChange: handleOnChange,
-            className: clsx(sharedClasses.Input, classes.Radio),
+            className: clsx(sharedClasses.Input, classes.Radio, className),
             'aria-checked': checked ? ('true' as const) : ('false' as const),
             'aria-hidden': ariaHidden,
             checked,
@@ -70,7 +71,6 @@ const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
           },
           rest,
         )}
-        ref={ref}
         type="radio"
         data-component="Radio"
       />
diff --git a/packages/react/src/Token/TokenBase.tsx b/packages/react/src/Token/TokenBase.tsx
index 8132c9ff3cd..dd50a47c10c 100644
--- a/packages/react/src/Token/TokenBase.tsx
+++ b/packages/react/src/Token/TokenBase.tsx
@@ -1,5 +1,6 @@
 import type {KeyboardEvent} from 'react'
 import React from 'react'
+import {clsx} from 'clsx'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import classes from './TokenBase.module.css'
 import {defaultTokenSize, type TokenSizeKeys} from './constants'
@@ -42,7 +43,10 @@ export interface TokenBaseProps
 }
 
 const TokenBase = React.forwardRef<HTMLButtonElement | HTMLAnchorElement | HTMLSpanElement | undefined, TokenBaseProps>(
-  ({onRemove, id, size = defaultTokenSize, isSelected: _isSelected, as: Component = 'span', ...rest}, forwardedRef) => {
+  (
+    {onRemove, id, className, size = defaultTokenSize, isSelected: _isSelected, as: Component = 'span', ...rest},
+    forwardedRef,
+  ) => {
     const handleKeyDown = (event: KeyboardEvent<HTMLSpanElement & HTMLAnchorElement & HTMLButtonElement>) => {
       if ((event.key === 'Backspace' || event.key === 'Delete') && onRemove) {
         onRemove()
@@ -57,10 +61,14 @@ const TokenBase = React.forwardRef<HTMLButtonElement | HTMLAnchorElement | HTMLS
 
     return (
       <Component
+        // TypeScript cannot resolve polymorphic ref types at compile time
+        // This assertion is safe because the ref will match the actual rendered element
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ref={forwardedRef as any}
         {...mergeProps(
           {
             onKeyDown: handleKeyDown,
-            className: classes.TokenBase,
+            className: clsx(classes.TokenBase, className),
             'data-cursor-is-interactive': isTokenInteractive({
               as: Component,
               onClick: rest.onClick,
@@ -73,10 +81,6 @@ const TokenBase = React.forwardRef<HTMLButtonElement | HTMLAnchorElement | HTMLS
           },
           consumerProps,
         )}
-        // TypeScript cannot resolve polymorphic ref types at compile time
-        // This assertion is safe because the ref will match the actual rendered element
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        ref={forwardedRef as any}
       />
     )
   },
diff --git a/packages/react/src/VisuallyHidden/VisuallyHidden.tsx b/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
index d2b8231d952..dd9aefbdb9d 100644
--- a/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
+++ b/packages/react/src/VisuallyHidden/VisuallyHidden.tsx
@@ -1,3 +1,4 @@
+import {clsx} from 'clsx'
 import type React from 'react'
 import {type HTMLAttributes} from 'react'
 import {mergeProps} from '../utils/mergeProps'
@@ -13,8 +14,8 @@ import classes from './VisuallyHidden.module.css'
  *
  * @see https://www.scottohara.me/blog/2023/03/21/visually-hidden-hack.html
  */
-export const VisuallyHidden = ({children, ...rest}: VisuallyHiddenProps) => {
-  return <span {...mergeProps({className: classes.VisuallyHidden}, rest)}>{children}</span>
+export const VisuallyHidden = ({className, children, ...rest}: VisuallyHiddenProps) => {
+  return <span {...mergeProps({className: clsx(classes.VisuallyHidden, className)}, rest)}>{children}</span>
 }
 
 export type VisuallyHiddenProps = React.PropsWithChildren<

From 1dc21a872972d95d56ec064e4f6e5f9e8a154a59 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 16:35:07 -0500
Subject: [PATCH 29/39] Migrate ActionList roots to mergeProps

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 .changeset/calm-action-lists-merge.md         |  5 ++++
 packages/react/src/ActionList/Group.tsx       | 20 ++++++-------
 .../ActionList/GroupHeadingTrailingAction.tsx | 23 +++++++++------
 packages/react/src/ActionList/Heading.tsx     | 29 +++++++++++--------
 packages/react/src/ActionList/Item.test.tsx   |  1 +
 packages/react/src/ActionList/Item.tsx        |  5 ++--
 6 files changed, 50 insertions(+), 33 deletions(-)
 create mode 100644 .changeset/calm-action-lists-merge.md

diff --git a/.changeset/calm-action-lists-merge.md b/.changeset/calm-action-lists-merge.md
new file mode 100644
index 00000000000..ac258866b05
--- /dev/null
+++ b/.changeset/calm-action-lists-merge.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+ActionList: Preserve component behavior and styling when merging consumer props
diff --git a/packages/react/src/ActionList/Group.tsx b/packages/react/src/ActionList/Group.tsx
index 5d981a41947..e508e7893f1 100644
--- a/packages/react/src/ActionList/Group.tsx
+++ b/packages/react/src/ActionList/Group.tsx
@@ -11,6 +11,7 @@ import type {FCWithSlotMarker} from '../utils/types/Slots'
 import {GroupHeadingTrailingAction} from './GroupHeadingTrailingAction'
 import {useFeatureFlag} from '../FeatureFlags'
 import {GroupContext} from './GroupContext'
+import {mergeProps} from '../utils/mergeProps'
 
 const GROUP_HEADING_TRAILING_ACTION_FEATURE_FLAG = 'primer_react_action_list_group_heading_trailing_action'
 
@@ -28,11 +29,7 @@ const Heading: React.FC<HeadingProps & React.HTMLAttributes<HTMLHeadingElement>>
   id,
   ...rest
 }) => {
-  return (
-    <Component className={className} id={id} {...rest}>
-      {children}
-    </Component>
-  )
+  return <Component {...mergeProps({className, id}, rest)}>{children}</Component>
 }
 
 type HeadingWrapProps = {
@@ -73,7 +70,6 @@ export const Group: FCWithSlotMarker<React.PropsWithChildren<ActionListGroupProp
   auxiliaryText,
   selectionVariant,
   role,
-  className,
   'aria-label': ariaLabel,
   ...props
 }) => {
@@ -98,10 +94,14 @@ export const Group: FCWithSlotMarker<React.PropsWithChildren<ActionListGroupProp
 
   return (
     <li
-      className={clsx(className, groupClasses.Group)}
-      data-component="ActionList.Group"
-      role={listRole ? 'none' : undefined}
-      {...props}
+      {...mergeProps(
+        {
+          className: groupClasses.Group,
+          'data-component': 'ActionList.Group',
+          role: listRole ? 'none' : undefined,
+        },
+        props,
+      )}
     >
       <GroupContext.Provider value={{selectionVariant, groupHeadingId}}>
         {title && !slots.groupHeading ? (
diff --git a/packages/react/src/ActionList/GroupHeadingTrailingAction.tsx b/packages/react/src/ActionList/GroupHeadingTrailingAction.tsx
index a9b809c7466..9dc25e90921 100644
--- a/packages/react/src/ActionList/GroupHeadingTrailingAction.tsx
+++ b/packages/react/src/ActionList/GroupHeadingTrailingAction.tsx
@@ -4,6 +4,7 @@ import {IconButton} from '../Button'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import type {SlotMarker} from '../utils/types/Slots'
 import type {ActionListTrailingActionProps} from './TrailingAction'
+import {mergeProps} from '../utils/mergeProps'
 
 /**
  * Props for `ActionList.GroupHeading.TrailingAction`.
@@ -21,17 +22,21 @@ export type ActionListGroupHeadingTrailingActionProps = Omit<ActionListTrailingA
 const GroupHeadingTrailingActionImpl = forwardRef(
   ({as = 'button', icon, label, href = null, tooltipDirection = 'w', ...props}, forwardedRef) => (
     <IconButton
-      as={as}
-      aria-label={label}
-      icon={icon}
-      variant="invisible"
-      size="small"
-      tooltipDirection={tooltipDirection}
-      href={href}
+      {...mergeProps(
+        {
+          as,
+          'aria-label': label,
+          icon,
+          variant: 'invisible' as const,
+          size: 'small' as const,
+          tooltipDirection,
+          href,
+          'data-component': 'ActionList.GroupHeading.TrailingAction',
+        },
+        props,
+      )}
       // @ts-expect-error StyledButton wants both Anchor and Button refs
       ref={forwardedRef}
-      data-component="ActionList.GroupHeading.TrailingAction"
-      {...props}
     />
   ),
 ) as PolymorphicForwardRefComponent<'button' | 'a', ActionListGroupHeadingTrailingActionProps> & {
diff --git a/packages/react/src/ActionList/Heading.tsx b/packages/react/src/ActionList/Heading.tsx
index b8dd90e305d..3c5920a00bf 100644
--- a/packages/react/src/ActionList/Heading.tsx
+++ b/packages/react/src/ActionList/Heading.tsx
@@ -8,6 +8,7 @@ import {invariant} from '../utils/invariant'
 import {clsx} from 'clsx'
 import classes from './Heading.module.css'
 import visuallyHiddenClasses from '../_VisuallyHidden.module.css'
+import {mergeProps} from '../utils/mergeProps'
 
 type HeadingLevels = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
 type HeadingVariants = 'large' | 'medium' | 'small'
@@ -19,7 +20,7 @@ export type ActionListHeadingProps = {
   style?: React.CSSProperties
 }
 
-export const Heading = forwardRef(({as, size, children, visuallyHidden = false, className, ...props}, forwardedRef) => {
+export const Heading = forwardRef(({as, size, children, visuallyHidden = false, ...props}, forwardedRef) => {
   const innerRef = React.useRef<HTMLHeadingElement>(null)
   const mergedRef = useMergedRefs(forwardedRef, innerRef)
 
@@ -35,18 +36,22 @@ export const Heading = forwardRef(({as, size, children, visuallyHidden = false,
   return (
     <HeadingComponent
       as={as}
-      variant={size}
+      {...mergeProps(
+        {
+          variant: size,
+          // use custom id if it is provided. Otherwise, use the id from the context
+          id: props.id ?? headingId,
+          // Apply the visually-hidden styles directly to the heading rather than wrapping
+          // it in a span (a heading isn't valid phrasing content inside a span).
+          className: clsx(classes.ActionListHeader, {
+            [visuallyHiddenClasses.InternalVisuallyHidden]: visuallyHidden,
+          }),
+          'data-component': 'ActionList.Heading',
+          'data-list-variant': listVariant,
+        },
+        props,
+      )}
       ref={mergedRef}
-      // use custom id if it is provided. Otherwise, use the id from the context
-      id={props.id ?? headingId}
-      // Apply the visually-hidden styles directly to the heading rather than wrapping
-      // it in a span (a heading isn't valid phrasing content inside a span).
-      className={clsx(className, classes.ActionListHeader, {
-        [visuallyHiddenClasses.InternalVisuallyHidden]: visuallyHidden,
-      })}
-      data-component="ActionList.Heading"
-      data-list-variant={listVariant}
-      {...props}
     >
       {children}
     </HeadingComponent>
diff --git a/packages/react/src/ActionList/Item.test.tsx b/packages/react/src/ActionList/Item.test.tsx
index 1dbfb0d453b..21d3556e2c9 100644
--- a/packages/react/src/ActionList/Item.test.tsx
+++ b/packages/react/src/ActionList/Item.test.tsx
@@ -208,6 +208,7 @@ describe('ActionList.Item', () => {
     )
     const button = container.querySelector('button')
     expect(button).toHaveTextContent('Item 1')
+    expect(button).toHaveAttribute('type', 'button')
     // Ensure passed prop "disabled" is applied to the button
     expect(button).toHaveAttribute('aria-disabled', 'true')
     const listItems = container.querySelectorAll('li')
diff --git a/packages/react/src/ActionList/Item.tsx b/packages/react/src/ActionList/Item.tsx
index 1606952e3e1..88dce805b95 100644
--- a/packages/react/src/ActionList/Item.tsx
+++ b/packages/react/src/ActionList/Item.tsx
@@ -17,6 +17,7 @@ import {clsx} from 'clsx'
 import {fixedForwardRef} from '../utils/modern-polymorphic'
 import {Tooltip} from '../TooltipV2'
 import {TooltipContext} from '../TooltipV2/TooltipContext'
+import {mergeProps} from '../utils/mergeProps'
 
 type ActionListSubItemProps = {
   children?: React.ReactNode
@@ -51,9 +52,9 @@ export const SubItem: React.FC<ActionListSubItemProps> = ({children}) => {
 SubItem.displayName = 'ActionList.SubItem'
 
 const ButtonItemContainer = React.forwardRef<HTMLButtonElement, React.HTMLAttributes<HTMLButtonElement>>(
-  ({children, style, ...props}, forwardedRef) => {
+  ({children, ...props}, forwardedRef) => {
     return (
-      <button type="button" ref={forwardedRef as React.Ref<HTMLButtonElement>} style={style} {...props}>
+      <button {...mergeProps({}, props)} ref={forwardedRef as React.Ref<HTMLButtonElement>} type="button">
         {children}
       </button>
     )

From 1e0c5a4997acb7daee3987eca42fd6cc71c5654a Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 16:55:25 -0500
Subject: [PATCH 30/39] Preserve ActionList prop behavior

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 .changeset/calm-action-lists-merge.md              |  5 -----
 packages/react/src/ActionList/Group.tsx            |  3 ++-
 .../src/ActionList/GroupHeadingTrailingAction.tsx  |  4 ++--
 packages/react/src/ActionList/Heading.tsx          | 14 +++++++++-----
 packages/react/src/ActionList/Item.test.tsx        | 10 ++++++++++
 packages/react/src/ActionList/Item.tsx             |  4 ++--
 6 files changed, 25 insertions(+), 15 deletions(-)
 delete mode 100644 .changeset/calm-action-lists-merge.md

diff --git a/.changeset/calm-action-lists-merge.md b/.changeset/calm-action-lists-merge.md
deleted file mode 100644
index ac258866b05..00000000000
--- a/.changeset/calm-action-lists-merge.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@primer/react': patch
----
-
-ActionList: Preserve component behavior and styling when merging consumer props
diff --git a/packages/react/src/ActionList/Group.tsx b/packages/react/src/ActionList/Group.tsx
index e508e7893f1..7f18e8a9d76 100644
--- a/packages/react/src/ActionList/Group.tsx
+++ b/packages/react/src/ActionList/Group.tsx
@@ -70,6 +70,7 @@ export const Group: FCWithSlotMarker<React.PropsWithChildren<ActionListGroupProp
   auxiliaryText,
   selectionVariant,
   role,
+  className,
   'aria-label': ariaLabel,
   ...props
 }) => {
@@ -96,7 +97,7 @@ export const Group: FCWithSlotMarker<React.PropsWithChildren<ActionListGroupProp
     <li
       {...mergeProps(
         {
-          className: groupClasses.Group,
+          className: clsx(groupClasses.Group, className),
           'data-component': 'ActionList.Group',
           role: listRole ? 'none' : undefined,
         },
diff --git a/packages/react/src/ActionList/GroupHeadingTrailingAction.tsx b/packages/react/src/ActionList/GroupHeadingTrailingAction.tsx
index 9dc25e90921..e8fea3bce10 100644
--- a/packages/react/src/ActionList/GroupHeadingTrailingAction.tsx
+++ b/packages/react/src/ActionList/GroupHeadingTrailingAction.tsx
@@ -22,6 +22,8 @@ export type ActionListGroupHeadingTrailingActionProps = Omit<ActionListTrailingA
 const GroupHeadingTrailingActionImpl = forwardRef(
   ({as = 'button', icon, label, href = null, tooltipDirection = 'w', ...props}, forwardedRef) => (
     <IconButton
+      // @ts-expect-error StyledButton wants both Anchor and Button refs
+      ref={forwardedRef}
       {...mergeProps(
         {
           as,
@@ -35,8 +37,6 @@ const GroupHeadingTrailingActionImpl = forwardRef(
         },
         props,
       )}
-      // @ts-expect-error StyledButton wants both Anchor and Button refs
-      ref={forwardedRef}
     />
   ),
 ) as PolymorphicForwardRefComponent<'button' | 'a', ActionListGroupHeadingTrailingActionProps> & {
diff --git a/packages/react/src/ActionList/Heading.tsx b/packages/react/src/ActionList/Heading.tsx
index 3c5920a00bf..3bb1ec3ec26 100644
--- a/packages/react/src/ActionList/Heading.tsx
+++ b/packages/react/src/ActionList/Heading.tsx
@@ -20,7 +20,7 @@ export type ActionListHeadingProps = {
   style?: React.CSSProperties
 }
 
-export const Heading = forwardRef(({as, size, children, visuallyHidden = false, ...props}, forwardedRef) => {
+export const Heading = forwardRef(({as, size, children, visuallyHidden = false, className, ...props}, forwardedRef) => {
   const innerRef = React.useRef<HTMLHeadingElement>(null)
   const mergedRef = useMergedRefs(forwardedRef, innerRef)
 
@@ -35,6 +35,7 @@ export const Heading = forwardRef(({as, size, children, visuallyHidden = false,
 
   return (
     <HeadingComponent
+      ref={mergedRef}
       as={as}
       {...mergeProps(
         {
@@ -43,15 +44,18 @@ export const Heading = forwardRef(({as, size, children, visuallyHidden = false,
           id: props.id ?? headingId,
           // Apply the visually-hidden styles directly to the heading rather than wrapping
           // it in a span (a heading isn't valid phrasing content inside a span).
-          className: clsx(classes.ActionListHeader, {
-            [visuallyHiddenClasses.InternalVisuallyHidden]: visuallyHidden,
-          }),
+          className: clsx(
+            classes.ActionListHeader,
+            {
+              [visuallyHiddenClasses.InternalVisuallyHidden]: visuallyHidden,
+            },
+            className,
+          ),
           'data-component': 'ActionList.Heading',
           'data-list-variant': listVariant,
         },
         props,
       )}
-      ref={mergedRef}
     >
       {children}
     </HeadingComponent>
diff --git a/packages/react/src/ActionList/Item.test.tsx b/packages/react/src/ActionList/Item.test.tsx
index 21d3556e2c9..5a2835e7b8d 100644
--- a/packages/react/src/ActionList/Item.test.tsx
+++ b/packages/react/src/ActionList/Item.test.tsx
@@ -214,6 +214,16 @@ describe('ActionList.Item', () => {
     const listItems = container.querySelectorAll('li')
     expect(listItems.length).toBe(2)
   })
+  it('allows consumers to override the button type', async () => {
+    const props = {type: 'submit'} as const
+    const {container} = HTMLRender(
+      <ActionList>
+        <ActionList.Item {...props}>Item 1</ActionList.Item>
+      </ActionList>,
+    )
+
+    expect(container.querySelector('button')).toHaveAttribute('type', 'submit')
+  })
   it('should render ActionList.Item as li when item has proper aria role', async () => {
     const {container} = HTMLRender(
       <ActionList role="listbox">
diff --git a/packages/react/src/ActionList/Item.tsx b/packages/react/src/ActionList/Item.tsx
index 88dce805b95..441f120363e 100644
--- a/packages/react/src/ActionList/Item.tsx
+++ b/packages/react/src/ActionList/Item.tsx
@@ -51,10 +51,10 @@ export const SubItem: React.FC<ActionListSubItemProps> = ({children}) => {
 
 SubItem.displayName = 'ActionList.SubItem'
 
-const ButtonItemContainer = React.forwardRef<HTMLButtonElement, React.HTMLAttributes<HTMLButtonElement>>(
+const ButtonItemContainer = React.forwardRef<HTMLButtonElement, React.ButtonHTMLAttributes<HTMLButtonElement>>(
   ({children, ...props}, forwardedRef) => {
     return (
-      <button {...mergeProps({}, props)} ref={forwardedRef as React.Ref<HTMLButtonElement>} type="button">
+      <button ref={forwardedRef as React.Ref<HTMLButtonElement>} type="button" {...mergeProps({}, props)}>
         {children}
       </button>
     )

From 28b19cabd8d2dfa4e9ec87718025b212ef5a0c97 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 16:42:42 -0500
Subject: [PATCH 31/39] Migrate Button roots to mergeProps

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 .changeset/bright-buttons-merge.md       |  5 +++
 packages/react/src/Button/Button.tsx     |  3 +-
 packages/react/src/Button/IconButton.tsx | 41 ++++++++++++++----------
 packages/react/src/Button/LinkButton.tsx |  3 +-
 4 files changed, 33 insertions(+), 19 deletions(-)
 create mode 100644 .changeset/bright-buttons-merge.md

diff --git a/.changeset/bright-buttons-merge.md b/.changeset/bright-buttons-merge.md
new file mode 100644
index 00000000000..cfef16dd2f3
--- /dev/null
+++ b/.changeset/bright-buttons-merge.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Button: Preserve component behavior and styling when merging consumer props
diff --git a/packages/react/src/Button/Button.tsx b/packages/react/src/Button/Button.tsx
index 30f64bd9d67..367ccbe00a1 100644
--- a/packages/react/src/Button/Button.tsx
+++ b/packages/react/src/Button/Button.tsx
@@ -2,10 +2,11 @@ import {forwardRef, type JSX} from 'react'
 import type {ButtonProps} from './types'
 import {ButtonBase} from './ButtonBase'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
+import {mergeProps} from '../utils/mergeProps'
 
 const ButtonComponent = forwardRef(({children, ...props}, forwardedRef): JSX.Element => {
   return (
-    <ButtonBase ref={forwardedRef} as="button" type="button" {...props}>
+    <ButtonBase {...mergeProps({as: 'button', type: 'button'}, props)} ref={forwardedRef}>
       {children}
     </ButtonBase>
   )
diff --git a/packages/react/src/Button/IconButton.tsx b/packages/react/src/Button/IconButton.tsx
index b48d54475a5..753bbaa0788 100644
--- a/packages/react/src/Button/IconButton.tsx
+++ b/packages/react/src/Button/IconButton.tsx
@@ -6,7 +6,7 @@ import {Tooltip} from '../TooltipV2/Tooltip'
 import {TooltipContext} from '../TooltipV2/TooltipContext'
 import {TooltipContext as TooltipContextV1} from '../Tooltip/TooltipContext'
 import classes from './ButtonBase.module.css'
-import {clsx} from 'clsx'
+import {mergeProps} from '../utils/mergeProps'
 
 const IconButton = forwardRef(
   (
@@ -20,7 +20,6 @@ const IconButton = forwardRef(
       unsafeDisableTooltip = false,
       keyshortcuts,
       keybindingHint,
-      className,
       ...props
     },
     forwardedRef,
@@ -43,13 +42,17 @@ const IconButton = forwardRef(
     if (withoutTooltip) {
       return (
         <ButtonBase
-          icon={Icon}
-          className={clsx(className, classes.IconButton)}
-          data-component="IconButton"
-          type="button"
-          aria-label={ariaLabel}
-          disabled={disabled}
-          {...props}
+          {...mergeProps(
+            {
+              icon: Icon,
+              className: classes.IconButton,
+              'data-component': 'IconButton',
+              type: 'button',
+              'aria-label': ariaLabel,
+              disabled,
+            },
+            props,
+          )}
           // @ts-expect-error StyledButton wants both Anchor and Button refs
           ref={forwardedRef}
         />
@@ -66,14 +69,18 @@ const IconButton = forwardRef(
           _privateDisableTooltip={hasActivePopup}
         >
           <ButtonBase
-            icon={Icon}
-            className={clsx(className, classes.IconButton)}
-            data-component="IconButton"
-            type="button"
-            aria-keyshortcuts={keyshortcuts ?? undefined}
-            // If description is provided, we will use the tooltip to describe the button, so we need to keep the aria-label to label the button.
-            aria-label={description ? ariaLabel : undefined}
-            {...props}
+            {...mergeProps(
+              {
+                icon: Icon,
+                className: classes.IconButton,
+                'data-component': 'IconButton',
+                type: 'button',
+                'aria-keyshortcuts': keyshortcuts ?? undefined,
+                // If description is provided, we will use the tooltip to describe the button, so we need to keep the aria-label to label the button.
+                'aria-label': description ? ariaLabel : undefined,
+              },
+              props,
+            )}
           />
         </Tooltip>
       )
diff --git a/packages/react/src/Button/LinkButton.tsx b/packages/react/src/Button/LinkButton.tsx
index a617581fa8b..7244e1ea4c7 100644
--- a/packages/react/src/Button/LinkButton.tsx
+++ b/packages/react/src/Button/LinkButton.tsx
@@ -2,12 +2,13 @@ import {forwardRef, type JSX} from 'react'
 import type {LinkButtonProps as BaseLinkButtonProps, ButtonProps} from './types'
 import {ButtonBase} from './ButtonBase'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
+import {mergeProps} from '../utils/mergeProps'
 
 export type LinkButtonProps = BaseLinkButtonProps & ButtonProps
 
 const LinkButton = forwardRef(({children, as: Component = 'a', ...props}, forwardedRef): JSX.Element => {
   return (
-    <ButtonBase as={Component} ref={forwardedRef} data-component="LinkButton" {...props}>
+    <ButtonBase {...mergeProps({as: Component, 'data-component': 'LinkButton'}, props)} ref={forwardedRef}>
       {children}
     </ButtonBase>
   )

From 2a7e15c9400d933f7b7392a0e96d4ed1ac09981b Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Tue, 11 Aug 2026 16:56:58 -0500
Subject: [PATCH 32/39] Preserve Button prop behavior

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9541ca7f-0281-4223-a839-39d75393d922
---
 .changeset/bright-buttons-merge.md       |  5 -----
 packages/react/src/Button/Button.tsx     |  2 +-
 packages/react/src/Button/IconButton.tsx | 10 ++++++----
 packages/react/src/Button/LinkButton.tsx |  2 +-
 4 files changed, 8 insertions(+), 11 deletions(-)
 delete mode 100644 .changeset/bright-buttons-merge.md

diff --git a/.changeset/bright-buttons-merge.md b/.changeset/bright-buttons-merge.md
deleted file mode 100644
index cfef16dd2f3..00000000000
--- a/.changeset/bright-buttons-merge.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-'@primer/react': patch
----
-
-Button: Preserve component behavior and styling when merging consumer props
diff --git a/packages/react/src/Button/Button.tsx b/packages/react/src/Button/Button.tsx
index 367ccbe00a1..080d67fd329 100644
--- a/packages/react/src/Button/Button.tsx
+++ b/packages/react/src/Button/Button.tsx
@@ -6,7 +6,7 @@ import {mergeProps} from '../utils/mergeProps'
 
 const ButtonComponent = forwardRef(({children, ...props}, forwardedRef): JSX.Element => {
   return (
-    <ButtonBase {...mergeProps({as: 'button', type: 'button'}, props)} ref={forwardedRef}>
+    <ButtonBase ref={forwardedRef} {...mergeProps({as: 'button', type: 'button'}, props)}>
       {children}
     </ButtonBase>
   )
diff --git a/packages/react/src/Button/IconButton.tsx b/packages/react/src/Button/IconButton.tsx
index 753bbaa0788..617e751044f 100644
--- a/packages/react/src/Button/IconButton.tsx
+++ b/packages/react/src/Button/IconButton.tsx
@@ -7,6 +7,7 @@ import {TooltipContext} from '../TooltipV2/TooltipContext'
 import {TooltipContext as TooltipContextV1} from '../Tooltip/TooltipContext'
 import classes from './ButtonBase.module.css'
 import {mergeProps} from '../utils/mergeProps'
+import {clsx} from 'clsx'
 
 const IconButton = forwardRef(
   (
@@ -20,6 +21,7 @@ const IconButton = forwardRef(
       unsafeDisableTooltip = false,
       keyshortcuts,
       keybindingHint,
+      className,
       ...props
     },
     forwardedRef,
@@ -42,10 +44,12 @@ const IconButton = forwardRef(
     if (withoutTooltip) {
       return (
         <ButtonBase
+          // @ts-expect-error StyledButton wants both Anchor and Button refs
+          ref={forwardedRef}
           {...mergeProps(
             {
               icon: Icon,
-              className: classes.IconButton,
+              className: clsx(classes.IconButton, className),
               'data-component': 'IconButton',
               type: 'button',
               'aria-label': ariaLabel,
@@ -53,8 +57,6 @@ const IconButton = forwardRef(
             },
             props,
           )}
-          // @ts-expect-error StyledButton wants both Anchor and Button refs
-          ref={forwardedRef}
         />
       )
     } else {
@@ -72,7 +74,7 @@ const IconButton = forwardRef(
             {...mergeProps(
               {
                 icon: Icon,
-                className: classes.IconButton,
+                className: clsx(classes.IconButton, className),
                 'data-component': 'IconButton',
                 type: 'button',
                 'aria-keyshortcuts': keyshortcuts ?? undefined,
diff --git a/packages/react/src/Button/LinkButton.tsx b/packages/react/src/Button/LinkButton.tsx
index 7244e1ea4c7..b15aed99ca2 100644
--- a/packages/react/src/Button/LinkButton.tsx
+++ b/packages/react/src/Button/LinkButton.tsx
@@ -8,7 +8,7 @@ export type LinkButtonProps = BaseLinkButtonProps & ButtonProps
 
 const LinkButton = forwardRef(({children, as: Component = 'a', ...props}, forwardedRef): JSX.Element => {
   return (
-    <ButtonBase {...mergeProps({as: Component, 'data-component': 'LinkButton'}, props)} ref={forwardedRef}>
+    <ButtonBase ref={forwardedRef} {...mergeProps({as: Component, 'data-component': 'LinkButton'}, props)}>
       {children}
     </ButtonBase>
   )

From 5b3f3d2795aa291d8172c84dbdd187fcab5fad64 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Wed, 12 Aug 2026 09:29:20 -0500
Subject: [PATCH 33/39] Migrate Text root to mergeProps

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 84a0d8ca-13d3-4cb2-ab24-18fa2d9a8a14
---
 packages/react/src/Text/Text.tsx | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/packages/react/src/Text/Text.tsx b/packages/react/src/Text/Text.tsx
index 7bc199f10b8..35c9fea9557 100644
--- a/packages/react/src/Text/Text.tsx
+++ b/packages/react/src/Text/Text.tsx
@@ -3,6 +3,7 @@ import type React from 'react'
 import {type ForwardedRef} from 'react'
 import classes from './Text.module.css'
 import {fixedForwardRef, type PolymorphicProps} from '../utils/modern-polymorphic'
+import {mergeProps} from '../utils/mergeProps'
 
 export type TextProps<As extends React.ElementType = 'span'> = PolymorphicProps<
   As,
@@ -21,13 +22,17 @@ function Text<As extends React.ElementType>(props: TextProps<As>, ref: Forwarded
 
   return (
     <Component
-      className={clsx(className, classes.Text)}
-      data-component="Text"
-      data-size={size}
-      data-weight={weight}
-      data-white-space={whiteSpace}
-      {...rest}
       ref={ref}
+      {...mergeProps(
+        {
+          className: clsx(classes.Text, className),
+          'data-component': 'Text',
+          'data-size': size,
+          'data-weight': weight,
+          'data-white-space': whiteSpace,
+        },
+        rest,
+      )}
     />
   )
 }

From 30a75da791ceb02a9b470353fa027b331cb8b0b3 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Thu, 13 Aug 2026 16:20:06 -0500
Subject: [PATCH 34/39] Update TextInputWithTokens snapshot

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 565aa678-84c7-41f4-9281-17b47f3885ff
---
 .../__snapshots__/TextInputWithTokens.test.tsx.snap           | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/react/src/TextInputWithTokens/__snapshots__/TextInputWithTokens.test.tsx.snap b/packages/react/src/TextInputWithTokens/__snapshots__/TextInputWithTokens.test.tsx.snap
index e281566982b..44c031c6f53 100644
--- a/packages/react/src/TextInputWithTokens/__snapshots__/TextInputWithTokens.test.tsx.snap
+++ b/packages/react/src/TextInputWithTokens/__snapshots__/TextInputWithTokens.test.tsx.snap
@@ -1088,7 +1088,7 @@ exports[`TextInputWithTokens > renders a truncated set of tokens 1`] = `
             </span>
           </span>
           <span
-            class="prc-TextInputWithTokens-OverflowCountXLarge-zydSJ prc-Text-Text-jAl-N"
+            class="prc-Text-Text-jAl-N prc-TextInputWithTokens-OverflowCountXLarge-zydSJ"
             data-component="TextInputWithTokens.OverflowCount"
           >
             +
@@ -1217,7 +1217,7 @@ exports[`TextInputWithTokens > renders a truncated set of tokens 1`] = `
           </span>
         </span>
         <span
-          class="prc-TextInputWithTokens-OverflowCountXLarge-zydSJ prc-Text-Text-jAl-N"
+          class="prc-Text-Text-jAl-N prc-TextInputWithTokens-OverflowCountXLarge-zydSJ"
           data-component="TextInputWithTokens.OverflowCount"
         >
           +

From b9b6140774f3346737f9bb0701a2c2f4556797ec Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Wed, 12 Aug 2026 09:35:59 -0500
Subject: [PATCH 35/39] Migrate Link root to mergeProps

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 84a0d8ca-13d3-4cb2-ab24-18fa2d9a8a14
---
 packages/react/src/Link/Link.tsx | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/packages/react/src/Link/Link.tsx b/packages/react/src/Link/Link.tsx
index ca0b1734417..6c53350e161 100644
--- a/packages/react/src/Link/Link.tsx
+++ b/packages/react/src/Link/Link.tsx
@@ -5,6 +5,7 @@ import {useMergedRefs} from '../hooks'
 import classes from './Link.module.css'
 import type {ComponentProps} from '../utils/types'
 import {type PolymorphicProps, fixedForwardRef} from '../utils/modern-polymorphic'
+import {mergeProps} from '../utils/mergeProps'
 
 type StyledLinkProps<As extends React.ElementType = 'a'> = {
   as?: As
@@ -41,13 +42,17 @@ export const UnwrappedLink = <As extends React.ElementType = 'a'>(
 
   return (
     <Component
-      className={clsx(className, classes.Link)}
-      data-component="Link"
-      data-muted={muted}
-      data-inline={inline}
-      {...restProps}
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       ref={mergedRef as any}
+      {...mergeProps(
+        {
+          className: clsx(classes.Link, className),
+          'data-component': 'Link',
+          'data-muted': muted,
+          'data-inline': inline,
+        },
+        restProps,
+      )}
     />
   )
 }

From b89a6f1acb7939cfbf3680002993f1ede6ba6eef Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Wed, 12 Aug 2026 10:19:55 -0500
Subject: [PATCH 36/39] Migrate navigation roots to mergeProps

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 84a0d8ca-13d3-4cb2-ab24-18fa2d9a8a14
---
 ...underline-panels-controlled-panel-props.md |   5 +
 packages/react/src/ActionBar/ActionBar.tsx    | 104 +++++-----
 .../react/src/Breadcrumbs/Breadcrumbs.tsx     |  13 +-
 packages/react/src/NavList/NavList.tsx        |  81 +++++---
 packages/react/src/PageHeader/PageHeader.tsx  | 183 ++++++++++++------
 packages/react/src/Pagehead/Pagehead.tsx      |  13 +-
 packages/react/src/SideNav.tsx                |  11 +-
 .../src/SplitPageLayout/SplitPageLayout.tsx   | 114 ++++++++---
 packages/react/src/SubNav/SubNav.tsx          |  29 ++-
 packages/react/src/TabNav/TabNav.tsx          |  29 ++-
 .../deprecated/UnderlineNav/UnderlineNav.tsx  |  19 +-
 .../UnderlinePanels/UnderlinePanels.tsx       |  37 +++-
 .../UnderlinePanels.types.test.tsx            |  19 ++
 .../components/UnderlineTabbedInterface.tsx   |   8 +-
 14 files changed, 473 insertions(+), 192 deletions(-)
 create mode 100644 .changeset/underline-panels-controlled-panel-props.md
 create mode 100644 packages/react/src/experimental/UnderlinePanels/UnderlinePanels.types.test.tsx

diff --git a/.changeset/underline-panels-controlled-panel-props.md b/.changeset/underline-panels-controlled-panel-props.md
new file mode 100644
index 00000000000..c52f1dceee0
--- /dev/null
+++ b/.changeset/underline-panels-controlled-panel-props.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': major
+---
+
+UnderlinePanels: Remove unsupported panel attributes that are controlled by the component.
diff --git a/packages/react/src/ActionBar/ActionBar.tsx b/packages/react/src/ActionBar/ActionBar.tsx
index 4e5324b65fd..4ba42585c0b 100644
--- a/packages/react/src/ActionBar/ActionBar.tsx
+++ b/packages/react/src/ActionBar/ActionBar.tsx
@@ -13,6 +13,7 @@ import {useMergedRefs} from '../hooks'
 import {createDescendantRegistry} from '../utils/descendant-registry'
 import {OverflowObserverProvider} from '../internal/components/OverflowObserverProvider'
 import {useIsClipped} from '../internal/hooks/useOverflowObserver'
+import {mergeProps} from '../utils/mergeProps'
 
 type ChildProps =
   | {
@@ -332,12 +333,11 @@ function useActionBarItem(ref: React.RefObject<HTMLElement | null>, registryProp
 }
 
 export const ActionBarIconButton = forwardRef(
-  ({disabled, onClick, ...props}: ActionBarIconButtonProps, forwardedRef) => {
+  ({disabled, onClick, className, ...props}: ActionBarIconButtonProps, forwardedRef) => {
     const ref = useRef<HTMLButtonElement>(null)
     const mergedRef = useMergedRefs(forwardedRef, ref)
 
     const {size} = React.useContext(ActionBarContext)
-
     const {['aria-label']: ariaLabel, icon} = props
 
     const {dataOverflowingAttr} = useActionBarItem(
@@ -364,11 +364,16 @@ export const ActionBarIconButton = forwardRef(
 
     return (
       <IconButton
-        aria-disabled={disabled}
         ref={mergedRef}
-        size={size}
-        onClick={clickHandler}
-        {...props}
+        {...mergeProps(
+          {
+            'aria-disabled': disabled,
+            className: clsx(className),
+            size,
+            onClick: clickHandler,
+          },
+          props,
+        )}
         variant="invisible"
         data-overflowing={dataOverflowingAttr}
       />
@@ -376,50 +381,57 @@ export const ActionBarIconButton = forwardRef(
   },
 )
 
-export const ActionBarButton = forwardRef(({disabled, onClick, ...props}: ActionBarButtonProps, forwardedRef) => {
-  const ref = useRef<HTMLButtonElement>(null)
-  const mergedRef = useMergedRefs(forwardedRef, ref)
-
-  const {size} = React.useContext(ActionBarContext)
+export const ActionBarButton = forwardRef(
+  ({disabled, onClick, className, children, leadingVisual, ...props}: ActionBarButtonProps, forwardedRef) => {
+    const ref = useRef<HTMLButtonElement>(null)
+    const mergedRef = useMergedRefs(forwardedRef, ref)
 
-  const {children, leadingVisual} = props
+    const {size} = React.useContext(ActionBarContext)
 
-  const {dataOverflowingAttr} = useActionBarItem(
-    ref,
-    useMemo(
-      (): ChildProps => ({
-        type: 'action',
-        label: children,
-        // Only forward the leading visual to the overflow menu when it is a component
-        // that can be rendered as an icon (e.g. an octicon), matching ActionBar.IconButton.
-        icon: typeof leadingVisual === 'function' ? (leadingVisual as ActionBarIconButtonProps['icon']) : undefined,
-        disabled: !!disabled,
-        onClick: onClick as MouseEventHandler,
-      }),
-      [children, leadingVisual, disabled, onClick],
-    ),
-  )
+    const {dataOverflowingAttr} = useActionBarItem(
+      ref,
+      useMemo(
+        (): ChildProps => ({
+          type: 'action',
+          label: children,
+          // Only forward the leading visual to the overflow menu when it is a component
+          // that can be rendered as an icon (e.g. an octicon), matching ActionBar.IconButton.
+          icon: typeof leadingVisual === 'function' ? (leadingVisual as ActionBarIconButtonProps['icon']) : undefined,
+          disabled: !!disabled,
+          onClick: onClick as MouseEventHandler,
+        }),
+        [children, leadingVisual, disabled, onClick],
+      ),
+    )
 
-  const clickHandler = useCallback(
-    (event: React.MouseEvent<HTMLButtonElement>) => {
-      if (disabled) return
-      onClick?.(event)
-    },
-    [disabled, onClick],
-  )
+    const clickHandler = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        if (disabled) return
+        onClick?.(event)
+      },
+      [disabled, onClick],
+    )
 
-  return (
-    <Button
-      aria-disabled={disabled}
-      ref={mergedRef}
-      size={size}
-      onClick={clickHandler}
-      {...props}
-      variant="invisible"
-      data-overflowing={dataOverflowingAttr}
-    />
-  )
-})
+    return (
+      <Button
+        ref={mergedRef}
+        {...mergeProps(
+          {
+            'aria-disabled': disabled,
+            className: clsx(className),
+            children,
+            leadingVisual,
+            size,
+            onClick: clickHandler,
+          },
+          props,
+        )}
+        variant="invisible"
+        data-overflowing={dataOverflowingAttr}
+      />
+    )
+  },
+)
 
 const ActionBarGroupContext = React.createContext<{
   isOverflowing: boolean
diff --git a/packages/react/src/Breadcrumbs/Breadcrumbs.tsx b/packages/react/src/Breadcrumbs/Breadcrumbs.tsx
index 00f3f266787..190e4218079 100644
--- a/packages/react/src/Breadcrumbs/Breadcrumbs.tsx
+++ b/packages/react/src/Breadcrumbs/Breadcrumbs.tsx
@@ -12,6 +12,7 @@ import type {ResizeObserverEntry} from '../hooks/useResizeObserver'
 import {useOnEscapePress} from '../hooks/useOnEscapePress'
 import {useOnOutsideClick} from '../hooks/useOnOutsideClick'
 import {type PolymorphicProps, fixedForwardRef} from '../utils/modern-polymorphic'
+import {mergeProps} from '../utils/mergeProps'
 
 export type BreadcrumbsProps = React.PropsWithChildren<{
   /**
@@ -389,11 +390,15 @@ const BreadcrumbsItem = fixedForwardRef(
     const {as: Component = 'a', selected, className, ...rest} = props
     return (
       <Component
-        className={clsx(className, classes.Item, selected && 'selected')}
-        aria-current={selected ? 'page' : undefined}
         ref={ref}
-        data-component="Breadcrumbs.Item"
-        {...rest}
+        {...mergeProps(
+          {
+            className: clsx(classes.Item, selected && 'selected', className),
+            'aria-current': selected ? 'page' : undefined,
+            'data-component': 'Breadcrumbs.Item',
+          },
+          rest,
+        )}
       />
     )
   },
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index db954644f45..30550e6a4d5 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -23,6 +23,7 @@ import HeadingComponent from '../Heading'
 import visuallyHiddenClasses from '../_VisuallyHidden.module.css'
 import type {FCWithSlotMarker} from '../utils/types/Slots'
 import {asSlot} from '../utils/as-slot'
+import {mergeProps} from '../utils/mergeProps'
 
 type HeadingLevels = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
 
@@ -54,7 +55,7 @@ export type NavListProps = {
 } & React.ComponentProps<'nav'>
 
 const Root = React.forwardRef<HTMLElement, NavListProps>(
-  ({children, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ...props}, ref) => {
+  ({children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ...props}, ref) => {
     const [slots, childrenWithoutHeading] = useSlots(children, {
       heading: Heading,
     })
@@ -69,7 +70,18 @@ const Root = React.forwardRef<HTMLElement, NavListProps>(
     const navLabelledby = ariaLabelledby ?? (ariaLabel ? undefined : headingId)
 
     return (
-      <nav {...props} aria-label={ariaLabel} aria-labelledby={navLabelledby} ref={ref} data-component="NavList">
+      <nav
+        ref={ref}
+        {...mergeProps(
+          {
+            className: clsx(className),
+            'aria-label': ariaLabel,
+            'aria-labelledby': navLabelledby,
+          },
+          props,
+        )}
+        data-component="NavList"
+      >
         <NavListHeadingLevelContext.Provider value={headingLevel}>
           {heading ? React.cloneElement(heading, {id: headingId}) : null}
           <ActionListContainerContext.Provider
@@ -106,16 +118,20 @@ const Heading: FCWithSlotMarker<NavListHeadingProps> = ({
 }) => {
   return (
     <HeadingComponent
-      as={as}
-      variant="small"
-      className={clsx(
-        // Apply the visually-hidden styles directly to the heading rather than wrapping
-        // it in a span (a heading isn't valid phrasing content inside a span).
-        visuallyHidden ? visuallyHiddenClasses.InternalVisuallyHidden : navListClasses.Heading,
-        className,
+      {...mergeProps(
+        {
+          as,
+          variant: 'small' as const,
+          className: clsx(
+            // Apply the visually-hidden styles directly to the heading rather than wrapping
+            // it in a span (a heading isn't valid phrasing content inside a span).
+            visuallyHidden ? visuallyHiddenClasses.InternalVisuallyHidden : navListClasses.Heading,
+            className,
+          ),
+          'data-component': 'NavList.Heading',
+        },
+        props,
       )}
-      data-component="NavList.Heading"
-      {...props}
     >
       {children}
     </HeadingComponent>
@@ -143,7 +159,15 @@ export type NavListItemProps<As extends React.ElementType = React.ElementType> =
 
 const ItemComponent = fixedForwardRef(
   <As extends React.ElementType = 'a'>(
-    {'aria-current': ariaCurrent, children, defaultOpen, tooltipText, as: Component, ...props}: NavListItemProps<As>,
+    {
+      'aria-current': ariaCurrent,
+      children,
+      defaultOpen,
+      tooltipText,
+      as: Component,
+      className,
+      ...props
+    }: NavListItemProps<As>,
     ref: React.ForwardedRef<unknown>,
   ) => {
     const {depth} = React.useContext(SubNavContext)
@@ -182,13 +206,18 @@ const ItemComponent = fixedForwardRef(
     return (
       <InternalLinkItem
         ref={ref}
-        as={Component}
-        aria-current={ariaCurrent}
-        active={Boolean(ariaCurrent) && ariaCurrent !== 'false'}
-        style={{'--subitem-depth': depth} as React.CSSProperties}
-        data-component="NavList.Item"
-        _PrivateTooltipText={tooltipText}
-        {...props}
+        {...mergeProps(
+          {
+            as: Component,
+            className: clsx(className),
+            'aria-current': ariaCurrent,
+            active: Boolean(ariaCurrent) && ariaCurrent !== 'false',
+            style: {'--subitem-depth': depth} as React.CSSProperties,
+            'data-component': 'NavList.Item',
+            _PrivateTooltipText: tooltipText,
+          },
+          props,
+        )}
       >
         {children}
       </InternalLinkItem>
@@ -539,11 +568,15 @@ const GroupHeadingImpl: React.FC<NavListGroupHeadingProps> = ({as, className, ..
   const resolvedAs = as ?? (headingLevel ? levelToHeadingTag(headingLevel + 1) : 'h3')
   return (
     <ActionList.GroupHeading
-      as={resolvedAs}
-      className={clsx(navListClasses.GroupHeading, className)}
-      data-component="NavList.GroupHeading"
-      headingWrapElement="li"
-      {...rest}
+      {...mergeProps(
+        {
+          as: resolvedAs,
+          className: clsx(navListClasses.GroupHeading, className),
+          'data-component': 'NavList.GroupHeading',
+          headingWrapElement: 'li',
+        },
+        rest,
+      )}
     />
   )
 }
diff --git a/packages/react/src/PageHeader/PageHeader.tsx b/packages/react/src/PageHeader/PageHeader.tsx
index c334ec38440..942d1043f13 100644
--- a/packages/react/src/PageHeader/PageHeader.tsx
+++ b/packages/react/src/PageHeader/PageHeader.tsx
@@ -17,6 +17,7 @@ import {clsx} from 'clsx'
 
 import classes from './PageHeader.module.css'
 import {isSlot} from '../utils/is-slot'
+import {mergeProps} from '../utils/mergeProps'
 
 // Types that are shared between PageHeader children components
 export type ChildrenPropTypes = {
@@ -164,12 +165,18 @@ const Root = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageHeader
     return (
       <BaseComponent
         ref={appliedRef}
-        className={clsx(classes.PageHeader, className)}
-        data-component="PageHeader"
-        data-has-border={hasBorder ? 'true' : undefined}
-        data-has-nav={hasNavigation ? '' : undefined}
-        {...getResponsiveAttributes('title-size-variant', titleVariant)}
-        {...getNavHiddenDataAttributes(navigationHidden)}
+        {...mergeProps(
+          {
+            className: clsx(classes.PageHeader, className),
+            'data-component': 'PageHeader',
+            'data-has-border': hasBorder ? 'true' : undefined,
+            'data-has-nav': hasNavigation ? '' : undefined,
+          },
+          {
+            ...getResponsiveAttributes('title-size-variant', titleVariant),
+            ...getNavHiddenDataAttributes(navigationHidden),
+          },
+        )}
         aria-label={ariaLabel}
         role={role}
       >
@@ -190,9 +197,13 @@ const ContextArea: FCWithSlotMarker<React.PropsWithChildren<ChildrenPropTypes>>
 }) => {
   return (
     <div
-      className={clsx(classes.ContextArea, className)}
-      data-component="PageHeader.ContextArea"
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          className: clsx(classes.ContextArea, className),
+          'data-component': 'PageHeader.ContextArea',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </div>
@@ -216,14 +227,18 @@ const ParentLink = React.forwardRef<HTMLAnchorElement, ParentLinkProps>(
       <>
         <Link
           ref={ref}
-          as={as}
-          aria-label={ariaLabel}
-          muted
-          className={clsx(classes.ParentLink, className)}
-          data-component="PageHeader.ParentLink"
-          {...getHiddenDataAttributes(hidden)}
-          href={href}
-          {...rest}
+          {...mergeProps(
+            {
+              as,
+              'aria-label': ariaLabel,
+              muted: true,
+              className: clsx(classes.ParentLink, className),
+              'data-component': 'PageHeader.ParentLink',
+              ...getHiddenDataAttributes(hidden),
+              href,
+            },
+            rest,
+          )}
         >
           <ArrowLeftIcon />
           <div>{children}</div>
@@ -245,9 +260,13 @@ const ContextBar: React.FC<React.PropsWithChildren<ChildrenPropTypes>> = ({
 }) => {
   return (
     <div
-      className={clsx(classes.ContextBar, className)}
-      data-component="PageHeader.ContextBar"
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          className: clsx(classes.ContextBar, className),
+          'data-component': 'PageHeader.ContextBar',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </div>
@@ -263,9 +282,13 @@ const ContextAreaActions: React.FC<React.PropsWithChildren<ChildrenPropTypes>> =
 }) => {
   return (
     <div
-      className={clsx(classes.ContextAreaActions, className)}
-      data-component="PageHeader.ContextAreaActions"
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          className: clsx(classes.ContextAreaActions, className),
+          'data-component': 'PageHeader.ContextAreaActions',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </div>
@@ -288,12 +311,18 @@ const TitleArea = React.forwardRef<HTMLDivElement, React.PropsWithChildren<Title
     const appliedRef = mergedRefEnabled ? forwardedRef : providedOrCreatedRef
     return (
       <div
-        className={clsx(classes.TitleArea, className)}
         // @ts-expect-error it needs a non nullable ref
         ref={appliedRef}
-        data-component="TitleArea"
-        {...getResponsiveAttributes('size-variant', variant)}
-        {...getHiddenDataAttributes(hidden)}
+        {...mergeProps(
+          {
+            className: clsx(classes.TitleArea, className),
+            'data-component': 'TitleArea',
+          },
+          {
+            ...getResponsiveAttributes('size-variant', variant),
+            ...getHiddenDataAttributes(hidden),
+          },
+        )}
       >
         {children}
       </div>
@@ -311,9 +340,13 @@ const LeadingAction: FCWithSlotMarker<React.PropsWithChildren<ChildrenPropTypes>
 }) => {
   return (
     <div
-      className={clsx(classes.LeadingAction, className)}
-      data-component="PH_LeadingAction"
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          className: clsx(classes.LeadingAction, className),
+          'data-component': 'PH_LeadingAction',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </div>
@@ -326,9 +359,13 @@ LeadingAction.__SLOT__ = Symbol('PageHeader.LeadingAction')
 const Breadcrumbs: React.FC<React.PropsWithChildren<ChildrenPropTypes>> = ({children, className, hidden = false}) => {
   return (
     <div
-      className={clsx(classes.Breadcrumbs, className)}
-      data-component="PH_Breadcrumbs"
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          className: clsx(classes.Breadcrumbs, className),
+          'data-component': 'PH_Breadcrumbs',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </div>
@@ -339,9 +376,13 @@ const Breadcrumbs: React.FC<React.PropsWithChildren<ChildrenPropTypes>> = ({chil
 const LeadingVisual: React.FC<React.PropsWithChildren<ChildrenPropTypes>> = ({children, className, hidden = false}) => {
   return (
     <div
-      className={clsx(classes.LeadingVisual, className)}
-      data-component="PH_LeadingVisual"
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          className: clsx(classes.LeadingVisual, className),
+          'data-component': 'PH_LeadingVisual',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </div>
@@ -355,11 +396,15 @@ export type TitleProps = {
 const Title: React.FC<React.PropsWithChildren<TitleProps>> = ({children, className, hidden = false, as = 'h2'}) => {
   return (
     <Heading
-      className={clsx(classes.Title, className)}
-      data-component="PH_Title"
-      data-hidden={hidden}
-      as={as}
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          className: clsx(classes.Title, className),
+          'data-component': 'PH_Title',
+          'data-hidden': hidden,
+          as,
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </Heading>
@@ -374,9 +419,13 @@ const TrailingVisual: React.FC<React.PropsWithChildren<ChildrenPropTypes>> = ({
 }) => {
   return (
     <div
-      className={clsx(classes.TrailingVisual, className)}
-      data-component="PH_TrailingVisual"
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          className: clsx(classes.TrailingVisual, className),
+          'data-component': 'PH_TrailingVisual',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </div>
@@ -390,9 +439,13 @@ const TrailingAction: React.FC<React.PropsWithChildren<ChildrenPropTypes>> = ({
 }) => {
   return (
     <div
-      className={clsx(classes.TrailingAction, className)}
-      data-component="PH_TrailingAction"
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          className: clsx(classes.TrailingAction, className),
+          'data-component': 'PH_TrailingAction',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </div>
@@ -403,7 +456,15 @@ export type ActionsProps = React.PropsWithChildren<ChildrenPropTypes>
 
 const Actions = ({children, className, hidden = false}: ActionsProps) => {
   return (
-    <div className={clsx(classes.Actions, className)} data-component="PH_Actions" {...getHiddenDataAttributes(hidden)}>
+    <div
+      {...mergeProps(
+        {
+          className: clsx(classes.Actions, className),
+          'data-component': 'PH_Actions',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
+    >
       {children}
     </div>
   )
@@ -413,9 +474,13 @@ const Actions = ({children, className, hidden = false}: ActionsProps) => {
 const Description: React.FC<React.PropsWithChildren<ChildrenPropTypes>> = ({children, className, hidden = false}) => {
   return (
     <div
-      className={clsx(classes.Description, className)}
-      data-component="PageHeader.Description"
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          className: clsx(classes.Description, className),
+          'data-component': 'PageHeader.Description',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </div>
@@ -444,12 +509,16 @@ const Navigation: React.FC<React.PropsWithChildren<NavigationProps>> = ({
 
   return (
     <BaseComponent
-      // Render `aria-label` and `aria-labelledby` only on `nav` elements
-      aria-label={BaseComponent === 'nav' ? ariaLabel : undefined}
-      aria-labelledby={BaseComponent === 'nav' ? ariaLabelledBy : undefined}
-      className={clsx(classes.Navigation, className)}
-      data-component="PH_Navigation"
-      {...getHiddenDataAttributes(hidden)}
+      {...mergeProps(
+        {
+          // Render `aria-label` and `aria-labelledby` only on `nav` elements
+          'aria-label': BaseComponent === 'nav' ? ariaLabel : undefined,
+          'aria-labelledby': BaseComponent === 'nav' ? ariaLabelledBy : undefined,
+          className: clsx(classes.Navigation, className),
+          'data-component': 'PH_Navigation',
+        },
+        getHiddenDataAttributes(hidden),
+      )}
     >
       {children}
     </BaseComponent>
diff --git a/packages/react/src/Pagehead/Pagehead.tsx b/packages/react/src/Pagehead/Pagehead.tsx
index f393b5551fa..91b6f7cdf84 100644
--- a/packages/react/src/Pagehead/Pagehead.tsx
+++ b/packages/react/src/Pagehead/Pagehead.tsx
@@ -1,9 +1,20 @@
 import type React from 'react'
 import {clsx} from 'clsx'
 import classes from './Pagehead.module.css'
+import {mergeProps} from '../utils/mergeProps'
 
 const Pagehead = ({as: BaseComponent = 'div', className, ...rest}: PageheadProps) => {
-  return <BaseComponent className={clsx(classes.Pagehead, className)} data-component="Pagehead" {...rest} />
+  return (
+    <BaseComponent
+      {...mergeProps(
+        {
+          className: clsx(classes.Pagehead, className),
+          'data-component': 'Pagehead',
+        },
+        rest,
+      )}
+    />
+  )
 }
 
 /**
diff --git a/packages/react/src/SideNav.tsx b/packages/react/src/SideNav.tsx
index 54d67609262..8ee64f56a13 100644
--- a/packages/react/src/SideNav.tsx
+++ b/packages/react/src/SideNav.tsx
@@ -5,6 +5,7 @@ import type React from 'react'
 import {type PropsWithChildren} from 'react'
 import {clsx} from 'clsx'
 import classes from './SideNav.module.css'
+import {mergeProps} from './utils/mergeProps'
 
 type SideNavBaseProps = {
   as?: React.ElementType
@@ -56,9 +57,13 @@ const SideNavLink = ({selected, to, variant, className, children, ...rest}: Styl
   // https://reacttraining.com/react-router/web/api/NavLink/aria-current-string
   return (
     <Link
-      aria-current={isReactRouter || selected ? 'page' : undefined}
-      className={newClassName}
-      {...rest}
+      {...mergeProps(
+        {
+          'aria-current': isReactRouter || selected ? 'page' : undefined,
+          className: newClassName,
+        },
+        rest,
+      )}
       data-component="SideNav.Link"
     >
       {children}
diff --git a/packages/react/src/SplitPageLayout/SplitPageLayout.tsx b/packages/react/src/SplitPageLayout/SplitPageLayout.tsx
index 982eb443fbd..7e559363dd3 100644
--- a/packages/react/src/SplitPageLayout/SplitPageLayout.tsx
+++ b/packages/react/src/SplitPageLayout/SplitPageLayout.tsx
@@ -8,26 +8,33 @@ import type {
 } from '../PageLayout'
 import {PageLayout} from '../PageLayout'
 import type {WithSlotMarker} from '../utils/types'
+import {mergeProps} from '../utils/mergeProps'
+import {clsx} from 'clsx'
 
 // ----------------------------------------------------------------------------
 // SplitPageLayout
 
 export type SplitPageLayoutProps = {className?: string}
 
-export const Root: React.FC<React.PropsWithChildren<SplitPageLayoutProps>> = props => {
+export const Root: React.FC<React.PropsWithChildren<SplitPageLayoutProps>> = ({className, ...props}) => {
   return (
     <PageLayout
-      data-component="SplitPageLayout"
-      containerWidth="full"
-      padding="none"
-      columnGap="none"
-      rowGap="none"
-      _slotsConfig={{
-        header: Header,
-        footer: Footer,
-        sidebar: Sidebar,
-      }}
-      {...props}
+      {...mergeProps(
+        {
+          className: clsx(className),
+          'data-component': 'SplitPageLayout',
+          containerWidth: 'full' as const,
+          padding: 'none' as const,
+          columnGap: 'none' as const,
+          rowGap: 'none' as const,
+          _slotsConfig: {
+            header: Header,
+            footer: Footer,
+            sidebar: Sidebar,
+          },
+        },
+        props,
+      )}
     />
   )
 }
@@ -42,10 +49,23 @@ export type SplitPageLayoutHeaderProps = PageLayoutHeaderProps
 export const Header: React.FC<React.PropsWithChildren<SplitPageLayoutHeaderProps>> = ({
   padding = 'normal',
   divider = 'line',
+  className,
   ...props
 }) => {
-  // eslint-disable-next-line primer-react/direct-slot-children
-  return <PageLayout.Header data-component="SplitPageLayout.Header" padding={padding} divider={divider} {...props} />
+  return (
+    // eslint-disable-next-line primer-react/direct-slot-children
+    <PageLayout.Header
+      {...mergeProps(
+        {
+          className: clsx(className),
+          'data-component': 'SplitPageLayout.Header',
+          padding,
+          divider,
+        },
+        props,
+      )}
+    />
+  )
 }
 
 Header.displayName = 'SplitPageLayout.Header'
@@ -58,9 +78,22 @@ export type SplitPageLayoutContentProps = PageLayoutContentProps
 export const Content: React.FC<React.PropsWithChildren<SplitPageLayoutContentProps>> = ({
   width = 'large',
   padding = 'normal',
+  className,
   ...props
 }) => {
-  return <PageLayout.Content data-component="SplitPageLayout.Content" width={width} padding={padding} {...props} />
+  return (
+    <PageLayout.Content
+      {...mergeProps(
+        {
+          className: clsx(className),
+          'data-component': 'SplitPageLayout.Content',
+          width,
+          padding,
+        },
+        props,
+      )}
+    />
+  )
 }
 
 Content.displayName = 'SplitPageLayout.Content'
@@ -75,16 +108,22 @@ export const Pane: React.FC<React.PropsWithChildren<SplitPageLayoutPaneProps>> =
   sticky = true,
   padding = 'normal',
   divider = 'line',
+  className,
   ...props
 }) => {
   return (
     <PageLayout.Pane
-      data-component="SplitPageLayout.Pane"
-      position={position}
-      sticky={sticky}
-      padding={padding}
-      divider={divider}
-      {...props}
+      {...mergeProps(
+        {
+          className: clsx(className),
+          'data-component': 'SplitPageLayout.Pane',
+          position,
+          sticky,
+          padding,
+          divider,
+        },
+        props,
+      )}
     ></PageLayout.Pane>
   )
 }
@@ -99,15 +138,21 @@ export const Sidebar: React.FC<React.PropsWithChildren<SplitPageLayoutSidebarPro
   position = 'start',
   padding = 'normal',
   divider = 'line',
+  className,
   ...props
 }) => {
   return (
     <PageLayout.Sidebar
-      data-component="SplitPageLayout.Sidebar"
-      position={position}
-      padding={padding}
-      divider={divider}
-      {...props}
+      {...mergeProps(
+        {
+          className: clsx(className),
+          'data-component': 'SplitPageLayout.Sidebar',
+          position,
+          padding,
+          divider,
+        },
+        props,
+      )}
     />
   )
 }
@@ -122,10 +167,23 @@ export type SplitPageLayoutFooterProps = PageLayoutFooterProps
 export const Footer: React.FC<React.PropsWithChildren<SplitPageLayoutFooterProps>> = ({
   padding = 'normal',
   divider = 'line',
+  className,
   ...props
 }) => {
-  // eslint-disable-next-line primer-react/direct-slot-children
-  return <PageLayout.Footer data-component="SplitPageLayout.Footer" padding={padding} divider={divider} {...props} />
+  return (
+    // eslint-disable-next-line primer-react/direct-slot-children
+    <PageLayout.Footer
+      {...mergeProps(
+        {
+          className: clsx(className),
+          'data-component': 'SplitPageLayout.Footer',
+          padding,
+          divider,
+        },
+        props,
+      )}
+    />
+  )
 }
 
 Footer.displayName = 'SplitPageLayout.Footer'
diff --git a/packages/react/src/SubNav/SubNav.tsx b/packages/react/src/SubNav/SubNav.tsx
index 5e18a782fd9..fe261e84ca0 100644
--- a/packages/react/src/SubNav/SubNav.tsx
+++ b/packages/react/src/SubNav/SubNav.tsx
@@ -4,6 +4,7 @@ import React from 'react'
 
 import styles from './SubNav.module.css'
 import type {WithSlotMarker} from '../utils/types'
+import {mergeProps} from '../utils/mergeProps'
 
 export type SubNavProps = React.ComponentProps<'nav'> & {
   actions?: React.ReactNode
@@ -21,9 +22,13 @@ const SubNav = React.forwardRef<HTMLElement, SubNavProps>(function SubNav(
   return (
     <nav
       ref={forwardRef}
-      className={clsx(className, 'SubNav', styles.SubNav)}
-      aria-label={label}
-      {...rest}
+      {...mergeProps(
+        {
+          className: clsx('SubNav', styles.SubNav, className),
+          'aria-label': label,
+        },
+        rest,
+      )}
       data-component="SubNav"
     >
       <div className={clsx('SubNav-body', styles.Body)}>{children}</div>
@@ -37,7 +42,11 @@ SubNav.displayName = 'SubNav'
 
 const SubNavLinks = React.forwardRef<HTMLDivElement, SubNavLinksProps>(({children, className, ...rest}, forwardRef) => {
   return (
-    <div ref={forwardRef} className={clsx(className, styles.Links)} {...rest} data-component="SubNav.Links">
+    <div
+      ref={forwardRef}
+      {...mergeProps({className: clsx(styles.Links, className)}, rest)}
+      data-component="SubNav.Links"
+    >
       {children}
     </div>
   )
@@ -51,10 +60,14 @@ const SubNavLink = React.forwardRef<HTMLAnchorElement, SubNavLinkProps>(
     return (
       <a
         ref={forwardRef}
-        className={clsx(className, styles.Link)}
-        data-selected={rest.selected}
-        aria-current={rest.selected}
-        {...rest}
+        {...mergeProps(
+          {
+            className: clsx(styles.Link, className),
+            'data-selected': rest.selected,
+            'aria-current': rest.selected,
+          },
+          rest,
+        )}
         data-component="SubNav.Link"
       >
         {children}
diff --git a/packages/react/src/TabNav/TabNav.tsx b/packages/react/src/TabNav/TabNav.tsx
index 673e61ea5de..970766b7bdb 100644
--- a/packages/react/src/TabNav/TabNav.tsx
+++ b/packages/react/src/TabNav/TabNav.tsx
@@ -5,6 +5,7 @@ import {FocusKeys, useFocusZone} from '../hooks/useFocusZone'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 
 import styles from './TabNav.module.css'
+import {mergeProps} from '../utils/mergeProps'
 
 /**
  * @deprecated
@@ -14,7 +15,7 @@ export type TabNavProps = React.HTMLProps<HTMLDivElement>
 /**
  * @deprecated
  */
-function TabNav({children, 'aria-label': ariaLabel, ...rest}: TabNavProps) {
+function TabNav({children, className, 'aria-label': ariaLabel, ...rest}: TabNavProps) {
   const customContainerRef = useRef<HTMLElement>(null)
 
   // Detect if the TabNav is inside an ActionMenu.
@@ -51,7 +52,11 @@ function TabNav({children, 'aria-label': ariaLabel, ...rest}: TabNavProps) {
   )
 
   return (
-    <div {...rest} ref={navRef as React.RefObject<HTMLDivElement>} data-component="TabNav">
+    <div
+      ref={navRef as React.RefObject<HTMLDivElement>}
+      {...mergeProps({className: clsx(className)}, rest)}
+      data-component="TabNav"
+    >
       <nav aria-label={ariaLabel} className={styles.TabNavNav}>
         <div role="tablist" className={styles.TabNavTabList}>
           {children}
@@ -83,11 +88,21 @@ const TabNavLink = React.forwardRef(function TabNavLink(
   return (
     <Component
       ref={ref}
-      role="tab"
-      tabIndex={-1}
-      aria-selected={selected ? true : undefined}
-      className={clsx('TabNav-item', styles.TabNavLink, selected && 'selected', selected && styles.Selected, className)}
-      {...rest}
+      {...mergeProps(
+        {
+          role: 'tab',
+          tabIndex: -1,
+          'aria-selected': selected ? true : undefined,
+          className: clsx(
+            'TabNav-item',
+            styles.TabNavLink,
+            selected && 'selected',
+            selected && styles.Selected,
+            className,
+          ),
+        },
+        rest,
+      )}
       data-component="TabNav.Link"
     />
   )
diff --git a/packages/react/src/deprecated/UnderlineNav/UnderlineNav.tsx b/packages/react/src/deprecated/UnderlineNav/UnderlineNav.tsx
index 0134f462f39..4bf57aeecaa 100644
--- a/packages/react/src/deprecated/UnderlineNav/UnderlineNav.tsx
+++ b/packages/react/src/deprecated/UnderlineNav/UnderlineNav.tsx
@@ -2,6 +2,7 @@ import {clsx} from 'clsx'
 import type {To} from 'history'
 import React from 'react'
 import classes from './UnderlineNav.module.css'
+import {mergeProps} from '../../utils/mergeProps'
 
 export type UnderlineNavProps = {
   actions?: React.ReactNode
@@ -18,7 +19,7 @@ function UnderlineNav({actions, className, align, children, full, label, ...rest
     'PRC-UnderlineNav--right': align,
   })
   return (
-    <nav className={navClasses} aria-label={label} {...rest}>
+    <nav {...mergeProps({className: navClasses, 'aria-label': label}, rest)}>
       <div className={clsx(classes.UnderlineNavBody, 'PRC-UnderlineNav-body')}>{children}</div>
       {actions && <div className={clsx(classes.UnderlineNavActions, 'PRC-UnderlineNav-actions')}>{actions}</div>}
     </nav>
@@ -37,8 +38,20 @@ const UnderlineNavLink = React.forwardRef<HTMLAnchorElement, UnderlineNavLinkPro
   forwardRef,
 ) {
   const linkClasses = clsx(classes.UnderlineNavItem, className, classes.UnderlineNavLink)
-  // eslint-disable-next-line jsx-a11y/anchor-has-content
-  return <a ref={forwardRef} data-selected={selected ? '' : undefined} className={linkClasses} {...props} />
+
+  return (
+    // eslint-disable-next-line jsx-a11y/anchor-has-content
+    <a
+      ref={forwardRef}
+      {...mergeProps(
+        {
+          'data-selected': selected ? '' : undefined,
+          className: linkClasses,
+        },
+        props,
+      )}
+    />
+  )
 })
 
 UnderlineNavLink.displayName = 'UnderlineNav.Link'
diff --git a/packages/react/src/experimental/UnderlinePanels/UnderlinePanels.tsx b/packages/react/src/experimental/UnderlinePanels/UnderlinePanels.tsx
index 1d0d3022a89..6db391f5c8d 100644
--- a/packages/react/src/experimental/UnderlinePanels/UnderlinePanels.tsx
+++ b/packages/react/src/experimental/UnderlinePanels/UnderlinePanels.tsx
@@ -22,6 +22,7 @@ import {isSlot} from '../../utils/is-slot'
 import type {FCWithSlotMarker} from '../../utils/types'
 import {Tabs, useTab, useTabList, useTabPanel} from '../Tabs'
 import type {TabListHookProps} from '../Tabs/types'
+import {mergeProps} from '../../utils/mergeProps'
 
 export type UnderlinePanelsProps = {
   /**
@@ -73,7 +74,13 @@ export type TabProps = PropsWithChildren<{
   icon?: FC<IconProps>
 }>
 
-export type PanelProps = React.HTMLAttributes<HTMLDivElement>
+export type PanelProps = Omit<
+  React.HTMLAttributes<HTMLDivElement>,
+  'aria-labelledby' | 'data-selected' | 'hidden' | 'id' | 'role'
+> & {
+  'aria-labelledby'?: never
+  'data-selected'?: never
+}
 
 // Internal-only positional value injected via cloneElement to pair the Nth tab
 // with the Nth panel. Not part of the public Tab/Panel API.
@@ -233,9 +240,13 @@ const UnderlinePanels: FCWithSlotMarker<UnderlinePanelsProps> = ({
       <Tabs id={parentId} value={selectedValue} onValueChange={({value}) => setSelectedValue(value)}>
         <UnderlineWrapper
           ref={wrapperRef}
-          data-icons-visible={iconsVisible}
-          className={clsx(className, classes.StyledUnderlineWrapper)}
-          {...props}
+          {...mergeProps(
+            {
+              'data-icons-visible': iconsVisible,
+              className: clsx(classes.StyledUnderlineWrapper, className),
+            },
+            props,
+          )}
         >
           <UnderlineItemList
             ref={listRef}
@@ -262,9 +273,14 @@ const TabImpl: FC<TabProps & WithValue> = ({onSelect, value, ...itemProps}) => {
   return (
     <UnderlineItem
       as="button"
-      {...itemProps}
-      {...restTabProps}
+      {...mergeProps(restTabProps, itemProps)}
       type="button"
+      aria-controls={restTabProps['aria-controls']}
+      aria-disabled={restTabProps['aria-disabled']}
+      aria-selected={restTabProps['aria-selected']}
+      id={restTabProps.id}
+      role={restTabProps.role}
+      tabIndex={restTabProps.tabIndex}
       onClick={(event: React.MouseEvent<HTMLButtonElement>) => {
         if (!event.defaultPrevented && typeof onSelect === 'function') {
           onSelect(event)
@@ -295,7 +311,14 @@ const PanelImpl: FC<PanelProps & WithValue> = ({children, value, ...panelRest})
   const {tabPanelProps} = useTabPanel<HTMLDivElement>({value: value ?? ''})
 
   return (
-    <div {...panelRest} {...tabPanelProps}>
+    <div
+      {...mergeProps(tabPanelProps, panelRest)}
+      aria-labelledby={tabPanelProps['aria-labelledby']}
+      data-selected={tabPanelProps['data-selected']}
+      hidden={tabPanelProps.hidden}
+      id={tabPanelProps.id}
+      role={tabPanelProps.role}
+    >
       {children}
     </div>
   )
diff --git a/packages/react/src/experimental/UnderlinePanels/UnderlinePanels.types.test.tsx b/packages/react/src/experimental/UnderlinePanels/UnderlinePanels.types.test.tsx
new file mode 100644
index 00000000000..9e1f3d5e10a
--- /dev/null
+++ b/packages/react/src/experimental/UnderlinePanels/UnderlinePanels.types.test.tsx
@@ -0,0 +1,19 @@
+import UnderlinePanels from './UnderlinePanels'
+
+export function panelDoesNotAcceptControlledAttributes() {
+  return (
+    <UnderlinePanels aria-label="Example">
+      <UnderlinePanels.Tab>Tab</UnderlinePanels.Tab>
+      {/* @ts-expect-error UnderlinePanels controls the panel's accessible relationship */}
+      <UnderlinePanels.Panel aria-labelledby="custom-tab">Panel</UnderlinePanels.Panel>
+      {/* @ts-expect-error UnderlinePanels controls the panel's selected state */}
+      <UnderlinePanels.Panel data-selected="forced">Panel</UnderlinePanels.Panel>
+      {/* @ts-expect-error UnderlinePanels controls panel visibility */}
+      <UnderlinePanels.Panel hidden>Panel</UnderlinePanels.Panel>
+      {/* @ts-expect-error UnderlinePanels controls the panel ID */}
+      <UnderlinePanels.Panel id="custom-panel">Panel</UnderlinePanels.Panel>
+      {/* @ts-expect-error UnderlinePanels controls the panel role */}
+      <UnderlinePanels.Panel role="region">Panel</UnderlinePanels.Panel>
+    </UnderlinePanels>
+  )
+}
diff --git a/packages/react/src/internal/components/UnderlineTabbedInterface.tsx b/packages/react/src/internal/components/UnderlineTabbedInterface.tsx
index 3e7de268225..06cdde29b4e 100644
--- a/packages/react/src/internal/components/UnderlineTabbedInterface.tsx
+++ b/packages/react/src/internal/components/UnderlineTabbedInterface.tsx
@@ -9,6 +9,7 @@ import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../../
 
 import classes from './UnderlineTabbedInterface.module.css'
 import {clsx} from 'clsx'
+import {mergeProps} from '../../utils/mergeProps'
 
 // The gap between the list items. It is a constant because the gap is used to calculate the possible number of items that can fit in the container.
 export const GAP = 8
@@ -39,9 +40,8 @@ export const UnderlineWrapper = forwardRef((props, ref) => {
 
   return (
     <Component
-      className={clsx(classes.UnderlineWrapper, className)}
       ref={ref as ForwardedRef<HTMLDivElement>}
-      {...rest}
+      {...mergeProps({className: clsx(classes.UnderlineWrapper, className)}, rest)}
     >
       {children}
     </Component>
@@ -50,7 +50,7 @@ export const UnderlineWrapper = forwardRef((props, ref) => {
 
 export const UnderlineItemList = forwardRef(({children, className, ...rest}, forwardedRef) => {
   return (
-    <ul className={clsx(className, classes.UnderlineItemList)} ref={forwardedRef} {...rest}>
+    <ul ref={forwardedRef} {...mergeProps({className: clsx(classes.UnderlineItemList, className)}, rest)}>
       {children}
     </ul>
   )
@@ -75,7 +75,7 @@ export const UnderlineItem = React.forwardRef((props, ref) => {
   const {as: Component = 'a', children, counter, icon: Icon, loadingCounters, className, ...rest} = props
   const textContent = getTextContent(children)
   return (
-    <Component {...rest} ref={ref} className={clsx(classes.UnderlineItem, className)}>
+    <Component ref={ref} {...mergeProps({className: clsx(classes.UnderlineItem, className)}, rest)}>
       {Icon && <span data-component="icon">{isElement(Icon) ? Icon : <Icon />}</span>}
       {children && (
         <span data-component="text" data-content={textContent || undefined}>

From 30dc0a1b385113f025da7f1bd59a6b01d0222f8e Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Wed, 12 Aug 2026 11:19:36 -0500
Subject: [PATCH 37/39] Use patch changeset for UnderlinePanels types

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 84a0d8ca-13d3-4cb2-ab24-18fa2d9a8a14
---
 .changeset/underline-panels-controlled-panel-props.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/underline-panels-controlled-panel-props.md b/.changeset/underline-panels-controlled-panel-props.md
index c52f1dceee0..636667fb6df 100644
--- a/.changeset/underline-panels-controlled-panel-props.md
+++ b/.changeset/underline-panels-controlled-panel-props.md
@@ -1,5 +1,5 @@
 ---
-'@primer/react': major
+'@primer/react': patch
 ---
 
 UnderlinePanels: Remove unsupported panel attributes that are controlled by the component.

From b0586c08572e56d5cc3fa153fb860dcf28fe3474 Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Wed, 12 Aug 2026 11:21:43 -0500
Subject: [PATCH 38/39] Avoid clsx for single class names

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 84a0d8ca-13d3-4cb2-ab24-18fa2d9a8a14
---
 packages/react/src/ActionBar/ActionBar.tsx          |  4 ++--
 packages/react/src/NavList/NavList.tsx              |  4 ++--
 .../react/src/SplitPageLayout/SplitPageLayout.tsx   | 13 ++++++-------
 packages/react/src/TabNav/TabNav.tsx                |  6 +-----
 4 files changed, 11 insertions(+), 16 deletions(-)

diff --git a/packages/react/src/ActionBar/ActionBar.tsx b/packages/react/src/ActionBar/ActionBar.tsx
index 4ba42585c0b..93b25b4c235 100644
--- a/packages/react/src/ActionBar/ActionBar.tsx
+++ b/packages/react/src/ActionBar/ActionBar.tsx
@@ -368,7 +368,7 @@ export const ActionBarIconButton = forwardRef(
         {...mergeProps(
           {
             'aria-disabled': disabled,
-            className: clsx(className),
+            className,
             size,
             onClick: clickHandler,
           },
@@ -418,7 +418,7 @@ export const ActionBarButton = forwardRef(
         {...mergeProps(
           {
             'aria-disabled': disabled,
-            className: clsx(className),
+            className,
             children,
             leadingVisual,
             size,
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index 30550e6a4d5..a756085efac 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -74,7 +74,7 @@ const Root = React.forwardRef<HTMLElement, NavListProps>(
         ref={ref}
         {...mergeProps(
           {
-            className: clsx(className),
+            className,
             'aria-label': ariaLabel,
             'aria-labelledby': navLabelledby,
           },
@@ -209,7 +209,7 @@ const ItemComponent = fixedForwardRef(
         {...mergeProps(
           {
             as: Component,
-            className: clsx(className),
+            className,
             'aria-current': ariaCurrent,
             active: Boolean(ariaCurrent) && ariaCurrent !== 'false',
             style: {'--subitem-depth': depth} as React.CSSProperties,
diff --git a/packages/react/src/SplitPageLayout/SplitPageLayout.tsx b/packages/react/src/SplitPageLayout/SplitPageLayout.tsx
index 7e559363dd3..d5047d55795 100644
--- a/packages/react/src/SplitPageLayout/SplitPageLayout.tsx
+++ b/packages/react/src/SplitPageLayout/SplitPageLayout.tsx
@@ -9,7 +9,6 @@ import type {
 import {PageLayout} from '../PageLayout'
 import type {WithSlotMarker} from '../utils/types'
 import {mergeProps} from '../utils/mergeProps'
-import {clsx} from 'clsx'
 
 // ----------------------------------------------------------------------------
 // SplitPageLayout
@@ -21,7 +20,7 @@ export const Root: React.FC<React.PropsWithChildren<SplitPageLayoutProps>> = ({c
     <PageLayout
       {...mergeProps(
         {
-          className: clsx(className),
+          className,
           'data-component': 'SplitPageLayout',
           containerWidth: 'full' as const,
           padding: 'none' as const,
@@ -57,7 +56,7 @@ export const Header: React.FC<React.PropsWithChildren<SplitPageLayoutHeaderProps
     <PageLayout.Header
       {...mergeProps(
         {
-          className: clsx(className),
+          className,
           'data-component': 'SplitPageLayout.Header',
           padding,
           divider,
@@ -85,7 +84,7 @@ export const Content: React.FC<React.PropsWithChildren<SplitPageLayoutContentPro
     <PageLayout.Content
       {...mergeProps(
         {
-          className: clsx(className),
+          className,
           'data-component': 'SplitPageLayout.Content',
           width,
           padding,
@@ -115,7 +114,7 @@ export const Pane: React.FC<React.PropsWithChildren<SplitPageLayoutPaneProps>> =
     <PageLayout.Pane
       {...mergeProps(
         {
-          className: clsx(className),
+          className,
           'data-component': 'SplitPageLayout.Pane',
           position,
           sticky,
@@ -145,7 +144,7 @@ export const Sidebar: React.FC<React.PropsWithChildren<SplitPageLayoutSidebarPro
     <PageLayout.Sidebar
       {...mergeProps(
         {
-          className: clsx(className),
+          className,
           'data-component': 'SplitPageLayout.Sidebar',
           position,
           padding,
@@ -175,7 +174,7 @@ export const Footer: React.FC<React.PropsWithChildren<SplitPageLayoutFooterProps
     <PageLayout.Footer
       {...mergeProps(
         {
-          className: clsx(className),
+          className,
           'data-component': 'SplitPageLayout.Footer',
           padding,
           divider,
diff --git a/packages/react/src/TabNav/TabNav.tsx b/packages/react/src/TabNav/TabNav.tsx
index 970766b7bdb..48d9eac7895 100644
--- a/packages/react/src/TabNav/TabNav.tsx
+++ b/packages/react/src/TabNav/TabNav.tsx
@@ -52,11 +52,7 @@ function TabNav({children, className, 'aria-label': ariaLabel, ...rest}: TabNavP
   )
 
   return (
-    <div
-      ref={navRef as React.RefObject<HTMLDivElement>}
-      {...mergeProps({className: clsx(className)}, rest)}
-      data-component="TabNav"
-    >
+    <div ref={navRef as React.RefObject<HTMLDivElement>} {...mergeProps({className}, rest)} data-component="TabNav">
       <nav aria-label={ariaLabel} className={styles.TabNavNav}>
         <div role="tablist" className={styles.TabNavTabList}>
           {children}

From 057b4de017df1fb8cbdc125593dc77ecaf43bdbd Mon Sep 17 00:00:00 2001
From: Josh Black <joshblack@github.com>
Date: Wed, 12 Aug 2026 11:23:56 -0500
Subject: [PATCH 39/39] Clarify UnderlinePanels type correction

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 84a0d8ca-13d3-4cb2-ab24-18fa2d9a8a14
---
 .changeset/underline-panels-controlled-panel-props.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/underline-panels-controlled-panel-props.md b/.changeset/underline-panels-controlled-panel-props.md
index 636667fb6df..dd4eaf85abb 100644
--- a/.changeset/underline-panels-controlled-panel-props.md
+++ b/.changeset/underline-panels-controlled-panel-props.md
@@ -2,4 +2,4 @@
 '@primer/react': patch
 ---
 
-UnderlinePanels: Remove unsupported panel attributes that are controlled by the component.
+UnderlinePanels: Correct Panel types to exclude attributes controlled by the component.