@astryxdesign/core 0.3.0 → 0.4.0-canary.058f476

package/src/AlertDialog/AlertDialog.test.tsx

@@ -10,8 +10,10 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {AlertDialog} from './AlertDialog';
+import {useImperativeAlertDialog} from './useImperativeAlertDialog';
 
 beforeEach(() => {
   HTMLDialogElement.prototype.showModal = vi.fn(function (
@@ -111,4 +113,209 @@ describe('AlertDialog', () => {
     render(<AlertDialog {...defaultProps} />);
     expect(screen.getByText('Cancel')).toBeInTheDocument();
   });
+
+  describe('keyboard', () => {
+    it('calls onOpenChange(false) on Escape', async () => {
+      const onOpenChange = vi.fn();
+      render(<AlertDialog {...defaultProps} onOpenChange={onOpenChange} />);
+      fireEvent.keyDown(screen.getByRole('alertdialog'), {key: 'Escape'});
+      await waitFor(() => expect(onOpenChange).toHaveBeenCalledWith(false));
+    });
+
+    it('does not call onAction on Escape', () => {
+      const onAction = vi.fn();
+      render(<AlertDialog {...defaultProps} onAction={onAction} />);
+      fireEvent.keyDown(screen.getByRole('alertdialog'), {key: 'Escape'});
+      expect(onAction).not.toHaveBeenCalled();
+    });
+
+    it('activates cancel with Enter', async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+      render(<AlertDialog {...defaultProps} onOpenChange={onOpenChange} />);
+      screen.getByRole('button', {name: 'Cancel'}).focus();
+      await user.keyboard('{Enter}');
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+
+    it('activates the action button with Space', async () => {
+      const user = userEvent.setup();
+      const onAction = vi.fn();
+      render(<AlertDialog {...defaultProps} onAction={onAction} />);
+      screen.getByRole('button', {name: 'Delete'}).focus();
+      await user.keyboard(' ');
+      expect(onAction).toHaveBeenCalled();
+    });
+
+    it('reaches both buttons by Tab, cancel first', async () => {
+      const user = userEvent.setup();
+      render(<AlertDialog {...defaultProps} />);
+      const cancel = screen.getByRole('button', {name: 'Cancel'});
+      const action = screen.getByRole('button', {name: 'Delete'});
+      cancel.focus();
+      expect(cancel).toHaveFocus();
+      await user.tab();
+      expect(action).toHaveFocus();
+    });
+  });
+
+  describe('focus', () => {
+    it('marks cancel as the initial focus target', () => {
+      render(<AlertDialog {...defaultProps} />);
+      // Dialog focuses [data-autofocus] itself after showModal(), so the
+      // contract this component owns is which element carries the attribute.
+      expect(screen.getByRole('button', {name: 'Cancel'})).toHaveAttribute(
+        'data-autofocus',
+      );
+      expect(screen.getByRole('button', {name: 'Delete'})).not.toHaveAttribute(
+        'data-autofocus',
+      );
+    });
+
+    it('keeps the initial focus target on the least destructive action', () => {
+      render(<AlertDialog {...defaultProps} cancelLabel="Never mind" />);
+      expect(screen.getByRole('button', {name: 'Never mind'})).toHaveAttribute(
+        'data-autofocus',
+      );
+    });
+
+    it('returns focus to the trigger when it closes', async () => {
+      const trigger = document.createElement('button');
+      trigger.textContent = 'Open';
+      document.body.appendChild(trigger);
+      trigger.focus();
+
+      const {rerender} = render(<AlertDialog {...defaultProps} />);
+      rerender(<AlertDialog {...defaultProps} isOpen={false} />);
+
+      await waitFor(() => expect(trigger).toHaveFocus());
+      trigger.remove();
+    });
+
+    it('does not disable the cancel button while the action is loading', () => {
+      render(<AlertDialog {...defaultProps} isActionLoading />);
+      expect(screen.getByRole('button', {name: 'Cancel'})).toBeEnabled();
+    });
+  });
+
+  describe('aria', () => {
+    it('marks the action button busy while loading', () => {
+      render(<AlertDialog {...defaultProps} isActionLoading />);
+      expect(screen.getByRole('button', {name: /Delete/})).toHaveAttribute(
+        'aria-busy',
+        'true',
+      );
+    });
+
+    it('is a modal alertdialog', () => {
+      render(<AlertDialog {...defaultProps} />);
+      expect(screen.getByRole('alertdialog')).toHaveAttribute(
+        'aria-modal',
+        'true',
+      );
+    });
+
+    describe('the inline preview path', () => {
+      it('does not claim the alertdialog role', () => {
+        render(<AlertDialog {...defaultProps} isInline />);
+        expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+      });
+
+      it('exposes a named group instead, with no aria-modal', () => {
+        render(<AlertDialog {...defaultProps} isInline />);
+        const group = screen.getByRole('group', {name: 'Delete item?'});
+        expect(group).not.toHaveAttribute('aria-modal');
+        const describedBy = group.getAttribute('aria-describedby');
+        expect(describedBy).toBeTruthy();
+        expect(document.getElementById(describedBy!)).toHaveTextContent(
+          'This action cannot be undone.',
+        );
+      });
+    });
+  });
+});
+
+describe('useImperativeAlertDialog', () => {
+  const noop = () => {};
+
+  function Harness({onAction = noop}: {onAction?: () => unknown}) {
+    const alert = useImperativeAlertDialog();
+    return (
+      <>
+        <button
+          type="button"
+          onClick={() =>
+            alert.show({
+              title: 'Delete item?',
+              description: 'This action cannot be undone.',
+              actionLabel: 'Delete',
+              onAction,
+            })
+          }>
+          Open
+        </button>
+        <button type="button" onClick={alert.hide}>
+          Close it
+        </button>
+        <span data-testid="is-open">{String(alert.isOpen)}</span>
+        {alert.element}
+      </>
+    );
+  }
+
+  it('renders nothing until show is called', () => {
+    render(<Harness />);
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('false');
+  });
+
+  it('shows the dialog with the given options', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument();
+    expect(screen.getByText('Delete item?')).toBeInTheDocument();
+    expect(
+      screen.getByText('This action cannot be undone.'),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('true');
+  });
+
+  it('hides on hide()', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Close it'}));
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('false');
+  });
+
+  it('closes when the dialog cancels', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Cancel'}));
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('false');
+  });
+
+  it('forwards onAction and leaves closing to the caller', async () => {
+    const user = userEvent.setup();
+    const onAction = vi.fn();
+    render(<Harness onAction={onAction} />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Delete'}));
+    expect(onAction).toHaveBeenCalledTimes(1);
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument();
+  });
+
+  it('can be shown again after being hidden', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Close it'}));
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('true');
+  });
 });

package/src/AlertDialog/AlertDialog.tsx

@@ -39,7 +39,8 @@ export interface AlertDialogProps extends BaseProps<HTMLDialogElement> {
 
   /**
    * Renders alert dialog content inline without modal behavior.
-   * For documentation previews and showcases only.
+   * For documentation previews and showcases only. The inline path is not a
+   * modal, so it renders `role="group"` rather than `role="alertdialog"`.
    * @default false
    */
   isInline?: boolean;
@@ -100,9 +101,16 @@ export interface AlertDialogProps extends BaseProps<HTMLDialogElement> {
 /**
  * A confirmation dialog for destructive or irreversible actions.
  *
+ * Implements the WAI-ARIA APG Alert Dialog pattern:
+ * https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/
+ *
  * Uses `role="alertdialog"` and requires explicit user action to dismiss.
  * Cannot be dismissed by clicking outside. Escape key triggers cancel.
- * Initial focus goes to the cancel button (least destructive action).
+ * Initial focus goes to the cancel button (least destructive action), pinned
+ * with `data-autofocus` so it survives any change to the footer's order.
+ *
+ * The `isInline` preview path is not modal, so it renders `role="group"`
+ * instead — the alertdialog role would promise modality it does not have.
  *
  * @example
  * ```
@@ -153,7 +161,12 @@ export function AlertDialog({
       onOpenChange={onOpenChange}
       width={width}
       purpose="form"
-      role="alertdialog"
+      // `alertdialog` is a modal role: it promises an interruption the user
+      // has to deal with, a focus trap, and an inert page behind it. The
+      // inline path renders a plain always-present div with none of that, so
+      // the role would misdescribe it. `group` keeps the title and
+      // description associated with a container without claiming a dialog.
+      role={isInline ? 'group' : 'alertdialog'}
       aria-labelledby={titleId}
       aria-describedby={descriptionId}
       {...mergeProps(themeProps('alert-dialog'), {className, style})}
@@ -177,6 +190,11 @@ export function AlertDialog({
                 variant="ghost"
                 label={cancelLabel}
                 onClick={handleCancel}
+                // Dialog focuses [data-autofocus] itself after showModal(),
+                // because React's autoFocus runs during commit while the
+                // dialog is still invisible. Cancel is the least destructive
+                // choice, so it is the one that should be preselected.
+                data-autofocus
               />
               <Button
                 variant={actionVariant}

package/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: [
@@ -192,8 +203,11 @@ export const docsDense = {
     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: TopNav and SideNav are separate navigation landmarks, so pass `label` to each.'},
+      {guidance: true, description: 'Start the page heading inside `children`: AppShell owns the skip link, banner, and main landmarks but renders no heading, so the first content heading 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>; AppShell renders both, and a second main landmark makes the first ambiguous.'},
     ],
   },
   propDescriptions: {

package/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);
+  });
 });

package/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>

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -9,13 +9,21 @@ export const docs = {
   keywords: ["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],
   usage: {
     description:
-      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+      'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
+      {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
+      {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+      {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
+      {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},
+    ],
+    anatomy: [
+      {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},
+      {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},
     ],
   },
   props: [
@@ -68,13 +76,21 @@ export const docsZh = {
   displayName: 'Aspect Ratio',
   usage: {
     description:
-      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+      'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
+      {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
+      {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+      {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
+      {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},
+    ],
+    anatomy: [
+      {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},
+      {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},
     ],
   },
   props: [
@@ -110,13 +126,21 @@ export const docsDense = {
   description: 'maintains specific aspect ratio for children',
   usage: {
     description:
-      'Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.',
+      'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
+      {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
+      {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
+      {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
+      {guidance: false, description: 'Place it in a shrink-to-fit parent such as `inline-flex`, `width: fit-content` or a floated box. It contributes no intrinsic width there and collapses to zero.'},
+    ],
+    anatomy: [
+      {name: 'Ratio box', required: true, description: 'The outer element that holds the aspect ratio and clips overflow. Carries the `astryx-aspect-ratio` theme target, and the elliptical clip when `shape` is `ellipse`.'},
+      {name: 'Content slot', required: true, description: 'A wrapper that fills the ratio box and positions the child. With `fit` set it also sizes the child; without it the child styles itself.'},
     ],
   },
   propDescriptions: {