@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/TopNav/TopNavItem.spec.md

@@ -0,0 +1,189 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:TopNavItem
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-25
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/TopNav/TopNav.test.tsx,
+    apps/storybook/stories/TopNav.stories.tsx,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: [design:reduced-motion]
+architecture:
+  [
+    architecture:interaction-modality,
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: [spec:AST-085]
+---
+
+# TopNavItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                    |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `TopNavItem` with `label`, `href`, `target`, `as`, `isSelected`, `isDisabled`, `isIconOnly`, `icon`, `children`, and `size`; target `top-nav-item` with `mode` and `selected` states.                                       |
+| Behavior                | A link in the TopNav bar or drawer. Selected marks the current page; disabled drops the destination; in the drawer, activating it closes the drawer.                                                                        |
+| End-user impact         | Users see and hear which destination is current; a disabled item cannot navigate by any input; drawer users return to the page after choosing a destination.                                                                |
+| Builder impact          | None.                                                                                                                                                                                                                       |
+| Compatibility/readiness | Records shipped behavior; no prop, default, target, or export changes. Three implementation gaps (see Current-state impact).                                                                                                |
+| Review checks           | Reject a disabled item that keeps an `href` or fires `onClick`, a selected item without `aria-current="page"`, an icon-only item without an accessible name, or a drawer item that leaves the drawer open after navigating. |
+| Governing rules         | `component:TopNav` render modes; `spec:AST-085` (disabled items); `architecture:interaction-modality` (shared focus indicator); `architecture:component-theming-surface`.                                                   |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TopNavItem is one destination link inside TopNav. It owns the link's selected,
+disabled, and icon-only states and its rendering in the bar and in the mobile
+drawer. Consumer usage lives in `TopNavItem.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable; selection is caller-owned
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Caller props can replace item state.** Other DOM props spread onto the link
+  after `aria-current`, `aria-disabled`, and `tabIndex`, so a caller value
+  replaces them; a caller `aria-disabled` can hide a disabled item's state.
+  `architecture:public-component-api` INV5 keeps component-owned accessibility
+  from being overwritten by accident.
+- **Color transition under reduced motion.** The bar link's background and text
+  color still animate when reduced motion is requested; `design:reduced-motion`
+  DR3 allows no animated property for a fine pointer.
+- **A disabled item leaves the tab order.** A disabled item is an `<a>` without
+  `href` carrying `tabIndex=-1`, so keyboard users cannot reach it or learn that
+  it is disabled. `spec:AST-085` FR1 has a disabled control keep the tab stop it has
+  when enabled.
+
+## Ownership boundary
+
+**Owns**
+
+- The link element, its selected, disabled, and icon-only states, and its
+  bar and drawer renderings (FR1–FR7).
+
+**Does not own / non-goals**
+
+- Destination acceptance and blocking for every `href` this component renders —
+  owned by `family:navigation-destinations`.
+- Which item is selected — owned by the caller.
+- The bar's slots and render mode — owned by `component:TopNav` and
+  `component:AppShell`.
+- Router link rendering — owned by `LinkProvider` and the `as` component.
+
+## Public concepts
+
+| Concept   | Closed values or states | Meaning                                         | Availability by variant/orientation/state | Default | Owner                  | Stability | Invalid-value behavior            |
+| --------- | ----------------------- | ----------------------------------------------- | ----------------------------------------- | ------- | ---------------------- | --------- | --------------------------------- |
+| Selected  | `true`, `false`         | The item is the current page.                   | All modes.                                | `false` | `component:TopNavItem` | Stable    | Not applicable.                   |
+| Disabled  | `true`, `false`         | The item cannot navigate.                       | All modes.                                | `false` | `component:TopNavItem` | Stable    | Not applicable.                   |
+| Icon only | `true`, `false`         | Hides the visible text; `label` names the link. | All modes.                                | `false` | `component:TopNavItem` | Stable    | Without `icon` the link is empty. |
+| Size      | `sm`, `md`, `lg`        | Drawer row height and padding.                  | Drawer mode only; no effect in the bar.   | `md`    | `component:TopNavItem` | Stable    | TypeScript rejects other values.  |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                            | Basis                    |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | An enabled item renders the `as` component, else the `LinkProvider` link component, else `<a>`, with `href` and `target`, the forwarded `ref`, and other DOM props. It shows `icon`, then `children` if given, else `label`.                                                                                                                         | Current source and tests |
+| FR2 | `isSelected` sets `aria-current="page"` and the selected treatment; the selected fill stays under hover and touch press with no overlay.                                                                                                                                                                                                             | Current source and tests |
+| FR3 | `isDisabled` renders a plain `<a>` with no `href` and no `target` and `aria-disabled="true"`, and suppresses clicks, so no input can navigate or fire `onClick`. A disabled item MUST keep the tab stop it has when enabled (`spec:AST-085` FR1). Implementation gap: it is an `<a>` without `href` carrying `tabIndex=-1`, so it is not a tab stop. | Current source and tests |
+| FR4 | `isIconOnly` hides the text and sets `aria-label` to `label`.                                                                                                                                                                                                                                                                                        | Current source and tests |
+| FR5 | In `default` and `mobile-bar` modes the item is a horizontal bar link with `top-nav-item`. In `drawer` mode it is a full-width row sized by `size`, carries `data-mode="drawer"`, and on activation calls `onClick` and then closes the AppShell drawer.                                                                                             | Current source and tests |
+| FR6 | Both renderings paint the shared focus outline on keyboard focus and use the shared press feedback.                                                                                                                                                                                                                                                  | Current source           |
+| FR7 | `className`, `style`, and `xstyle` merge after component styles.                                                                                                                                                                                                                                                                                     | Current source           |
+
+### Allowed variation
+
+- **AV1 — Theme styling.** Themes may restyle `top-nav-item` per mode and
+  selected state.
+
+### Representative states
+
+| State     | Required invariant                                                                | Allowed variation |
+| --------- | --------------------------------------------------------------------------------- | ----------------- |
+| Rest      | Link with label.                                                                  | Theme styling.    |
+| Selected  | `aria-current="page"`; selected fill.                                             | Fill color.       |
+| Disabled  | No `href`, no click; keeps its tab stop. Implementation gap: `tabIndex=-1` (FR3). | Muted styling.    |
+| Icon only | `aria-label` from `label`; no visible text.                                       | Icon.             |
+| Drawer    | Full-width row; activation closes the drawer.                                     | Row size.         |
+
+### Transformation and precedence order
+
+- **ORD1 — Root element.** Disabled `<a>`, then `as`, then `LinkProvider`, then
+  `<a>`.
+- **ORD2 — Content.** `children`, then `label`.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Current page.** The selected item exposes `aria-current="page"`.
+- **AR2 — Disabled.** A disabled item is exposed as disabled and keeps its tab
+  stop (`spec:AST-085` FR1, FR5); see FR3's implementation gap.
+- **AR3 — Name.** An icon-only item is named by `label`.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | --------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Link             | Label with optional leading icon. | Current source and public docs | Prominent      | FR1, FR4           |
+| Selected state   | Neutral fill and stronger text.   | Current source                 | Prominent      | FR2                |
+
+`TopNavItem.doc.mjs` declares no anatomy of its own, so no anatomy-theming map
+is recorded.
+
+## Family and system relationships
+
+- `family:navigation-destinations` owns the accept/block decision for each
+  destination this component renders.
+- `component:TopNav` supplies the render mode; `component:AppShell` supplies
+  the drawer close action.
+- `architecture:interaction-modality` provides the shared focus indicator.
+
+## Verification map
+
+| Contract         | Verification                                                  | Representative states         | Mutation or failure expectation                        | Audit section                    |
+| ---------------- | ------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------ | -------------------------------- |
+| FR1, ORD1        | `TopNav.test.tsx` TopNavItem anchor, `as`, LinkProvider tests | Default, `as`, provider       | Wrong element or lost precedence fails.                | `audit:TopNavItem/behavior`      |
+| FR2–FR4, AR1–AR3 | `TopNav.test.tsx` TopNavItem state tests                      | Selected, disabled, icon only | Missing attribute or a navigating disabled item fails. | `audit:TopNavItem/accessibility` |
+| FR5              | `TopNav.test.tsx` disabled-navigation tests in both modes     | Default and drawer            | Lost click forwarding or href handling fails.          | `audit:TopNavItem/behavior`      |
+
+Pending conformance: the TopNavItem state test and the two disabled-navigation
+tests assert `tabIndex=-1` on a disabled item, pinning FR3's implementation
+gap; they change when disabled items follow `spec:AST-085`.
+
+Read from source, with no focused test yet: the disabled plain `<a>` taking precedence over `as` and `LinkProvider` (ORD1, FR3); other DOM props reaching the link (FR1); the `top-nav-item` target and its `mode` and `selected` states (FR5); the selected fill under hover and press (FR2); the drawer row size, `data-mode="drawer"`, and closing the drawer on activation (FR5); FR6; and FR7.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples. It links to
+their owners.

package/src/TopNav/TopNavMegaMenu.reduced-motion.source-build.test.mjs

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TopNavMegaMenu.reduced-motion.source-build.test.mjs
+ * @input Uses Babel, the core StyleX build config, and the TopNavMegaMenu
+ *   source
+ * @output Verifies the shipped panel follows design:reduced-motion: under
+ *   reduced motion it never rises (DR1), cross-fades in 200 ms on a touch
+ *   screen (DR2) and opens and closes at once with a mouse (DR3)
+ * @position Regression test for the compiled CSS of the mega-menu panel;
+ *   jsdom evaluates no media queries or transitions
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {transformAsync} from '@babel/core';
+import {describe, expect, it} from 'vitest';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CORE_ROOT = path.resolve(__dirname, '../..');
+const SOURCE = path.join(__dirname, 'TopNavMegaMenu.tsx');
+
+async function compiledRules() {
+  const result = await transformAsync(await fs.readFile(SOURCE, 'utf8'), {
+    babelrc: false,
+    configFile: path.join(CORE_ROOT, 'babel.config.json'),
+    filename: SOURCE,
+  });
+  return (result?.metadata?.stylex ?? []).map(([, rule]) => rule.ltr);
+}
+
+const REDUCED = /@media \(prefers-reduced-motion: ?reduce\)\{/;
+const REDUCED_COARSE =
+  /@media \(prefers-reduced-motion: ?reduce\) and \(pointer: ?coarse\)\{/;
+const REDUCED_FINE =
+  /@media \(prefers-reduced-motion: ?reduce\) and \(not \(pointer: ?coarse\)\)\{/;
+
+/** The declarations the rules matching `media` set, as one string each. */
+function declarationsUnder(rules, media) {
+  return rules
+    .filter(rule => media.test(rule))
+    .map(rule => rule.replace(/\s/g, ''));
+}
+
+describe('the mega-menu panel under reduced motion', () => {
+  it('never rises: no transform transition, and no offset (DR1)', async () => {
+    const reduced = declarationsUnder(await compiledRules(), REDUCED);
+    expect(reduced).toContainEqual(
+      expect.stringContaining('transition-property:opacity,overlay,display'),
+    );
+    expect(reduced).toContainEqual(expect.stringContaining('transform:none'));
+  });
+
+  it('cross-fades in 200 ms on easeInOut under a coarse pointer (DR2)', async () => {
+    const rules = await compiledRules();
+    // StyleX rewrites sibling media queries so they never overlap; every
+    // rule that sets the 200 ms still applies only to reduced motion under a
+    // coarse pointer.
+    const fade = rules.filter(rule =>
+      /transition-duration:(\.2s|200ms)/.test(rule),
+    );
+    expect(fade.length).toBeGreaterThan(0);
+    for (const rule of fade) {
+      expect(rule).toMatch(
+        /\(prefers-reduced-motion: ?reduce\) and \(pointer: ?coarse\)/,
+      );
+    }
+    const coarse = declarationsUnder(rules, REDUCED_COARSE);
+    expect(coarse).toContainEqual(
+      expect.stringMatching(
+        /transition-timing-function:cubic-bezier\(0?\.42,0,0?\.58,1\)/,
+      ),
+    );
+  });
+
+  it('opens and closes at once under a fine pointer (DR3)', async () => {
+    const fine = declarationsUnder(await compiledRules(), REDUCED_FINE);
+    expect(fine).toContainEqual(
+      expect.stringContaining('transition-duration:0s'),
+    );
+  });
+});

package/src/TopNav/TopNavMegaMenu.spec.md

@@ -0,0 +1,190 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:TopNavMegaMenu
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-25
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, accessibility]
+verified_by:
+  [
+    packages/core/src/TopNav/TopNavMegaMenu.test.tsx,
+    apps/storybook/stories/TopNavMenu.stories.tsx,
+  ]
+modules: []
+families: [family:overlay-dismissal]
+design_specs: [design:reduced-motion]
+architecture:
+  [
+    architecture:interaction-modality,
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: []
+---
+
+# TopNavMegaMenu component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                              |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `TopNavMegaMenu` with `label`, `items` and `featured` slots, `delay` (150), `hideDelay` (250), and `onOpenChange`; target `top-nav-mega-menu` with a `mode` state.                                                                                    |
+| Behavior                | In the bar, a button that opens a wide panel of links below the whole TopNav on hover or click; the panel is a labeled group, not an ARIA menu. In the drawer, a disclosure that expands items and featured content inline. Hidden in the mobile bar. |
+| End-user impact         | Users browse a grid of destinations with descriptions and a featured card; keyboard users reach the panel's links from the trigger; drawer users expand the group in place.                                                                           |
+| Builder impact          | None.                                                                                                                                                                                                                                                 |
+| Compatibility/readiness | Records shipped behavior; no public change. Four current-state gaps (see Current-state impact).                                                                                                                                                       |
+| Review checks           | Reject exposing the panel as `role="menu"`, wrapping it in a modal dialog, keyboard activation that closes an open panel, or a collapsed drawer group that stays reachable.                                                                           |
+| Governing rules         | `architecture:public-component-api` INV5 and INV7; `architecture:interaction-modality`; `component:TopNav` render modes.                                                                                                                              |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TopNavMegaMenu is a TopNav entry that reveals a large panel of destinations and
+featured content. It owns the trigger, the panel's open, close, and dismissal
+behavior, the panel layout, and the expandable drawer group. Consumer usage
+lives in `TopNavMegaMenu.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: open state is internal; `onOpenChange`
+  reports it
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **The trigger announces a menu.** The trigger carries `aria-haspopup="true"`,
+  which WAI-ARIA 1.2 defines as a menu popup, while the panel is a
+  `role="group"` (FR5).
+- **Motion under reduced motion.** The panel's fade and 4 px slide, the drawer
+  group's height, the chevrons' rotation, and the trigger's background and text
+  color still animate when reduced motion is requested. `design:reduced-motion` DR1–DR3 allow no animated property for a
+  fine pointer and only a short opacity change for touch.
+- **Same-label drawer groups share an id.** The drawer group's id is derived
+  from `label`, so two mega menus with the same label in one drawer produce
+  duplicate ids.
+- **The drawer trigger drops the ref.** In `drawer` mode the disclosure button
+  receives the caller's other DOM props but not `ref`.
+  `architecture:public-component-api` INV8 has the ref reach the element the
+  contract promises.
+
+## Ownership boundary
+
+**Owns**
+
+- The trigger, panel, open/close and dismissal behavior, panel layout, and
+  drawer group (FR1–FR11).
+
+**Does not own / non-goals**
+
+- Item rendering — owned by `component:TopNavMegaMenuItem`; featured cards —
+  owned by `component:TopNavMegaMenuFeaturedCard` or the caller.
+- Render mode and slot — owned by `component:TopNav`.
+- Native popover dismissal and layer hosting — owned by the shared popover and
+  layer runtime.
+
+## Public concepts
+
+No component-local concept beyond the consumer props in
+`TopNavMegaMenu.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                    |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| FR1  | In `default` mode the trigger is a `<button>` showing `label` and a chevron that turns when open; it carries `top-nav-mega-menu`, the forwarded `ref`, and other DOM props, exposes `aria-expanded`, and its `aria-controls` names the panel.                                                                                                                                                                                                                                                                      | Current source and tests |
+| FR2  | The panel is an auto popover with the trigger as its native invoker, anchored below the closest enclosing `<nav>` and aligned to the trigger's TopNav slot. The browser's light dismiss closes it, and opening a sibling mega menu closes it.                                                                                                                                                                                                                                                                      | Current source and tests |
+| FR3  | On a hover-capable pointer, hovering opens after `delay` ms and the panel stays transient: leaving the trigger and panel closes it after `hideDelay` ms, and re-entering the trigger cancels a pending close. A click pins it open. A click within 500 ms of a hover-open pins rather than closes; re-hovering an open panel does not restart that window. After a close, the pointer entering the panel does not reopen it.                                                                                       | Current source and tests |
+| FR4  | Enter and Space open the panel and never close an open one. Escape closes it and returns focus to the trigger.                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests |
+| FR5  | The panel is a `role="group"` named by `label`, not a `menu` and not a modal dialog. The group is followed by a close button named by `@astryx.popover.close` that stays visually hidden until it holds focus. A click-open moves focus to the panel's first link or button; a hover-open does not move focus.                                                                                                                                                                                                     | Current source and tests |
+| FR6  | The panel paints its own surface: `items` in a two-column grid, then `featured` beside it, wrapping on narrow widths. The panel is at most `min(960px, 100dvw − 16px)` wide and at most the space below the nav tall; taller content scrolls inside the panel. Without a reduced-motion preference, opening fades and slides in from 4 px above.                                                                                                                                                                   | Current source           |
+| FR7  | `onOpenChange` fires `true` when the panel shows and `false` when it hides, whatever the cause.                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source           |
+| FR8  | Caller `onClick`, `onMouseEnter`, and `onMouseLeave` on the trigger run before the built-in behavior and compose with it; a caller handler that calls `preventDefault()` cancels the built-in open or toggle for that event.                                                                                                                                                                                                                                                                                       | Current source and tests |
+| FR9  | In `drawer` mode the trigger is a full-width disclosure button with `aria-expanded` and `aria-controls` and `data-mode="drawer"`; activating it toggles the group, which holds `items` (rendering their drawer form) then `featured`. Collapsed content is `inert` and `aria-hidden`, and the group clips while collapsed and while it expands, and stops clipping once fully expanded. Without a reduced-motion preference, expansion animates the group's height. The trigger's `aria-controls` names the group. | Current source and tests |
+| FR10 | In `mobile-bar` mode TopNavMegaMenu renders nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests |
+| FR11 | The bar trigger and drawer trigger paint the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Slot content.** `items` may be any nodes; `featured` may be any nodes.
+
+### Representative states
+
+| State            | Required invariant                              | Allowed variation |
+| ---------------- | ----------------------------------------------- | ----------------- |
+| Hover-open       | Transient; closes when the pointer leaves.      | Delays.           |
+| Click-open       | Pinned; stays open when the pointer leaves.     | —                 |
+| Keyboard-open    | Opens on Enter or Space; Escape returns focus.  | —                 |
+| Tall content     | Panel scrolls inside; surface edges stay fixed. | Height.           |
+| Drawer collapsed | Content inert and hidden.                       | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Trigger handlers.** Caller handler first, then the built-in handler.
+
+### Performance and resources
+
+- **PR1 — Timers.** Hover timers clear on close and unmount.
+
+## Accessibility contract
+
+- **AR1 — Group, not menu.** A link grid is exposed as a named group, not an
+  ARIA menu, and not a modal dialog.
+- **AR2 — Trigger state.** The trigger exposes its expanded state and the panel
+  it controls.
+- **AR3 — Drawer disclosure.** The drawer trigger exposes its expanded state;
+  collapsed content is unreachable.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                       | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Trigger          | Bar-item styling with a chevron.                         | Current source and public docs | Prominent      | FR1                |
+| Panel            | Wide surface below the nav: item grid and featured area. | Current source and public docs | Prominent      | FR6                |
+| Drawer group     | Disclosure row with items and featured content.          | Current source                 | Supporting     | FR9                |
+
+`TopNavMegaMenu.doc.mjs` declares no anatomy of its own, so no anatomy-theming
+map is recorded.
+
+## Family and system relationships
+
+- `family:overlay-dismissal` owns Escape and close-request ordering for this
+  component's popover.
+- `component:TopNav` supplies the render mode and slot and is the panel's anchor.
+- `architecture:public-component-api` INV5 and INV7 govern forwarding and
+  handler composition.
+
+## Verification map
+
+| Contract          | Verification                                                        | Representative states                       | Mutation or failure expectation                      | Audit section                        |
+| ----------------- | ------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------- | ------------------------------------ |
+| FR1, FR5, AR1–AR2 | `TopNavMegaMenu.test.tsx` default-mode and popup-semantics suites   | Closed and open                             | A menu role, dialog wrapper, or broken link fails.   | `audit:TopNavMegaMenu/accessibility` |
+| FR2, FR3          | `TopNavMegaMenu.test.tsx` hover/click guard and dismissal suites    | Hover, click, leave, sibling, light dismiss | A lost guard or stale open state fails.              | `audit:TopNavMegaMenu/behavior`      |
+| FR4               | `TopNavMegaMenu.test.tsx` keyboard suite                            | Enter, Space, Escape                        | Toggling closed or lost focus return fails.          | `audit:TopNavMegaMenu/accessibility` |
+| FR8               | `TopNavMegaMenu.test.tsx` pass-through and owned-handler suites     | Bar and drawer                              | A replaced handler fails.                            | `audit:TopNavMegaMenu/behavior`      |
+| FR9–FR11, AR3     | `TopNavMegaMenu.test.tsx` mobile-bar, drawer, and focus-ring suites | Collapsed and expanded                      | Reachable collapsed content or a missing ring fails. | `audit:TopNavMegaMenu/behavior`      |
+
+Read from source, with no focused test yet: the visually hidden close button after the group (FR5); the forwarded `ref`, the `top-nav-mega-menu` target and its `mode` state, and the bar and drawer chevrons' turn (FR1, FR9); the drawer group's clipping while it expands and its height animation (FR9); where a click-open puts focus (FR5); the caller `preventDefault()` cancellation (FR8); anchoring below the enclosing `<nav>` and slot alignment (FR2); FR6; FR7; and the bar trigger's focus outline (FR11).
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, or popover
+mechanics. It links to their owners.

package/src/TopNav/TopNavMegaMenu.tsx

@@ -120,7 +120,11 @@ const styles = stylex.create({
   chevronOpen: {
     transform: 'rotate(180deg)',
   },
-  // Animation styles applied to the layer's popover element.
+  // Animation styles applied to the layer's popover element. Under
+  // `prefers-reduced-motion: reduce` the panel never rises (design:reduced-motion
+  // DR1): on a touch screen it cross-fades, 200 ms on easeInOut whatever the
+  // theme's duration (DR2, DR4), and with a mouse it opens and closes at once
+  // (DR3).
   panelAnimation: {
     opacity: {
       default: 0,
@@ -129,10 +133,23 @@ const styles = stylex.create({
     transform: {
       default: 'translateY(-4px)',
       ':popover-open': 'translateY(0)',
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    transitionProperty: {
+      default: 'opacity, transform, overlay, display',
+      '@media (prefers-reduced-motion: reduce)': 'opacity, overlay, display',
+    },
+    transitionDuration: {
+      default: durationVars['--duration-medium-min'],
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': '200ms',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        '0s',
+    },
+    transitionTimingFunction: {
+      default: easeVars['--ease-standard'],
+      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
+        'cubic-bezier(0.42, 0, 0.58, 1)',
     },
-    transitionProperty: 'opacity, transform, overlay, display',
-    transitionDuration: durationVars['--duration-medium-min'],
-    transitionTimingFunction: easeVars['--ease-standard'],
     transitionBehavior: 'allow-discrete',
     '@starting-style': {
       opacity: 0,