@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Heading/Heading.spec.md

@@ -0,0 +1,198 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Heading
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-27
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    .github/visual-baseline/manifest.json,
+    packages/core/src/Heading/Heading.test.tsx,
+    packages/core/src/Text/useTruncation.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    packages/core/src/theme/extensibleAxes.test.ts,
+    apps/storybook/stories/Heading.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-009, spec:AST-024]
+---
+
+# Heading component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | A semantic heading with a required `level`, an optional theme-extensible visual `type`, `weight`, `accessibilityLevel`, and the shared text controls documented in `Heading.doc.mjs`.      |
+| Behavior                | `level` picks `h1`–`h6` and the default visual scale; `type` and `weight` change only appearance; `accessibilityLevel` sets `aria-level` when it differs.                                  |
+| End-user impact         | Screen-reader users navigate a document outline that matches the page's sections, whatever size each heading is drawn at.                                                                  |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                               |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.                                                    |
+| Review checks           | Reject a visual `type` or `weight` that changes the element or level, a heading that renders without a level baseline, or a duplicate native tooltip for truncation.                       |
+| Governing rules         | `spec:AST-024` (custom visual types, weight precedence, unchanged accessibility); `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Heading marks a section or page title with native heading semantics and themed
+type. It keeps the document outline (`level`, `accessibilityLevel`) separate
+from appearance (`type`, `weight`). Its consumer documentation lives in
+`Text/Heading.doc.mjs`, as a member of the Text documentation; this record is
+Heading's own contract.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Truncation tooltip not reachable by keyboard (FR4).** A truncated Heading
+  is not focusable, so Tooltip attaches no focus trigger and sighted keyboard
+  users cannot reveal the clipped text, where WCAG 2.2 2.1.1 expects
+  functionality to be keyboard operable. The full text stays in the DOM for
+  assistive technology.
+
+## Ownership boundary
+
+**Owns**
+
+- The `h1`–`h6` element, its `heading` theming target, and `aria-level`.
+- Level-based and built-in display-type sizing, weight defaults, color, and the
+  shared text layout controls on the heading element.
+- Measuring truncation and deciding when to compose the truncation Tooltip.
+
+**Does not own / non-goals**
+
+- Theme enrollment and generated declarations for custom visual types — owned
+  by `spec:AST-024` and the theme build.
+- Non-heading text — owned by `component:Text`.
+- The truncation tooltip surface, layer, and `tooltip` target — owned by
+  Tooltip.
+- Heading content — owned by the caller.
+
+## Public concepts
+
+| Concept             | Closed values or states                                             | Meaning                                                       | Availability by variant/orientation/state | Default               | Owner               | Stability | Invalid-value behavior                                                                             |
+| ------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------- | --------------------- | ------------------- | --------- | -------------------------------------------------------------------------------------------------- |
+| Level               | 1–6                                                                 | Selects `h1`–`h6` and the level's visual scale.               | Always                                    | Required              | `component:Heading` | Stable    | TypeScript rejects other values.                                                                   |
+| Visual type         | `display-1`, `display-2`, `display-3`; theme additions              | Replaces the level's visual scale without changing semantics. | Always                                    | unset                 | `component:Heading` | Stable    | A theme-added value is reflected on `heading` and keeps the level's baseline (`spec:AST-024` FR4). |
+| Weight              | `normal`, `medium`, `semibold`, `bold`                              | Overrides the type or level default weight.                   | Always                                    | type or level default | `component:Heading` | Stable    | TypeScript rejects other values.                                                                   |
+| Accessibility level | 1–6                                                                 | The outline level exposed to assistive technology.            | Always                                    | `level`               | `component:Heading` | Stable    | TypeScript rejects other values.                                                                   |
+| Truncation          | `maxLines` 0 (none), 1, or more; tooltip on, off, or at a placement | Clamps lines and offers the full text in a Tooltip.           | Always                                    | 0; tooltip on         | `component:Heading` | Stable    | —                                                                                                  |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | `level` renders `h1`–`h6`. `accessibilityLevel` adds `aria-level` only when it differs from `level`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests |
+| FR2 | The heading carries the `heading` target reflecting `level`, `color`, and any supplied `type` and `weight`. A built-in `type` applies its display scale and default weight; otherwise the level's scale applies. A theme-added `type` keeps the level's scale as its baseline. An explicit `weight` wins over the type and level defaults.                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
+| FR3 | `color` defaults to `primary`; a theme-added color keeps the primary baseline until a theme paints it. `hasCapsize` renders `block` and trims to cap height; otherwise `maxLines` above 1 renders the line-clamp box, `maxLines={1}` renders `block`, and otherwise `display` (default `block`) applies. `justify` uses logical values; `start`, the default, sets no alignment, so the element follows its container's. `textWrap` and `hasStrikethrough` apply their text treatments.                                                                                                                                                                                                                                                     | Current source and tests |
+| FR4 | `maxLines={1}` clips one line with an ellipsis; a larger value clamps to that many lines unless `hasCapsize` is set, whose `block` display removes the clamp. With truncation, `wordBreak` defaults to `break-all` for one line and `break-word` otherwise. When the text is measured as truncated and `hasTruncateTooltip` is not `false`, a lazily loaded Tooltip anchored to the heading shows the full text at the given placement (default `above`); no native `title` is added. `hasTruncateTooltip={false}` takes no measurement. A truncation tooltip can be opened from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip opens on hover and touch only, because the heading is not focusable (Current-state impact). | Current source and tests |
+| FR5 | `ref` reaches the heading element. Supported DOM, ARIA, data, and event props reach it after the derived `aria-level`, so a caller `aria-level` wins; `xstyle`, `className`, and `style` merge in that order after component styles, with the line clamp applied after `style`.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may restyle `heading` per `level`, `color`,
+  `type`, and `weight` without changing the element or level.
+- **AV2 — Visual reuse.** Any level may use any visual type.
+
+### Representative states
+
+| State                   | Required invariant                                             | Allowed variation |
+| ----------------------- | -------------------------------------------------------------- | ----------------- |
+| Level only              | `h{level}` at the level's scale.                               | Level.            |
+| Display type            | Same element; display scale and weight; `data-type` reflected. | Type.             |
+| Theme-added type        | Same element; level baseline; `data-type` reflected.           | Theme paint.      |
+| Accessibility override  | `aria-level` differs from the element's level.                 | —                 |
+| Truncated with tooltip  | Clamped heading anchors one Tooltip with the full text.        | Placement.        |
+| Truncation, tooltip off | Clamped heading; no measurement; no Tooltip.                   | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Weight.** Explicit `weight` → built-in type default → level default
+  (`spec:AST-024` FR8).
+- **ORD2 — Scale.** Built-in `type` → level scale (also the baseline for a
+  theme-added type).
+- **ORD3 — Display.** `hasCapsize` (`block`) → `maxLines` above 1 (line-clamp
+  box) → `maxLines={1}` (`block`) → `display` prop.
+
+### Performance and resources
+
+- **PR1 — Measured only when needed.** Truncation is measured only when
+  `maxLines` is positive and the tooltip is enabled; re-measuring follows size
+  and content changes without a per-heading observer; the Tooltip module loads
+  only when the text is truncated.
+
+## Accessibility contract
+
+- **AR1 — Native heading.** The element is a native `h1`–`h6`; a visual type or
+  weight never changes the role, level, or name (`spec:AST-024` FR15).
+- **AR2 — Outline override.** `accessibilityLevel` exposes a different outline
+  level through `aria-level` without changing the element.
+- **AR3 — Truncated text.** The full text stays in the heading's DOM; the
+  truncation Tooltip is the only tooltip, and any description it adds is
+  Tooltip's.
+
+## Design relationships
+
+| Anatomy or state   | Design requirement                                      | Representation authority | Hierarchy role | Component contract |
+| ------------------ | ------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Heading            | A section or page title at the level's or type's scale. | Current source and docs  | Prominent      | FR1–FR3, AR1, AR2  |
+| Truncation tooltip | The full text when the heading is clamped.              | Tooltip                  | Supporting     | FR4, AR3           |
+
+Theming: the heading element is the single `heading` target. Its consumer
+documentation is a member of `Text/Heading.doc.mjs` and lists no anatomy, so no
+anatomy-theming block is declared; the truncation tooltip's target belongs to
+Tooltip.
+
+## Family and system relationships
+
+- `spec:AST-024` owns custom visual types, weight precedence, and the rule that
+  visual changes leave accessibility unchanged; FR2, ORD1, and AR1 apply it.
+- `component:Text` shares Heading's type styles and truncation mechanism.
+- `architecture:component-theming-surface` sets the rules the `heading` target
+  follows (INV6) and qualifies `type` as a theme-extensible axis (INV14).
+
+## Verification map
+
+| Contract | Verification                                                                                                | Representative states                     | Mutation or failure expectation                                                                                                                                                                                                                                                    | Audit section            |
+| -------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1, AR2 | `Heading.test.tsx` level and `accessibilityLevel` tests                                                     | Levels 1–6; differing override            | A wrong element, or a missing `aria-level` for a differing override, fails. Gap: no test asserts that an equal `accessibilityLevel` adds no `aria-level`.                                                                                                                          | `audit:Heading/a11y`     |
+| FR2      | `Heading.test.tsx` target, type, theme-added type, weight, and omitted-type tests; `extensibleAxes.test.ts` | Display types, theme-added type, weight   | A lost `heading` class or `data-level`, `data-color`, `data-type`, or `data-weight` reflection, a reflected omitted type, or a theme-added type losing its level baseline fails. Gap: the display scales, default weights, and weight precedence in paint have no automated check. | `audit:Heading/theming`  |
+| FR3      | Stable visual baseline `core-heading--level-1`; `Heading.stories.tsx`                                       | Level 1 default                           | A changed level-1 scale, color, or display comes back changed for review. Gap: the prop tests assert presence only, so color paint, `display` precedence, `justify`, `textWrap`, cap-height trim, strikethrough, and the theme-added color baseline have no automated check.       | `audit:Heading/behavior` |
+| FR4, PR1 | `Heading.test.tsx` truncation-measurement tests; `useTruncation.test.tsx`                                   | Tooltip on and off; content change        | Measuring with the tooltip off, not measuring with it on, or a missed re-measure fails. Gap: the ellipsis and line clamp, the `wordBreak` defaults, and the tooltip's appearance and placement have no automated check.                                                            | `audit:Heading/behavior` |
+| FR5      | `Heading.test.tsx` ref, `id`, and passthrough tests                                                         | Rerender; `id`; `data-testid`             | A detached ref, a lost `id`, or a lost test id fails. Gap: no test covers a caller `aria-level` winning, the styling-input merge order, or the line clamp after `style`.                                                                                                           | `audit:Heading/behavior` |
+| AR1      | `Heading.test.tsx` display-type element tests                                                               | Levels with display and theme-added types | A visual type that changes the element fails.                                                                                                                                                                                                                                      | `audit:Heading/a11y`     |
+| AR3      | Source review                                                                                               | Truncated heading                         | Gap: no Heading test asserts the absence of a native `title`.                                                                                                                                                                                                                      | `audit:Heading/a11y`     |
+| AR1, AR2 | Accessibility-tree evidence (`spec:AST-009` FR3)                                                            | Levels, override, display types           | Gap: no accessibility-tree check proves the heading role and level; the unit tests query the DOM.                                                                                                                                                                                  | `audit:Heading/a11y`     |
+
+## Decision log
+
+None recorded. The record describes shipped behavior.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/HoverCard/HoverCard.spec.md

@@ -0,0 +1,244 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:HoverCard
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-28
+owners: [cixzhang]
+review_triggers: [behavior, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/HoverCard/HoverCard.test.tsx,
+    packages/core/src/Layer/layerDismissalFamilies.test.tsx,
+    apps/storybook/stories/HoverCard.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:layer-runtime,
+  ]
+contributing: []
+system_specs: []
+---
+
+# 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`.                                                                                                                                                                                                          |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+HoverCard previews more information about a trigger, such as a profile or a
+link summary, without navigating away. It owns the trigger wiring, when the
+card opens and closes for each input, the card's semantics, and its surface.
+Consumer usage lives in `HoverCard.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- 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
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **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
+  caller already holds, so the card stays until focus or the pointer leaves the
+  trigger or the card (FR7).
+- **Hover timing does not use the shared hover recognizer.** The card runs its
+  own show and hide timers. `architecture:interaction-modality` INV11 has
+  `useHoverCard` take its hover timing from the shared hover recognizer.
+- **A roving trigger may not open on focus.** Under `focusTrigger="auto"` the
+  card reads the tab order only when the trigger's listeners attach, so a
+  trigger rendered with `tabindex="-1"` opens only on mouse hover after it takes
+  keyboard focus, until a re-render re-attaches them. A focusable trigger
+  `auto` does not recognize, such as a `<summary>` or an SVG link, never opens
+  on focus. `architecture:interaction-modality` INV4 keeps hover from being the
+  only discovery path.
+- **A replaced trigger loses its wiring.** The card wires its trigger element
+  when it opens or closes, when `label` changes, or when its listeners
+  re-attach. A trigger element replaced after mount gets no popup attributes,
+  description, or hover and focus opening until one of those happens (FR2,
+  FR3).
+- **Escape cannot close a card in another document.** HoverCard listens for
+  Escape only in the page's document, so a card 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).
+- **The hold follows only the pointer.** The card stays open only while the
+  pointer is on the trigger or the card. A card opened by keyboard focus closes
+  once the pointer crosses the trigger and leaves, while the trigger keeps
+  focus, and a hover-opened card the user has tabbed into closes when the
+  pointer leaves the trigger, dropping focus to the page. WCAG 1.4.13 requires
+  content shown on focus to persist until focus moves or the user dismisses it.
+- **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
+  the card (FR2).
+
+## Ownership boundary
+
+**Owns**
+
+- Trigger wiring, open and close behavior per input, card semantics, and the
+  `hover-card` surface (FR1–FR8).
+
+**Does not own / non-goals**
+
+- The trigger element and the card's body and actions — owned by the caller.
+- Layer hosting, positioning, and inline-safe portaling — owned by
+  `architecture:layer-runtime`; shared Escape ordering — owned by
+  `family:overlay-dismissal`.
+- The `useHoverCard` hook's public contract — an uncontracted module; this
+  record covers HoverCard's observable behavior.
+
+## Public concepts
+
+| Concept       | Closed values or states   | Meaning                                                                            | Availability by variant/orientation/state | Default | Owner                 | Stability | Invalid-value behavior           |
+| ------------- | ------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------- | ------- | --------------------- | --------- | -------------------------------- |
+| Popup role    | named dialog, group       | `label` makes the card a named `dialog`; without it the card is a `group`.         | Every card.                               | group   | `component:HoverCard` | Stable    | Not applicable.                  |
+| Focus trigger | `auto`, `always`, `never` | Whether focus opens the card: on focusable triggers (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. |
+
+## 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 |
+
+### Allowed variation
+
+- **AV1 — Content.** Any content, including interactive actions.
+- **AV2 — Theme styling.** Themes restyle `hover-card`.
+
+### Representative states
+
+| State               | Required invariant                             | Allowed variation |
+| ------------------- | ---------------------------------------------- | ----------------- |
+| Unlabelled          | `role="group"`; trigger described by the card. | Content.          |
+| Labelled            | Named `dialog`; trigger advertises the popup.  | Content.          |
+| Hover into card     | Stays open; actions usable.                    | Delays.           |
+| Escape from content | Closes; focus back on trigger; no reopen.      | —                 |
+| Tap-open            | Opens on lift; survives taps on its content.   | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Open state.** `isOpen`, then the input triggers, apart from FR7's
+  focus gap.
+
+### Performance and resources
+
+- **PR1 — Listeners.** An unchanged rerender does not rebind the trigger's
+  listeners; an element trigger rebinds them on each open and close, and any
+  trigger rebinds them when `onOpenChange` changes identity.
+
+## Accessibility contract
+
+- **AR1 — Popup semantics.** FR3.
+- **AR2 — Content on hover or focus.** FR4–FR6 keep the card hoverable,
+  dismissible, and persistent per WCAG 1.4.13, except FR6's other-document gap,
+  FR7's held-closed Escape gap, and the pointer-only hold (Current-state
+  impact).
+
+## Design relationships
+
+| Anatomy or state | Design requirement                               | Representation authority       | Hierarchy role    | Component contract |
+| ---------------- | ------------------------------------------------ | ------------------------------ | ----------------- | ------------------ |
+| Trigger          | Caller element that opens the card.              | Caller content                 | Context-dependent | FR2                |
+| Card             | Padded floating surface anchored to the trigger. | Current source and public docs | Prominent         | FR1                |
+| Body             | Caller content inside the card.                  | Caller content                 | Prominent         | FR1                |
+| Actions          | Optional caller buttons inside the card.         | Caller content                 | Supporting        | FR4                |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Trigger": {
+    "none": {
+      "reason": "intentional: The trigger is the caller's element and carries its own component's target."
+    }
+  },
+  "Card": {"target": "hover-card"},
+  "Body": {"inherits": "hover-card"},
+  "Actions": {
+    "none": {
+      "reason": "intentional: Actions are caller-rendered controls that carry their own components' targets."
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- `family:overlay-dismissal` owns Escape routing and topmost handling.
+- `architecture:layer-runtime` owns hosting, positioning, and portaling.
+- `architecture:interaction-modality` owns the focus modality FR4 uses and,
+  through INV11, the hover timing source for FR4.
+- `architecture:component-theming-surface` owns the `hover-card` target.
+
+## 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`       |
+
+Read from source, with no focused test yet:
+
+- FR1: the card's padding, and `xstyle`, `className`, and `style` reaching it.
+- FR3: restoring the trigger's own attributes on unmount.
+- FR4: the `delay` and `hideDelay` timing, and moving between the trigger and
+  the card keeping it open.
+- FR7: `isOpen` forcing the card, and the focus return after a controlled
+  close.
+- FR8: `hasHoverIndication`.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, or layer-system
+rules. It links to their owners.

package/src/HoverCard/HoverCard.test.tsx

@@ -1049,7 +1049,11 @@ describe('HoverCard', () => {
       __resetInteractionModalityForTest();
     });
 
-    /** A tap: the pointer sequence a finger produces before hover is faked. */
+    /**
+     * A tap, in the order a browser dispatches it: the finger's pointer events,
+     * then the hover it synthesizes, then the `click` that says the touch was a
+     * tap and not the start of a scroll.
+     */
     const tap = (element: HTMLElement) => {
       // A finger's arrival fires pointerenter too, and that is the path a pen
       // must not take — cover it here rather than starting at pointerdown.
@@ -1058,6 +1062,7 @@ describe('HoverCard', () => {
       fireEvent.pointerUp(element, {pointerType: 'touch'});
       // Touch synthesizes hover after the press; the card must not act on it.
       fireEvent.mouseEnter(element);
+      fireEvent.click(element);
     };
 
     it('opens on a tap when the trigger performs no action', async () => {
@@ -1141,6 +1146,8 @@ describe('HoverCard', () => {
         hidden: true,
       });
       fireEvent.pointerDown(action, {pointerType: 'touch'});
+      fireEvent.pointerUp(action, {pointerType: 'touch'});
+      fireEvent.click(action);
 
       await new Promise(resolve => setTimeout(resolve, 50));
       expect(onOpenChange).not.toHaveBeenCalledWith(false);
@@ -1166,10 +1173,93 @@ describe('HoverCard', () => {
         expect(onOpenChange).toHaveBeenCalledWith(true);
       });
 
-      fireEvent.pointerDown(screen.getByRole('button', {name: 'Elsewhere'}), {
-        pointerType: 'touch',
+      const elsewhere = screen.getByRole('button', {name: 'Elsewhere'});
+      fireEvent.pointerDown(elsewhere, {pointerType: 'touch'});
+      // Not yet: a popover closes when the outside tap lifts.
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
+
+      fireEvent.pointerUp(elsewhere, {pointerType: 'touch'});
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+
+    it('opens when the finger lifts, not when it lands', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <HoverCard
+          content={<span>Card content</span>}
+          onOpenChange={onOpenChange}
+          delay={0}>
+          Ruby Cheung
+        </HoverCard>,
+      );
+
+      const trigger = screen.getByText('Ruby Cheung');
+      fireEvent.pointerEnter(trigger, {pointerType: 'touch'});
+      fireEvent.pointerDown(trigger, {pointerType: 'touch'});
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalled();
+
+      fireEvent.pointerUp(trigger, {pointerType: 'touch'});
+      fireEvent.click(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+
+    it('never opens for a touch that turns into a scroll', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <HoverCard
+          content={<span>Card content</span>}
+          onOpenChange={onOpenChange}
+          delay={0}>
+          Ruby Cheung
+        </HoverCard>,
+      );
+
+      const trigger = screen.getByText('Ruby Cheung');
+      fireEvent.pointerEnter(trigger, {pointerType: 'touch'});
+      fireEvent.pointerDown(trigger, {pointerType: 'touch'});
+      fireEvent.pointerCancel(trigger, {pointerType: 'touch'});
+
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalled();
+    });
+
+    it('closes when a scroll starts outside, but not for one inside the card', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <>
+          <HoverCard
+            content={<p>Card content</p>}
+            onOpenChange={onOpenChange}
+            delay={0}
+            hideDelay={0}>
+            Ruby Cheung
+          </HoverCard>
+          <p>Page content</p>
+        </>,
+      );
+
+      tap(screen.getByText('Ruby Cheung'));
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
       });
+      onOpenChange.mockClear();
+
+      // Scrolling the card's own content keeps it.
+      const inside = await screen.findByText('Card content');
+      fireEvent.pointerDown(inside, {pointerType: 'touch'});
+      fireEvent.pointerCancel(inside, {pointerType: 'touch'});
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
 
+      const page = screen.getByText('Page content');
+      fireEvent.pointerDown(page, {pointerType: 'touch'});
+      fireEvent.pointerCancel(page, {pointerType: 'touch'});
       await waitFor(() => {
         expect(onOpenChange).toHaveBeenCalledWith(false);
       });