Skip to content

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.md
new file mode 100644
index 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
+@bhamodi
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 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.tsx
index 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.tsx
index 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 ? (
<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),
@@ -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 */}
<a
href={`#${MAIN_CONTENT_ID}`}
+ onClick={handleSkipLinkClick}
{...stylex.props(styles.skipLink)}
data-testid="skip-to-content">
- Skip to content
+ {t('@astryx.appShell.skipToContent')}
</a>
<Layout