From aa83ac257cca5fdb6ac7dc21dadf12da1559d0bd Mon Sep 17 00:00:00 2001
From: AK <144495202+AKnassa@users.noreply.github.com>
Date: Mon, 3 Aug 2026 15:16:04 -0400
Subject: [PATCH] fix(a11y): unique names for repeated nav landmarks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

axe landmark-unique (moderate): same-type landmarks need
distinguishable names. Story matrices rendered several navs with
identical default labels — fixed by passing distinct labels through
existing props (Layout, Pagination, TabList, Toolbar,
ToolbarEdgeCompensation, TablePagination stories). Component fix:
useTablePagination position=both emitted two navs with one name from
a single hook call — they now interpolate the label into distinct
top/bottom names via new en.json keys; single-position names stay
byte-identical. label config documented in doc.mjs.
Baseline: -8 entries.

Verified: 43/43 pagination + 147/147 wider slice tests, core
typecheck, eslint clean, axe audit exit 0 (0 new, 13 resolved)
across all six components.

Part of #4681.
---
 .../a11y-table-pagination-both-labels.md      |  6 +++
 .github/a11y-baseline.json                    | 40 -------------------
 apps/storybook/stories/Layout.stories.tsx     | 26 +++++++-----
 apps/storybook/stories/Pagination.stories.tsx | 23 +++++++++--
 apps/storybook/stories/TabList.stories.tsx    | 13 +++++-
 .../stories/TablePagination.stories.tsx       |  4 ++
 apps/storybook/stories/Toolbar.stories.tsx    |  5 ++-
 .../ToolbarEdgeCompensation.stories.tsx       |  9 +++--
 packages/core/locales/en.json                 | 10 ++++-
 .../pagination/useTablePagination.test.tsx    | 38 ++++++++++++++++--
 .../plugins/pagination/useTablePagination.tsx | 38 ++++++++++++++++--
 .../core/src/Table/useTablePagination.doc.mjs |  7 ++++
 12 files changed, 152 insertions(+), 67 deletions(-)
 create mode 100644 .changeset/a11y-table-pagination-both-labels.md

diff --git a/.changeset/a11y-table-pagination-both-labels.md b/.changeset/a11y-table-pagination-both-labels.md
new file mode 100644
index 000000000000..e7b167503a50
--- /dev/null
+++ b/.changeset/a11y-table-pagination-both-labels.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] useTablePagination: with `position='both'` the two pagination `<nav>` landmarks now get distinct accessible names — "{label} (top)" above the table and "{label} (bottom)" below it (axe landmark-unique). Consumer-supplied `label` values are interpolated into both names; single-position labels are unchanged.
+@AKnassa
diff --git a/.github/a11y-baseline.json b/.github/a11y-baseline.json
index 84e9c710ad67..64abeb3b819a 100644
--- a/.github/a11y-baseline.json
+++ b/.github/a11y-baseline.json
@@ -678,11 +678,6 @@
       "impact": "serious",
       "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
     },
-    {
-      "key": "Layout::Content Width — Responsive Panels::landmark-unique",
-      "impact": "moderate",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"
-    },
     {
       "key": "Layout::Content Width — Start Panel::color-contrast",
       "impact": "serious",
@@ -753,11 +748,6 @@
       "impact": "serious",
       "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
     },
-    {
-      "key": "Pagination::All Variants::landmark-unique",
-      "impact": "moderate",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"
-    },
     {
       "key": "PopArt::Debug Projection::color-contrast",
       "impact": "serious",
@@ -943,16 +933,6 @@
       "impact": "serious",
       "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
     },
-    {
-      "key": "TabList::Divider Gap (sm / md / lg)::landmark-unique",
-      "impact": "moderate",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"
-    },
-    {
-      "key": "TabList::Size Variants::landmark-unique",
-      "impact": "moderate",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"
-    },
     {
       "key": "Table::In Card Densities::color-contrast",
       "impact": "serious",
@@ -998,16 +978,6 @@
       "impact": "serious",
       "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
     },
-    {
-      "key": "TablePagination::Options Matrix::landmark-unique",
-      "impact": "moderate",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"
-    },
-    {
-      "key": "TablePagination::Position Both::landmark-unique",
-      "impact": "moderate",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"
-    },
     {
       "key": "TableRowStatus::Default::empty-table-header",
       "impact": "minor",
@@ -1103,16 +1073,6 @@
       "impact": "serious",
       "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
     },
-    {
-      "key": "Toolbar::Composition: Tab Navigation::landmark-unique",
-      "impact": "moderate",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"
-    },
-    {
-      "key": "ToolbarEdgeCompensation::Tabs in toolbar (all sizes)::landmark-unique",
-      "impact": "moderate",
-      "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"
-    },
     {
       "key": "useContainerReveal::Inverted Conceal::color-contrast",
       "impact": "serious",
diff --git a/apps/storybook/stories/Layout.stories.tsx b/apps/storybook/stories/Layout.stories.tsx
index 1bb496ec39e7..15c5ba912192 100644
--- a/apps/storybook/stories/Layout.stories.tsx
+++ b/apps/storybook/stories/Layout.stories.tsx
@@ -743,9 +743,7 @@ export const ThemedLayout: Story = {
   render: () => (
     <HStack gap={6} xstyle={styles.storySection}>
       <VStack gap={3}>
-        <p {...stylex.props(styles.sectionLabel)}>
-          Stone Theme
-        </p>
+        <p {...stylex.props(styles.sectionLabel)}>Stone Theme</p>
         <Theme theme={stoneTheme}>
           <Card width={400}>
             <Layout
@@ -779,9 +777,7 @@ export const ThemedLayout: Story = {
       </VStack>
 
       <VStack gap={3}>
-        <p {...stylex.props(styles.sectionLabel)}>
-          Neutral Theme
-        </p>
+        <p {...stylex.props(styles.sectionLabel)}>Neutral Theme</p>
         <Theme theme={neutralTheme}>
           <Card width={400}>
             <Layout
@@ -1229,7 +1225,11 @@ export const ContentWidthResponsive: Story = {
                 </LayoutHeader>
               }
               start={
-                <LayoutPanel width={160} hasDivider role="navigation">
+                <LayoutPanel
+                  width={160}
+                  hasDivider
+                  role="navigation"
+                  label="Wide navigation">
                   <NavItem active>Dashboard</NavItem>
                   <NavItem>Settings</NavItem>
                 </LayoutPanel>
@@ -1262,7 +1262,11 @@ export const ContentWidthResponsive: Story = {
                 </LayoutHeader>
               }
               start={
-                <LayoutPanel width={160} hasDivider role="navigation">
+                <LayoutPanel
+                  width={160}
+                  hasDivider
+                  role="navigation"
+                  label="Medium navigation">
                   <NavItem active>Dashboard</NavItem>
                   <NavItem>Settings</NavItem>
                 </LayoutPanel>
@@ -1295,7 +1299,11 @@ export const ContentWidthResponsive: Story = {
                 </LayoutHeader>
               }
               start={
-                <LayoutPanel width={160} hasDivider role="navigation">
+                <LayoutPanel
+                  width={160}
+                  hasDivider
+                  role="navigation"
+                  label="Narrow navigation">
                   <NavItem active>Dashboard</NavItem>
                   <NavItem>Settings</NavItem>
                 </LayoutPanel>
diff --git a/apps/storybook/stories/Pagination.stories.tsx b/apps/storybook/stories/Pagination.stories.tsx
index a87049796ee2..ae1f7c565746 100644
--- a/apps/storybook/stories/Pagination.stories.tsx
+++ b/apps/storybook/stories/Pagination.stories.tsx
@@ -156,6 +156,7 @@ export const AllVariants: Story = {
           totalItems={100}
           pageSize={10}
           variant="pages"
+          label="Pagination (pages)"
         />
       </div>
       <div>
@@ -165,19 +166,35 @@ export const AllVariants: Story = {
           totalItems={100}
           pageSize={10}
           variant="count"
+          label="Pagination (count)"
         />
       </div>
       <div>
         <p style={{marginBottom: 8, fontWeight: 500}}>compact</p>
-        <PaginationDemo page={3} totalPages={10} variant="compact" />
+        <PaginationDemo
+          page={3}
+          totalPages={10}
+          variant="compact"
+          label="Pagination (compact)"
+        />
       </div>
       <div>
         <p style={{marginBottom: 8, fontWeight: 500}}>dots</p>
-        <PaginationDemo page={3} totalPages={8} variant="dots" />
+        <PaginationDemo
+          page={3}
+          totalPages={8}
+          variant="dots"
+          label="Pagination (dots)"
+        />
       </div>
       <div>
         <p style={{marginBottom: 8, fontWeight: 500}}>none</p>
-        <PaginationDemo page={3} totalPages={10} variant="none" />
+        <PaginationDemo
+          page={3}
+          totalPages={10}
+          variant="none"
+          label="Pagination (none)"
+        />
       </div>
     </div>
   ),
diff --git a/apps/storybook/stories/TabList.stories.tsx b/apps/storybook/stories/TabList.stories.tsx
index cfaf8e935186..39481426181f 100644
--- a/apps/storybook/stories/TabList.stories.tsx
+++ b/apps/storybook/stories/TabList.stories.tsx
@@ -101,7 +101,11 @@ export const SizeVariants: Story = {
               size=\"{size}\"
             </div>
             <div style={{border: '1px dashed #ccc', display: 'inline-flex'}}>
-              <TabList value={value} onChange={setValue} size={size}>
+              <TabList
+                value={value}
+                onChange={setValue}
+                size={size}
+                aria-label={`Tabs (${size})`}>
                 <Tab value="home" label="Home" />
                 <Tab value="projects" label="Projects" />
                 <Tab value="settings" label="Settings" />
@@ -242,7 +246,12 @@ export const DividerGap: Story = {
             <span style={{font: '600 12px system-ui', color: '#4E606F'}}>
               size=&quot;{size}&quot; · hasDivider · matched Button size
             </span>
-            <TabList value={value} onChange={setValue} size={size} hasDivider>
+            <TabList
+              value={value}
+              onChange={setValue}
+              size={size}
+              hasDivider
+              aria-label={`Tabs (${size})`}>
               <Tab value="overview" label="Overview" />
               <Tab value="activity" label="Activity" />
               <Tab value="settings" label="Settings" />
diff --git a/apps/storybook/stories/TablePagination.stories.tsx b/apps/storybook/stories/TablePagination.stories.tsx
index 21f90aed37e7..280bcf1341f5 100644
--- a/apps/storybook/stories/TablePagination.stories.tsx
+++ b/apps/storybook/stories/TablePagination.stories.tsx
@@ -51,10 +51,12 @@ function PaginatedDemo({
   variant = 'pages',
   position = 'below',
   align = 'start',
+  label,
 }: {
   variant?: Variant;
   position?: Position;
   align?: Align;
+  label?: string;
 }) {
   const [page, setPage] = useState(1);
   const pageSize = 10;
@@ -67,6 +69,7 @@ function PaginatedDemo({
     variant,
     position,
     align,
+    label,
   });
 
   return (
@@ -394,6 +397,7 @@ export const OptionsMatrix: Story = {
                 variant={variant}
                 position={position}
                 align={align}
+                label={`Table pagination (${variant}, ${position}, ${align})`}
               />
             </div>
           )),
diff --git a/apps/storybook/stories/Toolbar.stories.tsx b/apps/storybook/stories/Toolbar.stories.tsx
index 6e219e029881..8c9119ed760a 100644
--- a/apps/storybook/stories/Toolbar.stories.tsx
+++ b/apps/storybook/stories/Toolbar.stories.tsx
@@ -414,7 +414,10 @@ export const WithTabNavigation: Story = {
               size={size}
               dividers={['bottom']}
               startContent={
-                <TabList value={tab} onChange={setTab}>
+                <TabList
+                  value={tab}
+                  onChange={setTab}
+                  aria-label={`Tab navigation (${size})`}>
                   <Tab value="overview" label="Overview" />
                   <Tab value="analytics" label="Analytics" />
                   <Tab value="settings" label="Settings" />
diff --git a/apps/storybook/stories/ToolbarEdgeCompensation.stories.tsx b/apps/storybook/stories/ToolbarEdgeCompensation.stories.tsx
index e0bf2b524b6a..f36061550545 100644
--- a/apps/storybook/stories/ToolbarEdgeCompensation.stories.tsx
+++ b/apps/storybook/stories/ToolbarEdgeCompensation.stories.tsx
@@ -1053,9 +1053,7 @@ export const CardLayoutContentWidthToolbar: Story = {
               <LayoutHeader hasDivider padding={0}>
                 <Toolbar
                   label="Card layout header"
-                  startContent={
-                    <Heading level={4}>Notifications</Heading>
-                  }
+                  startContent={<Heading level={4}>Notifications</Heading>}
                 />
               </LayoutHeader>
             }
@@ -1144,7 +1142,10 @@ export const WithTabs: Story = {
                 size={size}
                 dividers={['bottom']}
                 startContent={
-                  <TabList value={tab} onChange={setTab}>
+                  <TabList
+                    value={tab}
+                    onChange={setTab}
+                    aria-label={`Tab toolbar tabs (${size})`}>
                     <Tab value="overview" label="Overview" />
                     <Tab value="analytics" label="Analytics" />
                     <Tab value="settings" label="Settings" />
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 9c4b6111001d..77465ae620f3 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -669,7 +669,15 @@
   },
   "@astryx.table.pagination.label": {
     "defaultMessage": "Table pagination",
-    "description": "Screen-reader-only accessible name for the pagination `<nav>` appended below a data table. Kept separate from `@astryx.pagination.label` so translations may diverge."
+    "description": "Screen-reader-only accessible name for a table's pagination `<nav>` (rendered below and/or above the table per the plugin's position config). Kept separate from `@astryx.pagination.label` so translations may diverge. When position='both', this string is interpolated as the {label} value into `@astryx.table.pagination.labelAbove`/`labelBelow` — keep it compatible with those suffix templates."
+  },
+  "@astryx.table.pagination.labelAbove": {
+    "defaultMessage": "{label} (top)",
+    "description": "Accessible name for the pagination `<nav>` rendered above the table when position='both' renders two navs. `label` is the resolved base label (default \"Table pagination\" or consumer-supplied); the suffix keeps the two same-type landmarks distinguishable."
+  },
+  "@astryx.table.pagination.labelBelow": {
+    "defaultMessage": "{label} (bottom)",
+    "description": "Accessible name for the pagination `<nav>` rendered below the table when position='both' renders two navs. `label` is the resolved base label (default \"Table pagination\" or consumer-supplied); the suffix keeps the two same-type landmarks distinguishable."
   },
   "@astryx.timeInput.placeholder": {
     "defaultMessage": "Select a time",
diff --git a/packages/core/src/Table/plugins/pagination/useTablePagination.test.tsx b/packages/core/src/Table/plugins/pagination/useTablePagination.test.tsx
index ce9b1d499da0..22b68091c0c9 100644
--- a/packages/core/src/Table/plugins/pagination/useTablePagination.test.tsx
+++ b/packages/core/src/Table/plugins/pagination/useTablePagination.test.tsx
@@ -229,7 +229,7 @@ describe('useTablePagination', () => {
       ).toBeTruthy();
     });
 
-    it('transformTableContext renders Pagination above and below', () => {
+    it('transformTableContext renders distinctly named Pagination above and below', () => {
       render(
         <PaginatedTable
           data={generateItems(30)}
@@ -237,10 +237,40 @@ describe('useTablePagination', () => {
           position="both"
         />,
       );
-      const navs = screen.getAllByRole('navigation', {
-        name: 'Table pagination',
+      const table = screen.getByRole('table');
+      // Each nav landmark gets a unique accessible name (axe landmark-unique)
+      const topNav = screen.getByRole('navigation', {
+        name: 'Table pagination (top)',
+      });
+      const bottomNav = screen.getByRole('navigation', {
+        name: 'Table pagination (bottom)',
       });
-      expect(navs).toHaveLength(2);
+      // Top nav comes before the table, bottom nav after it in DOM order
+      expect(
+        table.compareDocumentPosition(topNav) &
+          Node.DOCUMENT_POSITION_PRECEDING,
+      ).toBeTruthy();
+      expect(
+        table.compareDocumentPosition(bottomNav) &
+          Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+    });
+
+    it('position="both" interpolates a consumer label into distinct nav names', () => {
+      render(
+        <PaginatedTable
+          data={generateItems(30)}
+          pageSize={10}
+          position="both"
+          label="Users table"
+        />,
+      );
+      expect(
+        screen.getByRole('navigation', {name: 'Users table (top)'}),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole('navigation', {name: 'Users table (bottom)'}),
+      ).toBeInTheDocument();
     });
 
     it('transformTableContext does not render Pagination when position is none', () => {
diff --git a/packages/core/src/Table/plugins/pagination/useTablePagination.tsx b/packages/core/src/Table/plugins/pagination/useTablePagination.tsx
index fbb562cc1e39..fcc2994043da 100644
--- a/packages/core/src/Table/plugins/pagination/useTablePagination.tsx
+++ b/packages/core/src/Table/plugins/pagination/useTablePagination.tsx
@@ -164,6 +164,9 @@ export interface UseTablePaginationConfig {
 
   /**
    * Accessible label for the pagination nav landmark.
+   * When `position` is 'both', the two navs get distinct names by suffixing
+   * this label — "{label} (top)" above and "{label} (bottom)" below — so
+   * same-type landmarks stay distinguishable to assistive technology.
    * @default 'Table pagination'
    */
   label?: string;
@@ -211,6 +214,10 @@ export function useTablePagination<T extends Record<string, unknown>>(
     label: labelFromProps,
   } = config;
   const label = labelFromProps ?? t('@astryx.table.pagination.label');
+  // position='both' renders two nav landmarks; suffix the base label so each
+  // gets a unique accessible name (axe landmark-unique).
+  const labelAbove = t('@astryx.table.pagination.labelAbove', {label});
+  const labelBelow = t('@astryx.table.pagination.labelBelow', {label});
 
   // Same guard as Pagination itself: 0/NaN/negative pageSize would produce an
   // Infinity/NaN totalPages here, which bypasses Pagination's own coercion
@@ -240,8 +247,20 @@ export function useTablePagination<T extends Record<string, unknown>>(
 
   // Keep current config in a ref so the plugin can read the latest values
   // without needing to recreate the plugin object on every change.
-  const configRef = useRef({paginationProps, position, align});
-  configRef.current = {paginationProps, position, align};
+  const configRef = useRef({
+    paginationProps,
+    position,
+    align,
+    labelAbove,
+    labelBelow,
+  });
+  configRef.current = {
+    paginationProps,
+    position,
+    align,
+    labelAbove,
+    labelBelow,
+  };
 
   // Stable plugin object \u2014 created once, reads config via ref.
   return useMemo(
@@ -251,6 +270,8 @@ export function useTablePagination<T extends Record<string, unknown>>(
           position: pos,
           paginationProps: props,
           align: a,
+          labelAbove: above,
+          labelBelow: below,
         } = configRef.current;
         if (pos === 'none') {
           return children;
@@ -277,7 +298,18 @@ export function useTablePagination<T extends Record<string, unknown>>(
               a === 'end' && styles.alignEnd,
               a === 'start' && styles.alignStart,
             )}>
-            <Pagination {...props} />
+            <Pagination
+              {...props}
+              // Two navs with the same name are indistinguishable landmarks;
+              // give each side a unique name when both render.
+              label={
+                pos === 'both'
+                  ? side === 'above'
+                    ? above
+                    : below
+                  : props.label
+              }
+            />
           </div>
         );
 
diff --git a/packages/core/src/Table/useTablePagination.doc.mjs b/packages/core/src/Table/useTablePagination.doc.mjs
index 77b6e220bfda..c7a1c5373095 100644
--- a/packages/core/src/Table/useTablePagination.doc.mjs
+++ b/packages/core/src/Table/useTablePagination.doc.mjs
@@ -72,6 +72,12 @@ export const docs = {
       description: 'Horizontal alignment of the pagination controls.',
       default: "'center'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description: "Accessible name for the pagination nav landmark. With position='both' the two navs get distinct names — the label suffixed as '(top)' and '(bottom)' — so same-type landmarks stay unique (axe landmark-unique).",
+      default: "'Table pagination'",
+    },
   ],
 };
 
@@ -129,5 +135,6 @@ export const docsDense = {
     pageSize: 'Items per page. Default 10.',
     variant: "Pagination variant: 'pages'|'count'|'compact'|'dots'|'none'.",
     position: "Render position: 'below'|'above'|'both'|'none'.",
+    label: "Accessible name for the nav landmark; position='both' emits '<label> (top)' / '<label> (bottom)'.",
   },
 };