From a432730c5ab595455ef597dae1ad7cd12ed3a36a Mon Sep 17 00:00:00 2001
From: Edward Zarecor <ed@tcril.org>
Date: Sat, 2 May 2026 15:22:00 -0400
Subject: [PATCH 1/2] fix(ActionRow): mark ActionRowSpacer as aria-hidden

The spacer is a purely decorative flex-grow element with no semantic
meaning; hiding it from the accessibility tree is more precise than
relying on AT heuristics for empty spans.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/ActionRow/index.tsx                     | 2 +-
 src/Alert/__snapshots__/Alert.test.tsx.snap | 4 ++++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/ActionRow/index.tsx b/src/ActionRow/index.tsx
index 5a698762f24..c0881d7a821 100644
--- a/src/ActionRow/index.tsx
+++ b/src/ActionRow/index.tsx
@@ -32,7 +32,7 @@ function ActionRow({
 }
 
 function ActionRowSpacer() {
-  return <span className="pgn__action-row-spacer" />;
+  return <span className="pgn__action-row-spacer" aria-hidden="true" />;
 }
 
 ActionRow.Spacer = ActionRowSpacer;
diff --git a/src/Alert/__snapshots__/Alert.test.tsx.snap b/src/Alert/__snapshots__/Alert.test.tsx.snap
index 6f7a0d15934..6e718d92166 100644
--- a/src/Alert/__snapshots__/Alert.test.tsx.snap
+++ b/src/Alert/__snapshots__/Alert.test.tsx.snap
@@ -17,6 +17,7 @@ exports[`<Alert /> renders with button and dismissible props 1`] = `
       className="pgn__alert-actions pgn__action-row"
     >
       <span
+        aria-hidden="true"
         className="pgn__action-row-spacer"
       />
       <button
@@ -56,6 +57,7 @@ exports[`<Alert /> renders with button prop 1`] = `
       className="pgn__alert-actions pgn__action-row"
     >
       <span
+        aria-hidden="true"
         className="pgn__action-row-spacer"
       />
       <button
@@ -87,6 +89,7 @@ exports[`<Alert /> renders with dismissible prop 1`] = `
       className="pgn__alert-actions pgn__action-row"
     >
       <span
+        aria-hidden="true"
         className="pgn__action-row-spacer"
       />
       <button
@@ -155,6 +158,7 @@ exports[`<Alert /> renders with stacked prop 1`] = `
       className="pgn__alert-actions pgn__action-row"
     >
       <span
+        aria-hidden="true"
         className="pgn__action-row-spacer"
       />
       <button

From c15a33d63a5f3c193e2f97c38aedb166279fe7c7 Mon Sep 17 00:00:00 2001
From: Edward Zarecor <ed@tcril.org>
Date: Sat, 2 May 2026 16:46:30 -0400
Subject: [PATCH 2/2] docs(ActionRow): document role=group and aria-label for
 button group usage

Without guidance, consumers using ActionRow to group interactive controls
have no nudge to add ARIA grouping semantics. Adds a README Accessibility
section with the recommended pattern (role="group" + aria-label) and a
live code example. Also adds interface-level JSDoc in index.tsx pointing
TypeScript consumers to the same pattern.

Addresses WCAG 4.1.2 Name, Role, Value and 1.3.1 Info and Relationships.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/ActionRow/README.md | 15 +++++++++++++++
 src/ActionRow/index.tsx | 17 +++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/src/ActionRow/README.md b/src/ActionRow/README.md
index 7ad955b1e70..7ded8cc2f94 100644
--- a/src/ActionRow/README.md
+++ b/src/ActionRow/README.md
@@ -18,6 +18,21 @@ in a row in a control bar or nav.
 
 ActionRow assumes that its last child is the primary action and lays out actions so that the last item is in a primary location. If horizontal, the primary action sits on the right. If stacked, the primary action sits at the top of the stack (this is done via `flex-direction: column-reverse;`).
 
+## Accessibility
+
+When ActionRow groups interactive controls (buttons, links), add `role="group"` and `aria-label`
+so assistive technology users can identify the group's purpose and distinguish multiple ActionRows
+on the same page:
+
+```jsx live
+<ActionRow role="group" aria-label="Form actions">
+  <Button variant="tertiary">Cancel</Button>
+  <Button variant="primary">Submit</Button>
+</ActionRow>
+```
+
+Both attributes are passed through to the underlying element via the standard HTML attributes spread.
+
 ## Basic Usage
 
 ```jsx live
diff --git a/src/ActionRow/index.tsx b/src/ActionRow/index.tsx
index c0881d7a821..9774e6c4748 100644
--- a/src/ActionRow/index.tsx
+++ b/src/ActionRow/index.tsx
@@ -1,6 +1,23 @@
 import React from 'react';
 import classNames from 'classnames';
 
+/**
+ * Layout utility that arranges action controls in a horizontal row or vertical stack.
+ *
+ * When ActionRow groups interactive controls (buttons, links), add `role="toolbar"`
+ * and `aria-label` so assistive technology users can identify the group and
+ * distinguish multiple ActionRows on the same page:
+ *
+ * ```jsx
+ * <ActionRow role="toolbar" aria-label="Form actions">
+ *   <Button variant="tertiary">Cancel</Button>
+ *   <Button variant="primary">Submit</Button>
+ * </ActionRow>
+ * ```
+ *
+ * Both props are accepted via the standard HTML attributes spread; no extra
+ * prop definitions are required.
+ */
 interface ActionRowProps extends React.HTMLAttributes<HTMLElement> {
   /** Specifies the base element */
   as?: React.ElementType;