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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/.changeset/appshell-mobile-banner-landmark.md b/.changeset/appshell-mobile-banner-landmark.mdnew file mode 100644index 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.++@cixzhangdiff --git a/.changeset/appshell-skip-link-focus-ring.md b/.changeset/appshell-skip-link-focus-ring.mdnew file mode 100644index 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.++@cixzhangdiff --git a/.github/a11y-baseline.json b/.github/a11y-baseline.jsonindex 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.mjsindex 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.tsxindex 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 thembeforeAll(() => {@@ -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.tsxindex 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 containerdisplay: '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({<ahref={`#${MAIN_CONTENT_ID}`}onClick={handleSkipLinkClick}- {...stylex.props(styles.skipLink)}+ {...focusOutlineProps.focusVisible(styles.skipLink)}data-testid="skip-to-content">{t('@astryx.appShell.skipToContent')}</a>