@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/ClickableCard/ClickableCard.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 6
+template_version: 7
 kind: component
 id: component:ClickableCard
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-28
 owners: [cixzhang]
 review_triggers:
   [
@@ -23,9 +23,13 @@ review_triggers:
 verified_by:
   [
     packages/core/src/ClickableCard/ClickableCard.test.tsx,
+    packages/core/src/Button/__tests__/Button.a11y.test.tsx,
+    packages/core/src/Button/__tests__/Button.a11y.chromium.spec.ts,
+    packages/core/src/__tests__/CardPress.a11y.chromium.spec.ts,
+    packages/core/src/hooks/useClickableContainer.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
     apps/storybook/stories/ClickableCard.stories.tsx,
-    apps/storybook/rtl-audit/targets.json,
+    .github/visual-baseline/manifest.json,
     scripts/check-knowledge.mjs,
   ]
 modules: []
@@ -33,153 +37,151 @@ families: [family:navigation-destinations]
 design_specs: []
 architecture:
   [
-    architecture:knowledge-contracts,
     architecture:public-component-api,
     architecture:component-theming-surface,
     architecture:interaction-modality,
     architecture:component-test-sufficiency,
   ]
 contributing: []
-system_specs: [spec:AST-005, spec:AST-029]
+system_specs: [spec:AST-005, spec:AST-009, spec:AST-085]
 ---
 
 # ClickableCard component contract
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                        |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | No public API change. The released `ClickableCard` component, props, ref target, theme target, and defaults remain unchanged.                                                                   |
-| Behavior                | A card provides one enlarged action or navigation surface while nested interactive descendants retain their own activation. A disabled card exposes no live activation or destination.          |
-| End-user impact         | People using assistive technology cannot activate a destination from a card presented as disabled; enabled action, navigation, and nested-control paths remain unchanged.                       |
-| Builder impact          | None. Existing `isDisabled` usage gains the disabled behavior its public docs already describe.                                                                                                 |
-| Compatibility/readiness | Backward-compatible defect repair plus observational documentation. No migration is required.                                                                                                   |
-| Review checks           | Reject a live destination in disabled state, duplicate activation, nested-control bubbling, a blocked navigation sink, lost focus indication, or a moved/reflected theme target.                |
-| Governing rules         | `family:navigation-destinations`, `architecture:interaction-modality`, `architecture:public-component-api`, `architecture:component-theming-surface`, and objective disabled-control semantics. |
+| Area                    | Contract                                                                                                                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | A Card with a required `label` and either `onClick` (action) or `href` (navigation), plus `isDisabled` and Card's padding, variant, elevation, and size inputs.                       |
+| Behavior                | A visually hidden native button or link owns the card's action; the whole card surface activates it, while nested controls and selected text keep their own outcomes.                 |
+| End-user impact         | People can activate a card from anywhere on it, by pointer or keyboard, and a disabled card stays reachable and announced while doing nothing.                                        |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                          |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact.                                             |
+| Review checks           | Reject a live destination while disabled, duplicate activation, activation from a nested control or selected text, a destination that skips the shared decision, or lost focus paint. |
+| Governing rules         | `family:navigation-destinations/FR1,FR3–FR5`; `architecture:interaction-modality/INV2–INV5`; `architecture:public-component-api/INV5–INV8`; `spec:AST-085` FR1, FR2, FR5, FR6.        |
 
 This table is a review projection; the body below is authoritative.
 
 ## Intent
 
-ClickableCard turns a Card surface into one action or navigation target without taking
-activation ownership from interactive descendants. This draft records verified released
-behavior and the objective disabled-link repair in the accompanying audit. It does not
-add a prop, destination mode, visual treatment, selection model, or caller obligation.
+ClickableCard turns a Card surface into one action or navigation target
+without taking activation away from the interactive content inside it.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: backward-compatible defect repair; public declarations,
-  defaults, theme target, DOM root, and enabled behavior remain unchanged
+- Compatibility class: records shipped behavior; no public prop, default,
+  DOM, target, or styling output changes
 - Controlled/uncontrolled behavior: not applicable
-- Migration decision: none; disabled cards now consistently suppress every activation
-  path already described as disabled
+- Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **Two focus indicators on nested controls (AR3).** The card draws its focus
+  outline while any descendant has keyboard focus, so focusing a nested
+  control shows the card outline and the control's own, where
+  `architecture:interaction-modality` INV3 allows one indicator per focus move.
+- **Disabled state not reflected on the target (FR4).** The `clickable-card`
+  target reflects `variant` but not the disabled state, so a theme cannot
+  style it there, where `architecture:component-theming-surface` INV6 keeps
+  state on the owning target.
+
 ## Ownership boundary
 
 **Owns**
 
-- One enlarged action or navigation surface and its accessible control.
-- Suppression of card activation when the event belongs to a nested interactive
-  descendant or selected text.
-- Enabled, disabled, hover, pressed, and focus-indicator behavior on the card surface.
-- The `clickable-card` target and reflected visual variant on the painted root.
+- The hidden native button or link that carries the card's action, and its
+  name.
+- Card-surface activation, and its suppression for nested interactive
+  descendants and selected text.
+- Enabled, disabled, hover, pressed, and delegated focus paint on the card.
+- The `clickable-card` target on the painted root.
 
 **Does not own / non-goals**
 
-- Selection or toggling; `component:SelectableCard` owns that model.
-- Semantics, paint, or activation of caller-supplied descendants.
-- Destination acceptance policy; `family:navigation-destinations` owns it.
-- Card padding, variant paint, radius, elevation, and size primitives; `component:Card`
-  supplies those released surfaces.
-- A new action requirement when both `href` and `onClick` are omitted. This draft
-  records the existing render without deciding a new API constraint.
+- Selection or toggling — owned by `component:SelectableCard`.
+- Semantics, paint, or activation of caller content.
+- Destination acceptance — owned by `family:navigation-destinations`.
+- Card padding, variant paint, radius, elevation, and sizing — owned by
+  `component:Card`.
 
 ## Public concepts
 
-| Concept           | Closed values or states                                             | Meaning                                                                                                                             | Availability by variant/orientation/state    | Default                                                     | Owner                                          | Stability                                       | Invalid-value behavior                                                 |
-| ----------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
-| Activation mode   | action, navigation, no supplied action                              | A hidden native button or link owns card activation; omission preserves the current render without inventing a destination.         | Every visual variant.                        | No supplied action when both inputs are omitted.            | `component:ClickableCard`                      | Observed released surface                       | Public types reject unsupported modes.                                 |
-| Interaction state | enabled, disabled                                                   | Enabled cards accept their supported activation paths. Disabled cards expose no live action or destination and leave the tab order. | Action and navigation modes.                 | enabled                                                     | `component:ClickableCard`                      | Observed released surface plus objective repair | Public boolean type admits only enabled or omitted.                    |
-| Nested ownership  | card surface, nested interactive descendant, selected text          | Only the card surface activates the card; descendants and selected text retain their own outcomes.                                  | Enabled cards.                               | Card surface when no nested owner or selection applies.     | `component:ClickableCard`                      | Observed released surface                       | Event targets outside the supported DOM path do not activate the card. |
-| Destination       | accepted or blocked                                                 | Every navigation sink uses the family decision before navigation.                                                                   | Navigation mode and every activation method. | No destination when `href` is omitted.                      | `family:navigation-destinations`               | Current family contract                         | Blocked destinations remain inert.                                     |
-| Visual surface    | Card padding, variant, elevation, size, and `clickable-card` target | Card supplies base paint and geometry; ClickableCard adds interaction paint and target identity.                                    | Every mode and state.                        | Current Card defaults; `variant=default`, `elevation=none`. | `component:Card` and `component:ClickableCard` | Observed released surface                       | Public types reject unsupported closed values.                         |
+| Concept          | Closed values or states                                | Meaning                                                      | Availability by variant/orientation/state | Default | Owner                            | Stability | Invalid-value behavior                   |
+| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ | ----------------------------------------- | ------- | -------------------------------- | --------- | ---------------------------------------- |
+| Activation mode  | action (`onClick`); navigation (`href`); neither (OQ1) | Which hidden native control owns the card's action.          | Every variant                             | neither | `component:ClickableCard`        | Stable    | `href` wins when both are given.         |
+| Disabled         | enabled; disabled                                      | Disabled cards stay focusable and announced but run nothing. | Both modes                                | enabled | `component:ClickableCard`        | Stable    | —                                        |
+| Nested ownership | card surface; nested interactive descendant; selection | Only a surface press activates the card.                     | Enabled cards                             | surface | `component:ClickableCard`        | Stable    | —                                        |
+| Destination      | accepted; blocked                                      | Every navigation sink uses the shared destination decision.  | Navigation mode                           | none    | `family:navigation-destinations` | Stable    | A blocked destination does not navigate. |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                            | Basis                                                                                                                       | Draft review state                                                                        |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| FR1 | The current root is Card's `div`. A visually hidden native button owns action semantics; a visually hidden native anchor owns enabled navigation semantics. The required label names that control.                                                             | Released source, docs, tests, and objective accessible-name semantics                                                       | Verified released behavior; no role or root change decided                                |
-| FR2 | Surface activation fires the consumer callback once, then performs an accepted navigation unless the callback cancels it. Activation belonging to a nested interactive descendant or selected text does not activate the card.                                 | Released docs, source, focused tests, and `architecture:public-component-api/INV7`                                          | Verified released behavior                                                                |
-| FR3 | Plain, new-tab, modified, middle-click, and delegated navigation use the shared destination decision. Blocked destinations do not navigate.                                                                                                                    | `family:navigation-destinations/FR1, FR3–FR5`                                                                               | Settled current family behavior                                                           |
-| FR4 | Disabled action cards use a native disabled button. Disabled navigation cards render an `aria-disabled` anchor with an explicit link role, no live `href` or `target`, leave the tab order, cancel direct synthetic activation, and expose no surface handler. | Public disabled docs, objective ARIA disabled-control semantics, current Link precedent, and red/green audit evidence       | Objective contract restoration in this audit; no API or visual decision                   |
-| FR5 | The root retains Card geometry and paint, adds pointer-capable hover and pressed overlay behavior only while enabled, and delegates focus indication from the hidden semantic control to the visible root.                                                     | Released source, stories, browser evidence, and `architecture:interaction-modality/INV2–INV5`                               | Verified released behavior; the separate open touch-press PR is not adopted by this draft |
-| FR6 | The root carries `clickable-card`, reflects `variant`, and composes supported ref, DOM, ARIA, data, event, class, style, and StyleX inputs without replacing component-owned behavior.                                                                         | `architecture:public-component-api/INV5–INV8`, `architecture:component-theming-surface/INV4–INV6`, source, and target tests | Verified released behavior                                                                |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Basis                                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| FR1 | The root is Card's `div`. With `href`, a visually hidden native link holds the destination and `target`; otherwise a visually hidden `button type="button"` calls `onClick`. `label` names that control, and the hidden control is the card's tab stop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source and tests                                                |
+| FR2 | A primary-button press on the card surface calls `onClick` once with the card as `currentTarget`, then performs an accepted navigation unless the callback cancels it. A middle press on the surface of a card given `href` opens an accepted destination in a new tab without calling `onClick`. A press inside a nested interactive descendant, or one that ends a text selection, does not activate the card. Activating the hidden button of an action card calls `onClick` once; activating the hidden link navigates without calling `onClick`.                                                                                                                                                                        | Current source and tests; `architecture:public-component-api` INV7      |
+| FR3 | Plain, new-tab, modified, middle-click, and surface-delegated navigation use the shared destination decision; a blocked destination does not navigate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `family:navigation-destinations` FR1, FR3–FR5                           |
+| FR4 | `isDisabled` keeps the hidden control focusable with `aria-disabled="true"`; Enter, Space, and clicks on it do nothing. A disabled link keeps its link role and name but has no `href` or `target`. The control stays focusable and announced (`spec:AST-085` FR1, FR2, FR5); the card's own click and mouseup handling and the caller's `onMouseUp` are removed, other caller event props still reach the root, and the surface shows no hover or pressed paint (`spec:AST-085` FR6), and renders at half opacity. The disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `clickable-card` target reflects no disabled state (Current-state impact). | Current source and tests                                                |
+| FR5 | While enabled, the root paints the shared hover overlay under a hover-capable pointer and the pressed overlay for mouse and touch presses, and a bordered card's border responds to hover. Keyboard focus on the hidden control shows the shared focus outline on the root.                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source, stories, and `architecture:interaction-modality`        |
+| FR6 | The root carries the `clickable-card` target reflecting `variant` beside Card's target. `ref` reaches the root; supported DOM, ARIA, data, and event props reach it; a caller `onMouseUp` runs after the card's own; `xstyle`, `className`, and `style` compose after the component styles.                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests; `architecture:public-component-api` INV5–INV8 |
 
 ### Allowed variation
 
-- **AV1 — Caller content.** Renderable caller content retains its own semantics,
-  theming, layout, and interaction ownership inside the card.
-- **AV2 — Router integration.** An accepted destination may use the native anchor or
-  the active LinkProvider implementation; a disabled or rejected destination invokes
-  neither custom navigation nor an imperative sink.
-- **AV3 — Card appearance.** Released Card variants, padding, elevation, and supported
-  sizing may vary without changing activation ownership.
+- **AV1 — Caller content.** Caller content keeps its own semantics, theming,
+  and interaction inside the card.
+- **AV2 — Router integration.** An accepted destination may use the native
+  link or the active link provider.
+- **AV3 — Card appearance.** Card variants, padding, elevation, and sizing vary
+  without changing activation ownership.
 
 ### Representative states
 
-| State                 | Required invariant                                                                                                                                          | Allowed variation                                            |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| Enabled action        | Hidden button is operable by keyboard and card surface; callback runs once.                                                                                 | Caller content and Card appearance may vary.                 |
-| Enabled navigation    | Hidden link retains accepted destination and browser affordances; every enlarged-surface sink uses the family decision.                                     | Native or provider router may own accepted navigation.       |
-| Disabled action       | Native button is disabled and no card activation occurs.                                                                                                    | Disabled paint follows current Card composition.             |
-| Disabled navigation   | Anchor keeps its link role and accessible name but has no destination or target, is out of the tab order, and direct or surface activation cannot navigate. | The inert anchor retains its label and disabled state.       |
-| Nested control        | Descendant control handles its own event without activating the card.                                                                                       | Any supported interactive descendant may own the event.      |
-| Narrow or RTL context | Logical geometry and activation ownership remain unchanged.                                                                                                 | Caller content may wrap; no directional glyph is owned here. |
+| State               | Required invariant                                                            | Allowed variation          |
+| ------------------- | ----------------------------------------------------------------------------- | -------------------------- |
+| Enabled action      | Hidden button operable by keyboard and by the surface; `onClick` runs once.   | Content and appearance.    |
+| Enabled navigation  | Hidden link keeps its destination; surface presses use the shared decision.   | Native or provider router. |
+| Disabled action     | Hidden button focusable with `aria-disabled`; nothing runs.                   | —                          |
+| Disabled navigation | Link role and name kept; no `href` or `target`; focusable; nothing navigates. | —                          |
+| Nested control      | The descendant handles its own event; the card does not activate.             | Any interactive child.     |
 
 ### Transformation and precedence order
 
-- **ORD1 — Event ownership.** Disabled state first suppresses card behavior; text
-  selection and nested interactive ownership then suppress card behavior; otherwise the
-  consumer callback runs before any accepted destination sink and may cancel it.
-- **ORD2 — Navigation.** Normalize and decide the destination before selecting native,
+- **ORD1 — Event ownership.** Disabled removes the card's own click and
+  mouseup handling; then text selection and nested interactive ownership
+  suppress card activation; otherwise, for a primary-button press, `onClick`
+  runs before any accepted destination and may cancel it, and a middle press
+  opens an accepted `href` without calling `onClick`.
+- **ORD2 — Navigation.** Decide the destination before choosing native,
   router, same-tab, new-tab, modified, middle-click, or delegated activation.
-- **ORD3 — Root composition.** Compose Card paint and geometry, `clickable-card`
-  reflection, focus delegation, enabled interaction paint, and supported consumer
-  styling on the visible root while the hidden control retains semantics.
 
 ### Performance and resources
 
-- The component creates local refs and uses the shared clickable-container hook. It owns
-  no timer, observer, network request, portal, asynchronous task, or layout measurement.
-- Current hook attribute synchronization is shared implementation behavior, not a new
-  component requirement in this draft.
+- **PR1 — Shared resources only.** ClickableCard installs the shared press
+  controller on mount and marks its root as a press surface only while
+  enabled; it adds no timer, observer, request, portal, or layout measurement
+  of its own.
 
 ## Accessibility contract
 
-- **AR1 — Native semantic owner.** The hidden button or enabled anchor exposes the
-  action's native role and the required label; the visual root does not duplicate that
-  role.
-- **AR2 — Disabled means inoperable.** `aria-disabled` never substitutes for behavior:
-  the disabled navigation anchor has no live destination and direct activation is
-  canceled. Disabled action mode uses native button disablement.
-- **AR3 — One visible focus indicator.** Keyboard focus on the hidden control paints the
-  shared focus indicator on the visible card root. Nested controls paint their own
-  indicators.
-- **AR4 — Modality parity.** Keyboard, pointer, and touch-capable users retain an
-  operable enabled path. Hover is an enhancement and never the only activation path.
+- **AR1 — Native semantic owner.** The hidden button or link exposes its
+  native role and the `label`; the visible root adds no role of its own.
+- **AR2 — Disabled stays perceivable.** A disabled card's control stays in the
+  tab order, announces `aria-disabled`, and is inert (FR4).
+- **AR3 — One focus indicator per focus move.** Focus on the hidden control is
+  shown once, on the card root (`architecture:interaction-modality` INV3).
+  Implementation gap: the root also outlines while a nested control has focus,
+  so that control shows two indicators (Current-state impact).
+- **AR4 — Modality parity.** Keyboard, pointer, and touch users each have an
+  operable path; hover is never the only one.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                           | Representation authority                                             | Hierarchy role                   | Component contract |
-| ---------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------- | ------------------ |
-| Container        | Paints the Card surface plus enabled interaction and delegated focus states. | Current Card and ClickableCard source plus shared interaction tokens | Context-dependent action surface | FR5–FR6, AR3–AR4   |
-| Content          | Retains caller-owned hierarchy and descendant interaction.                   | Caller-owned content                                                 | Context-dependent                | FR2, AV1           |
-
-This observational draft records current representation. It does not decide new
-proportions, density, colour, motion, or interaction feel.
+| Anatomy or state | Design requirement                                                   | Representation authority | Hierarchy role                   | Component contract |
+| ---------------- | -------------------------------------------------------------------- | ------------------------ | -------------------------------- | ------------------ |
+| Container        | The Card surface with enabled interaction paint and delegated focus. | Current source and docs  | Context-dependent action surface | FR4–FR6, AR3, AR4  |
+| Content          | Caller hierarchy and interaction, unchanged.                         | Caller-owned content     | Context-dependent                | FR2, AV1           |
 
 ### Theming anatomy
 
@@ -198,48 +200,42 @@ proportions, density, colour, motion, or interaction feel.
 
 ## Family and system relationships
 
-- `family:navigation-destinations` owns destination membership, accepted and blocked
-  results, and parity across navigation sinks.
-- `architecture:interaction-modality` owns shared modality and focus-indicator
-  visibility; ClickableCard owns the visible proxy for its hidden semantic control.
-- `architecture:component-theming-surface` owns target qualification and reflected
-  visual state on the painted root.
-- `architecture:public-component-api` owns the released subpath, BaseProps composition,
-  event cancellation, ref reachability, and compatibility boundary.
-- `architecture:component-test-sufficiency` and `spec:AST-029` own bounded audit
-  evidence and the red-before-green remediation trace.
-- `architecture:knowledge-contracts` keeps this observational draft from settling a
-  new public or design decision.
+- `family:navigation-destinations` owns destination acceptance and parity
+  across navigation sinks; FR3 applies it.
+- `architecture:interaction-modality` owns modality and focus-indicator rules;
+  FR5 and AR3 apply them and AR3 records the gap.
+- `architecture:component-theming-surface` sets the rules the `clickable-card`
+  target follows; FR4 records the disabled-state gap.
+- `architecture:public-component-api` owns ref, passthrough, cancellation, and
+  styling-input rules; FR2 and FR6 apply them.
+- `spec:AST-085` owns disabled-control behavior; FR4 and AR2 apply it.
 
 ## Verification map
 
-| Contract                   | Verification                                                                                   | Representative states                                                          | Mutation or failure expectation                                                                                            | Audit section                         |
-| -------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| FR1, AR1                   | `ClickableCard.test.tsx`, component-scoped axe, and Chromium accessibility inspection          | Action and navigation labels                                                   | Removing native semantics or the required name fails role/name evidence.                                                   | `audit:ClickableCard/accessibility`   |
-| FR2                        | `ClickableCard.test.tsx`                                                                       | Surface, hidden control, nested button/input, selected text, canceled callback | Duplicate or misowned activation changes callback counts or descendant outcomes.                                           | `audit:ClickableCard/behavior`        |
-| FR3                        | `useClickableContainer.test.tsx`, `ClickableCard.test.tsx`, and family-linked browser coverage | Plain, modified, middle, target, delegated, accepted, blocked                  | A blocked destination reaches any sink, or an accepted destination loses an activation method.                             | `audit:ClickableCard/navigation`      |
-| FR4, AR2                   | `ClickableCard.test.tsx` red/green case plus exact-head DOM inspection                         | Disabled action and disabled navigation                                        | Restoring `href`/`target`, custom-router invocation, default activation, or a live surface handler fails the focused case. | `audit:ClickableCard/accessibility`   |
-| FR5, AR3–AR4               | Storybook states, component-scoped a11y/RTL/visual checks, and receipted Chromium frames       | Enabled, disabled, keyboard focus, pointer hover/press, narrow, LTR/RTL        | Lost focus paint, hover-only operation, sticky disabled paint, or clipped/reflowed content fails browser evidence.         | `audit:ClickableCard/design-rendered` |
-| FR6                        | `ClickableCard.test.tsx`, theming target guards, typechecks, and source review                 | Ref, BaseProps, all variants, enabled/disabled                                 | Lost target reflection, ref, supported pass-through, or styling composition fails focused or repository checks.            | `audit:ClickableCard/api-theming`     |
-| Documentation and contract | `.doc.mjs`, Storybook, `scripts/check-knowledge.mjs`, changeset checks                         | Consumer docs, examples, draft contract, package subpath                       | Missing or stale docs, required structure, links, anatomy map, or release note fails repository checks.                    | `audit:ClickableCard/docs`            |
-
-Current audit scores, screenshots, eligibility, and run receipts remain in their wiki,
-pull-request, and trusted-check owners rather than this contract.
+| Contract            | Verification                                                                                                                                                                  | Representative states                                                | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                 | Audit section                       |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| FR1, AR1            | `ClickableCard.test.tsx` hidden-control, label, and target tests; `Button.a11y.test.tsx` and `Button.a11y.chromium.spec.ts` ClickableCard states                              | Action and navigation; `clickable-card` and `clickable-card-as-link` | A missing hidden button or link, a lost `aria-label` or `target`, an unexposed button role or name at the accessibility tree, or a link card losing its computed `link` role fails. Gap: the link card's name at the accessibility tree, and that the root adds no role, have no check.                                                                                                                                                         | `audit:ClickableCard/accessibility` |
+| FR2, ORD1           | `ClickableCard.test.tsx` surface, hidden-control, keyboard, nested-control, and selection tests                                                                               | Surface; hidden control; Enter; nested button and input; selection   | A missing or duplicate `onClick`, a wrong `currentTarget`, or activation from a nested control or selection fails. Gap: no test cancels navigation from `onClick`. No test covers activating the hidden link of a card given both `href` and `onClick`. No ClickableCard test covers a middle press on a card given `href`.                                                                                                                     | `audit:ClickableCard/behavior`      |
+| FR3, ORD2           | `useClickableContainer.test.tsx`; `ClickableCard.test.tsx` link tests                                                                                                         | Plain, modified, middle, target, accepted, blocked                   | A blocked destination reaching a sink, or a lost activation method, fails in the shared hook tests.                                                                                                                                                                                                                                                                                                                                             | `audit:ClickableCard/navigation`    |
+| FR4, AR2            | `ClickableCard.test.tsx` disabled and touch-press tests; `Button.a11y.chromium.spec.ts` `clickable-card-disabled` state                                                       | Disabled action and navigation                                       | A disabled control leaving the tab order, a live `href` or `target`, a callback that runs, a touch-press marker while disabled, or a disabled action card whose unavailable state or inertness (click, Enter, Space) fails at the accessibility tree fails. Gap: the disabled link card has no accessibility-tree check (`spec:AST-085` FR5), and disabled hover and mouse-press paint (`spec:AST-085` FR6) and the half opacity have no check. | `audit:ClickableCard/accessibility` |
+| FR5, AR3, AR4       | `ClickableCard.test.tsx` touch-press tests; `CardPress.a11y.chromium.spec.ts` on `core-clickablecard--with-on-click`; stable visual baseline `core-clickablecard--navigation` | Rest; desktop hover and mouse press; touch press                     | A hover that does not paint over rest, a mouse press that does not paint over hover, a touch press that does not match the desktop press or fade, or a changed rest appearance fails or comes back changed. Gap: the border hover and the focus outline have no automated check.                                                                                                                                                                | `audit:ClickableCard/design`        |
+| FR6                 | `ClickableCard.test.tsx` elevation tests; `themingTargets.test.ts`                                                                                                            | Elevations; target inventory                                         | A lost elevation class or target fails. Gap: no test covers the ref, DOM passthrough, `onMouseUp` order, or the styling-input merge.                                                                                                                                                                                                                                                                                                            | `audit:ClickableCard/api`           |
+| PR1                 | Source review                                                                                                                                                                 | Enabled and disabled                                                 | Gap: no automated check fails if ClickableCard adds its own timer, observer, or measurement.                                                                                                                                                                                                                                                                                                                                                    | `audit:ClickableCard/behavior`      |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                 | Consumer anatomy and current target                                  | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                                                   | `audit:ClickableCard/theming`       |
 
 ## Decision log
 
-None. This audit restores the already documented disabled outcome and does not settle a
-new public or design choice.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 
-- **OQ1 — Should rendering ClickableCard without `href` or `onClick` remain a supported
-  focusable no-op state, or should the public contract reject or inert that composition?**
-  (`human-api`) Current released types and rendering admit it; this observational audit
-  does not change that compatibility boundary.
+- **OQ1 — Should rendering ClickableCard without `href` or `onClick` remain a
+  supported focusable no-op, or should the public contract reject or inert
+  that composition?** (`human-api`) The released types and render admit it
+  today.
 
 ## Content boundary
 
-This file does not duplicate consumer prop tables or examples, current audit scores,
-screenshots, implementation steps, shared destination rules, or Card styling details.
-It links to their owners.
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, shared destination rules, or Card styling. It
+links to their owners.

package/src/ClickableCard/ClickableCard.test.tsx

@@ -4,7 +4,12 @@ import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {ClickableCard} from './ClickableCard';
-import {hasReleaseFade, readsPressStrength} from '../__tests__/pressState';
+import {
+  afterPaintsPress,
+  hasReleaseFade,
+  pressArmsShadowedByDefault,
+  readsPressStrength,
+} from '../__tests__/pressState';
 
 describe('ClickableCard', () => {
   it('renders children', () => {
@@ -257,11 +262,17 @@ describe('ClickableCard pressed state (touch)', () => {
       throw new Error('the card carries no pressable marker');
     }
     // The controller writes the card; the card owns the strength and its
-    // release, and `--_press-overlay` (what the `::after` paints) is the
-    // pressed token at that strength on both touch arms.
+    // release, and its `::after` paints the pressed token at that strength
+    // as its image on both arms, its hover and mouse colour yielding.
     expect(hasReleaseFade(card)).toBe(true);
     expect(readsPressStrength(card, '[data-astryx-press="on"]')).toBe(true);
     expect(readsPressStrength(card)).toBe(true);
+    expect(afterPaintsPress(card, '[data-astryx-press="on"]')).toBe(true);
+    expect(afterPaintsPress(card)).toBe(true);
+    // No press arm sits on a custom property the card also declares without
+    // it: in a layered stylesheet that declaration wins and the press never
+    // paints.
+    expect(pressArmsShadowedByDefault(card)).toEqual([]);
   });
 
   it('carries none of it when disabled', () => {

package/src/ClickableCard/ClickableCard.tsx

@@ -60,7 +60,11 @@ import {disabledInteractionProps} from '../utils/disabledInteraction';
 // element the controller writes to (`pressedAlpha`) at the press's strength,
 // 1 while on and 1 → 0 over the release, and inherited resolved by the
 // `::after` that paints it. See interactionOverlay.stylex.ts.
-const pressedOverlayColor = 'var(--_press-paint)';
+const pressedOverlayImage = 'var(--_press-paint-image)';
+/** Written by the press controller while it paints a press. */
+const PRESSED_ON = '[data-astryx-press="on"]';
+/** Written by the press controller for the press's release. */
+const PRESSED_FADING = '[data-astryx-press="fading"]';
 
 const styles = stylex.create({
   interactive: {
@@ -74,16 +78,18 @@ const styles = stylex.create({
   },
   // Hover and pressed overlay. Hover is guarded by @media (hover: hover) so
   // touch devices don't show a stuck hover state; the press has two arms,
-  // `:active` for a mouse and `data-astryx-press` for a finger.
+  // `:active` for a mouse and `data-astryx-press` for the press controller.
   overlay: {
-    // The `::after` layer paints whatever `--_press-overlay` says, and the
-    // interaction arms set that variable on the element itself. Setting the
-    // pseudo-element's colour from compound keys (`:active::after`) would
-    // leave the touch arms unable to outrank the mouse arm: a pseudo-element
-    // key carries the highest generated priority, and the `data-astryx-press`
-    // attribute the touch press model writes must win over `:active`, which
-    // still matches under a finger (see interactionOverlay.stylex.ts). Same
-    // enabled guard as the shared overlay utility.
+    // The `::after` layer paints the hover and mouse states as its colour,
+    // `--_press-overlay`, which their arms set on the element itself (same
+    // enabled guard as the shared overlay utility). The press the controller
+    // paints (a finger's, and on a touch-first device a mouse's or a key's)
+    // is the same layer's image, keyed on the `data-astryx-press` attribute
+    // the controller writes. Every arm of that press is a plain property of
+    // the `::after`, which outranks the layer's own defaults in a layered
+    // stylesheet and a flat one alike. A custom property's attribute arm
+    // does not: a layered build emits the property's default outside the
+    // priority layers its attribute arms land in, and the default wins.
     '--_press-overlay': {
       default: 'transparent',
       ':where(:not(:disabled,[aria-disabled="true"]))': {
@@ -98,32 +104,42 @@ const styles = stylex.create({
             colorVars['--color-overlay-hover'],
           ':active': colorVars['--color-overlay-pressed'],
         },
-        // The touch arms paint through the press's strength, which the
-        // card's `pressedAlpha` arms own: 1 on the first frame of a believed
-        // press, then 1 → 0 over the release. The `::after` inherits the
-        // resolved colour and repaints with it on every frame of the fade.
-        '[data-astryx-press="on"]': pressedOverlayColor,
-        '[data-astryx-press="fading"]': pressedOverlayColor,
       },
     },
-    // A believed touch press paints on the first frame, and the release is the
-    // strength's own animation, so neither may pass through the layer's colour
-    // transition (it would fade the onset in, and drag behind the release).
-    // The mouse states keep the fast fade.
-    '--_press-overlay-transition': {
-      default: durationVars['--duration-fast'],
-      '[data-astryx-press="on"]': '0s',
-      '[data-astryx-press="fading"]': '0s',
-    },
     '::after': {
       content: '""',
       position: 'absolute',
       inset: 0,
       pointerEvents: 'none',
-      transitionProperty: 'background-color',
-      transitionDuration: 'var(--_press-overlay-transition)',
+      // A press the controller paints shows on its first frame and fades on
+      // its strength's own animation, so the colour it replaces drops out at
+      // once rather than crossfading: no transition while it paints. The
+      // mouse states keep the fast fade.
+      transitionProperty: {
+        default: 'background-color',
+        [PRESSED_ON]: 'none',
+        [PRESSED_FADING]: 'none',
+      },
+      transitionDuration: durationVars['--duration-fast'],
       transitionTimingFunction: easeVars['--ease-standard'],
-      backgroundColor: 'var(--_press-overlay)',
+      // While the controller paints, the colour yields to the image: a
+      // touchscreen beside a fine pointer still matches `:active` under a
+      // finger, and the press would otherwise paint twice.
+      backgroundColor: {
+        default: 'var(--_press-overlay)',
+        [PRESSED_ON]: 'transparent',
+        [PRESSED_FADING]: 'transparent',
+      },
+      // The press at its strength, which the card's `pressedAlpha` arms own:
+      // 1 on the first frame of a believed press, then 1 → 0 over the
+      // release. The `::after` inherits the resolved paint and repaints with
+      // it on every frame of the fade. Read only inside this element's own
+      // arms, so a pressed ancestor's strength never paints here.
+      backgroundImage: {
+        default: null,
+        [PRESSED_ON]: pressedOverlayImage,
+        [PRESSED_FADING]: pressedOverlayImage,
+      },
     },
   },
   // Borderless variants (everything except `default`): drop the transparent