Skip to content

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

TypeScript

spec: Tooltip and HoverCard pin on press; InfoTip is the info preset (#9175)

Cindy Zhang1d8696ad9f70
diff --git a/docs/architecture/interaction-modality.md b/docs/architecture/interaction-modality.md
index 47d021b3cf..a351692a92 100644
--- a/docs/architecture/interaction-modality.md
+++ b/docs/architecture/interaction-modality.md
@@ -132,7 +132,11 @@ work.
tooltip pattern, so content too tall for the viewport scrolls inside it with
no keyboard path; its full content stays available to assistive technology
through the trigger's accessible description, and long or essential content
- belongs in a HoverCard or Popover.
+ belongs in a HoverCard or Popover. A tooltip that labels an action trigger
+ whose accessible name already carries its text is not a separate
+ interaction, so a tap on that trigger performs the action and does not open
+ the tooltip; information that lives only in a hint is reachable on touch
+ through `pressTrigger="toggle"` (`component:Tooltip` DEC-1).
- **INV5 — Existing state semantics win.** Disabled controls do not become
interactive because of modality. Read-only and busy controls preserve their
documented focus and activation behavior.
@@ -303,7 +307,7 @@ reachability, newer-intent precedence, and the evidence/scope guard were approve
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| INV1, INV2 | Programmatic-focus cases after keyboard and pointer input in representative component tests | Programmatic focus invents a modality, or pointer history paints the keyboard indicator |
| INV3 | Direct-owner, wrapper-owner, replaceable-indicator, and nested-action cases, including a Token inside an Item and a control inside a card; evidence gap for the shared-module cases: the module does not exist yet | No indicator, two indicators, replacement content that can opt out, or a component that writes the focus-owner attribute or selector itself |
-| INV4 | Keyboard, mouse, touch, and pen browser paths where applicable | Hover-only behavior, sticky touch hover, or unreachable action |
+| INV4 | Keyboard, mouse, touch, and pen browser paths where applicable; tap cases on an action trigger with a label tooltip and on a hint-only trigger with `pressTrigger="toggle"` | Hover-only behavior, sticky touch hover, unreachable action, a tap on an action trigger that opens its label tooltip, or hint-only information with no touch path |
| INV5 | Disabled, busy, and read-only DOM and activation assertions | Inactive control reacts, eligible control loses focus, or state changes with modality |
| INV6 | Public API review and representative source inspection | A component adds caller-controlled modality without a separate API decision |
| INV7 | Rendered-browser affected-state checks across geometry, clipping, scrolling, hit testing, built-in and custom-renderer paths | At an offered interaction point one modality loses every essential path, or evidence substitutes class equality for reachability/perceptibility |
diff --git a/docs/families/overlay-dismissal.md b/docs/families/overlay-dismissal.md
index e270e45e11..af0a409312 100644
--- a/docs/families/overlay-dismissal.md
+++ b/docs/families/overlay-dismissal.md
@@ -193,9 +193,10 @@ this record's current membership snapshot must be updated with it.
among the registered present members of the document it arrives in, and FR2
and FR3 apply within that document, so a host and the members nested in it
keep one order wherever they render. A member of another document is never a
- candidate. A Tooltip never wins or blocks an Escape press against another
- member (`spec:AST-003` FR4): Escape closes a Tooltip only when it is the only
- present member in its document. The stack listens once in each document that holds a
+ candidate. An unpinned Tooltip never wins or blocks an Escape press against
+ another member, and a Tooltip or HoverCard pinned open by a press takes Escape
+ first (`spec:AST-003` FR4, DEC-6): Escape closes an unpinned Tooltip only when
+ it is the only present member in its document. The stack listens once in each document that holds a
member and stops when its last member leaves.
- **FR9 — Focus returns in the opener's document.** Closing a trigger-anchored
member returns focus, when it would otherwise be lost, to the member's return
@@ -220,35 +221,35 @@ this record's current membership snapshot must be updated with it.
## Representative matrix
-| Member and state | Shared invariant | Deliberate variation |
-| ------------------------------------------------------ | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| Dialog inside Dialog | Inner dialog handles the first request | Dialog supplies native modality and focus behavior |
-| Popover inside Dialog | Popover handles the first Escape | Popover supplies anchoring, portal placement, and focus policy |
-| Registered descendant inside CommandPalette | Descendant handles the first Escape | CommandPalette inherits Dialog's shared stack participation |
-| Tooltip or HoverCard inside Dialog, in page | An open HoverCard handles the first Escape; over a Tooltip, the Dialog takes it | Hover families decide when they are present and how controlled state responds |
-| Lightbox or MobileNav above a required Dialog | Top member handles the request | Required Dialog uses `block` only when it is topmost |
-| Required Dialog alone | Request is consumed without closing | Dialog purpose selects `block` behavior |
-| Self-owned input popup | Popup participates while present | Input owns selection, focus, open state, positioning, and outside dismissal |
-| Two unrelated registered surfaces | Later active-cycle registration is topmost | Neither surface is treated as nested |
-| Platform close request sent to a lower Dialog | Lower Dialog stays open | The platform targets a host; the shared check decides whether it may close |
-| Popover in an iframe, Dialog in the page | Request goes to its own document's top member | The app renders into the second document through a portal |
-| Popover inside Dialog in an iframe | Popover handles the iframe's first request | Both register their own elements, so they rank in the iframe's order |
-| Tooltip or HoverCard inside Dialog, in iframe | An open HoverCard handles the first Escape there; over a Tooltip, the Dialog takes it | A Tooltip never wins or blocks Escape against another member (`spec:AST-003` FR4) |
-| ContextMenu in a Picture-in-Picture window | Escape closes it; focus returns to its opener there | The menu opens where the person pressed (FR8, FR9) |
-| BottomSheet or Lightbox in a Picture-in-Picture window | Escape closes it; focus returns to its return target there | The surface covers that window (FR8, FR9) |
-| BottomSheet or Lightbox in an embedded iframe | Not supported | A surface that covers its window works only where the window is the app (FR8) |
-| Drawer or MobileNav | Page only | Page-level surfaces stay in the page's document (FR8) |
+| Member and state | Shared invariant | Deliberate variation |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Dialog inside Dialog | Inner dialog handles the first request | Dialog supplies native modality and focus behavior |
+| Popover inside Dialog | Popover handles the first Escape | Popover supplies anchoring, portal placement, and focus policy |
+| Registered descendant inside CommandPalette | Descendant handles the first Escape | CommandPalette inherits Dialog's shared stack participation |
+| Tooltip or HoverCard inside Dialog, in page | An open HoverCard handles the first Escape; over an unpinned Tooltip, the Dialog takes it; a pinned Tooltip takes it first | Hover families decide when they are present and how controlled state responds |
+| Lightbox or MobileNav above a required Dialog | Top member handles the request | Required Dialog uses `block` only when it is topmost |
+| Required Dialog alone | Request is consumed without closing | Dialog purpose selects `block` behavior |
+| Self-owned input popup | Popup participates while present | Input owns selection, focus, open state, positioning, and outside dismissal |
+| Two unrelated registered surfaces | Later active-cycle registration is topmost | Neither surface is treated as nested |
+| Platform close request sent to a lower Dialog | Lower Dialog stays open | The platform targets a host; the shared check decides whether it may close |
+| Popover in an iframe, Dialog in the page | Request goes to its own document's top member | The app renders into the second document through a portal |
+| Popover inside Dialog in an iframe | Popover handles the iframe's first request | Both register their own elements, so they rank in the iframe's order |
+| Tooltip or HoverCard inside Dialog, in iframe | An open HoverCard handles the first Escape there; over an unpinned Tooltip, the Dialog takes it; a pinned Tooltip takes it first | An unpinned Tooltip never wins or blocks Escape against another member; a pinned Tooltip or HoverCard takes it first (`spec:AST-003` FR4, DEC-6) |
+| ContextMenu in a Picture-in-Picture window | Escape closes it; focus returns to its opener there | The menu opens where the person pressed (FR8, FR9) |
+| BottomSheet or Lightbox in a Picture-in-Picture window | Escape closes it; focus returns to its return target there | The surface covers that window (FR8, FR9) |
+| BottomSheet or Lightbox in an embedded iframe | Not supported | A surface that covers its window works only where the window is the app (FR8) |
+| Drawer or MobileNav | Page only | Page-level surfaces stay in the page's document (FR8) |
## Adoption and exceptions
-| Components or surface | Adoption | Current deviation or limitation |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Dialog, AlertDialog, Popover, MobileNav, Drawer, CommandPalette | shared owner; CommandPalette composes Dialog | none |
-| Tooltip, HoverCard | shared owner with DOM presence reporting | Neither provides nesting depth to descendant layers. Implementation gap: a Tooltip consumes Escape when it is the topmost layer, so the layer beneath it stays open for that press, and a Tooltip in another document is never closed by Escape (`component:Tooltip` FR6); FR8 gives that press to the layer beneath and closes a lone Tooltip in its own document. HoverCard reads its presence from the page's document, so in another document it takes no request (FR8) and returns no focus there (FR9) |
-| Focus traps with `onEscape` | shared owner through `useFocusTrap` | They provide DOM containment, not descendant depth |
-| BreadcrumbItem, ChatComposerInput, ComplexSelector, DateInput, DateRangeInput, DateTimeInput, Selector, MultiSelector, PowerSearch, BaseTypeahead, Typeahead, Tokenizer, SideNavHeading, SideNavItem, TabMenu, TopNavHeading, TopNavMenu, TopNavMegaMenu, Table, Lab TourStep, Lab ChatEmojiPicker | shared owner through `usePopover` or a composed Popover owner | Table filtering owns controlled Popover state and discards its draft on close; TourStep routes Popover close to the Tour; ChatEmojiPicker owns controlled Popover state |
-| DropdownMenu root, MoreMenu, ContextMenu, Selector, MultiSelector, TopNavHeading, TopNavMenu, TopNavMegaMenu, SideNavHeading, SideNavItem, BottomSheet, BottomSheetSwitcher, Lightbox | shared owner | Implementation gap: in another document (for BottomSheet, BottomSheetSwitcher and Lightbox, a Picture-in-Picture window), each decides focus return from the page's document and last input, so focus returns to the frame element or the page, or without the ring the last input in its document calls for (FR9) |
-| DropdownMenuSubMenu, PowerSearchEditPopover | local only | Must migrate from component-specific listeners or registries to the shared owner |
+| Components or surface | Adoption | Current deviation or limitation |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dialog, AlertDialog, Popover, MobileNav, Drawer, CommandPalette | shared owner; CommandPalette composes Dialog | none |
+| Tooltip, HoverCard | shared owner with DOM presence reporting | Neither provides nesting depth to descendant layers. Implementation gap: a Tooltip consumes Escape when it is the topmost layer, so the layer beneath it stays open for that press, and a Tooltip in another document is never closed by Escape (`component:Tooltip` FR6); FR8 gives that press to the layer beneath and closes a lone Tooltip in its own document. A Tooltip or HoverCard pinned open by a press takes Escape first (`spec:AST-003` FR4, DEC-6); implementation gap: the pin is not built (`component:Tooltip` FR9, `component:HoverCard` FR9). HoverCard reads its presence from the page's document, so in another document it takes no request (FR8) and returns no focus there (FR9) |
+| Focus traps with `onEscape` | shared owner through `useFocusTrap` | They provide DOM containment, not descendant depth |
+| BreadcrumbItem, ChatComposerInput, ComplexSelector, DateInput, DateRangeInput, DateTimeInput, Selector, MultiSelector, PowerSearch, BaseTypeahead, Typeahead, Tokenizer, SideNavHeading, SideNavItem, TabMenu, TopNavHeading, TopNavMenu, TopNavMegaMenu, Table, Lab TourStep, Lab ChatEmojiPicker | shared owner through `usePopover` or a composed Popover owner | Table filtering owns controlled Popover state and discards its draft on close; TourStep routes Popover close to the Tour; ChatEmojiPicker owns controlled Popover state |
+| DropdownMenu root, MoreMenu, ContextMenu, Selector, MultiSelector, TopNavHeading, TopNavMenu, TopNavMegaMenu, SideNavHeading, SideNavItem, BottomSheet, BottomSheetSwitcher, Lightbox | shared owner | Implementation gap: in another document (for BottomSheet, BottomSheetSwitcher and Lightbox, a Picture-in-Picture window), each decides focus return from the page's document and last input, so focus returns to the frame element or the page, or without the ring the last input in its document calls for (FR9) |
+| DropdownMenuSubMenu, PowerSearchEditPopover | local only | Must migrate from component-specific listeners or registries to the shared owner |
The rows marked partial or local are current adoption gaps against FR1, and the
rows naming an implementation gap are gaps against FR8 or FR9. They are not
@@ -259,18 +260,18 @@ modality, positioning, outside-dismissal, and open-state contracts.
## Verification map
-| Contract | Verification | Representative members and states | Mutation or failure expectation |
-| ------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| FR1, FR2, FR4, FR5 | `useLayerDismissal.test.tsx`; `BottomSheetSwitcher.test.tsx`; `ContextMenu.test.tsx`; `CommandPalette.test.tsx` | synthetic provider depth, same-DOM containment, non-modal switcher nesting, ContextMenu nested layers, CommandPalette descendant nesting, unrelated, blocking, content-handled, present/absent | Removing depth, presence filtering, or event deferral sends Escape to the wrong surface |
-| FR2, FR3, FR4, FR6 | `layerDismissalInvariants.test.tsx` | nested same-DOM Dialogs, Lightbox over Dialog, Dialog in BottomSheet, platform cancel, IME | One request closes two surfaces, closes a host before its child, or dismisses during composition |
-| FR1, FR2, FR3, FR7 | `layerDismissalFamilies.test.tsx` | Dialog, Lightbox, MobileNav, BottomSheet, Tooltip, HoverCard; controlled and blocking states | A family bypasses the stack, a lower member handles a request, or controlled ownership is ignored |
-| FR1 | `useFocusTrap.test.tsx` | active, nested, and deactivated traps with `onEscape` | A dismissible trap stays off the shared stack or nested traps respond together |
-| FR8 | `useLayerDismissal.test.tsx`; `Popover.test.tsx` | members in the page and a same-origin iframe; a Popover alone and inside a Dialog, in an iframe | A press in one document dismisses a member of another, or a host closes over its nested layer |
-| FR8 | `PopoverSecondDocument.a11y.chromium.spec.ts` | a Popover in an iframe and in a Picture-in-Picture window, alone and with one open in the page | A press in the second document misses its own layer or dismisses the page's |
-| FR9 | `DialogSecondDocument.a11y.browser.spec.ts` | a Dialog in an iframe and in a Picture-in-Picture window, closed by Escape or a control inside it, and a Dialog in an iframe opened from the page | Focus lands outside the opener's document, or its ring does not follow the closing input |
-| FR8, FR9 | Real-browser second-document checks; implementation gap: only Dialog and Popover have them | Dialog, Popover, DropdownMenu, MoreMenu, ContextMenu, Selector, MultiSelector, TopNavHeading, TopNavMenu, TopNavMegaMenu, SideNavHeading, SideNavItem, Tooltip and HoverCard, each in a same-origin iframe and in a Picture-in-Picture window: opens and takes Escape in the document it renders in (a Tooltip only when no other member is present), and returns focus in the opener's document | The member opens or ranks in another document, or focus lands on the frame element, the page, or the body |
-| FR8, FR9 | Real-browser second-document checks; implementation gap: none has them | BottomSheet, BottomSheetSwitcher, and Lightbox in a Picture-in-Picture window: opens, takes Escape, and returns focus to its return target there | The surface ranks in the page, or focus lands on the page or the body |
-| FR8 | Source check over Drawer and MobileNav | Drawer and MobileNav rendered from a control in a second document | A page-level surface moves into the second document |
+| Contract | Verification | Representative members and states | Mutation or failure expectation |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR2, FR4, FR5 | `useLayerDismissal.test.tsx`; `BottomSheetSwitcher.test.tsx`; `ContextMenu.test.tsx`; `CommandPalette.test.tsx` | synthetic provider depth, same-DOM containment, non-modal switcher nesting, ContextMenu nested layers, CommandPalette descendant nesting, unrelated, blocking, content-handled, present/absent | Removing depth, presence filtering, or event deferral sends Escape to the wrong surface |
+| FR2, FR3, FR4, FR6 | `layerDismissalInvariants.test.tsx` | nested same-DOM Dialogs, Lightbox over Dialog, Dialog in BottomSheet, platform cancel, IME | One request closes two surfaces, closes a host before its child, or dismisses during composition |
+| FR1, FR2, FR3, FR7 | `layerDismissalFamilies.test.tsx` | Dialog, Lightbox, MobileNav, BottomSheet, Tooltip, HoverCard; controlled and blocking states | A family bypasses the stack, a lower member handles a request, or controlled ownership is ignored |
+| FR1 | `useFocusTrap.test.tsx` | active, nested, and deactivated traps with `onEscape` | A dismissible trap stays off the shared stack or nested traps respond together |
+| FR8 | `useLayerDismissal.test.tsx`; `Popover.test.tsx` | members in the page and a same-origin iframe; a Popover alone and inside a Dialog, in an iframe | A press in one document dismisses a member of another, or a host closes over its nested layer |
+| FR8 | `PopoverSecondDocument.a11y.chromium.spec.ts` | a Popover in an iframe and in a Picture-in-Picture window, alone and with one open in the page | A press in the second document misses its own layer or dismisses the page's |
+| FR9 | `DialogSecondDocument.a11y.browser.spec.ts` | a Dialog in an iframe and in a Picture-in-Picture window, closed by Escape or a control inside it, and a Dialog in an iframe opened from the page | Focus lands outside the opener's document, or its ring does not follow the closing input |
+| FR8, FR9 | Real-browser second-document checks; implementation gap: only Dialog and Popover have them | Dialog, Popover, DropdownMenu, MoreMenu, ContextMenu, Selector, MultiSelector, TopNavHeading, TopNavMenu, TopNavMegaMenu, SideNavHeading, SideNavItem, Tooltip and HoverCard, each in a same-origin iframe and in a Picture-in-Picture window: opens and takes Escape in the document it renders in (an unpinned Tooltip only when no other member is present; a pinned Tooltip or HoverCard before the member beneath it), and returns focus in the opener's document | The member opens or ranks in another document, a pinned Tooltip lets Escape reach the member beneath it, or focus lands on the frame element, the page, or the body |
+| FR8, FR9 | Real-browser second-document checks; implementation gap: none has them | BottomSheet, BottomSheetSwitcher, and Lightbox in a Picture-in-Picture window: opens, takes Escape, and returns focus to its return target there | The surface ranks in the page, or focus lands on the page or the body |
+| FR8 | Source check over Drawer and MobileNav | Drawer and MobileNav rendered from a control in a second document | A page-level surface moves into the second document |
## Decision links
diff --git a/docs/specs/AST-003/spec.md b/docs/specs/AST-003/spec.md
index ef1511eb20..982b01e6ae 100644
--- a/docs/specs/AST-003/spec.md
+++ b/docs/specs/AST-003/spec.md
@@ -29,7 +29,7 @@ affects_consumer_docs: []
{
"scope": "global",
"triggers": {
- "layering": ["FR10", "DEC-1", "DEC-2", "DEC-3", "DEC-5"]
+ "layering": ["FR4", "FR10", "DEC-1", "DEC-2", "DEC-3", "DEC-5", "DEC-6"]
}
}
```
@@ -69,9 +69,12 @@ browsers receive a usable reduced fallback, not equivalent behavior.
- **FR3 — Blocking owners consume without closing.** A blocking owner prevents a
channel from reaching an owner behind it. Required Dialog is the representative
Escape/platform case.
-- **FR4 — Passive dependents never shield owners.** Tooltip is passive. It does
- not win or block dismissal and disappears as a consequence when its associated
- owner or trigger interaction closes.
+- **FR4 — Passive dependents never shield owners.** An unpinned Tooltip is
+ passive. It does not win or block dismissal and disappears as a consequence
+ when its associated owner or trigger interaction closes. A Tooltip or
+ HoverCard that a press pinned open (`component:Tooltip` FR9,
+ `component:HoverCard` FR9) is an active owner: it takes Escape first and
+ closes, and the owner beneath it stays open for that press (DEC-6).
- **FR5 — Associations are explicit.** Every active or blocking owner records an
optional parent owner and an interaction-branch root. A passive dependent
records its associated owner or trigger without creating an owner node or
@@ -187,6 +190,8 @@ Current `main` does not satisfy this spec completely:
- the stack has `close` and `block` but no passive role; Tooltip currently
consumes Escape ahead of associated owners;
+- no Tooltip or HoverCard pins open on a press yet (`component:Tooltip` FR9,
+ `component:HoverCard` FR9);
- no shared owner/branch association graph or outside-branch resolver exists;
- DropdownMenuSubMenu has a local parent-close chain, but outside channels do not
consume shared branch identity;
@@ -205,8 +210,8 @@ Current `main` does not satisfy this spec completely:
and passive roles plus parent-owner and branch-root association. Add pure
eligible-owner and outside-branch resolvers. Preserve the current
Escape/platform contract for existing active/blocking members while migrating.
-2. **Eligibility migration.** Make Tooltip passive and update Tooltip-over-owner
- tests. Keep HoverCard active because it can own interactive content. Migrate
+2. **Eligibility migration.** Make an unpinned Tooltip passive and a pinned
+ Tooltip active, and update Tooltip-over-owner tests. Keep HoverCard active because it can own interactive content. Migrate
CommandPalette and the local Escape implementations tracked by
`family:overlay-dismissal` onto eligible-owner delivery.
3. **Branch migration.** Project DropdownMenuContext's root/submenu chain into a
@@ -233,21 +238,22 @@ Interaction modality continues to follow `architecture:interaction-modality`.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| --------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| FR1–FR6 | Pure registry/resolver tests plus family interaction tests | active, blocking, passive Tooltip, visual-only, controlled owner | Passive surface wins, blocker leaks, or wrong owner closes |
-| FR7–FR10 | Branch resolver tests and real-browser outside interaction | root menu with two submenu levels; parent + child Popover; associated trigger | Outside root leaves submenu open, or child-only outside closes parent |
-| FR11–FR14 | Gesture-counter and browser event-order tests | native light dismiss before/after click; menu button; hover-open; touch; backdrop; swipe | Same gesture reopens any associated trigger or exposed hover reopens panel |
-| FR15–FR20 | Chromium/WebKit native host tests | Toast at root; Toast through one/two modals; CommandPalette above modal; ordinary local Popover | Global surface is behind/inert, loses state, or ordinary overlay becomes global |
-| FR21–FR23 | Supported/unsupported browser matrix and public-doc checks | anchor/fixed/custom; auto/manual; explicit controls; absent feature APIs | Docs promise equivalence or reduced fallback is unusable |
-| IR1–IR3 | API/type tests and mutation tests for resolvers/claims | one-at-a-time channel versus branch channel | One topmost query is reused for outside branches or timestamps replace identity |
-| IR4, IR5 | Public-surface snapshot and atomic change review | local Popover, global Toast, global CommandPalette | Generic global prop appears or unrelated behaviors are coupled in one change |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| FR1–FR6 | Pure registry/resolver tests plus family interaction tests | active, blocking, passive Tooltip, pinned Tooltip and HoverCard over a Dialog, visual-only, controlled owner | Passive surface wins, a pinned surface lets Escape reach the owner beneath, blocker leaks, or wrong owner closes |
+| FR7–FR10 | Branch resolver tests and real-browser outside interaction | root menu with two submenu levels; parent + child Popover; associated trigger | Outside root leaves submenu open, or child-only outside closes parent |
+| FR11–FR14 | Gesture-counter and browser event-order tests | native light dismiss before/after click; menu button; hover-open; touch; backdrop; swipe | Same gesture reopens any associated trigger or exposed hover reopens panel |
+| FR15–FR20 | Chromium/WebKit native host tests | Toast at root; Toast through one/two modals; CommandPalette above modal; ordinary local Popover | Global surface is behind/inert, loses state, or ordinary overlay becomes global |
+| FR21–FR23 | Supported/unsupported browser matrix and public-doc checks | anchor/fixed/custom; auto/manual; explicit controls; absent feature APIs | Docs promise equivalence or reduced fallback is unusable |
+| IR1–IR3 | API/type tests and mutation tests for resolvers/claims | one-at-a-time channel versus branch channel | One topmost query is reused for outside branches or timestamps replace identity |
+| IR4, IR5 | Public-surface snapshot and atomic change review | local Popover, global Toast, global CommandPalette | Generic global prop appears or unrelated behaviors are coupled in one change |
### Completion criteria
This spec is complete only when:
-- Tooltip is passive in Escape/platform and outside-branch coordination;
+- an unpinned Tooltip is passive in Escape/platform and outside-branch
+ coordination, and a pinned Tooltip or HoverCard takes Escape first;
- eligible-owner and associated-branch operations are shared and adopted by all
members named by `family:overlay-dismissal` for their relevant channels;
- outside a dropdown/menu root closes its entire open submenu cascade, while
@@ -273,8 +279,9 @@ This spec is complete only when:
**Decider:** `cixzhang`, `2026-08-30`
Escape and platform close select the topmost eligible active or blocking owner,
-not the topmost visible or registered surface. Tooltip is passive and cannot
-shield a Popover, menu, Dialog, or associated interactive element beneath it.
+not the topmost visible or registered surface. An unpinned Tooltip is passive
+and cannot shield a Popover, menu, Dialog, or associated interactive element
+beneath it; a pinned one is the person's own interaction (DEC-6).
Rejected: letting every visible transient layer consume one Escape. That makes
supplementary information block the interaction the user is trying to dismiss.
@@ -329,6 +336,18 @@ not equivalent positioning, stacking, association, or dismissal behavior.
Rejected: describing the current `display` fallback as a polyfill. It does not
implement the missing browser systems.
+### DEC-6 — A pinned layer is the person's own interaction
+
+**Reference:** `spec:AST-003/DEC-6`
+**Decider:** `cixzhang`, `2026-10-31`
+
+A Tooltip or HoverCard that a press pinned open is something the person asked
+to keep, so it is an active owner and Escape closes it before the owner beneath
+it. A Tooltip that only previews on hover or focus stays passive.
+
+Rejected: keeping every Tooltip passive, which lets Escape close a Dialog behind
+a tip the person pinned.
+
## Open questions
None.
diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md
index 7830f8b39a..cda613d027 100644
--- a/docs/specs/AST-082-native-first-surfaces/spec.md
+++ b/docs/specs/AST-082-native-first-surfaces/spec.md
@@ -85,7 +85,7 @@ depends only on runtimes it can maintain.
announcements). It is the same on every platform that offers the component.
- A platform honors a prop when the prop behaves the way core already defines
for that platform's input type. `tooltip` stays in the core: core defines
- what a tooltip does where there is no hover (Tooltip `touchTrigger`), and a
+ what a tooltip does where there is no hover (Tooltip `pressTrigger`), and a
touch platform behaves that way.
- A prop leaves the core only when a platform that offers the component cannot
match core's defined behavior for its input type. Such a prop belongs to the
diff --git a/docs/specs/AST-090-exit-motion/spec.md b/docs/specs/AST-090-exit-motion/spec.md
index cdda259f2d..613aa362ba 100644
--- a/docs/specs/AST-090-exit-motion/spec.md
+++ b/docs/specs/AST-090-exit-motion/spec.md
@@ -124,13 +124,19 @@ governs them in a touch presentation.
- **FR4 — A leaving surface takes no input.** From the moment its close begins,
no pointer press or key activates anything in a leaving surface's own content.
Toasts that a leaving dialog hosts are not its content (FR13).
-- **FR5 — A leaving surface keeps its dismissal role.** Until it is hidden, a
- leaving surface keeps the dismissal role it had while open (`spec:AST-003`
- FR1). A leaving active or blocking owner stays present on the shared
+- **FR5 — A leaving surface keeps its dismissal role, apart from a closing
+ pinned layer.** Until it is hidden, a leaving surface keeps the dismissal role
+ it had while open (`spec:AST-003` FR1), except a closing pinned `Tooltip` or
+ `HoverCard`, below. A leaving active or blocking owner stays present on the shared
dismissal stack (`family:overlay-dismissal` FR2), so an Escape press or
- platform close request during its exit does not reach an owner beneath it. A
- leaving passive dependent, such as `Tooltip`, stays passive and shields
- nothing (`spec:AST-003` FR4).
+ platform close request during its exit does not reach an owner beneath it,
+ except a closing pinned `Tooltip` or `HoverCard`, which leaves the stack when
+ its exit starts. A
+ leaving passive dependent, such as an unpinned `Tooltip`, stays passive and
+ shields nothing (`spec:AST-003` FR4). A pinned `Tooltip` or `HoverCard` that
+ is closing plays its exit and stops taking Escape once the exit starts: it is
+ no longer the stack's owner, so the member beneath it takes the next Escape
+ (`spec:AST-003` FR4, DEC-6).
- **FR6 — Focus leaves with the close.** A layer surface hands focus back when
its close begins, as it does with the exit off, and from then on its exit is
hidden from assistive technology: a screen reader neither reads nor announces
@@ -199,17 +205,22 @@ governs them in a touch presentation.
it does with the exit off, and its exit plays after that on the runtime's
shared exit copy (INV14), drawn in the top layer where the layer was. Native
close reconciliation stays single-fired (INV6). A leaving active or blocking
- owner keeps its place on the dismissal stack until its exit ends (FR5). A
+ owner keeps its place on the dismissal stack until its exit ends, except a
+ closing pinned Tooltip or HoverCard, which leaves it when its exit starts
+ (FR5). A
leaving Dialog keeps supplying its modal outlet until it is hidden (FR13);
BottomSheet's outlet behavior does not change.
- `architecture:component-style-authoring`: no claim changes. A layer's exit
is the one transient exit copy INV7 allows, made by the shared mechanism and
removed when the exit ends (FR9).
- `family:overlay-dismissal`: no claim changes. A leaving member stays present
- for FR2 until it is hidden, and animation stays member-owned (AV6).
+ for FR2 until it is hidden, except a closing pinned Tooltip or HoverCard,
+ which leaves the stack when its exit starts (FR5), and animation stays
+ member-owned (AV6).
- `spec:AST-003`: no claim changes. A leaving surface keeps its interaction role
- (FR1), and a leaving passive dependent such as `Tooltip` still never shields
- an owner (FR4, DEC-1). A leaving dialog is still the current native modal, so
+ (FR1), a leaving passive dependent such as an unpinned `Tooltip` still never
+ shields an owner (FR4, DEC-1), and a closing pinned `Tooltip` or `HoverCard`
+ gives up Escape when its exit starts (FR4, DEC-6). A leaving dialog is still the current native modal, so
it keeps its outlet and toasts stay operable above it (FR16, FR18).
- `spec:AST-094`: no claim changes. A touch presentation keeps the exit FR7 and
FR8 give it (FR14), and its motion roles stay internal (FR4, DEC-15). The exit
@@ -242,23 +253,23 @@ governs them in a touch presentation.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| -------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1 | Component unit suites run unchanged with default tokens | Every dialog and layer member in a pointer presentation, opened and closed | A surface stays rendered after its close with default tokens |
-| FR2 | Real-browser test under a theme that sets one kind, fine primary pointer | Dialogs on with layers off; layers on with dialogs off; a nested `Theme` | The unset kind animates, or the set kind closes at once |
-| FR3 | Real-browser frame sampling during an exit | A dialog with and without an opener, a fullscreen dialog, a layer in each placement, right-to-left | The surface leaves its entrance path, or keeps the entrance curve |
-| FR4 | Real-browser test | A press and an Enter key on a control inside a leaving surface | The control activates |
-| FR5 | Dismissal invariant tests | Escape during a leaving Dialog or Popover with an owner beneath; Escape during a leaving Tooltip over a Dialog | The owner beneath a leaving owner closes, or a leaving Tooltip absorbs the press |
-| FR6 | Unit and real-browser focus and accessibility-tree tests | Dialog and layer closes, by keyboard and by pointer; the accessibility tree during a layer exit | Dialog focus returns before the dialog is hidden or lands on the body; layer focus waits for the exit; a leaving layer's exit is in the accessibility tree |
-| FR7 | Unit tests | Controlled and uncontrolled closes | A callback or `isOpen` waits for the exit |
-| FR8 | Unit and real-browser tests | Reopen during an exit, unmount during an exit, `Activity` hidden during an exit | The surface disappears and reappears, or stays after unmount |
-| FR9 | Unit test with a suppressed end event; real-browser test with animations and transitions disabled page-wide | Open and close in one update; page-wide `transition: none`; no end event | The surface is present more than 100ms after its exit duration |
-| FR10 | Real-browser test with reduced motion emulated, fine primary pointer | Each kind turned on | An exit plays |
-| FR11 | Real-browser frame sampling during an exit | A hover card, a menu with an open sub-menu, a selector with a search query | The leaving surface shows other content, or none, before it is hidden |
-| FR12 | Token default tests, theme template inventory test, token documentation check | Defaults; the `BottomSheet` closing curve | A default drifts, or `BottomSheet` restates the curve |
-| FR13 | Real-browser test | A toast action pressed, and a toast dismissed, during a dialog exit; the same toast after the dialog is hidden | The toast ignores input or fades with the dialog during the exit, or loses its entries or timers when the dialog is hidden |
-| FR14 | Real-browser test with a coarse primary pointer, after hydration | A Dialog, a Popover, and a menu opened and closed by a finger, with each kind switched off and on; the same surfaces under reduced motion | A switch changes the touch exit, or the surface closes without the exit `spec:AST-094` FR7 and FR8 give it |
-| Platform | Real-browser tests in Chromium and WebKit | A dialog exit and a layer exit with each kind on; a layer close where the Popover API is missing | A layer exit paints outside the top layer or does not play, or a close without the Popover API is delayed |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | Component unit suites run unchanged with default tokens | Every dialog and layer member in a pointer presentation, opened and closed | A surface stays rendered after its close with default tokens |
+| FR2 | Real-browser test under a theme that sets one kind, fine primary pointer | Dialogs on with layers off; layers on with dialogs off; a nested `Theme` | The unset kind animates, or the set kind closes at once |
+| FR3 | Real-browser frame sampling during an exit | A dialog with and without an opener, a fullscreen dialog, a layer in each placement, right-to-left | The surface leaves its entrance path, or keeps the entrance curve |
+| FR4 | Real-browser test | A press and an Enter key on a control inside a leaving surface | The control activates |
+| FR5 | Dismissal invariant tests | Escape during a leaving Dialog or Popover with an owner beneath; Escape during a leaving unpinned Tooltip over a Dialog; Escape during the exit of a pinned Tooltip or HoverCard over a Dialog | The owner beneath a leaving owner closes, a leaving unpinned Tooltip absorbs the press, or a closing pinned Tooltip or HoverCard takes an Escape after its exit starts |
+| FR6 | Unit and real-browser focus and accessibility-tree tests | Dialog and layer closes, by keyboard and by pointer; the accessibility tree during a layer exit | Dialog focus returns before the dialog is hidden or lands on the body; layer focus waits for the exit; a leaving layer's exit is in the accessibility tree |
+| FR7 | Unit tests | Controlled and uncontrolled closes | A callback or `isOpen` waits for the exit |
+| FR8 | Unit and real-browser tests | Reopen during an exit, unmount during an exit, `Activity` hidden during an exit | The surface disappears and reappears, or stays after unmount |
+| FR9 | Unit test with a suppressed end event; real-browser test with animations and transitions disabled page-wide | Open and close in one update; page-wide `transition: none`; no end event | The surface is present more than 100ms after its exit duration |
+| FR10 | Real-browser test with reduced motion emulated, fine primary pointer | Each kind turned on | An exit plays |
+| FR11 | Real-browser frame sampling during an exit | A hover card, a menu with an open sub-menu, a selector with a search query | The leaving surface shows other content, or none, before it is hidden |
+| FR12 | Token default tests, theme template inventory test, token documentation check | Defaults; the `BottomSheet` closing curve | A default drifts, or `BottomSheet` restates the curve |
+| FR13 | Real-browser test | A toast action pressed, and a toast dismissed, during a dialog exit; the same toast after the dialog is hidden | The toast ignores input or fades with the dialog during the exit, or loses its entries or timers when the dialog is hidden |
+| FR14 | Real-browser test with a coarse primary pointer, after hydration | A Dialog, a Popover, and a menu opened and closed by a finger, with each kind switched off and on; the same surfaces under reduced motion | A switch changes the touch exit, or the surface closes without the exit `spec:AST-094` FR7 and FR8 give it |
+| Platform | Real-browser tests in Chromium and WebKit | A dialog exit and a layer exit with each kind on; a layer close where the Popover API is missing | A layer exit paints outside the top layer or does not play, or a close without the Popover API is delayed |
## Decision log
diff --git a/packages/core/src/Field/FieldLabel.spec.md b/packages/core/src/Field/FieldLabel.spec.md
index ecc40a708b..13769a5e57 100644
--- a/packages/core/src/Field/FieldLabel.spec.md
+++ b/packages/core/src/Field/FieldLabel.spec.md
@@ -38,15 +38,15 @@ system_specs: [spec:AST-020/FR1]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `FieldLabel` renders a visible or visually hidden label group for one control or a caller-labelled group, with optional description, optionality indicator, icon, tooltip, label-element BaseProps, and label-element ref. |
-| Behavior | Single-control mode uses a native label; group mode uses a labelled span. A description adds a wrapper div, while caller props and ref stay on the inner label element. Description clicks forward only to one associated control. |
-| End-user impact | People can identify a control or group, hear supporting text separately from its name, and activate eligible controls from the complete visible label area; a tap on the tooltip's info icon opens or closes the tooltip instead (DEC-1). The current tooltip remains unavailable to keyboard and screen-reader users. |
-| Builder impact | Builders provide stable control and description IDs, select group mode when labelling a composite, and wire `aria-labelledby` or `aria-describedby` on the controlled surface. |
-| Compatibility/readiness | Records shipped behavior and DEC-1; no API, default, or DOM change. Group mode renders a span while public types promise label props and ref, and the tooltip icon exposes its content only to a pointer; both are listed under Current-state impact. |
-| Review checks | Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, or undocumented public prop. |
-| Governing rules | Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1, SC 4.1.2; `architecture:public-component-api/INV1,INV5–INV9,INV12`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR1`. |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `FieldLabel` renders a visible or visually hidden label group for one control or a caller-labelled group, with optional description, optionality indicator, icon, tooltip, label-element BaseProps, and label-element ref. |
+| Behavior | Single-control mode uses a native label; group mode uses a labelled span. A description adds a wrapper div, while caller props and ref stay on the inner label element. Description clicks forward only to one associated control. |
+| End-user impact | People can identify a control or group, hear supporting text separately from its name, and activate eligible controls from the complete visible label area. Help behind the info button opens by pointer, touch, keyboard, and screen reader, and a tap, click, or key press on it never changes the control (DEC-1); the shipped icon stays pointer-only, and a mouse click on it still activates the control, until FR9 is built. |
+| Builder impact | Builders provide stable control and description IDs, select group mode when labelling a composite, and wire `aria-labelledby` or `aria-describedby` on the controlled surface. |
+| Compatibility/readiness | No API or default change; with `labelTooltip`, the info trigger becomes an InfoTip button after the label element, and a mouse click on it stops activating the control (FR9, DEC-1; not yet built). Group mode renders a span while public types promise label props and ref, and the shipped tooltip icon exposes its content only to a pointer; both are listed under Current-state impact. |
+| Review checks | Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, an info trigger inside the label element or one whose press activates the control, or undocumented public prop. |
+| Governing rules | Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1, SC 4.1.2; `component:InfoTip`; `architecture:public-component-api/INV1,INV5–INV9,INV12`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR1`. |
This table is a review projection; the body below is authoritative.
@@ -57,7 +57,7 @@ This table is a review projection; the body below is authoritative.
## Compatibility and migration
- Released default preserved: yes.
-- Compatibility class: records shipped behavior and DEC-1; no public prop, default, export, or DOM change.
+- Compatibility class: no public prop, default, or export change. With `labelTooltip`, the info trigger moves from an icon inside the label element to a `component:InfoTip` button after it, in one inline-flex row wrapping both, and a press on it, by any pointer or key, does not activate the control (FR9, DEC-1). Callers see that extra wrapper only when `labelTooltip` is set; their class, `xstyle`, and ref stay on the label element (FR6).
- Controlled/uncontrolled behavior: not applicable.
- Migration decision: DEC-1 needs no caller change; the ref typing is OQ1.
@@ -76,33 +76,33 @@ This table is a review projection; the body below is authoritative.
- The associated control or group's value, disabled semantics, focus model, keyboard behavior, and ARIA wiring beyond the label's own IDs.
- The caller's layout around the label group.
-- Tooltip surface behavior and icon rendering, which delegate to Tooltip and `component:Icon`; FieldLabel still owns whether its chosen trigger exposes that content.
+- The info trigger, its press toggle, and the tooltip surface, which delegate to `component:InfoTip` and through it to `component:Tooltip`; FieldLabel owns where the trigger renders, its name, and that its content is exposed.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ---------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| label mode | single control; group | Chooses a native `<label htmlFor>` or a `<span>` referenced through `aria-labelledby`. | All uses. | single control | `component:FieldLabel` | released | Boolean-constrained; see OQ1 for root/ref typing. |
-| label visibility | visible; visually hidden | Keeps label and description accessible while removing their layout space when hidden. | Both label modes. | visible | `component:FieldLabel` | released | Boolean-constrained. |
-| optionality marker | none; optional; required | Shows the localized exception to FormLayout's form-level optionality default. | Visible and hidden labels. | none | `component:FieldLabel` | released | When both booleans are true, optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required. |
-| leading icon | absent; icon type; rendered node | Adds visual content before the label text. | Both label modes. | absent | `component:FieldLabel` | released | Rendered through the shared icon slot. |
-| explanatory tooltip | absent; localized string | Adds the shared info-icon anchor and tooltip surface after the label; a tap on the icon opens or closes the tooltip without activating the control (FR9). | Both label modes. | absent | `component:FieldLabel` | released | The anchor is pointer-only (FR8 gap). |
-| supporting description | absent; rendered node with optional explicit ID | Keeps supporting content separate from the accessible name and available for description. | Both label modes. | absent | `component:FieldLabel` | released | Missing ID leaves association to the caller. |
-| description activation | forwarding; non-forwarding | For one control, noninteractive description clicks mirror native-label activation. | Single mode only. | forwarding | `component:FieldLabel` | released | Group mode and interactive descendants do not forward. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| label mode | single control; group | Chooses a native `<label htmlFor>` or a `<span>` referenced through `aria-labelledby`. | All uses. | single control | `component:FieldLabel` | released | Boolean-constrained; see OQ1 for root/ref typing. |
+| label visibility | visible; visually hidden | Keeps label and description accessible while removing their layout space when hidden. | Both label modes. | visible | `component:FieldLabel` | released | Boolean-constrained. |
+| optionality marker | none; optional; required | Shows the localized exception to FormLayout's form-level optionality default. | Visible and hidden labels. | none | `component:FieldLabel` | released | When both booleans are true, optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required. |
+| leading icon | absent; icon type; rendered node | Adds visual content before the label text. | Both label modes. | absent | `component:FieldLabel` | released | Rendered through the shared icon slot. |
+| explanatory tooltip | absent; localized string | Adds a `component:InfoTip` after the label element; a tap, click, or key press on it opens or closes the tooltip without activating the control (FR9). | Both label modes. | absent | `component:FieldLabel` | released | The shipped anchor is pointer-only until FR9 is built (FR8 gap). |
+| supporting description | absent; rendered node with optional explicit ID | Keeps supporting content separate from the accessible name and available for description. | Both label modes. | absent | `component:FieldLabel` | released | Missing ID leaves association to the caller. |
+| description activation | forwarding; non-forwarding | For one control, noninteractive description clicks mirror native-label activation. | Single mode only. | forwarding | `component:FieldLabel` | released | Group mode and interactive descendants do not forward. |
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| FR1 | Single-control mode renders `<label htmlFor={inputID}>`; group mode renders a non-label element with `labelID` for caller-owned `aria-labelledby`. | Established public interface; HTML and ARIA semantics |
-| FR2 | Visible and hidden labels retain the label text; hidden label and description boxes remain in the accessibility tree and leave no layout slot. | Established public interface |
-| FR3 | Descriptions remain siblings of the label so they do not enter the control's accessible name. Noninteractive description clicks forward to one eligible control; group labels and interactive descendants do not forward activation. | Established public interface; native label behavior |
-| FR4 | FormLayout optionality suppresses the matching visible marker; without a form default, the requested marker is localized and shown. When both flags are true, optional wins, except inside a FormLayout whose default is optional, where the optional marker is suppressed and the required marker shows. | Established public interface and current tests |
-| FR5 | Label icons, tooltip anchors, required/optional text, and description content preserve source order. The label element uses a horizontal flex row; the optional label/description wrapper uses block flow. All component-owned spacing is logical or direction-neutral. | Established public interface and source observation |
-| FR6 | Accepted data, ARIA, DOM, class, style, event, and `xstyle` inputs compose on the label element without replacing the component-owned target or association. When a description renders, the outer wrapper is layout-only and caller props stay on the inner label element. | `architecture:public-component-api/INV5–INV7` |
-| FR7 | The public ref and label-element props MUST describe the element FieldLabel renders in each mode; which root element and public type group mode uses is OQ1. Implementation gap: group mode renders a `<span>` while the public BaseProps and ref types are fixed to `HTMLLabelElement`. | `architecture:public-component-api/INV8,INV9`; current runtime/types |
-| FR8 | The optional tooltip's explanatory content MUST be reachable by keyboard (WCAG 2.2 SC 2.1.1) and its trigger MUST have an accessible name and role (WCAG 2.2 SC 4.1.2). Implementation gap: it anchors to an anonymous, nonfocusable info icon, so the content is pointer-only. | WCAG 2.2 SC 2.1.1, SC 4.1.2; `spec:AST-020/FR1` |
-| FR9 | A tap on the tooltip's info icon, by finger or pen, opens or closes the tooltip as `component:Tooltip` FR5 states under `touchTrigger="tap"`, and does not activate the associated control. A mouse click on the icon activates the control like the rest of the label, and hover shows the tooltip. | DEC-1 |
+| ID | Invariant | Basis |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| FR1 | Single-control mode renders `<label htmlFor={inputID}>`; group mode renders a non-label element with `labelID` for caller-owned `aria-labelledby`. | Established public interface; HTML and ARIA semantics |
+| FR2 | Visible and hidden labels retain the label text; hidden label and description boxes remain in the accessibility tree and leave no layout slot. | Established public interface |
+| FR3 | Descriptions remain siblings of the label so they do not enter the control's accessible name. Noninteractive description clicks forward to one eligible control; group labels and interactive descendants do not forward activation. | Established public interface; native label behavior |
+| FR4 | FormLayout optionality suppresses the matching visible marker; without a form default, the requested marker is localized and shown. When both flags are true, optional wins, except inside a FormLayout whose default is optional, where the optional marker is suppressed and the required marker shows. | Established public interface and current tests |
+| FR5 | Label icons, tooltip anchors, required/optional text, and description content preserve source order. The label element uses a horizontal flex row; the optional label/description wrapper uses block flow. With `labelTooltip`, one inline-flex row wraps the label element and the InfoTip that follows it (FR9). All component-owned spacing is logical or direction-neutral. | Established public interface and source observation |
+| FR6 | Accepted data, ARIA, DOM, class, style, event, and `xstyle` inputs compose on the label element without replacing the component-owned target or association. When a description renders, the outer wrapper is layout-only and caller props stay on the inner label element; the `labelTooltip` row (FR9) is layout-only in the same way, so caller class, `xstyle`, and ref stay on the label element. | `architecture:public-component-api/INV5–INV7` |
+| FR7 | The public ref and label-element props MUST describe the element FieldLabel renders in each mode; which root element and public type group mode uses is OQ1. Implementation gap: group mode renders a `<span>` while the public BaseProps and ref types are fixed to `HTMLLabelElement`. | `architecture:public-component-api/INV8,INV9`; current runtime/types |
+| FR8 | The optional tooltip's explanatory content MUST be reachable by keyboard (WCAG 2.2 SC 2.1.1) and its trigger MUST have an accessible name and role (WCAG 2.2 SC 4.1.2); FR9's InfoTip button meets both. Implementation gap: the shipped trigger is an anonymous, nonfocusable info icon, so the content is pointer-only until FR9 is built. | WCAG 2.2 SC 2.1.1, SC 4.1.2; `spec:AST-020/FR1` |
+| FR9 | With `labelTooltip`, FieldLabel renders `component:InfoTip` with that content after the label element and outside it, and wraps the label element and the InfoTip in one inline-flex row, as it wraps the label and description, so no button sits inside a `<label>`; caller class, `xstyle`, and ref stay on the label element, and the row renders only when `labelTooltip` is set. With `isLabelHidden`, the InfoTip is visually hidden with the label, leaves no layout slot (FR2), and becomes visible while it has keyboard focus (WCAG 2.4.7); the button's name is a localized string that includes the label text ("About Auto-save"). A tap, click, Enter, or Space on the info trigger opens or closes the tooltip (`component:Tooltip` FR9) and never activates, focuses, or toggles the associated control; hover and focus preview it. Implementation gap: the shipped icon sits inside the label element; a tap by finger or pen opens or closes the tooltip without activating the control, but a mouse click on it also activates the control (Current-state impact). | DEC-1; HTML label content model; WCAG 2.2 SC 2.1.1, SC 2.4.7, SC 4.1.2 |
### Allowed variation
@@ -112,23 +112,23 @@ This table is a review projection; the body below is authoritative.
### Representative states
-| State | Required invariant | Allowed variation |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
-| single label | Native label association reaches the one control. | Visible or visually hidden. |
-| group label | Label element is not a literal label and is referenceable by `labelID`. | Caller owns group role and `aria-labelledby`. |
-| description | Supporting content remains outside the label and may expose `descriptionID`. | Text or structured content. |
-| optional or required | One localized exception marker follows label text. | Suppressed when it matches FormLayout's default. |
-| disabled presentation | Label uses disabled text treatment and no pointer cursor. | Associated control owns actual disabled state. |
-| icon and tooltip | Shared Icon and Tooltip render their owned paint; the tooltip trigger is keyboard-reachable and named (FR8). Implementation gap: the anchor is nonfocusable and unnamed. | Either slot may be absent. |
+| State | Required invariant | Allowed variation |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| single label | Native label association reaches the one control. | Visible or visually hidden. |
+| group label | Label element is not a literal label and is referenceable by `labelID`. | Caller owns group role and `aria-labelledby`. |
+| description | Supporting content remains outside the label and may expose `descriptionID`. | Text or structured content. |
+| optional or required | One localized exception marker follows label text. | Suppressed when it matches FormLayout's default. |
+| disabled presentation | Label uses disabled text treatment and no pointer cursor. | Associated control owns actual disabled state. |
+| icon and tooltip | Shared Icon and InfoTip render their owned paint; the InfoTip button follows the label element, is keyboard-reachable and named, and its press never reaches the control (FR8, FR9). Implementation gap: the shipped anchor is nonfocusable, unnamed, and inside the label. | Either slot may be absent. |
### Transformation and precedence order
- **ORD1 — Optionality.** The FormLayout default suppresses its matching marker first; then optional wins when both local booleans are true.
-- **ORD2 — Label-element composition.** Component target and base styles apply before caller `xstyle`, class, and inline style composition on the label element; association and label-element choice remain component-owned. An optional description adds a layout wrapper without retargeting those inputs.
+- **ORD2 — Label-element composition.** Component target and base styles apply before caller `xstyle`, class, and inline style composition on the label element; association and label-element choice remain component-owned. An optional description, or a `labelTooltip` row (FR9), adds a layout wrapper without retargeting those inputs.
### Performance and resources
-- **PR1 — No retained resource.** FieldLabel owns no global listener, observer, timer, or external store. Description activation reuses the shared input-container hook with local refs, and a `labelTooltip` brings the shared Tooltip's listeners and layer.
+- **PR1 — No retained resource.** FieldLabel owns no global listener, observer, timer, or external store. Description activation reuses the shared input-container hook with local refs, and a `labelTooltip` brings InfoTip's, and so Tooltip's, listeners and layer.
## Accessibility contract
@@ -137,7 +137,9 @@ This table is a review projection; the body below is authoritative.
- **AR3 — Hidden labels.** Visually hidden label and description content remain programmatically available.
- **AR4 — Activation boundary.** Description activation never hijacks interactive descendants and never forwards from a group label to one control.
- **AR5 — Tooltip reachability.** Tooltip content MUST be reachable by keyboard
- (WCAG 2.2 SC 2.1.1) through a named trigger (SC 4.1.2) (FR8). Implementation gap: the anonymous, nonfocusable anchor exposes it only to a pointer.
+ (WCAG 2.2 SC 2.1.1) through a named trigger (SC 4.1.2), the InfoTip button
+ that follows the label (FR8, FR9). Implementation gap: until FR9 is built,
+ the anonymous, nonfocusable anchor exposes it only to a pointer.
## Design relationships
@@ -151,18 +153,18 @@ No current repository design record governs component-local visual tuning. The i
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| FR1–FR3, AR1–AR4 | `FieldLabel.test.tsx` association, ref, and description-forwarding cases; `FieldLabelAudit.a11y.chromium.spec.ts` default, custom-theme, RTL, and narrow cases in light and dark | Single, group, description, interactive description child | A wrong label element, lost association, nested description, or forwarded group or interactive click fails. Evidence gap: no test asserts the hidden label and description leave no layout slot. | `audit:FieldLabel/accessibility` |
-| FR4, ORD1 | `FieldLabel.test.tsx` optional, required, both-set, and i18n cases; `FormLayout.test.tsx` default-optionality cases through Field | Optional, required, both, localized | A wrong localized marker, required winning over optional, or a marker that restates the form default fails. | `audit:FieldLabel/behavior` |
-| FR5 | `FieldLabel.test.tsx` label-icon, tooltip, and tooltip-with-optional cases | Icon, tooltip, optionality | A missing icon or tooltip anchor fails. Evidence gap: no test asserts source order, the flex row, or logical spacing. | `audit:FieldLabel/layout` |
-| FR6, ORD2 | `FieldLabel.test.tsx` ref, layout-item, and label-target cases; `themingTargets.test.ts` | Ref; composed target; with a description wrapper | A dropped ref or a lost `field-label` target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts caller class, style, `xstyle`, data, and event props on the inner label element with a description wrapper. | `audit:FieldLabel/api` |
-| FR7 | Evidence gap: no type test pins the public ref and props against the rendered group span | — | — | `audit:FieldLabel/api` |
-| FR8, AR5 | `FieldLabelAudit.a11y.chromium.spec.ts` tooltip-anchor count | Tooltip present | The audit records the one anonymous, nonfocusable anchor; it changes when the FR8 gap closes. | `audit:FieldLabel/accessibility` |
-| FR9 | `FieldLabel.test.tsx` finger-tap, pen-tap, and mouse-click checkbox cases; `FieldLabelTap.a11y.chromium.spec.ts` touch-tap and mouse-click text-field cases | Checkbox; text field | A tap that toggles or focuses the control, or a mouse click that does not activate it, fails. | `audit:FieldLabel/accessibility` |
-| PR1 | Evidence gap: no test asserts the absence of retained resources | — | — | `audit:FieldLabel/code-health` |
-| Documentation | `docPropLiterals.test.ts`; `docPropReferences.test.ts` | Documented props and defaults | A documented literal or prop reference that drifts from the source type fails. | `audit:FieldLabel/docs` |
-| RTL applicability | `apps/storybook/rtl-audit/verified-not-applicable.json` entry for `core/FieldLabel` | Checked-in FieldLabel stories | A story that gains directional placement or behavior makes the not-applicable entry stale. | `audit:FieldLabel/i18n-rtl` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
+| FR1–FR3, AR1–AR4 | `FieldLabel.test.tsx` association, ref, and description-forwarding cases; `FieldLabelAudit.a11y.chromium.spec.ts` default, custom-theme, RTL, and narrow cases in light and dark | Single, group, description, interactive description child | A wrong label element, lost association, nested description, or forwarded group or interactive click fails. Evidence gap: no test asserts the hidden label and description leave no layout slot. | `audit:FieldLabel/accessibility` |
+| FR4, ORD1 | `FieldLabel.test.tsx` optional, required, both-set, and i18n cases; `FormLayout.test.tsx` default-optionality cases through Field | Optional, required, both, localized | A wrong localized marker, required winning over optional, or a marker that restates the form default fails. | `audit:FieldLabel/behavior` |
+| FR5 | `FieldLabel.test.tsx` label-icon, tooltip, and tooltip-with-optional cases | Icon, tooltip, optionality | A missing icon or tooltip anchor fails. Evidence gap: no test asserts source order, the flex row, or logical spacing; and, until FR9 is built, the `labelTooltip` row with the InfoTip after the label element. | `audit:FieldLabel/layout` |
+| FR6, ORD2 | `FieldLabel.test.tsx` ref, layout-item, and label-target cases; `themingTargets.test.ts` | Ref; composed target; with a description wrapper | A dropped ref or a lost `field-label` target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts caller class, style, `xstyle`, data, and event props on the inner label element with a description wrapper, or, until FR9 is built, with the `labelTooltip` row. | `audit:FieldLabel/api` |
+| FR7 | Evidence gap: no type test pins the public ref and props against the rendered group span | — | — | `audit:FieldLabel/api` |
+| FR8, AR5 | `FieldLabelAudit.a11y.chromium.spec.ts` tooltip-anchor count | Tooltip present | The audit records the one anonymous, nonfocusable anchor; once FR9 is built it asserts one named InfoTip button outside the label element. | `audit:FieldLabel/accessibility` |
+| FR9 | `FieldLabel.test.tsx` finger-tap, pen-tap, and mouse-click checkbox cases; `FieldLabelTap.a11y.chromium.spec.ts` touch-tap and mouse-click text-field cases; evidence gap until built: Enter and Space on the InfoTip button, the button's place outside the label, and the hidden-label cases | Checkbox, text field, and Switch labels; finger, pen, mouse, Enter, and Space; `isLabelHidden` with keyboard focus on the InfoTip | A tap that toggles or focuses the control fails today. Until FR9 is built the mouse-click cases assert the shipped activation; once built, a click or key press on the info trigger that activates, focuses, or toggles the control, an info button inside the label element, a trigger without the label in its name, or a hidden label's InfoTip that takes layout space or stays invisible while focused fails. | `audit:FieldLabel/accessibility` |
+| PR1 | Evidence gap: no test asserts the absence of retained resources | — | — | `audit:FieldLabel/code-health` |
+| Documentation | `docPropLiterals.test.ts`; `docPropReferences.test.ts` | Documented props and defaults | A documented literal or prop reference that drifts from the source type fails. | `audit:FieldLabel/docs` |
+| RTL applicability | `apps/storybook/rtl-audit/verified-not-applicable.json` entry for `core/FieldLabel` | Checked-in FieldLabel stories | A story that gains directional placement or behavior makes the not-applicable entry stale. | `audit:FieldLabel/i18n-rtl` |
## Current-state impact
@@ -170,15 +172,21 @@ No current repository design record governs component-local visual tuning. The i
props and ref are typed for `HTMLLabelElement`, against
`architecture:public-component-api` INV8 and INV9; the fix is OQ1.
- **Tooltip reachability (FR8, AR5).** The label tooltip is pointer-only,
- against WCAG 2.2 SC 2.1.1 and 4.1.2.
+ against WCAG 2.2 SC 2.1.1 and 4.1.2, until FR9's InfoTip is built.
+- **A mouse click on the info icon activates the control (FR9).** The shipped
+ icon sits inside the label element; a finger or pen tap opens its help
+ without activating the control, but a mouse click on it also focuses or
+ toggles the control.
## Decision log
-- **DEC-1 — A tap on the info icon is for its help.** A tap on the
- tooltip's info icon, by finger or pen, opens or closes the tooltip and does not
- activate the label's control, so asking for help never toggles a switch or
- focuses a field. A mouse click on the icon keeps native label activation,
- and hover shows the help. Rejected: leaving the tap to the label.
+- **DEC-1 — A press on the info trigger is for its help.** A tap, click,
+ Enter, or Space on the label's info trigger opens or closes the help and
+ never activates the label's control, so asking what a setting does never
+ toggles a switch or focuses a field, for any pointer or key. The trigger is
+ `component:InfoTip`, the info-icon preset over Tooltip's press toggle, after
+ the label element, because a `<label>` may contain no control other than the
+ one it labels. Rejected: leaving the tap, or a mouse click, to the label.
The label-element and ref typing is OQ1.
diff --git a/packages/core/src/HoverCard/HoverCard.spec.md b/packages/core/src/HoverCard/HoverCard.spec.md
index a35bbece50..f170195ab0 100644
--- a/packages/core/src/HoverCard/HoverCard.spec.md
+++ b/packages/core/src/HoverCard/HoverCard.spec.md
@@ -9,7 +9,7 @@ superseded_by: null
approved_by: cixzhang
approved_at: 2026-10-28
owners: [cixzhang]
-review_triggers: [behavior, theming, accessibility]
+review_triggers: [public-api, behavior, theming, accessibility]
verified_by:
[
packages/core/src/HoverCard/HoverCard.test.tsx,
@@ -25,24 +25,25 @@ architecture:
architecture:component-theming-surface,
architecture:interaction-modality,
architecture:layer-runtime,
+ architecture:public-component-api,
]
contributing: []
-system_specs: []
+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`, `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `hover-card`. |
-| Behavior | A floating card of rich, possibly interactive content anchored to a trigger. It opens on hover after `delay`, on focus, and on a qualifying tap, 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 advertises; without, a group that describes the trigger. |
-| 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 popup dialog or as the trigger's description. |
-| Builder impact | None. |
-| Compatibility/readiness | Records shipped behavior; no public change. Seven 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, or `aria-expanded` set on a trigger whose role does not support it. |
-| Governing rules | WCAG 1.4.13; `family:overlay-dismissal`; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract | `HoverCard` with `children` (trigger), `content`, `label`, `placement` (`above`), `alignment` (`center`), `delay` (300), `hideDelay` (200), `focusTrigger`, `pressTrigger` (`none`), `touchTrigger` (`tap` deprecated by `component:Tooltip` DEP-0016), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `hover-card`. `useHoverCard` takes the same `pressTrigger` and `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 qualifying tap, 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 advertises; without, a group that describes the trigger. With `pressTrigger="toggle"`, hover and focus preview it, and a click, tap, Enter, or Space on a button trigger pins it open until Escape, a second press, a press outside, or focus leaving. |
+| 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 popup dialog or as the trigger's description. With the toggle, a pinned card stays open while people read or use it, whatever the pointer does. |
+| Builder impact | A trigger whose information lives only in the card passes `pressTrigger="toggle"` and a button trigger (DEC-1). `touchTrigger="tap"` callers migrate by trigger kind: the deprecating release's codemod rewrites icon and span triggers and reports the rest (`component:Tooltip` DEP-0016), and `component:Tooltip` CLN-0024 names each remaining kind's replacement at the next minor. |
+| Compatibility/readiness | Additive `pressTrigger`, default `none`; `touchTrigger="tap"` deprecated and `touchTrigger` folded into `pressTrigger` at the next minor (`component:Tooltip` DEP-0016, CLN-0024). FR9, FR10, and AR3 are not yet built; eight further 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, or `aria-expanded` set on a trigger whose role does not support it, a pinned card that closes on pointer leave, or a non-button toggle trigger without the development warning. |
+| Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (deprecation); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
This table is a review projection; the body below is authoritative.
@@ -55,17 +56,41 @@ Consumer usage lives in `HoverCard.doc.mjs`.
## Compatibility and migration
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
+- Released default preserved: the defaults stay `pressTrigger="none"` and
+ `touchTrigger="auto"`. In patch releases `auto` keeps its released
+ behavior: a tap opens the card unless the trigger itself performs an
+ action. The one exception is a disabled control, which is not an action, so
+ its reason opens on a tap; that restoration ships on its own as a patch
+ `[fix]`. FR5's walk, under which a tap that already acts on a control around
+ the trigger does not open the card, needs app code where a hint-only
+ trigger sits inside a control (it declares `pressTrigger="toggle"`), so it
+ is a breaking change under `spec:AST-017` FR1 and DEC-17 and ships with
+ CLN-0024 in the next minor; no caller's behavior changes in a patch
+- Compatibility class: additive `pressTrigger`; `touchTrigger="tap"` is
+ deprecated; FR5's walk is a breaking change for the next minor
+ (`component:Tooltip` CLN-0024); no DOM or styling change without
+ `pressTrigger`
- Controlled/uncontrolled behavior: uncontrolled by default; `isOpen` forces the
state, and a controlled card reports close requests through
- `onOpenChange(false)` without closing itself (FR7)
-- Migration decision: none
+ `onOpenChange(false)` without closing itself (FR7); under
+ `pressTrigger="toggle"` a press on a controlled card reports the toggled
+ value through `onOpenChange` and does not change the state itself (FR9)
+- Migration decision: `component:Tooltip` DEP-0016, then CLN-0024 in the next
+ minor; both cover HoverCard's and `useHoverCard`'s `touchTrigger`, with the
+ same codemods, and CLN-0024 brings FR5's walk to `auto`
Consumer migration instructions belong in consumer docs and release notes.
## Current-state impact
+- **A tap inside a control still opens the card.** The shipped
+ `touchTrigger="auto"` asks only whether the trigger itself performs an action,
+ so a name or ID inside a clickable card opens its card on the tap that opens
+ the card behind it. The walk ships with `component:Tooltip` CLN-0024 (FR5,
+ DEC-1).
+- **Press-to-pin is not built.** `pressTrigger`, its toggle (FR9), and the
+ trigger wiring and announcement (FR10) are specified and not implemented.
+ `touchTrigger="tap"` is the shipped way to open on every tap.
- **A held-closed card still opens on focus.** With `isOpen={false}`, the hover
path stays shut but focus on the trigger opens the card, so a caller cannot
hold it closed. Escape then only reports `onOpenChange(false)`, which the
@@ -96,6 +121,7 @@ Consumer migration instructions belong in consumer docs and release notes.
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.
+ A card pinned by a press (FR9) is held whatever the pointer does.
- **Mixed text children get no trigger.** Text children that reach React as
several strings, such as `Edited {when}`, have no element to attach to: no
focusable span or popup attributes are added, and hover and focus never open
@@ -106,7 +132,8 @@ Consumer migration instructions belong in consumer docs and release notes.
**Owns**
- Trigger wiring, open and close behavior per input, card semantics, and the
- `hover-card` surface (FR1–FR8).
+ `hover-card` surface (FR1–FR8), including the press toggle and the trigger
+ state it sets (FR9, FR10).
**Does not own / non-goals**
@@ -119,24 +146,27 @@ Consumer migration instructions belong in consumer docs and release notes.
## 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 (FR4's gap), always, or never. | Every trigger. | `auto` | `component:HoverCard` | Stable | TypeScript rejects other values. |
-| Touch trigger | `auto`, `tap`, `none` | Whether a tap opens it: unless the trigger performs its own action, always, never. | Touch without hover. | `auto` | `component:HoverCard` | Stable | TypeScript rejects other values. |
+| 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 (FR4's gap), always, or never. | Every trigger. | `auto` | `component:HoverCard` | Stable | TypeScript rejects other values. |
+| Press trigger | `none`, `toggle` | Whether a click, tap, Enter, or Space on the trigger pins the card open: never, leaving taps to `touchTrigger`, or on every press (FR9). | Button triggers; a non-button trigger keeps tap-only opening (FR9). | `none` | `component:HoverCard` | Stable | TypeScript rejects other values. |
+| Touch trigger | `auto`, `tap`, `none` | Whether a tap opens it: unless the tap already acts, as the innermost control around the tapped element decides (DEC-1); always; never. Ignored under `pressTrigger="toggle"`. | Touch without hover. | `auto` | `component:HoverCard` | Stable; `tap` deprecated (`component:Tooltip` DEP-0016); folds into `pressTrigger` (CLN-0024) | 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: a single string or number child is wrapped in a focusable inline span; element `children` attach to their first element inside an inline-safe wrapper. | Current source and tests |
-| FR3 | With `label`, the card is `role="dialog"` named by `label`; the trigger gets `aria-haspopup="dialog"` and, only when its role supports it, `aria-expanded`, each replacing the trigger's own value while the card is wired, plus `aria-controls` naming the card while open, merged with the trigger's own; 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). Implementation gap: under `auto` the tab order is read only when the trigger's listeners attach, on mount and on a re-render that re-attaches them, so a trigger rendered with `tabindex="-1"` does not open on focus until such a re-render follows its move into the tab order (Current-state impact). | WCAG 1.4.13; tests |
-| FR5 | On touch, a completed tap opens it per `touchTrigger` when the finger lifts; a touch that becomes a scroll does not. A tap on the card's own content keeps it open; a second tap on the trigger, a tap outside, or a scroll starting outside closes it. | Current source and tests |
-| FR6 | Escape closes a visible card through the shared dismissal stack when it is the topmost layer in the page, so a layer underneath stays open. Implementation gap: a card rendered into another document, such as an iframe or a Picture-in-Picture window, with no layer beneath it is never closed by Escape (Current-state impact). 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. Implementation gap: with `isOpen={false}`, focus on the trigger still opens the card, and Escape then only reports `onOpenChange(false)` (Current-state impact). `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`: a single string or number child) adds a hover cue to the inline trigger. | Current source and tests |
+| 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: a single string or number child is wrapped in a focusable inline span; element `children` attach to their first element inside an inline-safe wrapper. | Current source and tests |
+| FR3 | With `label`, the card is `role="dialog"` named by `label`; the trigger gets `aria-haspopup="dialog"` and, only when its role supports it, `aria-expanded`, each replacing the trigger's own value while the card is wired, plus `aria-controls` naming the card while open, merged with the trigger's own; 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). Implementation gap: under `auto` the tab order is read only when the trigger's listeners attach, on mount and on a re-render that re-attaches them, so a trigger rendered with `tabindex="-1"` does not open on focus until such a re-render follows its move into the tab order (Current-state impact). | WCAG 1.4.13; tests |
+| FR5 | On touch, a completed tap opens it per `touchTrigger` when the finger lifts; a touch that becomes a scroll does not. Under `auto`, a tap that already acts leaves it shut, decided as `component:Tooltip` DEC-1 decides it: the innermost control from the tapped element outward, the trigger included, decides, and a disabled or `aria-disabled` control is not an action (DEC-1). Implementation gap: the walk ships with `component:Tooltip` CLN-0024 in the next minor; until then `auto` asks only whether the trigger itself performs an action, apart from a disabled control (Compatibility and migration). A tap on the card's own content keeps it open; a second tap on the trigger, a tap outside, or a scroll starting outside closes it. Under `pressTrigger="toggle"`, FR9 decides what a tap does and `touchTrigger` is ignored. | Current source and tests |
+| FR6 | Escape closes a visible card through the shared dismissal stack when it is the topmost layer in the page, so a layer underneath stays open. Implementation gap: a card rendered into another document, such as an iframe or a Picture-in-Picture window, with no layer beneath it is never closed by Escape (Current-state impact). 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. Implementation gap: with `isOpen={false}`, focus on the trigger still opens the card, and Escape then only reports `onOpenChange(false)` (Current-state impact). `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`: a single string or number child) adds a hover cue to the inline trigger. | Current source and tests |
+| FR9 | With `pressTrigger="toggle"` and a trigger whose role is `button` (a `<button>` or `role="button"`), a click, a completed tap, Enter, or Space on the trigger pins the card open, and the same press on a pinned card closes it. Hover and focus still preview it per FR4; on touch no preview opens and a tap pins it, while a touch that becomes a scroll pins nothing. A pinned card stays open when the pointer leaves the trigger and the card, and a press on its own content keeps it pinned; Escape (FR6), a second press on the trigger, a press outside the trigger and the card, or focus moving outside them closes it. In a controlled card a press reports the toggled value through `onOpenChange` and does not change the state itself (FR7). A press that pins or closes the layer stops at its trigger: it does not reach a clickable row, card, or container around it, or the control a label names. A trigger whose role is not `button` gets a development warning and keeps tap-only opening: a tap opens the card as `touchTrigger="tap"` does, and no press pins it. Implementation gap: not yet built (Current-state impact). | DEC-1; WCAG 1.4.13, 2.1.1 |
+| FR10 | While `pressTrigger="toggle"` wires a button trigger, the trigger carries `aria-expanded`, `true` only while pinned, and `aria-controls` naming the card while it shows, with or without `label`, each replacing the trigger's own value while wired and restored on cleanup; FR3's popup role and description are kept. When the card pins, a polite live region announces it once: its `label` when it has one, else its text. Implementation gap: not yet built (Current-state impact). | DEC-1; WAI-ARIA 1.2 `aria-expanded` |
### Allowed variation
@@ -171,6 +201,12 @@ Consumer migration instructions belong in consumer docs and release notes.
dismissible, and persistent per WCAG 1.4.13, except FR6's other-document gap,
FR7's held-closed Escape gap, and the pointer-only hold (Current-state
impact).
+- **AR3 — A pinned card is a toggletip.** Under `pressTrigger="toggle"` the
+ trigger is a named button that reports `aria-expanded` and `aria-controls`
+ (FR10); keyboard and touch users pin and close the card without hover (FR9);
+ it is announced once when it pins (FR10); and it persists until Escape, a
+ second press, a press outside, or focus leaving (FR9, WCAG 1.4.13).
+ Implementation gap: not yet built.
## Design relationships
@@ -212,13 +248,14 @@ Consumer migration instructions belong in consumer docs and release notes.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, FR2, FR8 | `HoverCard.test.tsx` render, wrapper, portal, theme font, and SSR tests | Text and element triggers; default open | A stray target, lost font, or hydration mismatch fails. | `audit:HoverCard/anatomy` |
-| FR3, AR1 | `HoverCard.test.tsx` role and trigger-attribute tests | Labelled and unlabelled; supported and unsupported roles | Wrong role, or trigger attributes that are not replaced and restored as stated, fail. | `audit:HoverCard/accessibility` |
-| FR4–FR6, AR2 | `HoverCard.test.tsx` hover, Escape, refocus, and touch tests | Hover, focus, tap, Escape from trigger and content | A card that cannot be reached or dismissed fails. | `audit:HoverCard/behavior` |
-| FR7 | `HoverCard.test.tsx` isEnabled, isDefaultOpen, and onOpenChange tests; `layerDismissalFamilies.test.tsx` controlled HoverCard case | Disabled, default open | Wrong state reporting fails. | `audit:HoverCard/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current target | Missing, extra, or stale mappings fail validation. | `audit:HoverCard/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1, FR2, FR8 | `HoverCard.test.tsx` render, wrapper, portal, theme font, and SSR tests | Text and element triggers; default open | A stray target, lost font, or hydration mismatch fails. | `audit:HoverCard/anatomy` |
+| FR3, AR1 | `HoverCard.test.tsx` role and trigger-attribute tests | Labelled and unlabelled; supported and unsupported roles | Wrong role, or trigger attributes that are not replaced and restored as stated, fail. | `audit:HoverCard/accessibility` |
+| FR4–FR6, AR2 | `HoverCard.test.tsx` hover, Escape, refocus, and touch tests; tap-destination cases an evidence gap until built | Hover, focus, tap, Escape from trigger and content; a trigger inside a link or a clickable card; a disabled control inside a clickable row | A card that cannot be reached or dismissed, or that opens on a tap that already acts, fails. | `audit:HoverCard/behavior` |
+| FR7 | `HoverCard.test.tsx` isEnabled, isDefaultOpen, and onOpenChange tests; `layerDismissalFamilies.test.tsx` controlled HoverCard case | Disabled, default open | Wrong state reporting fails. | `audit:HoverCard/behavior` |
+| FR9, FR10, AR3 | Evidence gap until built: a press-toggle suite in `HoverCard.test.tsx` and a controlled pinned case in `layerDismissalFamilies.test.tsx` | Click, Enter, Space, and tap pin; second press, press outside, focus leaving, and Escape close; pointer leave and presses on the card keep the pin; labelled and unlabelled; non-button trigger; a toggle trigger inside a ClickableCard, an Item row, and a `<label>` | A press that does not pin or close as stated, a pin lost on pointer leave, a missing or stale `aria-expanded` or `aria-controls`, a second announcement, a non-button trigger without the warning or its tap fallback, or a pinning press that also activates the card, row, or labelled control around the trigger, fails. | `audit:HoverCard/behavior` |
+| 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:
@@ -232,7 +269,27 @@ Read from source, with no focused test yet:
## Decision log
-No component-local decision is recorded.
+### DEC-1 — A press pins the card; a tap that already acts stays with its control
+
+**Reference:** `component:HoverCard/DEC-1`
+**Decider:** `cixzhang`, `2026-10-31`
+
+A card keeps previewing on hover and focus, and `pressTrigger="toggle"` adds
+one more open state of the same layer: a press pins it, so people on touch,
+keyboard, or a screen reader can keep it open to read or use it. Components
+declare `pressTrigger="toggle"` where the card is the only home of their
+information, such as a timestamp's details. `touchTrigger="auto"`, the
+default until `touchTrigger` folds into `pressTrigger` at the next minor, is
+the fallback: under it, a tap that already acts does not open the card. The
+walk that decides it starts at the tapped element and the innermost control
+decides; a disabled or `aria-disabled` control is not an action; and an
+element that acts only through a role-less `onClick` is a caller fix, as
+`component:Tooltip` DEC-1 states. The deprecation of `touchTrigger="tap"` and
+the fold are `component:Tooltip` DEP-0016 and CLN-0024, which apply here
+unchanged.
+
+Rejected: judging the trigger alone, which lets one tap open a name's card over
+the card the same tap opened.
## Open questions
diff --git a/packages/core/src/InfoTip/InfoTip.spec.md b/packages/core/src/InfoTip/InfoTip.spec.md
new file mode 100644
index 0000000000..5e8419a05d
--- /dev/null
+++ b/packages/core/src/InfoTip/InfoTip.spec.md
@@ -0,0 +1,193 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:InfoTip
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-31
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility]
+verified_by:
+ [
+ packages/lab/src/InfoTip/InfoTip.test.tsx,
+ packages/core/src/Tooltip/Tooltip.test.tsx,
+ scripts/check-knowledge.mjs,
+ ]
+modules: []
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:public-component-api,
+ architecture:icon-resolution-and-component-slots,
+ ]
+contributing: []
+system_specs: [spec:AST-017, spec:AST-094]
+---
+
+# InfoTip component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `InfoTip` from `@astryxdesign/core` with `content`, `label` (a localized "More information"), `size` (`sm`), a `ref` forwarded to the button, and BaseProps' `xstyle`, `className`, and `style`. The `@astryxdesign/lab` export is a deprecated re-export for one release. |
+| Behavior | A named info-icon button wrapped in `component:Tooltip` with `pressTrigger="toggle"`: hover and focus preview the help, and a click, tap, Enter, or Space pins it open until Escape, a second press, a press outside, or focus leaving. |
+| End-user impact | People on a mouse, touch, keyboard, or screen reader can open, keep open, and close the help behind an "i", and hear it once when it pins. |
+| Builder impact | Use InfoTip for help next to a label, value, or metric instead of composing an icon inside Tooltip. Lab callers change the import. |
+| Compatibility/readiness | New in Core; Core has no implementation yet (Current-state impact). The Lab component ships with Tooltip's `touchTrigger="tap"` and an English default name. |
+| Review checks | Reject a layer, listener, timer, or dismissal rule of InfoTip's own, a trigger that is not a named button, an untranslated default name, or a prop beyond those FR3 lists. |
+| Governing rules | `component:Tooltip` FR9, FR10, AR6; `architecture:public-component-api` INV21; `spec:AST-094` FR42; `spec:AST-017` (lifecycle). |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+InfoTip is the info-icon preset over Tooltip's press toggle. It owns the
+trigger button, its icon, its name, and its default, so every "i" in a product
+reads and behaves the same; Tooltip owns when the help opens and closes.
+Consumer usage lives in `InfoTip.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: not yet released in Core; the Lab component's
+ props keep their meaning
+- Compatibility class: additive Core export; the Lab component moves to Core
+ with the same props and opens through `pressTrigger="toggle"` instead of
+ `touchTrigger="tap"`
+- Controlled/uncontrolled behavior: uncontrolled only; open state is Tooltip's
+- Migration decision: DEC-1; the `@astryxdesign/lab` `InfoTip` export stays one
+ release as a deprecated re-export of the Core component, then is removed
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Core has no InfoTip yet.** Only the Lab component ships. It wraps a named
+ button in Tooltip with `touchTrigger="tap"`, so a tap opens the help, hover
+ and focus open it, and nothing pins it (`component:Tooltip` FR9 is not
+ built). Its default name is the English literal "More information" (FR1).
+
+## Ownership boundary
+
+**Owns**
+
+- The trigger button, its info icon, its accessible name and default, and its
+ touch hit area (FR1, AR1).
+- What InfoTip passes to Tooltip (FR2).
+
+**Does not own / non-goals**
+
+- When the help previews, pins, closes, and is announced, its surface, and its
+ Escape order — owned by `component:Tooltip` FR3–FR10 and
+ `family:overlay-dismissal`.
+- Info artwork resolution — owned by the icon registry
+ (`architecture:icon-resolution-and-component-slots`).
+- Rich or interactive help — `component:HoverCard` with
+ `pressTrigger="toggle"`.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ------- | ----------------------- | ------------------------------------------- | ----------------------------------------- | ------- | ------------------- | --------- | -------------------------------- |
+| Size | `xsm`, `sm`, `md`, `lg` | The info icon's size: 12, 16, 20, or 24 px. | Every InfoTip. | `sm` | `component:InfoTip` | Stable | TypeScript rejects other values. |
+
+## Behavioral and layout contract
+
+| ID | Invariant | Basis |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| FR1 | InfoTip renders one `<button type="button">` named by `label`, else the translated `@astryx.infoTip.label` ("More information"), containing the registry's `info` icon at `size`. Implementation gap: the Lab component's default name is an untranslated English literal (Current-state impact). | DEC-1; WCAG 2.2 SC 4.1.2; `architecture:icon-resolution-and-component-slots` |
+| FR2 | InfoTip wraps its button in `component:Tooltip` with `content` and `pressTrigger="toggle"`, and adds no layer, listener, timer, announcement, or dismissal rule of its own: previewing, pinning, closing, the trigger's `aria-expanded` and `aria-controls`, and the announcement are Tooltip's FR3–FR10. Implementation gap: the Lab component passes `touchTrigger="tap"` (Current-state impact). | DEC-1; `architecture:public-component-api` INV21 |
+| FR3 | The public props are `content` (required; short, noninteractive help), `label`, `size`, a `ref` forwarded to the button, and BaseProps' `xstyle`, `className`, and `style`; InfoTip takes no open-state, placement, or trigger props. | DEC-1 |
+| FR4 | The `@astryxdesign/lab` `InfoTip` export re-exports the Core component, marked deprecated with static metadata, for one release, and is then removed. | `spec:AST-017` FR29, FR29a |
+
+### Allowed variation
+
+- **AV1 — Icon artwork.** Themes may replace the registry's `info` artwork.
+- **AV2 — Help text.** `content` varies; it stays short and noninteractive.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------- | ------------------------------------------------------------------ | ----------------- |
+| Closed | A named button with the info icon; `aria-expanded="false"`. | Size. |
+| Preview | Tooltip shows on hover or keyboard focus and describes the button. | — |
+| Pinned | Tooltip stays open, `aria-expanded="true"`, announced once. | — |
+
+### Transformation and precedence order
+
+- **ORD1 — Name.** `label`, then the translated default.
+
+### Performance and resources
+
+- **PR1 — No resource of its own.** InfoTip adds no listener, observer, timer,
+ or layer beyond the shared hit-area watch AR1 requires; Tooltip's are the
+ only others it brings.
+
+## Accessibility contract
+
+- **AR1 — The trigger is a named button.** The button is in the tab order,
+ named (FR1), and, under a coarse pointer, reaches 44 px through an invisible
+ hit area where its neighbors leave room: the hit area never overlaps a
+ neighbor's target and is clamped to half the gap between close neighbors
+ (`spec:AST-094` FR42). Implementation gap: not yet built in Core.
+- **AR2 — The help is a toggletip.** `component:Tooltip` AR6: keyboard and
+ touch users pin and close the help without hover, the button reports
+ `aria-expanded`, and the help is announced once when it pins.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Trigger button | A small round button that holds the icon. | Current Lab source | Supporting | FR1, AR1 |
+| Info icon | The registry's `info` artwork at `size`. | Icon registry | Supporting | FR1 |
+| Help surface | Tooltip's surface with `content`. | `component:Tooltip` | Prominent | FR2 |
+
+## Family and system relationships
+
+- `component:Tooltip` owns the press toggle, preview, announcement, and
+ surface; InfoTip is built entirely on it (DEC-1).
+- `family:overlay-dismissal` owns Escape order through Tooltip.
+- `architecture:icon-resolution-and-component-slots` owns the `info` artwork.
+- InfoTip and Tooltip are one API, for the reason DEC-1 gives: InfoTip is built
+ entirely on Tooltip's toggle and adds no layer, listener, or dismissal rule of
+ its own, as `component:MoreMenu` is built on DropdownMenu.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| FR1, AR1 | `InfoTip.test.tsx` (Lab today) name and button cases; evidence gap until built: the translated default and the coarse-pointer hit area | Default and custom name; each size | A trigger that is not a named button, an untranslated default, or a coarse-pointer hit area that stays under 44 px where its neighbors leave room or reaches a neighbor's target fails. | `audit:InfoTip/accessibility` |
+| FR2, AR2 | Evidence gap until built: Core `InfoTip.test.tsx` press cases over `component:Tooltip`'s press-toggle suite | Hover and focus preview; click, tap, Enter, Space pin; Escape | A press that does not pin, or a listener or layer InfoTip owns, fails. | `audit:InfoTip/behavior` |
+| FR3 | Evidence gap until built: a type test of the public props | `content`, `label`, `size`, `ref`, `xstyle`, `className`, `style` | A prop beyond those, or a `ref` that does not reach the button, fails. | `audit:InfoTip/api` |
+| FR4 | Evidence gap until built: an export test of the Lab re-export | Lab import | A Lab export that is not the Core component, or lacks the deprecation metadata, fails. | `audit:InfoTip/api` |
+
+## Decision log
+
+### DEC-1 — InfoTip is a preset over Tooltip's toggle
+
+**Reference:** `component:InfoTip/DEC-1`
+**Decider:** `cixzhang`, `2026-10-31`
+
+Help behind an "i" is the same job as a tooltip that pins on a press, so
+InfoTip supplies only the named button, its icon, and its default, and is
+built entirely on `component:Tooltip` with `pressTrigger="toggle"`. A component
+built entirely on another public API is one API with it
+(`architecture:public-component-api` INV21, the reasoning `spec:AST-107` DEC-2
+and DEC-3 apply to a component over a public factory), as `component:MoreMenu`
+is over DropdownMenu, so InfoTip adds no second way to do Tooltip's job.
+
+Rejected: a general toggletip component, which would repeat Tooltip's and
+HoverCard's previews.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate Tooltip's open, close, or announcement rules,
+consumer prop tables, or examples. It links to their owners.
diff --git a/packages/core/src/StatusDot/StatusDot.spec.md b/packages/core/src/StatusDot/StatusDot.spec.md
index 7b2414b4e5..ad3e8bea50 100644
--- a/packages/core/src/StatusDot/StatusDot.spec.md
+++ b/packages/core/src/StatusDot/StatusDot.spec.md
@@ -28,22 +28,22 @@ architecture:
architecture:theme-tokens,
]
contributing: []
-system_specs: [spec:AST-009]
+system_specs: [spec:AST-009, spec:AST-094]
---
# StatusDot component contract
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | A fixed 8px status dot with a required theme-extensible `variant` and a required `label`, plus optional `isPulsing`, `tooltip`, and `icon`. |
-| Behavior | The dot is an image named by `label`; a renderable `icon` paints inside it in the variant's ink and is hidden from assistive technology; a tooltip is reachable by hover, touch, and keyboard (FR5). |
-| End-user impact | Screen-reader users hear the status without hover; sighted users see a color signal, optionally pulsing and optionally carrying a non-color mark. |
-| Builder impact | None; the record describes shipped behavior. |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Three gaps are listed under Current-state impact. |
-| Review checks | Reject a dot without an accessible name, a dot without a tooltip that adds its own tab stop, an icon exposed to assistive technology, a pulse that ignores reduced motion, or a second target. |
-| Governing rules | `architecture:component-theming-surface/INV2,INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:theme-tokens/INV11`; WCAG 2.2 2.1.1. |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | A fixed 8px status dot with a required theme-extensible `variant` and a required `label`, plus optional `isPulsing`, `tooltip`, and `icon`. |
+| Behavior | The dot is an image named by `label`; a renderable `icon` paints inside it in the variant's ink and is hidden from assistive technology; a standalone dot with a tooltip is a button named by `label` whose press pins the tooltip (`pressTrigger="toggle"`), so the tooltip is reachable by hover, touch, and keyboard; inside a button, link, menu item, or option, the dot stays an image and the host's accessible name carries the tooltip text (FR5). |
+| End-user impact | Screen-reader users hear the status without hover; sighted users see a color signal, optionally pulsing and optionally carrying a non-color mark. Inside a button, link, menu item, or option, sighted touch users lose the dot's visible tooltip text, and the host's accessible name carries the status for screen readers (FR5). |
+| Builder impact | StatusDot decides by placement. A standalone dot with a tooltip is a toggle button; inside a button, link, menu item, or option, the host carries the status in its accessible name, so a control never nests another control (FR5). A host named by `aria-label`, such as a Tab with `isLabelHidden`, takes no name from its content, so its caller includes the status in that label. |
+| Compatibility/readiness | No API or default change; a standalone dot with a tooltip becomes a button trigger with `pressTrigger="toggle"` no later than `component:Tooltip` FR5's walk ships, and a dot inside an interactive element hands its tooltip text to the host (FR5, not yet built). Three gaps are listed under Current-state impact. |
+| Review checks | Reject a dot without an accessible name, a dot without a tooltip that adds its own tab stop, an icon exposed to assistive technology, a pulse that ignores reduced motion, or a second target. |
+| Governing rules | `architecture:component-theming-surface/INV2,INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:theme-tokens/INV11`; WCAG 2.2 2.1.1. |
This table is a review projection; the body below is authoritative.
@@ -56,8 +56,11 @@ optional pulse, optional inner mark, and its accessible name.
## Compatibility and migration
- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
- or styling output changes. The dot emits only the canonical `status-dot`
+- Compatibility class: no public prop, default, or styling output change; with a
+ `tooltip`, a standalone dot becomes a button named by `label` inside Tooltip
+ with `pressTrigger="toggle"`, adopted no later than `component:Tooltip`
+ FR5's walk ships with its CLN-0024, and a dot inside a button, link, menu item, or option
+ stays an image whose tooltip text joins the host's accessible name (FR5). The dot emits only the canonical `status-dot`
target; the `statusdot` alias is not emitted
- Controlled/uncontrolled behavior: not applicable; StatusDot holds no state
- Migration decision: none
@@ -74,7 +77,14 @@ Consumer migration instructions belong in consumer docs and release notes.
- **Tooltip not reachable by keyboard (FR5).** The dot has no tab stop, so
Tooltip attaches no focus trigger and sighted keyboard users cannot reveal
the tooltip text, where WCAG 2.2 2.1.1 expects functionality to be keyboard
- operable. The accessible name still carries the status.
+ operable. The accessible name still carries the status. Today a tap opens a
+ dot's tooltip, because the dot performs no action and Tooltip's default
+ `auto` opens on such a tap, and a standalone dot does not yet take
+ `pressTrigger="toggle"`, so its tooltip has no pin for touch or keyboard.
+ FR5 changes a dot inside a button, link, menu item, or option to an image
+ whose tooltip previews on hover only, so sighted touch users lose its visible
+ tooltip text there; the host's accessible name carries the status for screen
+ readers.
- **Accent and neutral dots in forced colors (FR2).** The `accent` and
`neutral` dots draw no border, so in forced-colors mode they lose their plate
and disappear; no current record sets their treatment (OQ1). The accessible
@@ -89,7 +99,8 @@ Consumer migration instructions belong in consumer docs and release notes.
- The pulse and its reduced-motion suppression.
- The assistive-technology-hidden wrapper that places optional icon content
inside the dot.
-- The dot's image role and accessible name.
+- The dot's image role, its button role when it is standalone with a tooltip,
+ and its accessible name.
**Does not own / non-goals**
@@ -103,23 +114,23 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- | -------- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| Tone (`variant`) | `success`, `warning`, `error`, `accent`, `neutral`; theme additions | Selects the plate color and the ink an icon paints with. | All dots | Required | `component:StatusDot` | Stable | A theme-added value is reflected on `status-dot` and keeps a safe theme-independent baseline (FR2); TypeScript rejects unregistered values. |
-| Pulse | resting; pulsing | Signals ongoing activity by fading the dot in and out. | All tones | resting | `component:StatusDot` | Stable | — |
-| Status icon | present when `icon` is renderable; absent | Adds a non-color mark inside the dot. | All tones | absent | `component:StatusDot` | Stable | `false`, `true`, `null`, `undefined`, and `''` render no icon wrapper. |
-| Tooltip | present when `tooltip` is a non-empty string; absent | Explains the status; reachable by hover, touch, and keyboard (FR5). | All tones | absent | `component:StatusDot` | Stable | An empty string renders no tooltip. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tone (`variant`) | `success`, `warning`, `error`, `accent`, `neutral`; theme additions | Selects the plate color and the ink an icon paints with. | All dots | Required | `component:StatusDot` | Stable | A theme-added value is reflected on `status-dot` and keeps a safe theme-independent baseline (FR2); TypeScript rejects unregistered values. |
+| Pulse | resting; pulsing | Signals ongoing activity by fading the dot in and out. | All tones | resting | `component:StatusDot` | Stable | — |
+| Status icon | present when `icon` is renderable; absent | Adds a non-color mark inside the dot. | All tones | absent | `component:StatusDot` | Stable | `false`, `true`, `null`, `undefined`, and `''` render no icon wrapper. |
+| Tooltip | present when `tooltip` is a non-empty string; absent | Explains the status; a standalone dot becomes a button whose press pins it, reachable by hover, touch, and keyboard; inside an interactive element the host carries the text (FR5). | All tones | absent | `component:StatusDot` | Stable | An empty string renders no tooltip. |
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | StatusDot always renders one inline-flex `span` dot, 8 by 8 CSS pixels, fully rounded, that does not shrink in a flex row, carrying the `status-dot` target and only that target. | Current source and tests |
-| FR2 | `success`, `warning`, and `error` are strong status fills: under `architecture:theme-tokens` INV11 each paints `--color-<status>` with `--color-on-<status>` ink and keeps a visible `CanvasText` border in forced-colors mode. `accent` paints `--color-accent` with `--color-on-accent` ink, and `neutral` paints `--color-icon-secondary` with the surface color as ink; these two are not INV11 status roles, and no current record sets their forced-colors treatment (OQ1). The target reflects `variant` for every value, and an extensible tone has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added value the active theme does not paint receives no component plate or ink, leaving a transparent 8px box (Current-state impact). | Current source and tests |
-| FR3 | `isPulsing` animates the dot's opacity from 1 to 0.5 and back over 2 seconds, ease-in-out, indefinitely; under `prefers-reduced-motion: reduce` the animation is removed and the dot rests. | Current source and tests |
-| FR4 | A renderable `icon` renders in a wrapper centered inside the dot and filling its 8px field; it paints from `currentColor`, the variant's ink. A non-renderable value leaves the dot childless. | Current source and tests |
-| FR5 | A non-empty `tooltip` wraps the dot in Tooltip with that text; otherwise no tooltip renders. A tooltip opens from the keyboard as well as on hover and touch (WCAG 2.2 2.1.1). Implementation gap: the dot has no tab stop, so the tooltip opens on hover and touch only (Current-state impact). | Current source and tests |
-| FR6 | `ref` reaches the dot. Supported DOM, ARIA, data, and event props reach the dot after its role and name; `xstyle`, `className`, and `style` merge in that order after component styles. | Current source and tests |
+| ID | Invariant | Basis |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| FR1 | StatusDot always renders one inline-flex `span` dot, 8 by 8 CSS pixels, fully rounded, that does not shrink in a flex row, carrying the `status-dot` target and only that target. | Current source and tests |
+| FR2 | `success`, `warning`, and `error` are strong status fills: under `architecture:theme-tokens` INV11 each paints `--color-<status>` with `--color-on-<status>` ink and keeps a visible `CanvasText` border in forced-colors mode. `accent` paints `--color-accent` with `--color-on-accent` ink, and `neutral` paints `--color-icon-secondary` with the surface color as ink; these two are not INV11 status roles, and no current record sets their forced-colors treatment (OQ1). The target reflects `variant` for every value, and an extensible tone has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added value the active theme does not paint receives no component plate or ink, leaving a transparent 8px box (Current-state impact). | Current source and tests |
+| FR3 | `isPulsing` animates the dot's opacity from 1 to 0.5 and back over 2 seconds, ease-in-out, indefinitely; under `prefers-reduced-motion: reduce` the animation is removed and the dot rests. | Current source and tests |
+| FR4 | A renderable `icon` renders in a wrapper centered inside the dot and filling its 8px field; it paints from `currentColor`, the variant's ink. A non-renderable value leaves the dot childless. | Current source and tests |
+| FR5 | A non-empty `tooltip` renders by placement; without one, no tooltip renders. A standalone dot is wrapped in Tooltip with that text and `pressTrigger="toggle"` and is the toggle's button trigger, named by `label`, so hover and keyboard focus preview the tooltip and a tap, click, Enter, or Space pins it (`component:Tooltip` FR9), and keyboard users reach it (WCAG 2.2 2.1.1). StatusDot adopts the toggle no later than `component:Tooltip` FR5's walk ships, so a standalone dot's tooltip stays reachable on touch. A dot inside an interactive element (a button, link, menu item, or option) is a non-interactive image wrapped in Tooltip without the toggle, because a control cannot nest another control: its tooltip previews on hover only, and its tooltip text joins the host's accessible name, so the host carries the status for screen readers (`architecture:interaction-modality` INV4). A host named by `aria-label` takes no name from its content, so its caller includes the status in that label. Implementation gap: the dot has no tab stop and uses Tooltip's default touch trigger, so the tooltip opens on hover and touch only (Current-state impact). | Current source and tests; `component:Tooltip` DEC-1 |
+| FR6 | `ref` reaches the dot. Supported DOM, ARIA, data, and event props reach the dot after its role and name; `xstyle`, `className`, and `style` merge in that order after component styles. | Current source and tests |
### Allowed variation
@@ -130,33 +141,45 @@ Consumer migration instructions belong in consumer docs and release notes.
### Representative states
-| State | Required invariant | Allowed variation |
-| ------------ | ---------------------------------------------------------------------- | ----------------- |
-| Plain dot | Childless image named by `label`; not focusable. | Tone. |
-| With icon | Icon inside an `aria-hidden` wrapper; the dot keeps its role and name. | Artwork. |
-| Pulsing | Opacity pulse runs; with reduced motion requested, it does not. | Tone. |
-| With tooltip | Dot keeps its role and name; Tooltip owns the surface. | Tooltip text. |
+| State | Required invariant | Allowed variation |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| Plain dot | Childless image named by `label`; not focusable. | Tone. |
+| With icon | Icon inside an `aria-hidden` wrapper; the dot keeps its role and name. | Artwork. |
+| Pulsing | Opacity pulse runs; with reduced motion requested, it does not. | Tone. |
+| With tooltip | A standalone dot is a button named by `label` with `aria-expanded`; a press pins the tooltip; Tooltip owns the surface. | Tooltip text. |
+| Inside a control | Inside a button, link, menu item, or option, the dot is an image with no tab stop; the host's accessible name includes the tooltip text. | Host component. |
### Transformation and precedence order
-- **ORD1 — Dot attributes.** `role="img"` and `aria-label` → component class and
- `data-variant` → component styles → `xstyle` → `className` → `style` →
- caller props.
+- **ORD1 — Dot attributes.** The role first follows placement: a standalone dot
+ with a tooltip is the toggle's `button`; a dot without a tooltip, or inside
+ a button, link, menu item, or option, is `role="img"`. Then `aria-label` → component
+ class and `data-variant` → component styles → `xstyle` → `className` →
+ `style` → caller props.
### Performance and resources
- **PR1 — CSS-only motion.** The pulse is a CSS animation; StatusDot registers
- no listener, observer, or timer of its own.
+ no listener, observer, or timer of its own beyond the shared hit-area watch
+ AR2 requires for a standalone dot with a tooltip.
## Accessibility contract
- **AR1 — Name without hover.** The dot exposes `role="img"` with `label` as its
- accessible name for every variant, with or without a tooltip or icon; a caller
- `role` or `aria-label` replaces them (FR6).
+ accessible name for every variant, with or without an icon; standalone with a
+ tooltip it is a button with the same name, and inside an interactive element
+ its tooltip text joins the host's accessible name (FR5). A caller `role` or `aria-label`
+ replaces them (FR6).
- **AR2 — Tab stop.** A dot without a tooltip is a static image and adds no
- tab stop of its own. For a dot with a tooltip, FR5 governs: the tooltip is
- reachable from the keyboard, and today the dot adds no tab stop, which is the
- FR5 gap. A caller `tabIndex` passes through (FR6).
+ tab stop of its own. A standalone dot with a tooltip is a button in the tab
+ order whose press pins the tooltip (FR5), and a dot inside an interactive
+ element never adds a tab stop; today the dot adds no tab stop, which is the
+ FR5 gap. Under a coarse pointer, a standalone dot with a tooltip reaches 44 px
+ through an invisible hit area from the shared hit-area watch where its
+ neighbors leave room: the hit area never overlaps a neighbor's target and is
+ clamped to half the gap between close neighbors (`spec:AST-094` FR42);
+ implementation gap: not yet built. A caller `tabIndex`
+ passes through (FR6).
- **AR3 — Decorative icon.** The icon wrapper is `aria-hidden`, so the label
alone names the status.
- **AR4 — Color is not the only carrier.** The accessible name carries the
@@ -196,20 +219,20 @@ Consumer migration instructions belong in consumer docs and release notes.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | --------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| FR1, FR6 | `StatusDot.test.tsx` render, ref, test-id, and target suites | Every tone | Removing the dot, a lost ref or test id, or a second target fails. Gap: the 8px size test asserts presence only, and no test fails if the styling order (ORD1) changes; size is visible in `StatusDot.stories.tsx`. | `audit:StatusDot/anatomy` |
-| FR2 | `StatusDot.test.tsx` variant-ink suite; `extensibleAxes.test.ts` | Warning plate and ink; map wiring | Dropping `variant` reflection fails. The warning-ink test pins the `--color-warning` plate with `--color-on-warning` ink, and the forced-colors test asserts the compiled `CanvasText` outline. Gap: other tones' paint and the unthemed fallback have no automated check. | `audit:StatusDot/theming` |
-| FR3, AR5 | `StatusDot.stories.tsx` in a browser, with and without reduced motion | Resting and pulsing | Gap: the pulsing unit tests assert presence only; a missing pulse or reduced-motion rule is visible only in the rendered fixture. | `audit:StatusDot/motion` |
-| FR4, AR3 | `StatusDot.test.tsx` custom-icon suite | Icon, falsy values | Exposing the icon or rendering a wrapper for a falsy value fails. | `audit:StatusDot/anatomy` |
-| FR5, AR1, AR2 | `StatusDot.test.tsx` focusability and accessible-name suites | Every tone, with and without tooltip | A missing name, a tab stop on a dot without a tooltip, or a name that depends on the tooltip fails. Gap: the tooltip test asserts only that the dot renders, so dropping the Tooltip wrap passes, and no test covers a caller `role` or `aria-label` override. | `audit:StatusDot/a11y` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:StatusDot/theming` |
-| AR4, PR1 | Source review; `StatusDot.stories.tsx` | Plain dot, dot with icon | Gap: no automated check covers the non-color mark guidance or fails if StatusDot adds its own listener, observer, or timer. | `audit:StatusDot/a11y` |
-| AR1, AR3 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every tone, with icon and tooltip | Gap: no accessibility-tree check proves the image role and name or the hidden icon; the unit tests query the DOM. | `audit:StatusDot/a11y` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| FR1, FR6 | `StatusDot.test.tsx` render, ref, test-id, and target suites | Every tone | Removing the dot, a lost ref or test id, or a second target fails. Gap: the 8px size test asserts presence only, and no test fails if the styling order (ORD1) changes; size is visible in `StatusDot.stories.tsx`. | `audit:StatusDot/anatomy` |
+| FR2 | `StatusDot.test.tsx` variant-ink suite; `extensibleAxes.test.ts` | Warning plate and ink; map wiring | Dropping `variant` reflection fails. The warning-ink test pins the `--color-warning` plate with `--color-on-warning` ink, and the forced-colors test asserts the compiled `CanvasText` outline. Gap: other tones' paint and the unthemed fallback have no automated check. | `audit:StatusDot/theming` |
+| FR3, AR5 | `StatusDot.stories.tsx` in a browser, with and without reduced motion | Resting and pulsing | Gap: the pulsing unit tests assert presence only; a missing pulse or reduced-motion rule is visible only in the rendered fixture. | `audit:StatusDot/motion` |
+| FR4, AR3 | `StatusDot.test.tsx` custom-icon suite | Icon, falsy values | Exposing the icon or rendering a wrapper for a falsy value fails. | `audit:StatusDot/anatomy` |
+| FR5, AR1, AR2 | `StatusDot.test.tsx` focusability and accessible-name suites; evidence gap until built: standalone toggle cases and the coarse-pointer hit area; a dot with a tooltip inside a Button and inside a MenuItem | Every tone, with and without tooltip; a standalone dot with a tooltip; a dot inside a Button and inside a MenuItem | A missing name, a tab stop on a dot without a tooltip, or a name that depends on the tooltip fails. Gap: the tooltip test asserts only that the dot renders, so dropping the Tooltip wrap passes, and no test covers a caller `role` or `aria-label` override. Once FR5 is built, a standalone dot with a tooltip that is not a named button, that a tap, click, Enter, or Space does not pin, fails. A dot inside a Button or a MenuItem that renders a nested button or tab stop, opens its tooltip on a tap, or whose host's accessible name lacks the status, fails. A standalone dot with a tooltip whose coarse-pointer hit area stays under 44 px where its neighbors leave room, or reaches a neighbor's target, fails. | `audit:StatusDot/a11y` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:StatusDot/theming` |
+| AR4, PR1 | Source review; `StatusDot.stories.tsx` | Plain dot, dot with icon | Gap: no automated check covers the non-color mark guidance or fails if StatusDot adds its own listener, observer, or timer. | `audit:StatusDot/a11y` |
+| AR1, AR3 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every tone, with icon and tooltip | Gap: no accessibility-tree check proves the image role and name or the hidden icon; the unit tests query the DOM. | `audit:StatusDot/a11y` |
## Decision log
-None recorded. The record describes shipped behavior.
+None recorded. The tooltip's toggle follows `component:Tooltip` DEC-1.
## Open questions
diff --git a/packages/core/src/Tooltip/Tooltip.spec.md b/packages/core/src/Tooltip/Tooltip.spec.md
index e254ec329d..fb7062d07a 100644
--- a/packages/core/src/Tooltip/Tooltip.spec.md
+++ b/packages/core/src/Tooltip/Tooltip.spec.md
@@ -9,7 +9,7 @@ superseded_by: null
approved_by: cixzhang
approved_at: 2026-10-28
owners: [cixzhang]
-review_triggers: [behavior, theming, accessibility]
+review_triggers: [public-api, behavior, theming, accessibility]
verified_by:
[
packages/core/src/Tooltip/Tooltip.test.tsx,
@@ -32,22 +32,22 @@ architecture:
architecture:public-component-api,
]
contributing: []
-system_specs: [spec:AST-003]
+system_specs: [spec:AST-003, spec:AST-017]
---
# Tooltip component contract
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `Tooltip` with `content`, `children` or `anchorRef`, `placement` (`above`), `alignment` (`center`), `delay` (200), `hideDelay` (0), `focusTrigger` (`auto`), `touchTrigger` (`auto`), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `tooltip`. |
-| Behavior | A `role="tooltip"` layer that describes its trigger. It opens on hover after `delay`, on keyboard focus, and on a qualifying tap; it stays open while the pointer moves onto it, and closes on leave, Escape, or pressing the trigger (a press that focuses a text field reopens it). |
-| End-user impact | Mouse, keyboard, and touch users can each reveal the hint, move onto it, and dismiss it; screen-reader users hear it as the trigger's description. |
-| Builder impact | None. |
-| Compatibility/readiness | Records shipped behavior; no public change. Nine implementation gaps (see Current-state impact). |
-| Review checks | Reject a tooltip that cannot be hovered or dismissed (WCAG 1.4.13), one that opens on a tap's focus or on pointer focus of a trigger that is not a text field, or a lost `aria-describedby` link. |
-| Governing rules | WCAG 1.4.13; `family:overlay-dismissal`; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `Tooltip` with `content`, `children` or `anchorRef`, `placement` (`above`), `alignment` (`center`), `delay` (200), `hideDelay` (0), `focusTrigger` (`auto`), `pressTrigger` (`none`), `touchTrigger` (`auto`; `tap` deprecated by DEP-0016), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `tooltip`. `useTooltip` takes the same `pressTrigger` and `touchTrigger`. |
+| Behavior | A `role="tooltip"` layer that describes its trigger. It opens on hover after `delay`, on keyboard focus, and on a qualifying tap; it stays open while the pointer moves onto it, and closes on leave, Escape, or pressing the trigger (a press that focuses a text field reopens it). With `pressTrigger="toggle"`, hover and focus preview it, and a click, tap, Enter, or Space on a button trigger pins it open until Escape, a second press, a press outside, or focus leaving. |
+| End-user impact | Mouse, keyboard, and touch users can each reveal the hint, move onto it, and dismiss it; screen-reader users hear it as the trigger's description. With the toggle, people on touch, keyboard, or a screen reader can keep it open to read it, and hear it once when it pins. |
+| Builder impact | A trigger whose information lives only in the tooltip passes `pressTrigger="toggle"` and a button trigger (DEC-1). `touchTrigger="tap"` callers migrate by trigger kind: the deprecating release's codemod rewrites icon and span triggers and reports the rest (DEP-0016), and CLN-0024 names each remaining kind's replacement at the next minor. |
+| Compatibility/readiness | Additive `pressTrigger`, default `none`; `touchTrigger="tap"` deprecated (DEP-0016); `touchTrigger` folds into `pressTrigger` at the next minor (CLN-0024). FR9, FR10, and AR6 are not yet built; ten further implementation gaps (see Current-state impact). |
+| Review checks | Reject a tooltip that cannot be hovered or dismissed (WCAG 1.4.13), one that opens on a tap's focus or on pointer focus of a trigger that is not a text field, a lost `aria-describedby` link, a pinned tooltip that closes on pointer leave or lets Escape pass to the layer beneath, a toggle without `aria-expanded`, or a non-button toggle trigger without the development warning. |
+| Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (deprecation); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
This table is a review projection; the body below is authoritative.
@@ -60,13 +60,56 @@ in `Tooltip.doc.mjs`.
## Compatibility and migration
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; runtime, DOM, styling,
- targets, and public API remain unchanged
+- Released default preserved: the defaults stay `pressTrigger="none"` and
+ `touchTrigger="auto"`. In patch releases `auto` keeps its released
+ behavior: a tap opens the tooltip unless the trigger itself performs an
+ action. The one exception is a disabled control, which is not an action, so
+ its reason opens on a tap; that restoration ships on its own as a patch
+ `[fix]`. FR5's walk, under which a tap that already acts on a control around
+ the trigger does not open the tooltip, needs app code where a hint-only
+ trigger sits inside a control (it declares `pressTrigger="toggle"`), so it
+ is a breaking change under `spec:AST-017` FR1 and DEC-17 and ships with
+ CLN-0024 in the next minor; no caller's behavior changes in a patch
+- Compatibility class: additive `pressTrigger`; `touchTrigger="tap"` is
+ deprecated (DEP-0016); FR5's walk is a breaking change for the next minor
+ (CLN-0024); DOM, styling, and targets remain unchanged without `pressTrigger`
- Controlled/uncontrolled behavior: uncontrolled by default; `isOpen` forces the
state, and a controlled tooltip reports close requests through
- `onOpenChange(false)` without closing itself (FR7)
-- Migration decision: none
+ `onOpenChange(false)` without closing itself (FR7); under
+ `pressTrigger="toggle"` a press on a controlled tooltip reports the toggled
+ value through `onOpenChange` and does not change the state itself (FR9)
+- Migration decision: DEP-0016, then CLN-0024 in the next minor
+
+### DEP-0016 — Deprecate `touchTrigger="tap"`
+
+| Field | Value |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `DEP-0016` |
+| cleanup | `CLN-0024` |
+| package | `@astryxdesign/core` |
+| surface | `touchTrigger="tap"` on `Tooltip`, `HoverCard`, `useTooltip`, and `useHoverCard` |
+| old contract | Every completed tap opens the layer, even on a trigger that performs its own action; a mouse click, Enter, or Space does not keep it open |
+| replacement | `pressTrigger="toggle"`: a tap still opens the layer, and a click, Enter, or Space pins it too (FR9); a non-button trigger keeps tap-only opening (FR9) |
+| direct authority | `component:Tooltip` DEC-1 and `component:HoverCard` DEC-1. Owner: `cixzhang` |
+| warning | Static `@deprecated` metadata on the `tap` value; consumer docs and the release notes name `DEP-0016` and `pressTrigger="toggle"`. No runtime warning (`spec:AST-017` FR29, FR29a). When `touchTrigger` and `pressTrigger="toggle"` are both given, `pressTrigger` wins |
+| migration | Mechanical only where the result is observably the same: on a trigger that is statically a non-interactive element, such as an icon or a span, `pressTrigger="toggle"` replaces `touchTrigger="tap"`. That rewrite keeps every production behavior because FR9 keeps a non-button toggle trigger on tap-only opening, as `touchTrigger="tap"` does; in development such a trigger also gets FR9's warning, which points its caller to a button trigger. On a trigger whose tooltip repeats its own text, a button, a link, or an element the codemod cannot identify, the toggle changes what a click, Enter, or Space does (and on a button adds `aria-expanded`), so the caller migrates by hand; the deprecated `tap` keeps working until CLN-0024 |
+| codemod | An `astryx upgrade` codemod staged in `packages/cli/assets/codemods/transforms/next/`, with tests and fixtures, checked by the codemod verify workflow, and available in the release that deprecates `tap`: it rewrites static `touchTrigger="tap"` to `pressTrigger="toggle"` only where the trigger is statically a non-interactive icon or span, which FR9 keeps on tap-only opening, reports every other `touchTrigger="tap"` site (an own-text trigger, a button, a link, or an unknown element) with a manual-migration note and leaves it unchanged, removes static `touchTrigger="auto"`, and reports spreads and dynamic values it cannot prove (`spec:AST-017` FR29c, FR29d) |
+| downstream | In the deprecating release, Core FieldLabel's info icon moves from `touchTrigger="tap"` to `component:InfoTip` with `pressTrigger="toggle"` (`component:FieldLabel` FR9), and Lab InfoTip and the CLI page templates migrate too, the templates to a button trigger with `pressTrigger="toggle"` so they carry no development warning (`spec:AST-017` FR29c); docs, stories, templates, and examples teach only `pressTrigger` |
+| transition | no prior transition |
+| state | `proposed` |
+| target plan | `CLN-0024` in the next minor release |
+
+### CLN-0024 — `touchTrigger` folds into `pressTrigger`
+
+| Field | Value |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `CLN-0024` |
+| lifecycle | `DEP-0016` |
+| delta | `touchTrigger` is removed from `Tooltip`, `HoverCard`, `useTooltip`, and `useHoverCard`. `pressTrigger` takes `auto`, `toggle`, and `none`, default `auto`: `auto` is the released `touchTrigger="auto"` (a tap opens the layer unless the trigger performs its own action, and no press pins it), `none` is the released `touchTrigger="none"` (no tap or press opens it), and `toggle` is unchanged. `auto` gains FR5's walk: a tap that already acts on a control around the trigger does not open the layer. A hint-only trigger inside a control migrates by declaring `pressTrigger="toggle"`, which no codemod can decide; Astryx's own info-only triggers (InfoTip, FieldLabel's info button, and a standalone StatusDot) declare it before this minor; a StatusDot inside a button, link, menu item, or option stays an image whose status the host's accessible name carries. One prop decides what a press does |
+| replacement | Each remaining `touchTrigger="tap"` site has a named replacement (`spec:AST-017` FR8): a button or link whose only job is its tooltip takes `pressTrigger="toggle"`, so its tooltip keeps a touch path; a button or link with its own action whose accessible name already carries the layer's text drops `tap` and takes `auto`, so a tap performs the action and opens no layer (`architecture:interaction-modality` INV4's case); any other button or link with its own action moves the layer's information to an adjacent info trigger that declares `pressTrigger="toggle"`, such as an InfoTip, or into its visible label, so that information keeps a touch path, and then drops `tap`; a trigger whose tooltip repeats its own text takes `pressTrigger="toggle"` (FR9's own-text exception); an unknown element is reported for a manual choice (`architecture:interaction-modality` INV4) |
+| codemod | The minor's `astryx upgrade` codemod, with tests and fixtures: `touchTrigger="none"` becomes `pressTrigger="none"`; `touchTrigger="auto"` and the released `pressTrigger="none"` are removed, since `auto` reproduces them; `pressTrigger="toggle"` is kept and any `touchTrigger` beside it removed; a remaining `touchTrigger="tap"` becomes `pressTrigger="toggle"` on an own-text trigger the codemod can identify; every button and link `tap` site is reported with the options in its note (`pressTrigger="toggle"` when the trigger's only job is its layer; remove `tap` for `auto` when the trigger's accessible name already carries the layer's text; otherwise move the information to an adjacent InfoTip or the visible label, then remove `tap`), since no static check tells them apart, and every other remaining `tap` site is reported; spreads and dynamic values are reported |
+| rollback | Restore `touchTrigger` and the two-value `pressTrigger` from the final-patch baseline |
+| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
Consumer migration instructions belong in consumer docs and release notes.
@@ -83,10 +126,20 @@ Consumer migration instructions belong in consumer docs and release notes.
tooltip rendered into an iframe or a Picture-in-Picture window with no layer
beneath it is never closed by Escape. WCAG 1.4.13 requires such content to
be dismissible (FR6).
+- **A tap inside a control still opens the tooltip.** The shipped
+ `touchTrigger="auto"` asks only whether the trigger itself performs an action,
+ so a truncated label inside a link opens its tooltip on the tap that follows
+ the link, and a disabled control's reason opens on no tap. The walk ships
+ with CLN-0024 and the disabled-control restoration as a patch (FR5, DEC-1).
+- **Press-to-pin is not built.** `pressTrigger`, its toggle (FR9), the trigger
+ wiring and announcement (FR10), and a pinned tooltip's Escape priority
+ (`spec:AST-003` FR4) are specified and not implemented, and the codemod
+ DEP-0016 names does not exist yet. `touchTrigger="tap"` is the shipped way to
+ open on every tap.
- **The tooltip consumes Escape until AST-003 ships.** A visible, topmost
tooltip handles Escape, as `family:overlay-dismissal` records, so the layer
underneath it, such as a Dialog, stays open for that press. `spec:AST-003`
- FR4, accepted and not yet implemented, makes Tooltip passive.
+ FR4, accepted and not yet implemented, makes an unpinned tooltip passive.
- **Hover timing does not use the shared hover recognizer.** The tooltip runs
its own show and hide timers, without the recognizer's intent group that
shows the next trigger at once. `architecture:interaction-modality` INV11 has
@@ -127,7 +180,8 @@ Consumer migration instructions belong in consumer docs and release notes.
- The rendered tooltip surface and content inside that surface (FR1).
- Trigger wiring and when the tooltip opens and closes for each input
- (FR2–FR8).
+ (FR2–FR8), including the press toggle and the trigger state it sets (FR9,
+ FR10).
**Does not own / non-goals**
@@ -141,23 +195,26 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ------------- | ------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- | ------- | ------------------- | --------- | -------------------------------- |
-| Focus trigger | `auto`, `always`, `never` | Whether keyboard focus opens the tooltip: on focusable triggers (FR4's gap), always, or never. | Every trigger mode. | `auto` | `component:Tooltip` | Stable | TypeScript rejects other values. |
-| Touch trigger | `auto`, `tap`, `none` | Whether a tap opens it: unless the trigger performs its own action, always, or never. | Touch and pen without hover. | `auto` | `component:Tooltip` | Stable | TypeScript rejects other values. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------- | ------------------- | ------------------------------------------------------------------------- | -------------------------------- |
+| Focus trigger | `auto`, `always`, `never` | Whether keyboard focus opens the tooltip: on focusable triggers (FR4's gap), always, or never. | Every trigger mode. | `auto` | `component:Tooltip` | Stable | TypeScript rejects other values. |
+| Press trigger | `none`, `toggle` | Whether a click, tap, Enter, or Space on the trigger pins the tooltip open: never, leaving taps to `touchTrigger`, or on every press (FR9). | Button triggers; a non-button trigger keeps tap-only opening (FR9). | `none` | `component:Tooltip` | Stable | TypeScript rejects other values. |
+| Touch trigger | `auto`, `tap`, `none` | Whether a tap opens it: unless the tap already acts, as the innermost control around the tapped element decides (DEC-1); always; or never. Ignored under `pressTrigger="toggle"`. | Touch and pen without hover. | `auto` | `component:Tooltip` | Stable; `tap` deprecated (DEP-0016); folds into `pressTrigger` (CLN-0024) | TypeScript rejects other values. |
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1 | The rendered tooltip contains one owned surface, `role="tooltip"`, carrying the `tooltip` target, at most 300 px wide, with the supplied `content` inside; content has no separate target and there is no arrow. | Current source, docs, and tests |
-| FR2 | Trigger wiring: a single string or number child is wrapped in a focusable inline span; element `children` attach to their first element; `anchorRef` attaches to that element. The trigger's `aria-describedby` gains the tooltip id, merged with and later restored to any existing value. Implementation gap: the wiring runs only when the trigger's listeners attach, so a trigger element replaced after mount, or a trigger whose own `aria-describedby` changes, loses it until a re-render re-attaches them (Current-state impact). | Current source and tests |
-| FR3 | On a hover-capable pointer, entering the trigger opens after `delay` ms; leaving closes after `hideDelay` ms. With `hideDelay` 0 a short bridge lets the pointer move onto the surface without closing it, and the surface stays open while hovered. | WCAG 1.4.13; tests |
-| FR4 | Focus that matches `:focus-visible` opens the tooltip per `focusTrigger`: keyboard focus, programmatic focus that follows keyboard input (AR4), pointer focus on a text-entry trigger, which browsers mark focus-visible, and programmatic focus on a text-entry trigger unless a finger or pen pressed that trigger and the last input was a pointer press, and on any other trigger unless the last input was a pointer (after keyboard input, as in AR4, or before any input). Implementation gap: script focus after a pointer press that focused nothing opens it, because the hook reads `:focus-visible` alone (Current-state impact). Focus a tap leaves behind, and other pointer focus, does not. Focus leaving the trigger schedules the hide as a pointer leave does. Under `focusTrigger="auto"`, focus opens the tooltip on any focusable trigger. Implementation gap: `auto` recognizes only an explicit non-negative `tabindex`, HTML links, buttons, form fields, and editable elements, so a `<summary>` or an SVG link never opens on keyboard focus; and it reads the tab order only when it attaches the trigger's listeners, on mount and again when `focusTrigger`, `isEnabled`, `isOpen`, `delay`, `hideDelay`, or `onOpenChange` changes, so a trigger rendered with `tabindex="-1"` does not open on focus until such a re-render follows its move into the tab order (Current-state impact). | Current source and tests |
-| FR5 | On touch, a completed tap opens per `touchTrigger` when the finger lifts; a touch that becomes a scroll, or a press the browser does not count as a tap, does not open it. A second tap on the trigger, a tap outside, or a scroll starting outside closes it. | Current source and tests |
-| FR6 | Escape closes a visible tooltip; Escape during text composition is ignored. Escape routing follows `family:overlay-dismissal`: a visible topmost tooltip in the page handles that Escape, so a layer underneath stays open for that press. Implementation gap: a tooltip rendered into another document, such as an iframe or a Picture-in-Picture window, with no layer beneath it is never closed by Escape (Current-state impact). `spec:AST-003` FR4, accepted and not yet implemented, makes Tooltip passive (Current-state impact). Pressing an uncontrolled tooltip's trigger closes it; a press that focuses a text-entry trigger reopens it through FR4. | WCAG 1.4.13; tests |
-| FR7 | `isOpen` forces the tooltip shown or hidden, and `isOpen={true}` suppresses hover and focus hiding; a controlled tooltip answers Escape by calling `onOpenChange(false)` without hiding, and is not closed by pressing the trigger. `isDefaultOpen` opens it on mount, still dismissible. Implementation gap: with `isOpen={false}`, any focus FR4 opens on, keyboard focus or a click into a text-field trigger, still opens the tooltip and reports `onOpenChange(true)`, and Escape then only reports `onOpenChange(false)`, so it stays until focus or the pointer leaves the trigger or the tooltip, or the caller re-renders with a new `onOpenChange` (Current-state impact). `isEnabled={false}` disables triggers and drops a pending open. | Current source and tests |
-| FR8 | `onOpenChange` reports each show and hide. `hasHoverIndication` (`auto`: a single string or number child) adds a hover cue to the inline trigger. | Current source and tests |
+| ID | Invariant | Basis |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| FR1 | The rendered tooltip contains one owned surface, `role="tooltip"`, carrying the `tooltip` target, at most 300 px wide, with the supplied `content` inside; content has no separate target and there is no arrow. | Current source, docs, and tests |
+| FR2 | Trigger wiring: a single string or number child is wrapped in a focusable inline span; element `children` attach to their first element; `anchorRef` attaches to that element. The trigger's `aria-describedby` gains the tooltip id, merged with and later restored to any existing value. Implementation gap: the wiring runs only when the trigger's listeners attach, so a trigger element replaced after mount, or a trigger whose own `aria-describedby` changes, loses it until a re-render re-attaches them (Current-state impact). | Current source and tests |
+| FR3 | On a hover-capable pointer, entering the trigger opens after `delay` ms; leaving closes after `hideDelay` ms. With `hideDelay` 0 a short bridge lets the pointer move onto the surface without closing it, and the surface stays open while hovered. | WCAG 1.4.13; tests |
+| FR4 | Focus that matches `:focus-visible` opens the tooltip per `focusTrigger`: keyboard focus, programmatic focus that follows keyboard input (AR4), pointer focus on a text-entry trigger, which browsers mark focus-visible, and programmatic focus on a text-entry trigger unless a finger or pen pressed that trigger and the last input was a pointer press, and on any other trigger unless the last input was a pointer (after keyboard input, as in AR4, or before any input). Implementation gap: script focus after a pointer press that focused nothing opens it, because the hook reads `:focus-visible` alone (Current-state impact). Focus a tap leaves behind, and other pointer focus, does not. Focus leaving the trigger schedules the hide as a pointer leave does. Under `focusTrigger="auto"`, focus opens the tooltip on any focusable trigger. Implementation gap: `auto` recognizes only an explicit non-negative `tabindex`, HTML links, buttons, form fields, and editable elements, so a `<summary>` or an SVG link never opens on keyboard focus; and it reads the tab order only when it attaches the trigger's listeners, on mount and again when `focusTrigger`, `isEnabled`, `isOpen`, `delay`, `hideDelay`, or `onOpenChange` changes, so a trigger rendered with `tabindex="-1"` does not open on focus until such a re-render follows its move into the tab order (Current-state impact). | Current source and tests |
+| FR5 | On touch, a completed tap opens per `touchTrigger` when the finger lifts; a touch that becomes a scroll, or a press the browser does not count as a tap, does not open it. Under `auto`, a tap that already acts leaves it shut: walking out from the tapped element, the trigger included, the innermost button, link, label, form control, option, menu item, or row or card made clickable with `useClickableContainer` decides, and a disabled or `aria-disabled` control is not an action, so a disabled control's reason opens on a tap even inside a clickable row or card (DEC-1). Implementation gap: the walk ships with CLN-0024 in the next minor; until then `auto` asks only whether the trigger itself performs an action, apart from a disabled control (Compatibility and migration). A second tap on the trigger, a tap outside, or a scroll starting outside closes it. Under `pressTrigger="toggle"`, FR9 decides what a tap does and `touchTrigger` is ignored. | Current source and tests |
+| FR6 | Escape closes a visible tooltip; Escape during text composition is ignored. Escape routing follows `family:overlay-dismissal`: a visible topmost tooltip in the page handles that Escape, so a layer underneath stays open for that press. Implementation gap: a tooltip rendered into another document, such as an iframe or a Picture-in-Picture window, with no layer beneath it is never closed by Escape (Current-state impact). `spec:AST-003` FR4, accepted and not yet implemented, makes an unpinned tooltip passive and gives a pinned one Escape first (Current-state impact). Outside `pressTrigger="toggle"`, pressing an uncontrolled tooltip's trigger closes it; a press that focuses a text-entry trigger reopens it through FR4. | WCAG 1.4.13; tests |
+| FR7 | `isOpen` forces the tooltip shown or hidden, and `isOpen={true}` suppresses hover and focus hiding; a controlled tooltip answers Escape by calling `onOpenChange(false)` without hiding, and is not closed by pressing the trigger. `isDefaultOpen` opens it on mount, still dismissible. Implementation gap: with `isOpen={false}`, any focus FR4 opens on, keyboard focus or a click into a text-field trigger, still opens the tooltip and reports `onOpenChange(true)`, and Escape then only reports `onOpenChange(false)`, so it stays until focus or the pointer leaves the trigger or the tooltip, or the caller re-renders with a new `onOpenChange` (Current-state impact). `isEnabled={false}` disables triggers and drops a pending open. | Current source and tests |
+| FR8 | `onOpenChange` reports each show and hide. `hasHoverIndication` (`auto`: a single string or number child) adds a hover cue to the inline trigger. | Current source and tests |
+| FR9 | With `pressTrigger="toggle"` and a trigger whose role is `button` (a `<button>` or `role="button"`), a click, a completed tap, Enter, or Space on the trigger pins the tooltip open, and the same press on a pinned tooltip closes it. Hover and keyboard focus still preview it per FR3 and FR4; on touch no preview opens and a tap pins it, while a touch that becomes a scroll pins nothing. A pinned tooltip stays open when the pointer leaves the trigger and the surface; Escape (FR6), a second press, a press outside the trigger and the surface, or focus moving outside them closes it. In a controlled tooltip a press reports the toggled value through `onOpenChange` and does not change the state itself (FR7). A press that pins or closes the layer stops at its trigger: it does not reach a clickable row, card, or container around it, or the control a label names. A trigger whose role is not `button` gets a development warning and keeps tap-only opening: a tap opens the tooltip as `touchTrigger="tap"` does, and no press pins it. A trigger whose tooltip repeats its own visible text, such as a truncated Text that is its own tab stop, may take `pressTrigger="toggle"` without being a button: a press pins it as on a button trigger, and it gets no development warning, no `aria-expanded` or `aria-controls`, and no announcement, since its text is already its content. Implementation gap: not yet built (Current-state impact). | DEC-1; WCAG 1.4.13, 2.1.1 |
+| FR10 | While `pressTrigger="toggle"` wires a button trigger, the trigger carries `aria-expanded`, `true` only while pinned, and `aria-controls` naming the surface while it shows, each replacing the trigger's own value while wired and restored on cleanup; FR2's `aria-describedby` is kept. When the tooltip pins, its text is announced once through a polite live region; a preview announces nothing beyond the description. Implementation gap: not yet built (Current-state impact). | DEC-1; WAI-ARIA 1.2 `aria-expanded` |
### Allowed variation
@@ -196,6 +253,12 @@ Consumer migration instructions belong in consumer docs and release notes.
held-closed Escape gap as the exceptions to Escape dismissal. Hiding when focus leaves, showing on hover,
and hiding on leave go beyond the required parts `spec:AST-020` FR15 adopts
and are this record's named exception, kept because they ship.
+- **AR6 — A pinned tooltip is a toggletip.** Under `pressTrigger="toggle"` the
+ trigger is a named button that reports `aria-expanded` and `aria-controls`
+ (FR10), apart from FR9's trigger whose tooltip repeats its own text; keyboard and touch users pin and close the tooltip without hover
+ (FR9); it is announced once when it pins (FR10); and it persists until
+ Escape, a second press, a press outside, or focus leaving (FR9, WCAG 1.4.13).
+ Implementation gap: not yet built.
## Design relationships
@@ -228,14 +291,16 @@ has no arrow element.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| FR1 | `Tooltip.test.tsx` role/content suite | Rendered surface and supplied content | Removing the surface or content fails existing tooltip role and text assertions. | `audit:Tooltip/anatomy` |
-| FR2–FR8 | `Tooltip.test.tsx`; `useTooltip.test.tsx` | Hover, focus, tap, Escape, controlled, default open | Wrong open or close for an input fails. | `audit:Tooltip/behavior` |
-| AR1–AR4 | `Tooltip.a11y.test.tsx`; `Tooltip.a11y.chromium.spec.ts`; `TooltipHoverBridge.a11y.chromium.spec.ts`; `TooltipFocusReturn.a11y.chromium.spec.ts` | Real-browser hover bridge and focus return | A tooltip that vanishes on the way to it or strands focus fails. | `audit:Tooltip/accessibility` |
-| AR5 | `Tooltip.a11y.test.tsx`; `Tooltip.a11y.chromium.spec.ts` | Wrapped, text, anchor, and hook triggers | A lost role, description, keyboard-focus show, or Escape dismissal fails; focus-leave hide, hover show, and leave hide run as advisory rows (Current-state impact). | `audit:Tooltip/accessibility` |
-| FR5 | `Tooltip.test.tsx` touch suite; `TouchTrigger.a11y.chromium.spec.ts` | Tap open, scroll, second tap, tap outside | A tap that fails to open or close as stated fails. | `audit:Tooltip/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Tooltip/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| FR1 | `Tooltip.test.tsx` role/content suite | Rendered surface and supplied content | Removing the surface or content fails existing tooltip role and text assertions. | `audit:Tooltip/anatomy` |
+| FR2–FR8 | `Tooltip.test.tsx`; `useTooltip.test.tsx` | Hover, focus, tap, Escape, controlled, default open | Wrong open or close for an input fails. | `audit:Tooltip/behavior` |
+| AR1–AR4 | `Tooltip.a11y.test.tsx`; `Tooltip.a11y.chromium.spec.ts`; `TooltipHoverBridge.a11y.chromium.spec.ts`; `TooltipFocusReturn.a11y.chromium.spec.ts` | Real-browser hover bridge and focus return | A tooltip that vanishes on the way to it or strands focus fails. | `audit:Tooltip/accessibility` |
+| AR5 | `Tooltip.a11y.test.tsx`; `Tooltip.a11y.chromium.spec.ts` | Wrapped, text, anchor, and hook triggers | A lost role, description, keyboard-focus show, or Escape dismissal fails; focus-leave hide, hover show, and leave hide run as advisory rows (Current-state impact). | `audit:Tooltip/accessibility` |
+| FR5 | `Tooltip.test.tsx` touch suite; `TouchTrigger.a11y.chromium.spec.ts`; `useTouchTrigger.test.ts`, with tap-destination cases an evidence gap until built | Tap open, scroll, second tap, tap outside; a trigger inside a link, a clickable row, or a clickable card; a trigger in running text; a disabled control inside a clickable row | A tap that fails to open or close as stated, opens the tooltip on a tap that already acts, or leaves a disabled control's reason shut fails. | `audit:Tooltip/behavior` |
+| FR9, FR10, AR6 | Evidence gap until built: a press-toggle suite in `Tooltip.test.tsx` and `useTooltip.test.tsx`, and a real-touch and keyboard case in `TouchTrigger.a11y.chromium.spec.ts` | Click, Enter, Space, and tap pin; second press, press outside, focus leaving, and Escape close; pointer leave keeps the pin; controlled; non-button trigger; a truncated Text trigger whose tooltip repeats its text; a toggle trigger inside a ClickableCard, an Item row, and a `<label>` | A press that does not pin or close as stated, a pin lost on pointer leave, a missing or stale `aria-expanded` or `aria-controls`, a second announcement, a non-button trigger without the warning or its tap fallback, an own-text trigger that warns, gets `aria-expanded`, or is announced, or a pinning press that also activates the card, row, or labelled control around the trigger, fails. | `audit:Tooltip/behavior` |
+| DEP-0016, CLN-0024 | Evidence gap until built: the codemod's tests and fixtures beside its transform, and the codemod verify workflow | `touchTrigger="tap"` on an icon and a span, and on an own-text trigger, an info-only button, a button with its own action, a link, and an unknown element, under each codemod; `"auto"` and `"none"`; `pressTrigger` beside `touchTrigger`; spreads and dynamic values | A rewrite that changes behavior; under DEP-0016's codemod, a rewritten own-text, button, link, or unknown-element site; under CLN-0024's codemod, a rewritten button, link, or unknown-element site, or an identifiable own-text site left unrewritten; a reported site without its manual-migration note (all three options for a button or link); a missed static use; or a silently skipped dynamic one fails. | `audit:Tooltip/api` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Tooltip/theming` |
Read from source, with no focused test yet:
@@ -255,7 +320,40 @@ Read from source, with no focused test yet:
## Decision log
-No component-local decision is recorded.
+### DEC-1 — A press pins the layer; a tap that already acts stays with its control
+
+**Reference:** `component:Tooltip/DEC-1`
+**Decider:** `cixzhang`, `2026-10-31`
+
+A tooltip keeps previewing on hover and focus, and `pressTrigger="toggle"`
+adds one more open state of the same layer: a press pins it, so people on
+touch, keyboard, or a screen reader can keep it open long enough to read it. A
+pinned tooltip is a toggletip, so its trigger is a button that reports
+`aria-expanded`. Components declare `pressTrigger="toggle"` where the tooltip
+is the only home of their information, such as an info icon, a status dot, or
+a timestamp.
+
+`touchTrigger="auto"`, the default until `touchTrigger` folds into
+`pressTrigger` at the next minor (CLN-0024), is the fallback. Under it, a tap
+that already acts does not open the layer, so one tap does one thing: a
+truncated label inside a link follows the link, while a truncated label in
+running text opens its tooltip. Whether a tap acts is decided by walking out
+from the tapped element: the innermost control on that path decides, whether a
+button, link, label, form control, option, menu item, or row or card made
+clickable with `useClickableContainer`, the trigger included. A disabled or
+`aria-disabled` control is not an action, so its reason opens on a tap, even
+inside a clickable row or card. An element that acts only through a role-less
+`onClick` is a caller fix: it needs a role.
+
+The walk ships with the fold at the next minor (CLN-0024).
+`touchTrigger="tap"` is deprecated in favor of the toggle (DEP-0016).
+`component:HoverCard` DEC-1 applies the same rules, and `component:InfoTip` is
+the info-icon preset over the toggle.
+
+Rejected: a separate toggletip component, which would repeat Tooltip's and
+HoverCard's previews (`architecture:public-component-api` INV21).
+
+Rejected: judging the trigger alone, which lets one tap do two things.
## Open questions