Skip to content

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

TypeScript

fix(core): AppShell audit: banner landmark on mobile, shared skip-link focus ring, corrected mobileNav doc examples (#4944)

Cindy Zhangd1441a63d7d1
diff --git a/.changeset/appshell-doc-example-mobilenav-header.md b/.changeset/appshell-doc-example-mobilenav-header.md
new file mode 100644
index 0000000000..083de8eb25
--- /dev/null
+++ b/.changeset/appshell-doc-example-mobilenav-header.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] AppShell: the two worked examples of the `mobileNav` escape hatch passed `title` to `MobileNav`, which does not accept it: `MobileNavProps` omits the native `title` attribute and the drawer heading prop is `header`. Copying either example produced a type error and a drawer with no heading. Both now say `header`. The doc also gains an anatomy list and accessibility guidance covering the landmark structure AppShell owns.
+
+@cixzhang
diff --git a/.changeset/appshell-mobile-banner-landmark.md b/.changeset/appshell-mobile-banner-landmark.md
new file mode 100644
index 0000000000..59fde20c51
--- /dev/null
+++ b/.changeset/appshell-mobile-banner-landmark.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] AppShell: the mobile top bar rendered for a sidenav-only layout is now a `banner` landmark, matching the header region of a layout that has a `topNav`. Previously the page's landmark structure changed depending on which nav slots it filled: a screen-reader user on a small viewport got no banner region at all. When a `banner` slot is present the existing header keeps the role, so there is still exactly one.
+
+@cixzhang
diff --git a/.changeset/appshell-skip-link-focus-ring.md b/.changeset/appshell-skip-link-focus-ring.md
new file mode 100644
index 0000000000..d51ebe248f
--- /dev/null
+++ b/.changeset/appshell-skip-link-focus-ring.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] AppShell: the skip link now draws the shared Astryx focus ring instead of the browser default outline, so it follows `--color-accent` and matches every other focusable surface in a custom theme.
+
+@cixzhang
diff --git a/.github/a11y-baseline.json b/.github/a11y-baseline.json
index 735d5121f2..e3ebd4ad2e 100644
--- a/.github/a11y-baseline.json
+++ b/.github/a11y-baseline.json
@@ -3,51 +3,6 @@
"version": 1,
"generatedAt": "2026-07-31T09:21:12.717Z",
"entries": [
- {
- "key": "AppShell::Auto Height::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "AppShell::Controlled Collapse::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "AppShell::Full Featured::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "AppShell::Playground::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "AppShell::Side Nav Only::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "AppShell::Top Nav Only::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "AppShell::Top Nav With Side Nav::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "AppShell::With Banner::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
- {
- "key": "AppShell::With Mobile Nav::color-contrast",
- "impact": "serious",
- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"
- },
{
"key": "Avatar::Default::color-contrast",
"impact": "serious",
diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjs
index 4f5d961eea..2e207a42d5 100644
--- a/packages/core/src/AppShell/AppShell.doc.mjs
+++ b/packages/core/src/AppShell/AppShell.doc.mjs
@@ -14,8 +14,19 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Choose the right height: use "fill" for dashboards with internal scrolling and "auto" for pages that grow with content.'},
{guidance: true, description: 'Set `contentPadding` based on content type: 4 for forms and settings, 0 for tables and dashboards.'},
+ {guidance: true, description: 'Give every nav slot an accessible name. AppShell renders TopNav and SideNav as separate navigation landmarks, and a screen reader lists them by name, so pass `label` to each one.'},
+ {guidance: true, description: 'Start the page heading inside `children`. AppShell owns the skip link, the banner landmark and the main landmark, but it renders no heading, so the first heading in the content area is the page h1.'},
{guidance: false, description: "Nest one AppShell inside another; it's the outermost layout frame."},
{guidance: false, description: 'Use for sub-page layouts; use Layout for content areas within AppShell.'},
+ {guidance: false, description: 'Add your own skip link or <main> element. AppShell already renders both, and a second main landmark makes the first ambiguous.'},
+ ],
+ anatomy: [
+ {name: 'Skip link', required: true, description: 'First focusable element on the page. Visually hidden until focused, then moves focus to the main content area.'},
+ {name: 'Banner', required: false, description: 'The banner slot, for system-wide announcements. Renders above the top nav, inside the banner landmark.'},
+ {name: 'Top navigation', required: false, description: 'The topNav slot, typically TopNav. Below the mobile breakpoint it becomes a compact bar carrying the nav toggle.'},
+ {name: 'Side navigation', required: false, description: 'The sideNav slot, typically SideNav. Inline above the breakpoint, moved into the mobile drawer below it.'},
+ {name: 'Main content', required: true, description: 'children, rendered in the main landmark. Scrolls internally when height is fill, and with the page when it is auto.'},
+ {name: 'Mobile nav drawer', required: false, description: 'Generated below the breakpoint from the nav slots unless mobileNav disables or replaces it. A modal dialog: it traps focus and returns focus to the toggle on close.'},
],
},
props: [
diff --git a/packages/core/src/AppShell/AppShell.test.tsx b/packages/core/src/AppShell/AppShell.test.tsx
index 1178746d1e..49a9bf6864 100644
--- a/packages/core/src/AppShell/AppShell.test.tsx
+++ b/packages/core/src/AppShell/AppShell.test.tsx
@@ -19,11 +19,13 @@ import {
afterEach,
} from 'vitest';
import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
import {AppShell} from './AppShell';
import {InternationalizationProvider} from '../i18n';
import {MobileNav} from '../MobileNav';
import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
import {TopNav, TopNavHeading, TopNavItem} from '../TopNav';
+import {useAppShellMobile} from './AppShellMobileContext';
// jsdom doesn't implement showModal/close on <dialog>, so we mock them
beforeAll(() => {
@@ -778,4 +780,141 @@ describe('AppShell', () => {
expect(ref).toHaveBeenCalled();
expect(ref.mock.calls[0][0]).toBe(screen.getByTestId('shell'));
});
+ // ===========================================================================
+ // Keyboard operation
+ //
+ // The focus TRAP and focus RESTORE contracts of the drawer are native
+ // <dialog> behaviour and cannot be asserted here: jsdom has no dialog
+ // implementation, so this file shims showModal()/close() with an `open`
+ // attribute. Those two were verified in Chromium instead. What is asserted
+ // here is everything the shim can still prove: the keyboard path to each
+ // control, and the ARIA wiring between the toggle and the drawer.
+ // ===========================================================================
+
+ it('reaches the skip link with Tab and moves focus to main with Enter', async () => {
+ const user = userEvent.setup();
+ render(
+ <AppShell topNav={<TopNav label="Main navigation" />}>
+ <div>Content</div>
+ </AppShell>,
+ );
+
+ await user.tab();
+ const skipLink = screen.getByTestId('skip-to-content');
+ expect(skipLink).toHaveFocus();
+
+ await user.keyboard('{Enter}');
+ expect(screen.getByRole('main')).toHaveFocus();
+ });
+
+ it('opens the mobile drawer from the keyboard and points the toggle at it', async () => {
+ mockMql = createMockMatchMedia(true);
+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+ const user = userEvent.setup();
+
+ render(
+ <AppShell sideNav={<TestSideNav />}>
+ <div>Content</div>
+ </AppShell>,
+ );
+
+ const toggle = screen.getByRole('button', {name: 'Open navigation'});
+ expect(toggle).toHaveAttribute('aria-expanded', 'false');
+
+ toggle.focus();
+ await user.keyboard('{Enter}');
+
+ expect(toggle).toHaveAttribute('aria-expanded', 'true');
+ const drawer = screen.getByRole('dialog', {hidden: true});
+ // aria-controls has to name the drawer that actually opened, or a screen
+ // reader cannot follow the toggle to it.
+ expect(toggle.getAttribute('aria-controls')).toBe(drawer.id);
+ expect(drawer.id).toBeTruthy();
+ });
+
+ // ===========================================================================
+ // Banner landmark on the mobile top bar
+ // ===========================================================================
+
+ it('exposes the mobile top bar as a banner landmark in a sidenav-only layout', () => {
+ mockMql = createMockMatchMedia(true);
+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+
+ render(
+ <AppShell sideNav={<TestSideNav />}>
+ <div>Content</div>
+ </AppShell>,
+ );
+
+ // Same landmark structure as the topNav layout: one banner region holding
+ // the top bar, whichever nav slots the page happens to fill.
+ expect(screen.getByRole('banner')).toBeInTheDocument();
+ });
+
+ it('renders exactly one banner landmark when a banner slot joins the mobile top bar', () => {
+ mockMql = createMockMatchMedia(true);
+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+
+ render(
+ <AppShell banner={<div>Announcement</div>} sideNav={<TestSideNav />}>
+ <div>Content</div>
+ </AppShell>,
+ );
+
+ expect(screen.getAllByRole('banner')).toHaveLength(1);
+ });
+
+ // ===========================================================================
+ // useAppShellMobile
+ // ===========================================================================
+
+ function MobileProbe() {
+ const {isMobile, isMobileNavOpen, isMobileNavEnabled, mobileNavId} =
+ useAppShellMobile();
+ return (
+ <span data-testid="probe">
+ {JSON.stringify({
+ isMobile,
+ isMobileNavOpen,
+ isMobileNavEnabled,
+ hasId: mobileNavId != null,
+ })}
+ </span>
+ );
+ }
+
+ it('useAppShellMobile is inert outside an AppShell', () => {
+ render(<MobileProbe />);
+ expect(JSON.parse(screen.getByTestId('probe').textContent)).toEqual({
+ isMobile: false,
+ isMobileNavOpen: false,
+ isMobileNavEnabled: false,
+ hasId: false,
+ });
+ });
+
+ it('useAppShellMobile reports the shell mobile state and drawer id', async () => {
+ mockMql = createMockMatchMedia(true);
+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+ const user = userEvent.setup();
+
+ render(
+ <AppShell sideNav={<TestSideNav />}>
+ <MobileProbe />
+ </AppShell>,
+ );
+
+ expect(JSON.parse(screen.getByTestId('probe').textContent)).toEqual({
+ isMobile: true,
+ isMobileNavOpen: false,
+ isMobileNavEnabled: true,
+ hasId: true,
+ });
+
+ await user.click(screen.getByRole('button', {name: 'Open navigation'}));
+
+ expect(
+ JSON.parse(screen.getByTestId('probe').textContent).isMobileNavOpen,
+ ).toBe(true);
+ });
});
diff --git a/packages/core/src/AppShell/AppShell.tsx b/packages/core/src/AppShell/AppShell.tsx
index e435c95a9a..45c7d64aea 100644
--- a/packages/core/src/AppShell/AppShell.tsx
+++ b/packages/core/src/AppShell/AppShell.tsx
@@ -51,6 +51,7 @@ import type {AppShellMobileContextValue} from './AppShellMobileContext';
import type {SpacingStep} from '../utils/types';
import type {BaseProps} from '../BaseProps';
import {mergeProps, mergeRefs, isRenderable} from '../utils';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {useMediaQuery} from '../hooks/useMediaQuery';
import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
import {themeProps} from '../utils/themeProps';
@@ -217,7 +218,7 @@ export interface AppShellProps extends BaseProps<HTMLDivElement> {
* <AppShell mobileNav={{ hasToggle: false }}>
* <MobileNavToggle />
* </AppShell>
- * <AppShell mobileNav={<MobileNav title="Menu">...</MobileNav>} />
+ * <AppShell mobileNav={<MobileNav header="Menu">...</MobileNav>} />
* <AppShell mobileNav={false} />
* ```
*/
@@ -409,8 +410,8 @@ const styles = stylex.create({
flexShrink: 0,
overflow: 'clip',
position: 'sticky',
- top: 'var(--appshell-header-height, 0px)',
- height: 'calc(100dvh - var(--appshell-header-height, 0px))',
+ top: 'var(--_app-shell-header-height, 0px)',
+ height: 'calc(100dvh - var(--_app-shell-header-height, 0px))',
// Ensure children (LayoutPanel → SideNav) fill the sticky container
display: 'flex',
flexDirection: 'column',
@@ -441,7 +442,7 @@ const styles = stylex.create({
* topNav={<TopNav label="Navigation" heading={<TopNavHeading heading="My App" />} />}
* sideNav={<SideNav>{navSections}</SideNav>}
* mobileNav={
- * <MobileNav isOpen={mobileOpen} onOpenChange={(open) => setMobileOpen(open)} title="My App">
+ * <MobileNav isOpen={mobileOpen} onOpenChange={(open) => setMobileOpen(open)} header="My App">
* {navSections}
* </MobileNav>
* }>
@@ -512,14 +513,19 @@ export function AppShell({
const [uncontrolledMobileOpen, setUncontrolledMobileOpen] = useState(false);
const isMobileNavOpen = mobileNavConfig?.isOpen ?? uncontrolledMobileOpen;
+ const mobileNavOnOpenChange = mobileNavConfig?.onOpenChange;
const setMobileNavOpen = useCallback(
(open: boolean) => {
if (!mobileNavIsControlled) {
setUncontrolledMobileOpen(open);
}
- mobileNavConfig?.onOpenChange?.(open);
+ mobileNavOnOpenChange?.(open);
},
- [mobileNavIsControlled, mobileNavConfig],
+ // Depend on the callback itself, not on the config object: the documented
+ // usage is an inline `mobileNav={{isOpen, onOpenChange}}` literal, which is
+ // a new object every render and would otherwise churn this callback and the
+ // context value memo built from it on every render of the shell.
+ [mobileNavIsControlled, mobileNavOnOpenChange],
);
// Move focus to the main content container when the skip link is activated.
@@ -577,7 +583,7 @@ export function AppShell({
const updateHeight = () => {
const height = headerEl.getBoundingClientRect().height;
- shellEl.style.setProperty('--appshell-header-height', `${height}px`);
+ shellEl.style.setProperty('--_app-shell-header-height', `${height}px`);
};
observeResize(headerEl, () => updateHeight());
@@ -669,20 +675,19 @@ export function AppShell({
</LayoutHeader>
) : undefined;
- const headerContent =
- headerInner != null ? (
- <div
- ref={headerRef}
- // Top-level banner landmark for the header region (topNav + banner).
- // Safe here: the wrapper is never nested inside main/nav/other landmarks.
- role="banner"
- {...mergeProps(
- themeProps('app-shell-header', {variant}),
- stylex.props(navAreaStyle, isAuto && styles.headerSticky),
- )}>
- {headerInner}
- </div>
- ) : undefined;
+ const headerContent = isRenderable(headerInner) ? (
+ <div
+ ref={headerRef}
+ // Top-level banner landmark for the header region (topNav + banner).
+ // Safe here: the wrapper is never nested inside main/nav/other landmarks.
+ role="banner"
+ {...mergeProps(
+ themeProps('app-shell-header', {variant}),
+ stylex.props(navAreaStyle, isAuto && styles.headerSticky),
+ )}>
+ {headerInner}
+ </div>
+ ) : undefined;
// =========================================================================
// Build sideNav content
@@ -760,6 +765,11 @@ export function AppShell({
const autoMobileTopBar =
shouldShowAutoToggle && !hasTopNav && hasSideNav ? (
<div
+ // Banner landmark for the mobile top bar, so the sidenav-only layout
+ // exposes the same landmark structure as the topNav one. Only when
+ // there is no headerContent: a banner slot with no topNav renders both,
+ // and two sibling banner regions is worse than the one this restores.
+ role={headerContent == null ? 'banner' : undefined}
{...mergeProps(
themeProps('app-shell-header', {variant}),
stylex.props(navAreaStyle, isAuto && styles.headerSticky),
@@ -805,7 +815,7 @@ export function AppShell({
<a
href={`#${MAIN_CONTENT_ID}`}
onClick={handleSkipLinkClick}
- {...stylex.props(styles.skipLink)}
+ {...focusOutlineProps.focusVisible(styles.skipLink)}
data-testid="skip-to-content">
{t('@astryx.appShell.skipToContent')}
</a>