An open source design system that's fully customizable and agent ready
TypeScript
fix(core): focusable AppShell skip-link target, localized label, banner landmark (#4366)
Baraa Hamodi5ee8b272dee2
diff --git a/.changeset/a11y-appshell-skip-banner.md b/.changeset/a11y-appshell-skip-banner.mdnew file mode 100644index 0000000000..13039992cb--- /dev/null+++ b/.changeset/a11y-appshell-skip-banner.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] AppShell: make the skip-link target focusable (tabIndex={-1}), localize the skip-link label via the i18n catalog, and expose the header region as a banner landmark+@bhamodidiff --git a/packages/core/locales/en.json b/packages/core/locales/en.jsonindex a2d9f2092e..01280f9b71 100644--- a/packages/core/locales/en.json+++ b/packages/core/locales/en.json@@ -235,6 +235,10 @@"defaultMessage": "Mobile navigation","description": "Screen-reader-only accessible name for the mobile-only navigation region on small viewports. \"Mobile\" = phone/tablet (small screen), not \"movable\"."},+ "@astryx.appShell.skipToContent": {+ "defaultMessage": "Skip to content",+ "description": "Text of the skip link — the first focusable element on the page, visible only while keyboard-focused. Activating it jumps focus past the navigation to the main content area. Imperative verb; keep short."+ },"@astryx.avatar.nameWithStatus": {"defaultMessage": "{name}, {status}","description": "Screen-reader accessible name for an Avatar showing a status indicator; composes the person's name with the status label, e.g. \"Jane Doe, Online\". {name} = the avatar's name/alt text, {status} = the status dot's label. Adjust separator and order per locale."diff --git a/packages/core/src/AppShell/AppShell.test.tsx b/packages/core/src/AppShell/AppShell.test.tsxindex a9c66cbc5d..1178746d1e 100644--- a/packages/core/src/AppShell/AppShell.test.tsx+++ b/packages/core/src/AppShell/AppShell.test.tsx@@ -20,6 +20,7 @@ import {} from 'vitest';import {render, screen, fireEvent} from '@testing-library/react';import {AppShell} from './AppShell';+import {InternationalizationProvider} from '../i18n';import {MobileNav} from '../MobileNav';import {SideNav, SideNavItem, SideNavSection} from '../SideNav';import {TopNav, TopNavHeading, TopNavItem} from '../TopNav';@@ -205,6 +206,60 @@ describe('AppShell', () => {expect(main).toHaveAttribute('id', 'astryx-app-shell-main');});+ it('moves focus to the main content when the skip link is activated', () => {+ render(+ <AppShell>+ <div>Content</div>+ </AppShell>,+ );+ const skipLink = screen.getByTestId('skip-to-content');+ const main = screen.getByRole('main');+ // The target must be programmatically focusable for focus to move+ expect(main).toHaveAttribute('tabindex', '-1');+ fireEvent.click(skipLink);+ expect(document.activeElement).toBe(main);+ });++ it('skip link text comes from the i18n catalog', () => {+ render(+ <InternationalizationProvider+ locale="en"+ overrides={{en: {'@astryx.appShell.skipToContent': 'Jump to main'}}}>+ <AppShell>+ <div>Content</div>+ </AppShell>+ </InternationalizationProvider>,+ );+ expect(screen.getByTestId('skip-to-content').textContent).toBe(+ 'Jump to main',+ );+ });++ // ===========================================================================+ // Banner landmark+ // ===========================================================================++ it('exposes the header region as a banner landmark', () => {+ render(+ <AppShell topNav={<div>Top Nav</div>}>+ <div>Content</div>+ </AppShell>,+ );+ const banner = screen.getByRole('banner');+ expect(banner).toBeInTheDocument();+ // banner must be top-level — not nested inside another landmark+ expect(screen.getByRole('main')).not.toContainElement(banner);+ });++ it('does not render a banner landmark without header content', () => {+ render(+ <AppShell>+ <div>Content</div>+ </AppShell>,+ );+ expect(screen.queryByRole('banner')).not.toBeInTheDocument();+ });+// ===========================================================================// SideNav accessibility// ===========================================================================diff --git a/packages/core/src/AppShell/AppShell.tsx b/packages/core/src/AppShell/AppShell.tsxindex 1799a7ce2c..e435c95a9a 100644--- a/packages/core/src/AppShell/AppShell.tsx+++ b/packages/core/src/AppShell/AppShell.tsx@@ -341,6 +341,15 @@ const styles = stylex.create({fontWeight: fontWeightVars['--font-weight-semibold'],fontSize: typeScaleVars['--text-body-size'],},+ // Programmatic focus target for the skip link. The main container is only+ // focusable via tabIndex={-1} (never tabbable), so a focus ring around the+ // entire content area would be noise rather than guidance — suppress it.+ mainFocusTarget: {+ outline: {+ default: null,+ ':focus': 'none',+ },+ },elevatedBackdrop: {position: 'absolute',@@ -513,6 +522,13 @@ export function AppShell({[mobileNavIsControlled, mobileNavConfig],);+ // Move focus to the main content container when the skip link is activated.+ // Hash navigation alone doesn't reliably move focus in every browser, so+ // focus the target explicitly (it's focusable via tabIndex={-1}).+ const handleSkipLinkClick = useCallback(() => {+ document.getElementById(MAIN_CONTENT_ID)?.focus();+ }, []);+const isFill = height === 'fill';const isAuto = height === 'auto';@@ -657,6 +673,9 @@ export function AppShell({headerInner != null ? (<divref={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),@@ -705,8 +724,11 @@ export function AppShell({padding={contentPadding ?? 0}role="main"id={MAIN_CONTENT_ID}+ // Focusable skip-link target (WCAG 2.4.1) — without tabIndex, several+ // browsers won't move focus to the div when the skip link is activated.+ tabIndex={-1}isScrollable={isFill}- xstyle={contentAreaStyle}>+ xstyle={[contentAreaStyle, styles.mainFocusTarget]}>{children}</LayoutContent>);@@ -782,9 +804,10 @@ export function AppShell({{/* Skip-to-content link */}<ahref={`#${MAIN_CONTENT_ID}`}+ onClick={handleSkipLinkClick}{...stylex.props(styles.skipLink)}data-testid="skip-to-content">- Skip to content+ {t('@astryx.appShell.skipToContent')}</a><Layout