Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[Spec] motion DEC-1: every hover-to-display interaction is debounced (#7327)

Cindy Zhangddedd4c58228
diff --git a/docs/design/motion.md b/docs/design/motion.md
index 6018bc9cbc..e1472f4123 100644
--- a/docs/design/motion.md
+++ b/docs/design/motion.md
@@ -60,7 +60,67 @@ justification. Loading and status MUST remain understandable without animation.
The source wiki does not establish responsive-path, interruption, or
input-specific motion rules beyond the principles above. Those concerns remain
-open for separately evidenced decisions.
+open for separately evidenced decisions, except the hover-to-display rule below.
+
+### Hover-to-display delay
+
+A hover-to-display interaction is anything a hover-capable pointer reveals,
+shows, or expands: a tooltip, a hover card, a hover-opened menu or flyout, a
+container that reveals content on hover, a preview, or a popover that opens on
+hover.
+
+- **Entry delay.** A hover-to-display interaction MUST wait a small delay
+ before it renders or updates, so a pointer brushing across the trigger does
+ not cause eager rendering or updates. The surface's owner chooses the default
+ delay; its record MAY set the delay to zero, with its reason
+ (`architecture:interaction-modality` INV11).
+- **Exit guard.** Leaving the trigger MUST NOT flicker the content out: the
+ content stays until a short exit delay elapses or, for a container reveal,
+ until its fade completes, so a brush out and back in reads as one hover. Under
+ `prefers-reduced-motion: reduce` a container reveal's fade is instant
+ (`design:reduced-motion` DR3), so its content leaves at once.
+- **Pointer-specific.** Keyboard focus reveals immediately with no dwell. The
+ hover gate never delays touch or a coarse pointer; whether a tap opens a
+ surface stays with its owner (`architecture:interaction-modality` INV4).
+- **Group hand-off.** Within a group of triggers, a pointer that moves from one
+ open trigger to the next shows the next at once; the entry delay applies to
+ the first open only (`architecture:interaction-modality` INV11).
+- **Default on; adjustable.** The delay and guard are on by default, and each
+ owner sets its own default values. A timer-driven surface (a tooltip, a hover
+ card, a hover-opened menu or flyout) exposes them as `delay` and `hideDelay`,
+ in milliseconds, and a caller shortens or removes them only for a stated use
+ case. A container reveal keeps its timing in CSS; a caller opts into its
+ entry delay with `hoverDelay`, and its exit fade has no option.
+
+Inventory of hover-to-display surfaces and their defaults:
+
+| Surface | Entry delay | Exit guard | Conforms |
+| ----------------------------------------------- | ----------------------------------------- | --------------------------------------- | ---------------------------------------------------- |
+| `Tooltip` | on, `delay` | `hideDelay`, else the hover bridge | yes |
+| `HoverCard` | on, `delay` | on, `hideDelay` | yes |
+| `TopNavMenu` | on, `delay` | on, `hideDelay` | yes |
+| `TopNavMegaMenu` | on, `delay` | on, `hideDelay` | yes |
+| `DropdownMenu` submenu | on, no option | on, no option | partial: no `delay` or `hideDelay` option |
+| `SideNavItem` collapsed flyout | on, no option | on, no option | partial: no `delay` or `hideDelay` option |
+| `TopNavHeading` menu | none on a first open, no option | on, no option | no: first open has no entry delay (gap, FR5) |
+| `SideNavHeading` menu | none on a first open, no option | on, no option | no: first open has no entry delay (gap, FR5) |
+| `Slider` value tooltip | none (`delay` set to zero) | on | no: zero delay with no recorded reason |
+| `Overlay` with `showOn="hover"` | none, no option | exit fade, instant under reduced motion | no: no entry delay |
+| Container reveal (`Thumbnail`, `TreeList` rows) | opt-in | exit fade, instant under reduced motion | partial: entry delay opt-in |
+| Markdown heading links | none (`module:Markdown/headingLinks` AR3) | exit fade, instant under reduced motion | partial: zero delay recorded in AR3 without a reason |
+
+A surface listed as not conforming is a gap for its owner to close or to justify
+with a recorded use case; this record does not change its shipped behavior.
+
+### Verification
+
+| Contract | Verification | Representative states | Failure signal |
+| -------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| DEC-1 | Unit tests with fake timers for tooltip, hover card and menu timing | brush in and out under the delay; dwell past the delay; leave and re-enter within the guard | content rendered before the delay elapses, or removed during the guard |
+| DEC-1 | Real-browser tests of container reveals | dwell; brush past; leave; reduced motion | content revealed before the dwell, or a fade under reduced motion |
+| DEC-1 | Real-browser keyboard and coarse-pointer tests | focus-within; a finger on a trigger | any dwell before a focus reveal; a hover delay applied to touch |
+| DEC-1 | Evidence gap: no group hand-off test exists until the INV11 recognizer is built | move from one open trigger to the next in a group; first open | — |
+| DEC-1 | Inventory review on a new or changed hover-to-display surface | each surface above | a surface with no entry delay and no recorded use case |
## Accessibility intent
@@ -82,13 +142,34 @@ promotion.
## Component contract links
-No component links are asserted in this seed draft.
+- Each surface in the inventory above owns its delay and guard values;
+ `architecture:interaction-modality` INV11 owns the hover-intent mechanism.
## Decision log
-No repository design decision has approved this record yet. It distills motion
-intent from the public Design Conventions wiki without copying duration values,
-CSS properties, or audit mechanics.
+This record distills motion intent from the public Design Conventions wiki
+without copying duration values, CSS properties, or audit mechanics. One point
+is decided:
+
+### DEC-1 — Every hover-to-display interaction is debounced
+
+**Reference:** `design:motion/DEC-1`
+**Decider:** `cixzhang`, `2026-10-11`; the `delay` and `hideDelay` options, `2026-11-06`
+
+Every hover-to-display interaction requires a small delay to prevent brush-over
+eager rendering and updates, and an exit guard so the content does not flicker
+out. The delay exists to prevent users brushing the interface from causing janky
+rerenders while they move their pointer; it is input handling, not motion
+taste. Keyboard focus reveals immediately and coarse pointers are not gated.
+Defaults are on; a caller opts out only for a stated use case. Timer-driven
+hover surfaces (tooltips, hover cards, hover-opened menus and flyouts) expose
+the wait as `delay` and the exit guard as `hideDelay` (milliseconds), as
+Tooltip, HoverCard and TopNavMenu already do. Within a group of triggers, a
+pointer moving from one open trigger to the next shows the next at once
+(`architecture:interaction-modality` INV11). Removing a
+surface's default delay is rejected inside this decision: it trades a pointer
+guard for no benefit to keyboard or touch users, who already see the content at
+once.
## Open questions
@@ -101,5 +182,6 @@ CSS properties, or audit mechanics.
## Content boundary
-This file defines motion intent. It does not define duration or easing tokens,
-CSS properties, animation APIs, component behavior, or audit checks.
+This file defines motion intent and the hover-to-display rule. It does not
+define duration or easing tokens, CSS properties, animation APIs, other
+component behavior, or audit checks.
diff --git a/docs/specs/components/SideNav/SideNavHeading.spec.md b/docs/specs/components/SideNav/SideNavHeading.spec.md
index 17b7ce1431..4f70cd1d00 100644
--- a/docs/specs/components/SideNav/SideNavHeading.spec.md
+++ b/docs/specs/components/SideNav/SideNavHeading.spec.md
@@ -45,7 +45,7 @@ system_specs: []
| Behavior | The product identity block at the top of SideNav. Which parts are links and which part opens the menu follows from the `*Href` props and `menu`; in a collapsed rail it is an icon-only link, menu button, or icon with a tooltip. |
| End-user impact | Users reach product, suite, and account destinations and a product menu, in both the expanded and the collapsed rail; screen-reader users hear named links, a named trigger, and a named menu. |
| Builder impact | None. |
-| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps (see Current-state impact). |
+| Compatibility/readiness | Shipping FR5 delays the first hover-open for mouse and pen users; no public API change. Seven implementation gaps (see Current-state impact). |
| Review checks | Reject a collapsed icon without a name, a menu popup wrapped in a modal dialog, a heading button inside `role="menu"`, or `headerEndContent` rendered inside the whole-heading link. |
| Governing rules | `architecture:public-component-api` INV5; `architecture:interaction-modality`; `family:navigation-destinations`. |
@@ -60,8 +60,10 @@ usage lives in `SideNavHeading.doc.mjs`.
## Compatibility and migration
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
+- Released default preserved: `no`; shipping FR5 delays the first hover-open
+ for mouse and pen users
+- Compatibility class: records shipped behavior except FR5's first-open delay;
+ no public API change
- Controlled/uncontrolled behavior: the menu's open state is internal
- Migration decision: none
@@ -69,6 +71,10 @@ Consumer migration instructions belong in consumer docs and release notes.
## Current-state impact
+- **Heading menu entry delay (FR5).** The menu opens on the first hover with
+ no entry delay. FR5 requires the shared delay, with no wait only for a
+ hand-off from another open menu in the same navigation.
+
- **Some configurations drop DOM props.** Other DOM props passed to
SideNavHeading (beyond `data-testid`, `className`, `style`, `xstyle`, and
`ref`) reach no element in the menu configurations and in the collapsed link
@@ -133,7 +139,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR2 | `headingHref` alone without `menu` makes the icon and text one link; with `headerEndContent` that content sits beside the link, not inside it. Other `*Href` props without `menu` make each line with an href its own link, and a linked icon is named by `heading`. `menu` without hrefs makes the whole block, apart from `headerEndContent`, open the menu; `menu` with hrefs makes each line with an href its own link, and the chevron button and the rest of the block, apart from `headerEndContent`, open the menu. | Current source and tests |
| FR3 | The icon link, the whole-heading link, and the menu-configuration heading link use the `as` component, else the `LinkProvider` link, else `<a>`. Supporting lines, and the heading line in the independent-links configuration, use the Link component, which does not receive `as`. | Current source and tests |
| FR4 | The chevron button is named by `@astryx.sideNav.heading.openMenu` and is the popover's trigger. | Current source and tests |
-| FR5 | On a hover-capable pointer, hovering opens the menu immediately and does not move focus; a click opens it and moves focus to the first menu item; a click within 500 ms of a hover-open keeps it open; Escape closes it and returns focus to the trigger. | Current source and tests |
+| FR5 | On a hover-capable pointer, a first hover-open waits the menu hover delay (150 ms by default, as in `TopNavMenu`), and moving to it from another open menu in the same navigation opens it at once (`architecture:interaction-modality` INV11; owner decision, Nov 6 2026 (Cindy); proposed in `design:motion` DEC-1). A hover-open does not move focus. A click opens it and moves focus to the first menu item; a click within 500 ms of a hover-open keeps it open; Escape closes it and returns focus to the trigger. | Cindy, 2026-11-06 |
| FR6 | The menu is a non-modal popover below the block, aligned to its start; in the expanded rail it overlaps the block. It contains a heading button that closes the menu (see Current-state impact for its content), then a `role="menu"` named by `heading` that holds `menu`. | Current source and tests |
| FR7 | Only the collapsed menu form gives `menu` descendants the close action NavMenu items call on selection; the expanded menu forms do not. | Current source |
| FR8 | In a collapsed rail, without `icon` it renders nothing. With `icon`: `headingHref` makes an icon-only link named by `heading`; else `menu` makes an icon-only button named by `heading` that is the native invoker of its menu popover; else the icon renders alone. Each form shows a tooltip with `heading` at the inline end; `headerEndContent` and the chevron are hidden. | Current source and tests |
@@ -196,7 +202,7 @@ map is recorded.
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| FR1–FR4, AR1 | `SideNav.test.tsx` SideNavHeading and headerEndContent suites | Each configuration | Wrong element, unnamed link, or misplaced end content fails. | `audit:SideNavHeading/behavior` |
-| FR5 | `SideNav.test.tsx` SideNavHeading hover/click guard suite | Hover, click, late click, Escape | Lost guard or focus return fails. | `audit:SideNavHeading/behavior` |
+| FR5 | `SideNav.test.tsx` SideNavHeading hover/click guard suite. Evidence gap: no test of the first-open delay or the hand-off | Hover, click, late click, Escape | Lost guard or focus return fails. | `audit:SideNavHeading/behavior` |
| FR6, AR2 | `SideNav.test.tsx` menu popover semantics suite | Whole trigger; mixed; collapsed | A dialog wrapper or misplaced menu role fails. | `audit:SideNavHeading/accessibility` |
| FR8 | `SideNav.test.tsx` SideNavHeading collapsed suite | Link, menu, plain, no icon | Missing name, tooltip, or invoker fails. | `audit:SideNavHeading/behavior` |
| FR9 | `SideNav.test.tsx` focus ring suite | Whole-heading link, collapsed link, menu trigger | A missing shared ring class fails. | `audit:SideNavHeading/accessibility` |
@@ -212,7 +218,8 @@ Read from source, with no focused test yet:
configuration.
- FR3: `as` on the icon and menu-configuration heading links, and the Link
component for the other lines.
-- FR5: that hover opens the menu without delay.
+- FR5: the click guard, Escape, and focus return. Its first-open delay is an
+ implementation gap.
- FR6: the popover's placement and the menu's name.
- FR7; FR8's tooltip placement at the inline end; and FR9 on the popover's
heading button and the linked icon.
diff --git a/docs/specs/components/TopNav/TopNavHeading.spec.md b/docs/specs/components/TopNav/TopNavHeading.spec.md
index 957b152309..535cb6fc09 100644
--- a/docs/specs/components/TopNav/TopNavHeading.spec.md
+++ b/docs/specs/components/TopNav/TopNavHeading.spec.md
@@ -45,7 +45,7 @@ system_specs: []
| Behavior | The product identity block. Which parts are links and which part opens the menu follows from which `*Href` props and `menu` are set (FR2). |
| End-user impact | Users reach product, suite, and account destinations and a product switcher menu; screen-reader users hear a named logo link and a named menu. |
| Builder impact | None. |
-| Compatibility/readiness | Records shipped behavior; no public change. Five implementation gaps (see Current-state impact). |
+| Compatibility/readiness | Shipping FR5 delays the first hover-open for mouse and pen users; no public API change. Six implementation gaps (see Current-state impact). |
| Review checks | Reject a logo link without an accessible name, a menu popup wrapped in a modal dialog, or a heading button placed inside `role="menu"`. |
| Governing rules | `architecture:public-component-api` INV5; `architecture:interaction-modality` (shared focus indicator); `architecture:component-theming-surface`. |
@@ -60,8 +60,10 @@ or a menu trigger and the product menu popover. Consumer usage lives in
## Compatibility and migration
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
+- Released default preserved: `no`; shipping FR5 delays the first hover-open
+ for mouse and pen users
+- Compatibility class: records shipped behavior except FR5's first-open delay;
+ no public API change
- Controlled/uncontrolled behavior: the menu's open state is internal
- Migration decision: none
@@ -69,6 +71,9 @@ Consumer migration instructions belong in consumer docs and release notes.
## Current-state impact
+- **Heading menu entry delay (FR5).** The menu opens on the first hover with
+ no entry delay. FR5 requires the shared delay, with no wait only for a
+ hand-off from another open menu in the same navigation.
- **Menu configurations drop DOM props.** When `menu` is set, other DOM props
passed to TopNavHeading (beyond `data-testid`, `className`, `style`, `xstyle`,
and `ref`) do not reach any element. `architecture:public-component-api` INV5
@@ -127,7 +132,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR2 | Configuration: no `heading` and no `menu` → logo only, a link named by `logoLabel` when `headingHref` is set, else a `div`; `headingHref` alone without `menu` → the whole block is one link; other `*Href` props without `menu` → each line with an href is its own link and a linked logo is named by `logoLabel`, else `heading`; `menu` without any href → the whole block opens the menu; `menu` with hrefs → the links stay independent, and the chevron button and the rest of the block open the menu; otherwise a plain `div`. | Current source and tests |
| FR3 | The logo link, the whole-heading link, the logo-only link, and the menu-configuration heading link use the `as` component, else the `LinkProvider` link, else `<a>`. Supporting lines, and the heading line in the independent-links configuration, use the Link component, which does not receive `as`. | Current source and tests |
| FR4 | In both menu configurations, the chevron is a button named by the translated `@astryx.topNav.heading.openMenu` that toggles the menu; it is at least 28 by 28 px. | Current source and tests |
-| FR5 | On a hover-capable pointer, hovering the block opens the menu immediately and does not move focus; a click within 500 ms of a hover-open keeps the menu open and moves focus to the first menu item, and a later click closes it. | Current source and tests |
+| FR5 | On a hover-capable pointer, a first hover-open of the block waits the menu hover delay (150 ms by default, as in `TopNavMenu`), and moving to it from another open menu in the same navigation opens it at once (`architecture:interaction-modality` INV11; owner decision, Nov 6 2026 (Cindy); proposed in `design:motion` DEC-1). A hover-open does not move focus. A click within 500 ms of a hover-open keeps the menu open and moves focus to the first menu item, and a later click closes it. | Cindy, 2026-11-06 |
| FR6 | Clicking a link inside a menu configuration navigates without toggling the menu. | Current source |
| FR7 | The menu is a non-modal popover below the block, aligned to its start and overlapping it. It contains a heading button that closes the menu (see Current-state impact for its content), then a `role="menu"` region named by `heading` (or `@astryx.topNav.heading.dialogLabel`) that holds `menu`. | Current source and tests |
| FR8 | Escape closes the menu and returns focus to the trigger. | Current source and tests |
@@ -195,7 +200,7 @@ is recorded.
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| FR1–FR3, AR1 | `TopNav.test.tsx` TopNavHeading render and logo-name tests | Each configuration | A wrong element or unnamed logo link fails. | `audit:TopNavHeading/behavior` |
| FR4, FR7, AR2–AR3 | `TopNav.test.tsx` menu popover semantics tests | Whole trigger; links plus trigger | A modal wrapper or misplaced menu role fails. | `audit:TopNavHeading/accessibility` |
-| FR5, FR8 | `TopNav.test.tsx` hover/click guard tests | Hover-open, click, late click, Escape | Losing the guard or focus return fails. | `audit:TopNavHeading/behavior` |
+| FR5, FR8 | `TopNav.test.tsx` hover/click guard tests. Evidence gap: no test of FR5's first-open delay or the hand-off | Hover-open, click, late click, Escape | Losing the guard or focus return fails. | `audit:TopNavHeading/behavior` |
| FR10 | `TopNav.test.tsx` TopNavHeading menu-popover suite (touch and mouse slides) | Touch and mouse slides across items | Removing the adoption fails the slide tests. | — |
| FR11 | `TopNav.test.tsx` TopNavHeading cases "includes the visible heading in the menu trigger name without hrefs", "includes the heading in the translated menu trigger name with independent links", and "keeps the translated generic menu trigger name when the optional heading is absent or empty" (Korean catalog) | Whole trigger; links plus trigger; no heading; empty heading | A name without the heading, a translated name that drops it, or a dangling separator without a heading fails. | `audit:TopNavHeading/accessibility` |
| RTL relation | RTL audit curated D2 and D8 target (`apps/storybook/rtl-audit/targets.json`) on `TopNav / Full example` | Heading logo and title, with 0px start and 8px end padding; LTR and RTL | A logo that is not at the inline start of the title, or an end padding that stays on the same physical side in RTL, fails D2 or D8. | `audit:TopNavHeading/i18n-rtl` |