@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/locales/zh-CN.json

@@ -635,26 +635,6 @@
     "defaultMessage": "清除排序",
     "description": "Screen-reader-only label on a column header button that will remove the current sort. \"Clear\" here means remove, not transparent. Part of the sort set."
   },
-  "@astryx.table.sort.direction.ascending": {
-    "defaultMessage": "升序",
-    "description": "Localized direction word interpolated as `direction` into @astryx.table.sort.sortedBy and @astryx.table.sort.sortedByWithPriority."
-  },
-  "@astryx.table.sort.direction.descending": {
-    "defaultMessage": "降序",
-    "description": "Localized direction word interpolated as `direction` into @astryx.table.sort.sortedBy and @astryx.table.sort.sortedByWithPriority."
-  },
-  "@astryx.table.sort.sortBy": {
-    "defaultMessage": "按 {label} 排序",
-    "description": "Aria label for a sortable Table header button when the column is unsorted. `label` is the column header text."
-  },
-  "@astryx.table.sort.sortedBy": {
-    "defaultMessage": "按 {label} 排序，{direction}",
-    "description": "Aria label for a sorted Table header button. `direction` is the localized direction word from @astryx.table.sort.direction.*."
-  },
-  "@astryx.table.sort.sortedByWithPriority": {
-    "defaultMessage": "按 {label} 排序，{direction}，优先级 {rank, number}/{total, number}",
-    "description": "Aria label for a sorted Table header button in multi-sort. `rank` is the 1-based position of this column in the sort order; `total` is the number of sorted columns."
-  },
   "@astryx.toast.dismiss": {
     "defaultMessage": "关闭通知",
     "description": "Screen-reader-only label on the X button of a Toast (transient notification popup). Distinct from `banner.dismiss` (persistent banner)."
@@ -1480,4 +1460,3 @@
     "description": "Default summary on the closed trigger of a lab TransferListSelector, stating how many options are currently chosen. Consumers usually override this with a domain phrase (e.g. \"7 columns\")."
   }
 }
-

package/locales/zh-TW.json

@@ -635,26 +635,6 @@
     "defaultMessage": "清除排序",
     "description": "Screen-reader-only label on a column header button that will remove the current sort. \"Clear\" here means remove, not transparent. Part of the sort set."
   },
-  "@astryx.table.sort.direction.ascending": {
-    "defaultMessage": "遞增",
-    "description": "Localized direction word interpolated as `direction` into @astryx.table.sort.sortedBy and @astryx.table.sort.sortedByWithPriority."
-  },
-  "@astryx.table.sort.direction.descending": {
-    "defaultMessage": "遞減",
-    "description": "Localized direction word interpolated as `direction` into @astryx.table.sort.sortedBy and @astryx.table.sort.sortedByWithPriority."
-  },
-  "@astryx.table.sort.sortBy": {
-    "defaultMessage": "依 {label} 排序",
-    "description": "Aria label for a sortable Table header button when the column is unsorted. `label` is the column header text."
-  },
-  "@astryx.table.sort.sortedBy": {
-    "defaultMessage": "依 {label} 排序，{direction}",
-    "description": "Aria label for a sorted Table header button. `direction` is the localized direction word from @astryx.table.sort.direction.*."
-  },
-  "@astryx.table.sort.sortedByWithPriority": {
-    "defaultMessage": "依 {label} 排序，{direction}，優先順序 {rank, number}/{total, number}",
-    "description": "Aria label for a sorted Table header button in multi-sort. `rank` is the 1-based position of this column in the sort order; `total` is the number of sorted columns."
-  },
   "@astryx.toast.dismiss": {
     "defaultMessage": "關閉通知",
     "description": "Screen-reader-only label on the X button of a Toast (transient notification popup). Distinct from `banner.dismiss` (persistent banner)."
@@ -1480,4 +1460,3 @@
     "description": "Default summary on the closed trigger of a lab TransferListSelector, stating how many options are currently chosen. Consumers usually override this with a domain phrase (e.g. \"7 columns\")."
   }
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.5",
+  "version": "0.7.6-canary.0bd3b37",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -839,7 +839,20 @@
     "docs.mjs",
     "groups.doc.mjs",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "!**/*.test.*",
+    "!**/*.spec.js",
+    "!**/*.spec.jsx",
+    "!**/*.spec.mjs",
+    "!**/*.spec.cjs",
+    "!**/*.spec.ts",
+    "!**/*.spec.tsx",
+    "!**/*.spec.mts",
+    "!**/*.spec.cts",
+    "!**/*.spec.d.ts",
+    "!**/__tests__/**",
+    "!**/__mocks__/**",
+    "!**/*.bench.*"
   ],
   "peerDependencies": {
     "@stylexjs/stylex": "^0.19.0",
@@ -847,6 +860,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.6-canary.0bd3b37",
+    "@astryxdesign/cli": "0.7.6-canary.0bd3b37",
+    "@astryxdesign/interaction-harness": "0.7.6-canary.0bd3b37",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -857,9 +873,7 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2",
-    "@astryxdesign/cli": "0.7.5",
-    "@astryxdesign/a11y-spec": "0.0.0"
+    "tailwindcss": "^4.3.2"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AlertDialog/AlertDialog.tsx

@@ -18,18 +18,19 @@
 
 import React, {useId, useCallback} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Dialog} from '../Dialog';
+import {Dialog} from '../Dialog/Dialog';
 import {Layout} from '../Layout/Layout';
 import {LayoutContent} from '../Layout/LayoutContent';
 import {LayoutFooter} from '../Layout/LayoutFooter';
-import {Stack} from '../Stack';
+import {Stack} from '../Stack/Stack';
 import {Heading} from '../Heading/Heading';
 import {Text} from '../Text/Text';
-import {Button, type ButtonVariant} from '../Button';
+import {Button} from '../Button/Button';
+import type {ButtonVariant} from '../Button';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
-import {useTranslator} from '../i18n';
+import {useTranslator} from '../i18n/useTranslator';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 
 const SMALL_SCREEN_QUERY = '(max-width: 640px)';

package/src/AppShell/AppShell.doc.mjs

@@ -96,7 +96,7 @@ export const docs = {
         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.',
+          'children, rendered in the main landmark. Scrolls internally when height is fill, and with the page when it is auto. While it scrolls content that overflows, it is a stop in the tab order; Tab entry moves on when its first focusable element is a plain link or button, and otherwise main is one stop before it.',
       },
       {
         name: 'Mobile nav drawer',

package/src/AppShell/AppShell.spec.md

@@ -36,7 +36,7 @@ system_specs: [spec:AST-012, spec:AST-027]
 | Behavior                | One page frame: skip link, then a header region, an inline side region, and one `main` region. Below the mobile breakpoint the side nav leaves the page and AppShell composes a mobile drawer from the nav slots, unless `mobileNav` disables or replaces it.                                                                                                                                        |
 | End-user impact         | Keyboard users get a skip link to the main region; screen-reader users get one banner and one main landmark; phone-width users reach the side nav through a toggle and drawer while page content, its input values, and focus survive the layout switch. When the side nav collapses or expands, the content's old and new wrap swap on the rail's clock instead of re-wrapping in one frame (FR17). |
 | Builder impact          | None. Callers fill slots and choose height, variant, content padding, and mobile behavior.                                                                                                                                                                                                                                                                                                           |
-| Compatibility/readiness | Records shipped behavior; no prop, default, or export changes. Five current-state gaps, listed under Current-state impact: page-level stacking values, a banner pinned against its docs, an unmeasured late header, a raw `content` drawer the toggle cannot reach, and a fill-height main region that is not a tab stop.                                                                            |
+| Compatibility/readiness | Records shipped behavior; no prop, default, or export changes. Four current-state gaps, listed under Current-state impact: page-level stacking values, a banner pinned against its docs, an unmeasured late header, and a raw `content` drawer the toggle cannot reach.                                                                                                                              |
 | Review checks           | Reject a second `main` or banner landmark from AppShell, a skip link that is not the first focusable element or does not move focus to `main`, a breakpoint that treats equality as mobile, or remounting page content when the breakpoint changes. Also reject a content area that animates its width during a side nav collapse or expand (FR17).                                                  |
 | Governing rules         | `spec:AST-012` FR8 (width points), `family:layout-regions` FR9, `architecture:theme-application` INV10, `spec:AST-027` FR1–FR5 (local stacking), `architecture:component-theming-surface`; `component:SideNav` FR6 and `spec:AST-105` FR8 (the content swap).                                                                                                                                        |
 
@@ -86,11 +86,6 @@ Consumer migration instructions belong in consumer docs and release notes.
   the auto toggle still renders, so its `aria-controls` names no element and its
   presses open nothing. WCAG 4.1.2 requires a control's relationships and state
   to be programmatically correct.
-- **The fill-height main region is not a tab stop while it overflows.** In
-  `height="fill"` the main region is a scroll container, but it is never a
-  sequential tab stop, so keyboard users reach overflowing content only through
-  the skip link or focusable content inside it. `spec:AST-025` FR12 requires
-  effective scroll content to stay keyboard reachable.
 
 ## Ownership boundary
 
@@ -155,7 +150,7 @@ the only component record in the AppShell root.
 | FR1  | The root element carries `app-shell`, the forwarded `ref`, `data-testid`, and other DOM props, and contains, in order: the skip link, the Layout frame (header region, inline side region, content region), then any mobile drawer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests                    |
 | FR2  | A slot is present when its value is renderable: not `null`, `undefined`, a boolean, or an empty string. A component that renders nothing still counts as present.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source and public types             |
 | FR3  | The header region renders only when `topNav` or `banner` is present; it carries `app-shell-header` and `role="banner"`, places `banner` above `topNav`, and is never inside another landmark. The sidenav-only mobile top bar (FR9) also carries `app-shell-header` and takes `role="banner"` only when no header region renders. AppShell renders at most one banner landmark.                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests                    |
-| FR4  | `children` render in one region with `role="main"` and `id="astryx-app-shell-main"`, programmatically focusable so the skip link can move focus to it; programmatic focus on it draws no focus ring. Its padding is `contentPadding`, default `0`. Whether it is a sequential tab stop is keyboard access to a scroll region (`spec:AST-025` FR12).                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests                    |
+| FR4  | `children` render in one region with `role="main"` and `id="astryx-app-shell-main"`, programmatically focusable so the skip link can move focus to it; programmatic focus on it draws no focus ring. Its padding is `contentPadding`, default `0`. Whether it is a sequential tab stop is keyboard access to a scroll region (`spec:AST-025` FR12). Focus that Tab moves onto it while it is a stop draws the standard focus ring, inset, until focus leaves it; in `elevated` with both navs the region takes the surface's rounded top-start corner while that ring shows.                                                                                                                                                                                               | Current source and tests                    |
 | FR5  | The skip link is the first focusable element in the shell. It links to `#astryx-app-shell-main`, shows the translated `@astryx.appShell.skipToContent` text, is visually hidden until focused, and on activation moves focus to the main region.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | WCAG 2.4.1; current source and tests        |
 | FR6  | `fill` sizes the root to `100dvh` and the inline side region and main region scroll on their own. `auto` gives the root a `100dvh` minimum, makes the header sticky at the block start, keeps the inline side region sticky below the measured height of a header present when the shell mounts in `auto`, with its own scrolling, and lets the page scroll. Header height is measured only in `auto`.                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests                    |
 | FR7  | Variant backgrounds: `wash` paints body background on the frame, nav areas, and content; `surface` paints surface on all three; `section` paints surface on the frame and divides the nav areas from content, and in `auto` the header paints surface itself; `elevated` paints body background on the frame and nav areas and surface on content (FR16 for the corner).                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests                    |
@@ -202,8 +197,10 @@ the only component record in the AppShell root.
 
 ### Performance and resources
 
-- **PR1 — Header measurement.** AppShell observes the header's size only in
-  `auto` and observes nothing in `fill`.
+- **PR1 — Measurement.** AppShell observes the header's size only in `auto`.
+  In `fill` it observes only whether the main region overflows (main's size,
+  its direct children's sizes, and its content), which decides whether main is
+  a sequential tab stop (FR4).
 - **PR2 — One media query.** The breakpoint switch uses one media query
   subscription per shell.
 
@@ -280,9 +277,9 @@ reachability, not a decision that it must stay unthemeable.
 
 | Contract            | Verification                                                                                                                                                                                                                                        | Representative states                                                                                                                                                                                                                                              | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                         | Audit section                  |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1–FR4, AR1        | `AppShell.test.tsx` slot, landmark, banner, and ref suites                                                                                                                                                                                          | Content only; each slot; mobile top bar with banner                                                                                                                                                                                                                | A missing or duplicate landmark, or a nested banner, fails role queries.                                                                                                                                                                                                                                                                                                                                | `audit:AppShell/anatomy`       |
+| FR1–FR4, AR1        | `AppShell.test.tsx` slot, landmark, banner, and ref suites; `AppShellMainKeyboard.a11y.browser.spec.ts` for main as a tab stop and its focus ring                                                                                                   | Content only; each slot; mobile top bar with banner; Tab, Shift+Tab, click and skip link onto an overflowing main                                                                                                                                                  | A missing or duplicate landmark, or a nested banner, fails role queries.                                                                                                                                                                                                                                                                                                                                | `audit:AppShell/anatomy`       |
 | FR5, AR2            | `AppShell.test.tsx` skip-link and keyboard suites                                                                                                                                                                                                   | First Tab; Enter; click; translated text                                                                                                                                                                                                                           | Losing the href, the focus move, or tab order fails.                                                                                                                                                                                                                                                                                                                                                    | `audit:AppShell/accessibility` |
-| FR6, PR1            | `AppShell.test.tsx` height-mode suites                                                                                                                                                                                                              | `fill`, `auto`, section header in `auto`                                                                                                                                                                                                                           | Dropping the header's sticky placement or measuring in `fill` fails.                                                                                                                                                                                                                                                                                                                                    | `audit:AppShell/behavior`      |
+| FR6, PR1            | `AppShell.test.tsx` height-mode and main keyboard access suites; `observeMainOverflow.test.ts`                                                                                                                                                      | `fill`, `auto`, section header in `auto`; main fitting and overflowing in `fill`                                                                                                                                                                                   | Dropping the header's sticky placement, measuring the header in `fill`, or not measuring main, fails.                                                                                                                                                                                                                                                                                                   | `audit:AppShell/behavior`      |
 | FR8                 | `AppShell.test.tsx` breakpoint suites                                                                                                                                                                                                               | `lg`, `xl`, `2xl`, explicit `md`, `none`; nearest, root, and built themes; SSR hint                                                                                                                                                                                | Wrong map, inclusive edge, or `none` entering mobile fails.                                                                                                                                                                                                                                                                                                                                             | `audit:AppShell/behavior`      |
 | FR9–FR12            | `AppShell.test.tsx` mobile suites; `MobileNavCloseEdgeCases.test.tsx` AppShell drawer suites                                                                                                                                                        | Sidenav only; both navs; heading-only TopNav; custom node                                                                                                                                                                                                          | A missing toggle, duplicated items, a stale drawer, or an early hide fails.                                                                                                                                                                                                                                                                                                                             | `audit:AppShell/behavior`      |
 | FR13, AR3           | `AppShell.test.tsx` keyboard drawer and `useAppShellMobile` suites                                                                                                                                                                                  | Outside a shell; inside, closed and open                                                                                                                                                                                                                           | A wrong id link or stale state fails.                                                                                                                                                                                                                                                                                                                                                                   | `audit:AppShell/accessibility` |
@@ -298,7 +295,7 @@ Read from source, with no focused test or baseline yet:
 - FR2: `null`, `true`, `false`, and `''` slots counting as absent, and a slot that renders
   nothing counting as present.
 - FR3: `banner` above `topNav`, and no header region with only `sideNav`.
-- FR4: the `contentPadding` value and its `0` default, and no focus ring on main.
+- FR4: the `contentPadding` value and its `0` default.
 - FR5: the skip link's visual hiding until focus; AR2: its shared focus outline.
 - FR6: root sizing and region scrolling in each height mode, and the sticky side
   region in `auto`.

package/src/AppShell/AppShell.tsx

@@ -33,6 +33,7 @@ import {
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
+  focusVars,
   fontWeightVars,
   radiusVars,
   spacingVars,
@@ -64,7 +65,10 @@ import type {AppShellMobileContextValue} from './AppShellMobileContext';
 import type {SpacingStep} from '../utils/types';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps, isRenderable} from '../utils';
-import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {
+  focusOutlineProps,
+  focusOutlineStyles,
+} from '../utils/focusOutline.stylex';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 import {observeResize} from '../utils/sharedResizeObserver';
 import {themeProps} from '../utils/themeProps';
@@ -77,6 +81,8 @@ import {
 import type {AppShellVariantMap} from './index';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {attachScrollKeyboardDelegation} from '../hooks/scrollKeyboardDelegation';
+import {observeMainOverflow} from './observeMainOverflow';
 const HasActivity = typeof React.Activity !== 'undefined';
 const ActivityWrapper = HasActivity
   ? ({
@@ -370,7 +376,7 @@ 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
+  // Programmatic focus target for the skip link. While main fits, it 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: {
@@ -379,6 +385,24 @@ const styles = stylex.create({
       ':focus': 'none',
     },
   },
+  // While main's focus ring shows, main follows the elevated surface's
+  // rounded top-start corner, so the ring keeps the surface's shape instead of
+  // drawing a square corner. Otherwise main keeps its corner and clips nothing.
+  mainElevatedCorner: {
+    borderStartStartRadius: {
+      default: null,
+      ':focus-visible': radiusVars['--radius-page'],
+    },
+  },
+  // While main scrolls its overflowing content it is a keyboard stop, and
+  // keyboard focus on it draws the standard ring, inset so the shell's own
+  // clipping cannot hide it.
+  mainScrollRegionInset: {
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': `calc(-1 * ${focusVars['--focus-outline-width']})`,
+    },
+  },
 
   elevatedBackdrop: {
     position: 'absolute',
@@ -615,9 +639,105 @@ export function AppShell({
     document.getElementById(MAIN_CONTENT_ID)?.focus();
   }, []);
 
+  // Main draws its focus ring only for focus a Tab press moved onto it, and
+  // keeps it for as long as that focus stays, even once the content fits.
+  // Programmatic focus (the skip link, a script's focus() on a route change)
+  // draws none (FR4), even after keyboard input, where :focus-visible alone
+  // would match. See the effect below for how a Tab move is told apart.
+  const [isTabFocus, setIsTabFocus] = useState(false);
+  // A window or tab switch blurs main without moving focus off it: main stays
+  // the document's active element, and focus comes back to it with no Tab
+  // press. The ring holds across that round trip; any real focus move ends it.
+  const isMainAwayRef = useRef(false);
+  const handleMainBlur = useCallback(
+    (event: React.FocusEvent<HTMLDivElement>) => {
+      if (event.target !== event.currentTarget) {
+        return;
+      }
+      if (document.activeElement === event.currentTarget) {
+        isMainAwayRef.current = true;
+        return;
+      }
+      isMainAwayRef.current = false;
+      setIsTabFocus(false);
+    },
+    [],
+  );
+
   const isFill = height === 'fill';
   const isAuto = height === 'auto';
 
+  // With `fill`, main is the page's scroller. While its content overflows it
+  // must be reachable from the keyboard even when nothing inside it is
+  // focusable (AST-025 FR12): it joins the tab order, and Tab entry moves on
+  // to its first link or button when it has one. Only `fill` observes main
+  // (PR1); LayoutContent keeps owning main's overflow and styles.
+  const [isMainOverflowing, setIsMainOverflowing] = useState(false);
+  const isMainScrollRegion = isFill && isMainOverflowing;
+  // Main's node is owned through a ref, never React state. Under `fill` its
+  // overflow is observed while the node is attached, and while main is a
+  // scroll region the keyboard delegation is attached to it. The ref callback
+  // changes with `fill`, so switching modes detaches and re-attaches main in
+  // the same commit; a detached or replaced node releases both before the new
+  // node takes over.
+  const mainNodeRef = useRef<HTMLDivElement | null>(null);
+  const mainOverflowRef = useRef<{
+    node: HTMLDivElement;
+    stop: () => void;
+  } | null>(null);
+  const mainDelegationRef = useRef<{
+    node: HTMLDivElement;
+    release: () => void;
+  } | null>(null);
+  const isMainScrollRegionRef = useRef(isMainScrollRegion);
+  const syncMainDelegation = useCallback(() => {
+    const node = isMainScrollRegionRef.current ? mainNodeRef.current : null;
+    const current = mainDelegationRef.current;
+    if (current?.node === node) {
+      return;
+    }
+    current?.release();
+    mainDelegationRef.current =
+      node == null
+        ? null
+        : {node, release: attachScrollKeyboardDelegation(node, node)};
+  }, []);
+  const setMainNode = useCallback(
+    (node: HTMLDivElement | null) => {
+      mainNodeRef.current = node;
+      const observed = isFill ? node : null;
+      const current = mainOverflowRef.current;
+      if (current?.node !== observed) {
+        current?.stop();
+        mainOverflowRef.current =
+          observed == null
+            ? null
+            : {
+                node: observed,
+                stop: observeMainOverflow(observed, setIsMainOverflowing),
+              };
+        if (observed == null) {
+          setIsMainOverflowing(false);
+        }
+      }
+      syncMainDelegation();
+    },
+    [isFill, syncMainDelegation],
+  );
+  useEffect(() => {
+    isMainScrollRegionRef.current = isMainScrollRegion;
+    syncMainDelegation();
+  }, [isMainScrollRegion, syncMainDelegation]);
+  useEffect(
+    () => () => {
+      mainOverflowRef.current?.stop();
+      mainOverflowRef.current = null;
+      mainDelegationRef.current?.release();
+      mainDelegationRef.current = null;
+    },
+    [],
+  );
+
   // Nav style derived values
   const hasBanner = isRenderable(banner);
   const hasTopNav = isRenderable(topNav);
@@ -781,6 +901,9 @@ export function AppShell({
   // (`component:SideNav` FR6).
   const railRef = useRef<HTMLDivElement>(null);
   const mainRef = useRef<HTMLDivElement>(null);
+  // Main's node goes to the glide above and to the overflow observation
+  // that, under `fill`, makes main a keyboard stop.
+  const mainRefs = useMergedRefs(mainRef, setMainNode);
   const backdropRef = useRef<HTMLDivElement>(null);
   const contentLayout = useAnimatedLayout({containerRef: shellRef});
   const pendingContentRef = useRef<{
@@ -949,18 +1072,115 @@ export function AppShell({
   // Build main content
   // =========================================================================
   const shouldElevateWithCorner = isElevated && hasTopNav && showSideNavInline;
+  // While main is a keyboard stop, a Tab keydown anywhere in the document
+  // (capture, so Shift+Tab from the page start counts too) marks the next
+  // focus move, and so does the window's focus event for keyboard focus that
+  // enters the document from outside (Tab or Shift+Tab from the page
+  // embedding this one), where the browser's own `:focus-visible` then tells
+  // a key from a pointer. A mark counts only once its event's dispatch has
+  // finished uncancelled (`eventPhase === 0`): the browser's own focus move
+  // follows that dispatch in the same task, while a focus() a page's handler
+  // calls during it is programmatic and draws no ring (FR4). The marks expire
+  // on a zero-delay timer, so a cancelled Tab, a Tab out of the document or a
+  // window focus with nothing focused leaves nothing for a later focus().
+  useEffect(() => {
+    if (!isMainScrollRegion) {
+      return;
+    }
+    let tabKeydown: KeyboardEvent | null = null;
+    let windowFocus: FocusEvent | null = null;
+    let expiry: ReturnType<typeof setTimeout> | undefined;
+    const expireMarks = () => {
+      clearTimeout(expiry);
+      expiry = setTimeout(() => {
+        tabKeydown = null;
+        windowFocus = null;
+      }, 0);
+    };
+    const onKeyDown = (event: KeyboardEvent) => {
+      tabKeydown = event.key === 'Tab' ? event : null;
+      windowFocus = null;
+      expireMarks();
+    };
+    const onPointerDown = () => {
+      tabKeydown = null;
+      windowFocus = null;
+    };
+    const onWindowFocus = (event: FocusEvent) => {
+      windowFocus = event;
+      expireMarks();
+    };
+    const onFocusIn = (event: FocusEvent) => {
+      // Still dispatching: this focus move is a handler's focus(), so it
+      // reads no mark and leaves the mark for the browser's own move.
+      const tabDone = tabKeydown != null && tabKeydown.eventPhase === 0;
+      const focusDone = windowFocus != null && windowFocus.eventPhase === 0;
+      const arrivedByTab = tabDone && tabKeydown?.defaultPrevented === false;
+      const enteredDocument = focusDone;
+      if (tabDone) {
+        tabKeydown = null;
+      }
+      if (focusDone) {
+        windowFocus = null;
+      }
+      const main = mainNodeRef.current;
+      const isMain = event.target != null && event.target === main;
+      if (isMainAwayRef.current) {
+        // Focus comes back after a window or tab switch (main keeps the ring
+        // it had), or lands elsewhere (main's ring is over).
+        isMainAwayRef.current = false;
+        if (isMain && !arrivedByTab) {
+          return;
+        }
+        if (!isMain) {
+          setIsTabFocus(false);
+          return;
+        }
+      }
+      if (isMain) {
+        setIsTabFocus(
+          arrivedByTab || (enteredDocument && main.matches(':focus-visible')),
+        );
+      }
+    };
+    document.addEventListener('keydown', onKeyDown, true);
+    document.addEventListener('pointerdown', onPointerDown, true);
+    document.addEventListener('focusin', onFocusIn, true);
+    window.addEventListener('focus', onWindowFocus);
+    return () => {
+      document.removeEventListener('keydown', onKeyDown, true);
+      document.removeEventListener('pointerdown', onPointerDown, true);
+      document.removeEventListener('focusin', onFocusIn, true);
+      window.removeEventListener('focus', onWindowFocus);
+      clearTimeout(expiry);
+    };
+  }, [isMainScrollRegion]);
+
+  // Tab focus on main draws the ring until main loses focus; programmatic
+  // focus never does (FR4).
+  const drawsMainFocusRing = isTabFocus;
 
   const mainInner = (
     <LayoutContent
-      ref={mainRef}
+      ref={mainRefs}
       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}
+      // A keyboard stop only while it scrolls overflowing content.
+      tabIndex={isMainScrollRegion ? 0 : -1}
       isScrollable={isFill}
-      xstyle={[contentAreaStyle, styles.mainFocusTarget]}>
+      onBlur={handleMainBlur}
+      xstyle={[
+        contentAreaStyle,
+        drawsMainFocusRing &&
+          shouldElevateWithCorner &&
+          styles.mainElevatedCorner,
+        drawsMainFocusRing
+          ? [focusOutlineStyles.focusVisible, styles.mainScrollRegionInset]
+          : styles.mainFocusTarget,
+      ]}>
       {children}
     </LayoutContent>
   );