Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(MobileNav): the drawer's content region is a navigation landmark named like the dialog (#10130)

Cindy Zhangd67a7848eeda
diff --git a/.changeset/mobilenav-navigation-landmark.md b/.changeset/mobilenav-navigation-landmark.md
new file mode 100644
index 0000000000..1be3e1427d
--- /dev/null
+++ b/.changeset/mobilenav-navigation-landmark.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] MobileNav: the drawer's content region is now a navigation landmark (`<nav>`) named like the drawer's dialog, so someone moving by landmarks on a phone finds the drawer's links, as they find SideNav's on a wide screen. SideNav items and a TopNav's drawer content both sit inside that one landmark.
+
+@cixzhang
diff --git a/docs/specs/components/MobileNav/MobileNav.spec.md b/docs/specs/components/MobileNav/MobileNav.spec.md
index bef16b81c4..f44bfb7a02 100644
--- a/docs/specs/components/MobileNav/MobileNav.spec.md
+++ b/docs/specs/components/MobileNav/MobileNav.spec.md
@@ -48,15 +48,15 @@ system_specs: [spec:AST-094/FR13, spec:AST-094/FR35]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `MobileNav` with `isOpen`, `onOpenChange`, `header`, `width` (320), `side` (`start`, `end`, `auto`; default `auto`), `label`, and `children`; target `mobile-nav` with a `side` state; `MobileNavToggle` with `label` and `children`. |
-| Behavior | A modal native dialog with a drawer that slides in from one inline edge, a header with a Close button, and a scrolling content region. Escape, the backdrop, and Close request closing; the dialog stays open while the drawer starts sliding out and closes within the slide-out (FR5), then focus returns to the opener. |
-| End-user impact | Phone users open navigation in a drawer that contains focus, lock the page behind it, close it any usual way, and land back on the control that opened it. |
-| Builder impact | None. |
-| Compatibility/readiness | Records shipped behavior; no public change. Seven implementation gaps: automatic side selection uses physical position, reduced motion still animates, its own top layer, close hold, and backdrop, a caller `id` disconnects the Toggle, a caller `aria-label` and `onCancel` are dropped, and the drawer has no navigation landmark (see Current-state impact). |
-| Review checks | Reject a non-modal drawer, a close that hides the drawer before its slide-out runs, focus not returned to a connected opener, a backdrop click inside the drawer that closes it, or a Toggle rendered outside an enabled AppShell mobile layout. |
-| Governing rules | `family:overlay-dismissal`; `architecture:layer-runtime` INV14; `component:AppShell` FR10–FR13; `design:bidirectionality` DR7; `design:reduced-motion` DR1–DR3; `architecture:public-component-api` INV5, INV7; `architecture:component-theming-surface`. |
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `MobileNav` with `isOpen`, `onOpenChange`, `header`, `width` (320), `side` (`start`, `end`, `auto`; default `auto`), `label`, and `children`; target `mobile-nav` with a `side` state; `MobileNavToggle` with `label` and `children`. |
+| Behavior | A modal native dialog with a drawer that slides in from one inline edge, a header with a Close button, and a scrolling content region. Escape, the backdrop, and Close request closing; the dialog stays open while the drawer starts sliding out and closes within the slide-out (FR5), then focus returns to the opener. |
+| End-user impact | Phone users open navigation in a drawer that contains focus, lock the page behind it, close it any usual way, and land back on the control that opened it. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps: automatic side selection uses physical position, reduced motion still animates, its own top layer, close hold, and backdrop, a caller `id` disconnects the Toggle, and a caller `aria-label` and `onCancel` are dropped (see Current-state impact). |
+| Review checks | Reject a non-modal drawer, a close that hides the drawer before its slide-out runs, focus not returned to a connected opener, a backdrop click inside the drawer that closes it, or a Toggle rendered outside an enabled AppShell mobile layout. |
+| Governing rules | `family:overlay-dismissal`; `architecture:layer-runtime` INV14; `component:AppShell` FR10–FR13; `design:bidirectionality` DR7; `design:reduced-motion` DR1–DR3; `architecture:public-component-api` INV5, INV7; `architecture:component-theming-surface`. |
This table is a review projection; the body below is authoritative.
@@ -106,10 +106,6 @@ Consumer migration instructions belong in consumer docs and release notes.
the backdrop's fade still run, for 0.01 s, rather than changing at once for a
fine pointer or cross-fading for touch. `design:reduced-motion` DR2 and DR3
allow no travel and, for a fine pointer, no animated property.
-- **The drawer has no navigation landmark.** The Content region is a plain
- element inside the modal dialog, which is not a landmark, so landmark
- navigation on a phone finds no navigation. FR14 makes the Content region a
- navigation landmark named like the dialog.
## Ownership boundary
diff --git a/packages/core/src/MobileNav/MobileNav.test.tsx b/packages/core/src/MobileNav/MobileNav.test.tsx
index 591abf58df..c007056356 100644
--- a/packages/core/src/MobileNav/MobileNav.test.tsx
+++ b/packages/core/src/MobileNav/MobileNav.test.tsx
@@ -10,7 +10,7 @@
*/
import {describe, it, expect, vi, beforeAll} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {render, screen, within, fireEvent} from '@testing-library/react';
import {MobileNav} from './MobileNav';
import {declaredValue} from '../__tests__/stylexDeclarations';
@@ -247,6 +247,67 @@ describe('MobileNav', () => {
);
});
+ it('puts the drawer content in a navigation landmark named like the dialog', () => {
+ const {rerender} = render(
+ <MobileNav isOpen={true} onOpenChange={() => {}} header="My Nav">
+ <a href="/home">Home</a>
+ </MobileNav>,
+ );
+ const dialog = screen.getByRole('dialog', {name: 'My Nav'});
+ const navigation = within(dialog).getByRole('navigation', {
+ name: 'My Nav',
+ });
+ expect(navigation).toContainElement(
+ screen.getByRole('link', {name: 'Home'}),
+ );
+ expect(within(dialog).getAllByRole('navigation')).toHaveLength(1);
+
+ rerender(
+ <MobileNav isOpen={true} onOpenChange={() => {}}>
+ <a href="/home">Home</a>
+ </MobileNav>,
+ );
+ expect(
+ within(screen.getByRole('dialog')).getByRole('navigation', {
+ name: 'Navigation',
+ }),
+ ).toBeInTheDocument();
+ });
+
+ it("names the landmark by the caller's aria-labelledby, as the dialog is", () => {
+ render(
+ <>
+ <h2 id="drawer-title">Workspace</h2>
+ <MobileNav
+ isOpen={true}
+ onOpenChange={() => {}}
+ aria-labelledby="drawer-title">
+ <a href="/home">Home</a>
+ </MobileNav>
+ </>,
+ );
+ const dialog = screen.getByRole('dialog', {name: 'Workspace'});
+ expect(
+ within(dialog).getByRole('navigation', {name: 'Workspace'}),
+ ).toBeInTheDocument();
+ });
+
+ it("falls back to the dialog's own name when the caller's aria-labelledby resolves to nothing", () => {
+ render(
+ <MobileNav
+ isOpen={true}
+ onOpenChange={() => {}}
+ header="My Nav"
+ aria-labelledby="missing-id">
+ <a href="/home">Home</a>
+ </MobileNav>,
+ );
+ const dialog = screen.getByRole('dialog', {name: 'My Nav'});
+ expect(
+ within(dialog).getByRole('navigation', {name: 'My Nav'}),
+ ).toBeInTheDocument();
+ });
+
it('opens dialog via showModal when isOpen becomes true', () => {
const {rerender} = render(
<MobileNav
diff --git a/packages/core/src/MobileNav/MobileNav.tsx b/packages/core/src/MobileNav/MobileNav.tsx
index 9592be734c..897895d05c 100644
--- a/packages/core/src/MobileNav/MobileNav.tsx
+++ b/packages/core/src/MobileNav/MobileNav.tsx
@@ -701,6 +701,9 @@ export function MobileNav({
);
const isStart = resolvedSide === 'start';
+ const navigationLabel =
+ label ??
+ (typeof header === 'string' ? header : t('@astryx.mobileNav.navigation'));
return (
<dialog
@@ -723,12 +726,7 @@ export function MobileNav({
)}
{...rest}
data-testid={testId}
- aria-label={
- label ??
- (typeof header === 'string'
- ? header
- : t('@astryx.mobileNav.navigation'))
- }
+ aria-label={navigationLabel}
// Presses inside the navigation do not reach handlers around where it
// is written.
{...layerClickBoundary({
@@ -773,8 +771,16 @@ export function MobileNav({
/>
</div>
- {/* Scrollable content */}
- <div {...stylex.props(styles.content)}>{children}</div>
+ {/* Scrollable content, the drawer's navigation landmark: a
+ modal dialog is not a landmark. */}
+ <nav
+ // Named as the dialog is: by the caller's aria-labelledby when
+ // it resolves, else by the dialog's own label.
+ aria-labelledby={rest['aria-labelledby']}
+ aria-label={navigationLabel}
+ {...stylex.props(styles.content)}>
+ {children}
+ </nav>
</div>
</LayerContentBoundary>
</LayerDepthProvider>
diff --git a/packages/core/src/MobileNav/__tests__/MobileNavLandmark.a11y.chromium.spec.ts b/packages/core/src/MobileNav/__tests__/MobileNavLandmark.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..1770ea6276
--- /dev/null
+++ b/packages/core/src/MobileNav/__tests__/MobileNavLandmark.a11y.chromium.spec.ts
@@ -0,0 +1,146 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(packages/core/src/(MobileNav|SideNav|TopNav|AppShell)/|apps/storybook/stories/(MobileNav|AppShell)\.stories)
+
+/**
+ * @file MobileNavLandmark.a11y.chromium.spec.ts
+ * @input Built MobileNav and AppShell stories, real Chromium, and its
+ * accessibility tree (CDP)
+ * @output Evidence that the open drawer exposes exactly one navigation
+ * landmark, named like its dialog, holding the drawer's links, for SideNav
+ * items and for a TopNav's drawer content
+ * @position Real-engine proof for component:MobileNav FR14; computed role and
+ * name need accessibility-tree evidence
+ */
+
+import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+interface AXNode {
+ readonly nodeId: string;
+ readonly parentId?: string;
+ readonly role?: {readonly value?: string};
+ readonly name?: {readonly value?: string};
+ readonly ignored?: boolean;
+}
+
+/** The open dialog's navigation landmarks, from Chromium's own tree. */
+async function drawerLandmarks(page: Page) {
+ const cdp = await page.context().newCDPSession(page);
+ const {nodes} = (await cdp.send('Accessibility.getFullAXTree')) as {
+ nodes: AXNode[];
+ };
+ const byId = new Map(nodes.map(node => [node.nodeId, node]));
+ const dialog = nodes.find(
+ node => !node.ignored && node.role?.value === 'dialog',
+ );
+ if (dialog == null) {
+ throw new Error('No open dialog in the accessibility tree');
+ }
+ const insideDialog = (node: AXNode) => {
+ for (
+ let parent = node.parentId != null ? byId.get(node.parentId) : undefined;
+ parent != null;
+ parent = parent.parentId != null ? byId.get(parent.parentId) : undefined
+ ) {
+ if (parent.nodeId === dialog.nodeId) {
+ return true;
+ }
+ }
+ return false;
+ };
+ const landmarks = nodes.filter(
+ node =>
+ !node.ignored && node.role?.value === 'navigation' && insideDialog(node),
+ );
+ const linksIn = (landmark: AXNode) =>
+ nodes.filter(node => {
+ if (node.ignored || node.role?.value !== 'link') {
+ return false;
+ }
+ for (
+ let parent =
+ node.parentId != null ? byId.get(node.parentId) : undefined;
+ parent != null;
+ parent = parent.parentId != null ? byId.get(parent.parentId) : undefined
+ ) {
+ if (parent.nodeId === landmark.nodeId) {
+ return true;
+ }
+ }
+ return false;
+ }).length;
+ return {
+ dialogName: dialog.name?.value ?? '',
+ landmarks: landmarks.map(node => ({
+ name: node.name?.value ?? '',
+ links: linksIn(node),
+ })),
+ };
+}
+
+test.describe('MobileNav navigation landmark (Chromium)', () => {
+ test('a drawer of SideNav items exposes one navigation landmark named like the dialog', async ({
+ page,
+ }) => {
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=core-mobilenav--with-side-nav-children&viewMode=story`,
+ );
+ await page.getByRole('button', {name: 'Open Drawer'}).click();
+ await expect(page.getByRole('dialog')).toBeVisible();
+ const {dialogName, landmarks} = await drawerLandmarks(page);
+ expect(dialogName).toBe('My App');
+ expect(landmarks).toHaveLength(1);
+ expect(landmarks[0].name).toBe(dialogName);
+ expect(landmarks[0].links).toBeGreaterThan(0);
+ });
+
+ test("SideNav's drawer mode in an AppShell on a phone exposes one navigation landmark named like the dialog", async ({
+ page,
+ }) => {
+ await page.setViewportSize({width: 390, height: 844});
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=core-appshell--side-nav-only&viewMode=story`,
+ );
+ await page
+ .getByRole('button', {name: /navigation|menu/i})
+ .first()
+ .click();
+ await expect(page.getByRole('dialog')).toBeVisible();
+ const {dialogName, landmarks} = await drawerLandmarks(page);
+ expect(landmarks).toHaveLength(1);
+ expect(landmarks[0].name).toBe(dialogName);
+ expect(landmarks[0].links).toBeGreaterThan(0);
+ });
+
+ test("a TopNav's drawer content on a phone sits inside one navigation landmark named like the dialog", async ({
+ page,
+ }) => {
+ await page.setViewportSize({width: 390, height: 844});
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=core-appshell--top-nav-with-side-nav&viewMode=story`,
+ );
+ await page
+ .getByRole('button', {name: /navigation|menu/i})
+ .first()
+ .click();
+ await expect(page.getByRole('dialog')).toBeVisible();
+ const {dialogName, landmarks} = await drawerLandmarks(page);
+ expect(landmarks).toHaveLength(1);
+ expect(landmarks[0].name).toBe(dialogName);
+ expect(landmarks[0].links).toBeGreaterThan(0);
+ });
+});