An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:HoverCard authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-28 owners: [cixzhang] review_triggers: [public-api, behavior, theming, accessibility] verified_by: [ packages/core/src/HoverCard/HoverCard.test.tsx, packages/core/src/HoverCard/popupTrigger.test.ts, packages/core/src/HoverCard/tests/HoverCardTriggerRoles.a11y.browser.spec.ts, packages/core/src/Layer/layerDismissalFamilies.test.tsx, packages/core/src/Layer/useTouchTrigger.test.ts, packages/core/src/Layer/touchTriggerTargets.test.tsx, apps/storybook/stories/HoverCard.stories.tsx, packages/core/src/HoverCard/tests/HoverCardAudit.a11y.chromium.spec.ts, .github/a11y-audit-axe.json, scripts/check-knowledge.mjs, ] modules: [] families: [family:overlay-dismissal] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:interaction-modality, architecture:layer-runtime, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-003, spec:AST-017]
HoverCard component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | HoverCard with children (trigger), content, label, placement (above), alignment (center), delay (300), hideDelay (200), focusTrigger, touchTrigger (auto), isEnabled, isOpen, isDefaultOpen, onOpenChange, and hasHoverIndication; target hover-card. useHoverCard takes the same touchTrigger. |
| Behavior | A floating card of rich, possibly interactive content anchored to a trigger. It opens on hover after delay, on focus, and on a tap that touchTrigger allows, stays open while the pointer is on the trigger or card, and closes on leave, Escape, or a tap outside. With label it is a named dialog the trigger names while open (and advertises, when the trigger's role supports it); without, a group that describes the trigger. With touchTrigger="none", touch never opens it. |
| End-user impact | Mouse, keyboard, and touch users can open the preview, move into it to use its actions, and dismiss it; screen-reader users hear it as a named dialog, announced as a popup on a button or link trigger, or as the trigger's description. Under the default touchTrigger="auto", a tap on a trigger that performs an action performs only that action. |
| Builder impact | touchTrigger answers whether it is safe to consume a tap to show the card (DEC-1): keep the default auto on a trigger that performs an action, pass tap where a tap only reveals the card, and pass none where a tap must never show it. |
| Compatibility/readiness | No public API change: touchTrigger keeps its released values and its default auto. Two implementation gaps (see Current-state impact). |
| Review checks | Reject an unnamed dialog, a card that cannot be hovered or dismissed (WCAG 1.4.13), Escape in the page that also closes a layer underneath, aria-expanded set on a trigger whose role does not support it, or a tap under touchTrigger="auto" that both performs the trigger's action and shows the card. |
| Governing rules | WCAG 1.4.13, 2.1.1; family:overlay-dismissal; spec:AST-003 FR4; spec:AST-017 (lifecycle); architecture:public-component-api INV9, INV21; architecture:layer-runtime; architecture:interaction-modality; architecture:component-theming-surface. |
Under none, no touch or pen tap opens the card.
This table is a review projection; the body below is authoritative.
Intent
HoverCard previews more information about a trigger, such as a profile or a
link summary, without navigating away. It owns the trigger wiring, when the
card opens and closes for each input, the card's semantics, and its surface.
Consumer usage lives in HoverCard.doc.mjs.
Compatibility and migration
- Released default preserved: yes.
touchTriggerkeeps its released values and its defaultauto. A disabled control is not an action, so its reason opens on a tap (FR5); that restoration ships on its own as a patch[fix] - Compatibility class: no public prop, default, or styling change. Text
written around an expression, such as
Edited {when}, now renders the focusable trigger span with the text hover cue, as a single string does; this ships as a patch[fix] - Controlled/uncontrolled behavior: uncontrolled by default;
isOpenforces the state, and a controlled card reports close requests throughonOpenChange(false)without closing itself (FR7) - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- Hover timing does not use the shared hover recognizer. The card runs its
own show and hide timers.
architecture:interaction-modalityINV11 hasuseHoverCardtake its hover timing from the shared hover recognizer. - The hold follows only the pointer. The card stays open only while the pointer is on the trigger or the card. A card opened by keyboard focus closes once the pointer crosses the trigger and leaves, while the trigger keeps focus, and a hover-opened card the user has tabbed into closes when the pointer leaves the trigger, dropping focus to the page. WCAG 1.4.13 requires content shown on focus to persist until focus moves or the user dismisses it.
Ownership boundary
Owns
- Trigger wiring, open and close behavior per input, card semantics, and the
hover-cardsurface (FR1–FR8).
Does not own / non-goals
- The trigger element and the card's body and actions — owned by the caller.
- Layer hosting, positioning, and inline-safe portaling — owned by
architecture:layer-runtime; shared Escape ordering — owned byfamily:overlay-dismissal. - The
useHoverCardhook's public contract — an uncontracted module; this record covers HoverCard's observable behavior.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Popup role | named dialog, group | label makes the card a named dialog; without it the card is a group. |
Every card. | group | component:HoverCard |
Stable | Not applicable. |
| Focus trigger | auto, always, never |
Whether focus opens the card: on focusable triggers, judged when focus arrives (FR4), always, or never. | Every trigger. | auto |
component:HoverCard |
Stable | TypeScript rejects other values. |
| Touch trigger | auto, tap, none |
Whether it is safe to consume a tap to show the card (DEC-1): auto shows it on a tap unless the trigger itself performs an action, a disabled control excepted (FR5); tap shows it on every tap; none on no tap. |
Touch and pen without hover. | auto |
component:HoverCard |
Stable | TypeScript rejects other values. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The open card is one surface carrying only the hover-card target, padded on every logical edge, with content inside and the theme's body font. xstyle, className, and style apply to the card. |
Current source and tests |
| FR2 | Trigger wiring: text children, strings and numbers (one, or several written around an expression such as Edited {when}) with holes such as false and null ignored, are wrapped in one focusable inline span; element children attach to their first element inside an inline-safe wrapper, and a first element replaced after mount, by new children or by a child that swaps its own root, is wired in place of the old one. |
Current source and tests |
| FR3 | With label, the card is role="dialog" named by label. A labelled trigger names the open card through aria-controls, merged with the trigger's own; it also gets aria-haspopup="dialog" and aria-expanded only when its role supports them (button, link and similar), never on a role-less element, each replacing the trigger's own value while the card is wired; the trigger's own values return on cleanup. Without label, the card is role="group" and the trigger's aria-describedby gains the card's id. |
Current source and tests |
| FR4 | On a hover-capable pointer, entering the trigger opens the card after delay ms; leaving the trigger or the card closes it after hideDelay ms, and moving between them keeps it open. Any focus on the trigger, keyboard, pointer, or programmatic, opens it per focusTrigger, except the focus a tap leaves behind, the refocus after an Escape dismiss (FR6), and the refocus after a controlled close (FR7). Under auto, whether focus counts is judged when it arrives: focus on the trigger itself, or within a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it. |
WCAG 1.4.13; tests |
| FR5 | On touch and pen, a completed tap opens the card per touchTrigger on lift; a touch that becomes a scroll does not. Under auto, a tap opens it unless the trigger itself performs an action; an aria-disabled control, or a label for a disabled control, is not an action, so a disabled control's reason opens on a tap (DEC-1). Under tap, every tap opens it; under none, no tap does. A tap on the card's content keeps it open; a tap on the trigger while it is open, a tap outside, or a scroll starting outside closes it. Whether auto also leaves the card shut when the tap acts on a control around the trigger is open (component:Tooltip OQ1). |
Current source and tests |
| FR6 | Escape closes a visible card through the shared dismissal stack when it is the topmost layer in its trigger's document, so a layer underneath stays open; a card rendered into another document, such as an iframe or a Picture-in-Picture window, takes the Escape pressed there. When focus was inside the card, it returns to the trigger, and that refocus does not reopen the card. | WCAG 1.4.13; tests |
| FR7 | isOpen forces the card shown or hidden, and isOpen={true} suppresses hover and focus hiding; a controlled card answers Escape by calling onOpenChange(false) without hiding, and setting isOpen={false} while focus is inside the card returns focus to the trigger. isDefaultOpen opens it on mount, still dismissible. isEnabled={false} disables the triggers. onOpenChange reports each show and hide. |
Current source and tests |
| FR8 | Content renders only while open; server markup and the first client render match, including a default-open card. hasHoverIndication (auto: text children: strings and numbers, with holes such as false and null ignored) adds a hover cue to the inline trigger. |
Current source and tests |
| FR11 | A press inside an open HoverCard surface acts only within that surface: it never activates the trigger, a clickable container around it, or the control a label names. Interactive content inside the card (a link, a button) keeps its own activation. The press still reaches page-level listeners, so a menu or Typeahead inside the surface keeps working. architecture:layer-runtime INV17 states this stop for every layer root. |
component:Tooltip FR11; architecture:layer-runtime INV17 |
Allowed variation
- AV1 — Content. Any content, including interactive actions.
- AV2 — Theme styling. Themes restyle
hover-card.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Unlabelled | role="group"; trigger described by the card. |
Content. |
| Labelled | Named dialog; trigger names it while open, and advertises the popup only when its role supports it. |
Content. |
| Hover into card | Stays open; actions usable. | Delays. |
| Escape from content | Closes; focus back on trigger; no reopen. | — |
| Tap-open | Opens on lift; survives taps on its content. | — |
Transformation and precedence order
- ORD1 — Open state.
isOpen, then the input triggers.
Performance and resources
- PR1 — Listeners. An unchanged rerender does not rebind the trigger's
listeners; an element trigger rebinds them on each open and close, and any
trigger rebinds them when
onOpenChangechanges identity.
Accessibility contract
- AR1 — Popup semantics. FR3.
- AR2 — Content on hover or focus. FR4–FR6 keep the card hoverable, dismissible, and persistent per WCAG 1.4.13, except the pointer-only hold (Current-state impact).
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Trigger | Caller element that opens the card. | Caller content | Context-dependent | FR2 |
| Card | Padded floating surface anchored to the trigger. | Current source and public docs | Prominent | FR1 |
| Body | Caller content inside the card. | Caller content | Prominent | FR1 |
| Actions | Optional caller buttons inside the card. | Caller content | Supporting | FR4 |
Theming anatomy
{
"Trigger": {
"none": {
"reason": "intentional: The trigger is the caller's element and carries its own component's target."
}
},
"Card": {"target": "hover-card"},
"Body": {"inherits": "hover-card"},
"Actions": {
"none": {
"reason": "intentional: Actions are caller-rendered controls that carry their own components' targets."
}
}
}
Family and system relationships
family:overlay-dismissalowns Escape routing and topmost handling.architecture:layer-runtimeowns hosting, positioning, and portaling.architecture:interaction-modalityowns the focus modality FR4 uses and, through INV11, the hover timing source for FR4.architecture:component-theming-surfaceowns thehover-cardtarget.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR2, FR8 | HoverCard.test.tsx render, wrapper, mixed-text and its hover cue, portal, theme font, SSR, replaced-trigger, and card xstyle/className/style tests; HoverCardAudit Chromium frames of HoverCard / Open States for the single target, equal padding on every logical edge, and the text trigger's dashed hover cue |
Text and element triggers; default open | A stray target, lost font, or hydration mismatch fails, and so do card xstyle, className, or style that do not reach the card, missing or unequal card padding, or a lost dashed cue on a text trigger. |
audit:HoverCard/anatomy |
| FR3, AR1 | HoverCard.test.tsx role, trigger-attribute, and attribute-restore tests; popupTrigger.test.ts role-support and attribute tests; HoverCardTriggerRoles.a11y.browser.spec.ts attribute checks and axe pass with a labelled role-less trigger open; HoverCardAudit frames and the audit axe pass on HoverCard / Open States |
Labelled and unlabelled; supported and unsupported roles | Wrong role, trigger attributes that are not replaced and restored as stated, or a new axe violation on an open card, fail. | audit:HoverCard/accessibility |
| FR4–FR6, AR2 | HoverCard.test.tsx hover, delay and hide-delay timing, trigger-to-card hold, Escape, refocus, and touch tests, and its focusTrigger="auto" roving, <summary>, wrapper, left-the-tab-order, and focus-inside-a-focusable-trigger cases, and its "in a second document" Escape, refocus, focus-into-card, late-trigger, and moving-trigger cases, and its focus-trap-container Escape case; HoverCardAudit hover-and-keyboard pass in Chromium; useTouchTrigger.test.ts and touchTriggerTargets.test.tsx disabled-control cases |
Hover, focus, tap, Escape from trigger and content, in the page and in a second document; a trigger attached after the hook mounts, and one moved into a frame and back; a trigger inside a focus-trap container; touchTrigger auto, tap, and none; an action trigger; a disabled control inside a clickable row |
A card that cannot be reached or dismissed, that opens before delay or closes before hideDelay, that closes while the pointer moves from the trigger into it, or that opens on a tap on a trigger that performs an action under auto or on any tap under none, fails. |
audit:HoverCard/behavior |
| FR7 | HoverCard.test.tsx isEnabled, isDefaultOpen, onOpenChange, isOpen forcing, and controlled-close focus-return tests; layerDismissalFamilies.test.tsx controlled HoverCard case |
Disabled, default open, held open, held closed, closed by the caller with focus inside | Wrong state reporting, a hover that hides a card held open or opens one held closed, or focus left inside a card the caller closes, fails. | audit:HoverCard/behavior |
| FR11 | HoverCard.test.tsx surface-press suite |
A card inside a clickable container and inside a <label>; a button inside the card |
A click on card content that runs the container's click handler or activates a labelled control, or a card button that stops working, fails. | — |
| Theming anatomy map | scripts/check-knowledge.mjs |
Consumer anatomy and current target | Missing, extra, or stale mappings fail validation. | audit:HoverCard/theming |
Read from source, with no focused test yet:
- FR3: restoring the trigger's own attributes on unmount.
- FR5: a pen's press counting as a tap.
- FR5: a tap on the trigger closing a card that a hover or focus opened, or one open since mount, a pen's tap after its hover included.
- FR7:
isOpen={true}keeping the card open when focus leaves the trigger. - FR8:
hasHoverIndication={true}.
Checked only in a browser, with no unit test:
- FR1: the card's padding.
Decision log
DEC-1 — touchTrigger decides whether a tap may show the card
Reference: component:HoverCard/DEC-1
Decider: cixzhang, 2026-10-31; amended 2026-11-01 and 2026-11-02
touchTrigger answers whether it is safe to consume a tap to show the card,
as component:Tooltip DEC-1 states: auto, the default, shows the card on a
tap only when the trigger performs no action of its own, so one tap does one
thing; tap declares that every tap may show it; none declares that no tap
may. An aria-disabled control, or a label for a disabled control, is not an
action, and an element that acts only through a role-less onClick is a
caller fix. HoverCard has no public toggle prop; toggle-style triggers follow
component:Tooltip DEC-1.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables, examples, or layer-system rules. It links to their owners.