@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/Chat/ChatSendButton.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 6
+template_version: 7
 kind: component
 id: component:ChatSendButton
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, theming, accessibility, testing]
 verified_by:
@@ -39,18 +39,17 @@ system_specs: [spec:AST-002, spec:AST-020, spec:AST-029, spec:AST-032]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                                                    |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | The exported control selects send or stop presentation from props over ChatComposer context, accepts `sm` or `md`, supports icon overrides, and extends the rendered Button with supported Button DOM, event, styling, and ref inputs.                                                      |
-| Behavior                | Send is disabled from explicit or composer readiness, stop remains enabled, state-specific actions run before a composed generic click handler, and current send artwork resolves from an explicit override before the shared fallback.                                                     |
-| End-user impact         | People receive a translated, state-appropriate send or stop action whose availability follows composer readiness.                                                                                                                                                                           |
-| Builder impact          | Builders can use the context defaults or supply every state and action explicitly for standalone composition.                                                                                                                                                                               |
-| Compatibility/readiness | This draft records current or remediated observable behavior. It adds no public prop, default, target, or compatibility promise. Consumers that used `onClick` to replace sending migrate that logic to `onSend`; implementation of the AST-032 component-slot requirement remains pending. |
-| Review checks           | Reject lost send/stop routing, consumer events that replace the state action, a disabled stop action, unlabelled icon-only output, dropped root inputs, or send fallback drift from the observed explicit-then-shared order.                                                                |
-| Governing rules         | `spec:AST-032/FR2-FR3` (current requirement, implementation pending with its owner); `architecture:public-component-api/INV5-INV8`; `architecture:interaction-modality`; `architecture:component-test-sufficiency`; `spec:AST-020`; `spec:AST-029`.                                         |
+| Area                    | Contract                                                                                                                                                                                                                                |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | The exported control selects send or stop presentation from props over ChatComposer context, accepts `sm` or `md`, supports icon overrides, and extends the rendered Button with supported Button DOM, event, styling, and ref inputs.  |
+| Behavior                | Send is disabled from explicit or composer readiness, stop remains enabled, state-specific actions run before a composed generic click handler, and current send artwork resolves from an explicit override before the shared fallback. |
+| End-user impact         | People receive a translated, state-appropriate send or stop action whose availability follows composer readiness.                                                                                                                       |
+| Builder impact          | None.                                                                                                                                                                                                                                   |
+| Compatibility/readiness | Records shipped behavior; no public change. One implementation gap, listed under Current-state impact.                                                                                                                                  |
+| Review checks           | Reject lost send/stop routing, consumer events that replace the state action, a disabled stop action, unlabelled icon-only output, dropped root inputs, or a lost explicit-first send icon or `arrowUp` fallback.                       |
+| Governing rules         | `spec:AST-032` FR2–FR3; `architecture:public-component-api` INV5–INV8; `architecture:interaction-modality`; `architecture:component-test-sufficiency`; `spec:AST-020`; `spec:AST-029`.                                                  |
 
-This table is a review projection. The draft body below records checkable current
-or remediated behavior and does not create product policy.
+This table is a review projection; the body below is authoritative.
 
 ## Intent
 
@@ -60,13 +59,21 @@ icon, styling, and ref seams available for standalone composition.
 
 ## Compatibility and migration
 
-- Released default preserved: no public default changes are made by this audit.
-- Compatibility class: patch-compatible event-composition repair plus observational documentation and evidence coverage.
-- Controlled/uncontrolled behavior: not applicable; explicit props take precedence over context-derived values.
-- Migration decision: consumers that previously used `onClick` to replace sending should move that logic to `onSend`, because the repaired component now runs the state action and then the accepted generic click.
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable; explicit props take
+  precedence over context-derived values
+- Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **The send icon has no component-slot stage.** Send artwork resolves from
+  `sendIcon`, then the shared `arrowUp`. `spec:AST-032` FR2–FR3 put a
+  component-icon slot stage in that resolution; ChatSendButton does not offer
+  it yet (FR3).
+
 ## Ownership boundary
 
 **Owns**
@@ -90,34 +97,34 @@ Consumer migration instructions belong in consumer docs and release notes.
 Consumer syntax remains in `ChatSendButton.doc.mjs`. This inventory closes the
 observable semantic surface without duplicating the prop table.
 
-| Concept      | Closed values or states                                        | Meaning                                                                                | Availability by variant/orientation/state | Default                                                     | Owner                               | Stability                  | Invalid-value behavior                                                                      |
-| ------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- | ----------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------- |
-| Action state | send; stop                                                     | Selects the name, Button variant, icon role, disabled rule, and state action.          | Every render.                             | Composer `isStopShown`, otherwise send.                     | `component:ChatSendButton`          | Observed released surface  | Values outside the boolean prop type are unsupported.                                       |
-| Availability | enabled; disabled                                              | Prevents send activation when content is not ready. Stop intentionally ignores it.     | Disabled applies only to send.            | Explicit `isDisabled`, otherwise inverse composer canSend.  | component and ChatComposer context  | Observed released surface  | Values outside the boolean prop type are unsupported.                                       |
-| Action       | state callback; composer fallback; composed generic click      | Runs the state action and then an accepted consumer click handler.                     | Enabled send and stop activation.         | `onSend` or submit current value; `onStop` or context stop. | component, context, and caller      | Remediated observable path | With no state callback or matching context action, only a supplied generic click can run.   |
-| Send icon    | explicit content; shared fallback                              | Selects artwork for the send state.                                                    | Send state.                               | `sendIcon`, then shared `arrowUp`.                          | component and caller                | Observed released surface  | Unsupported React content follows the shared Button rendering boundary.                     |
-| Stop icon    | explicit content; shared fallback                              | Selects artwork for the stop state.                                                    | Stop state.                               | `stopIcon`, then shared `stop`.                             | component and caller                | Observed released surface  | Unsupported React content follows the shared Button rendering boundary.                     |
-| Size         | `sm`; `md`                                                     | Selects the delegated Button size while preserving circular treatment.                 | Both states.                              | `md`.                                                       | `component:ChatSendButton`          | Observed released surface  | Values outside the public union are rejected by TypeScript.                                 |
-| Root surface | ref; supported Button DOM/data/ARIA/events; style/class/xstyle | Extends and styles the rendered Button without replacing component-owned action logic. | Every render.                             | Omitted.                                                    | `architecture:public-component-api` | Remediated observable path | Unsupported BaseProps omissions remain unsupported; owned semantics win accidental clashes. |
+| Concept      | Closed values or states                                        | Meaning                                                                                | Availability by variant/orientation/state | Default                                                     | Owner                               | Stability | Invalid-value behavior                                                                      |
+| ------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------- |
+| Action state | send; stop                                                     | Selects the name, Button variant, icon role, disabled rule, and state action.          | Every render.                             | Composer `isStopShown`, otherwise send.                     | `component:ChatSendButton`          | Stable    | Values outside the boolean prop type are unsupported.                                       |
+| Availability | enabled; disabled                                              | Prevents send activation when content is not ready. Stop intentionally ignores it.     | Disabled applies only to send.            | Explicit `isDisabled`, otherwise inverse composer canSend.  | component and ChatComposer context  | Stable    | Values outside the boolean prop type are unsupported.                                       |
+| Action       | state callback; composer fallback; composed generic click      | Runs the state action and then an accepted consumer click handler.                     | Enabled send and stop activation.         | `onSend` or submit current value; `onStop` or context stop. | component, context, and caller      | Stable    | With no state callback or matching context action, only a supplied generic click can run.   |
+| Send icon    | explicit content; shared fallback                              | Selects artwork for the send state.                                                    | Send state.                               | `sendIcon`, then shared `arrowUp`.                          | component and caller                | Stable    | Unsupported React content follows the shared Button rendering boundary.                     |
+| Stop icon    | explicit content; shared fallback                              | Selects artwork for the stop state.                                                    | Stop state.                               | `stopIcon`, then shared `stop`.                             | component and caller                | Stable    | Unsupported React content follows the shared Button rendering boundary.                     |
+| Size         | `sm`; `md`                                                     | Selects the delegated Button size while preserving circular treatment.                 | Both states.                              | `md`.                                                       | `component:ChatSendButton`          | Stable    | Values outside the public union are rejected by TypeScript.                                 |
+| Root surface | ref; supported Button DOM/data/ARIA/events; style/class/xstyle | Extends and styles the rendered Button without replacing component-owned action logic. | Every render.                             | Omitted.                                                    | `architecture:public-component-api` | Stable    | Unsupported BaseProps omissions remain unsupported; owned semantics win accidental clashes. |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                       | Basis                                                                                                                  | Draft review state                                                                                      |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| FR1 | The send state MUST render a primary icon-only Button named by the send translation, and it MUST be disabled when explicit or context-derived readiness is false.                                                                         | Current implementation, docs, tests, `spec:AST-020`, and shared Button behavior                                        | Verified current behavior                                                                               |
-| FR2 | The stop state MUST render a secondary icon-only Button named by the stop translation, remain enabled regardless of send readiness, and invoke explicit or context stop behavior.                                                         | Current implementation, docs, and tests                                                                                | Verified current behavior; the missing-handler public boundary is owned by `component:ChatComposer/OQ4` |
-| FR3 | Send icon resolution currently prefers `sendIcon` and otherwise resolves shared `arrowUp`. `spec:AST-032/FR2-FR3` separately owns a current requirement to add a component-icon slot; its implementation remains pending with that owner. | Current implementation, docs, tests, and current owner requirement in `spec:AST-032`                                   | Verified shipped two-stage behavior; the required AST-032 stage is not described as shipped             |
-| FR4 | Stop icon resolution currently prefers `stopIcon` and otherwise resolves the shared `stop` icon.                                                                                                                                          | Current implementation, docs, and tests                                                                                | Verified shipped behavior; this draft does not invent a stop component slot                             |
-| FR5 | Explicit state, disabled, callback, icon, and size props MUST win over their context or component fallback. A generic accepted click handler MUST compose after the selected state action rather than replace it.                         | Current implementation after audit repair plus `architecture:public-component-api/INV5-INV7` and API contributor guide | Settled objective repair with red-before-green focused tests                                            |
-| FR6 | Supported Button DOM, data, ARIA, className, style, xstyle, and ref inputs MUST reach or compose on the rendered Button while component-owned label, state, and activation behavior remain intact.                                        | Current implementation plus `architecture:public-component-api/INV5-INV8`                                              | Verify through source, type checks, and focused tests                                                   |
-| FR7 | The component MUST paint through the shared Button on the co-located `chat-send-button` target and preserve its circular component treatment.                                                                                             | Current implementation, Chat consumer docs, and `architecture:component-theming-surface`                               | Verified current target and composition                                                                 |
+| ID  | Invariant                                                                                                                                                                                                         | Basis                                                                                    |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| FR1 | The send state MUST render a primary icon-only Button named by the send translation, and it MUST be disabled when explicit or context-derived readiness is false.                                                 | Current implementation, docs, tests, `spec:AST-020`, and shared Button behavior          |
+| FR2 | The stop state MUST render a secondary icon-only Button named by the stop translation, remain enabled regardless of send readiness, and invoke explicit or context stop behavior.                                 | Current implementation, docs, and tests                                                  |
+| FR3 | Send icon resolution prefers `sendIcon` and otherwise resolves the shared `arrowUp`. Implementation gap: the component-icon slot stage `spec:AST-032` FR2–FR3 require is not offered (Current-state impact).      | Current implementation, docs, tests, and current owner requirement in `spec:AST-032`     |
+| FR4 | Stop icon resolution prefers `stopIcon` and otherwise resolves the shared `stop` icon.                                                                                                                            | Current implementation, docs, and tests                                                  |
+| FR5 | Explicit state, disabled, callback, icon, and size props MUST win over their context or component fallback. A generic accepted click handler MUST compose after the selected state action rather than replace it. | Current source and tests; `architecture:public-component-api` INV5–INV7                  |
+| FR6 | Supported Button DOM, data, ARIA, className, style, xstyle, and ref inputs MUST reach or compose on the rendered Button while component-owned label, state, and activation behavior remain intact.                | Current implementation plus `architecture:public-component-api/INV5-INV8`                |
+| FR7 | The component MUST paint through the shared Button on the co-located `chat-send-button` target and preserve its circular component treatment.                                                                     | Current implementation, Chat consumer docs, and `architecture:component-theming-surface` |
 
 ### Allowed variation
 
 - **AV1 — Context or standalone composition.** A builder may rely on ChatComposer
   context or provide all state, action, and disabled values explicitly.
 - **AV2 — Artwork.** Explicit send and stop content and shared fallback artwork may
-  vary within the observed icon-resolution behavior.
+  vary within the icon resolution FR3 and FR4 state.
 - **AV3 — Consumer styling.** Supported styling inputs may extend the Button while
   component-owned state and activation behavior remain.
 
@@ -141,7 +148,9 @@ observable semantic surface without duplicating the prop table.
 - **ORD3 — Resolve availability.** Stop remains enabled. Send uses explicit
   `isDisabled`, then inverse composer readiness, then disabled outside context.
 - **ORD4 — Resolve artwork.** In send, explicit `sendIcon` wins, then shared
-  `arrowUp`; in stop, explicit `stopIcon` wins, then shared `stop`.
+  `arrowUp`; in stop, explicit `stopIcon` wins, then shared `stop`. The
+  component-icon slot stage `spec:AST-032` FR2 requires is not offered yet
+  (FR3).
 - **ORD5 — Compose root.** Apply component-owned Button semantics and the
   `chat-send-button` target while preserving supported consumer root inputs.
 
@@ -163,14 +172,15 @@ observable semantic surface without duplicating the prop table.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                                                                           | Representation authority                                               | Hierarchy role           | Component contract |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------ | ------------------ |
-| Action button    | Circular compact Button carrying the current send or stop action.                                                            | Current source and consumer docs; exact tuning stays in code           | Primary/secondary action | FR1, FR2, FR7      |
-| Send artwork     | Upward send glyph unless explicit content wins; AST-032 currently requires a component slot whose implementation is pending. | Current source and docs; current requirement in `spec:AST-032/FR2-FR3` | Action cue               | FR3                |
-| Stop artwork     | Shared stop glyph unless explicit content wins.                                                                              | Current source and consumer docs                                       | Action cue               | FR4                |
+| Anatomy or state | Design requirement                                                | Representation authority                                     | Hierarchy role           | Component contract |
+| ---------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------ | ------------------ |
+| Action button    | Circular compact Button carrying the current send or stop action. | Current source and consumer docs; exact tuning stays in code | Primary/secondary action | FR1, FR2, FR7      |
+| Send artwork     | Upward send glyph unless explicit content wins (FR3's gap).       | Current source and docs; `spec:AST-032` FR2–FR3              | Action cue               | FR3                |
+| Stop artwork     | Shared stop glyph unless explicit content wins.                   | Current source and consumer docs                             | Action cue               | FR4                |
 
-This observational draft does not select new dimensions, variants, icon artwork,
-color roles, or visual prominence.
+This record selects no new dimensions, variants, icon artwork, color roles, or
+visual prominence. No anatomy-theming map is recorded yet; the block is
+optional during migration, so the map is deferred.
 
 The Chat family consumer doc catalogs `chat-send-button`. Button owns the
 underlying painting and interaction-state styling; the component target is
@@ -183,43 +193,44 @@ co-located on that painting element.
 - `architecture:public-component-api` owns BaseProps reachability, style/ref
   composition, and deliberate event composition.
 - `architecture:icon-resolution-and-component-slots` owns the shared slot model;
-  `spec:AST-032/FR2-FR3` currently requires that stage in send resolution, and
-  its implementation remains pending with the owner. This draft does not describe
-  the unshipped stage as current behavior.
+  `spec:AST-032` FR2–FR3 put a component-slot stage in send resolution, which is
+  not shipped (Current-state impact).
 - `architecture:component-theming-surface` owns the qualification and placement
   of the co-located `chat-send-button` target.
 - `architecture:interaction-modality` and `spec:AST-020` own pointer, keyboard,
   focus, and accessibility parity inherited through Button.
 - `architecture:component-test-sufficiency` owns public-seam regression coverage.
-- `spec:AST-029` owns this Night Watch observational backfill and prevents it from
-  settling new product meaning.
+- `spec:AST-029` owns the audit evidence inventory this record's verification
+  map follows.
 
 ## Verification map
 
-| Contract                  | Verification                                                                                                                | Representative states                                                                                                    | Mutation or failure expectation                                                                                                                  | Audit section                        |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
-| FR1, FR2, AR1-AR4         | `ChatSendButton.test.tsx`, `ChatSendButton.a11y.chromium.spec.ts`, and `ChatComposer.test.tsx`                              | Enabled/disabled send, stop with and without handler, context stop, keyboard/pointer, light/dark interaction states      | Label, disabled, native activation, state routing, or interaction paint drift fails focused or exact-head browser evidence.                      | `audit:ChatSendButton/accessibility` |
-| FR3                       | `ChatSendButton.test.tsx`; current AST-032 owner requirement and its pending implementation                                 | Explicit and shared-fallback send icon                                                                                   | Losing the observed two-stage precedence fails focused tests; the AST-032 owner verifies the required component-slot stage.                      | `audit:ChatSendButton/theming`       |
-| FR4                       | `ChatSendButton.test.tsx`                                                                                                   | Explicit and fallback stop icon                                                                                          | Losing explicit precedence or registry resolution fails focused assertions.                                                                      | `audit:ChatSendButton/behavior`      |
-| FR5, FR6                  | Red-before-green callback composition, ordering, size, root passthrough, disabled-click, and keyboard tests; types and lint | Send, stop, `sm`/`md`, ref/class/data/ARIA, Enter/Space                                                                  | Consumer events replacing state actions, cancellation reordering, lost root inputs, or modality drift fails focused tests.                       | `audit:ChatSendButton/api`           |
-| FR7                       | `themingTargets.test.ts`, exact-head browser receipts, and source inspection                                                | Send and stop themes                                                                                                     | Target removal, movement off paint, or undocumented target drift fails tests or browser evidence.                                                | `audit:ChatSendButton/theming`       |
-| RTL relation              | RTL shared-fixture route plus refreshed verified-N/A source receipts for ChatSendButton and ChatComposer                    | Send and stop                                                                                                            | Directional artwork, physical positioning, or transform invalidates the checked-in receipts.                                                     | `audit:ChatSendButton/i18n-rtl`      |
-| Browser matrix            | `ChatSendButton.a11y.chromium.spec.ts` exact-head 10-sensor receipts                                                        | Light/dark send and stop rest/hover/focus/press, disabled rest/hover, `sm`/`md`, 320px coarse pointer, D7 contrast pairs | A stale build, decoy selector, missing state, changed disabled paint, absent interaction pixels, failed contrast, or geometry miss fails closed. | `audit:ChatSendButton/visual`        |
-| Documentation and surface | Consumer docs, export checks, Storybook, and `check:knowledge`                                                              | Props, public subpath, states, draft contract                                                                            | Missing or stale docs, exports, relationships, or required draft structure fails validation.                                                     | `audit:ChatSendButton/docs`          |
+| Contract                  | Verification                                                                                                         | Representative states                                                                                                    | Mutation or failure expectation                                                                                                                  | Audit section                        |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
+| FR1, FR2, AR1-AR4         | `ChatSendButton.test.tsx`, `ChatSendButton.a11y.chromium.spec.ts`, and `ChatComposer.test.tsx`                       | Enabled/disabled send, stop with and without handler, context stop, keyboard/pointer, light/dark interaction states      | Label, disabled, native activation, state routing, or interaction paint drift fails focused or exact-head browser evidence.                      | `audit:ChatSendButton/accessibility` |
+| FR3                       | `ChatSendButton.test.tsx`                                                                                            | Explicit and shared-fallback send icon                                                                                   | Losing explicit-first precedence or the `arrowUp` fallback fails focused tests; the `spec:AST-032` slot stage is not tested here.                | `audit:ChatSendButton/theming`       |
+| FR4                       | `ChatSendButton.test.tsx`                                                                                            | Explicit and fallback stop icon                                                                                          | Losing explicit precedence or registry resolution fails focused assertions.                                                                      | `audit:ChatSendButton/behavior`      |
+| FR5, FR6                  | `ChatSendButton.test.tsx` callback composition, ordering, size, root passthrough, disabled-click, and keyboard tests | Send, stop, `sm`/`md`, ref/class/data/ARIA, Enter/Space                                                                  | Consumer events replacing state actions, cancellation reordering, lost root inputs, or modality drift fails focused tests.                       | `audit:ChatSendButton/api`           |
+| FR7                       | `themingTargets.test.ts` and `ChatSendButton.a11y.chromium.spec.ts`                                                  | Send and stop themes                                                                                                     | Target removal, movement off paint, or undocumented target drift fails tests or browser evidence.                                                | `audit:ChatSendButton/theming`       |
+| RTL relation              | RTL shared-fixture route plus refreshed verified-N/A source receipts for ChatSendButton and ChatComposer             | Send and stop                                                                                                            | Directional artwork, physical positioning, or transform invalidates the checked-in receipts.                                                     | `audit:ChatSendButton/i18n-rtl`      |
+| Browser matrix            | `ChatSendButton.a11y.chromium.spec.ts` browser states                                                                | Light/dark send and stop rest/hover/focus/press, disabled rest/hover, `sm`/`md`, 320px coarse pointer, D7 contrast pairs | A stale build, decoy selector, missing state, changed disabled paint, absent interaction pixels, failed contrast, or geometry miss fails closed. | `audit:ChatSendButton/visual`        |
+| Documentation and surface | Consumer docs, export checks, Storybook, and `check:knowledge`                                                       | Props, public subpath, states, contract                                                                                  | Missing or stale docs, exports, relationships, or required structure fails validation.                                                           | `audit:ChatSendButton/docs`          |
+
+Read from source, with no focused test yet:
+
+- FR5: explicit props winning over ChatComposer context.
+- FR6: `style` and `xstyle` reaching the root.
 
 ## Decision log
 
-None. This draft records current facts, one objective event-composition repair,
-and one current AST-032 requirement whose implementation remains pending with its
-owner. It introduces no component-local public API, default, compatibility,
-ownership, or subjective visual decision.
+No component-local decision is recorded.
 
 ## Open questions
 
 - **Cross-reference: stop without handler.** `component:ChatComposer/OQ4` owns
   the unresolved policy for a visible stop action without an explicit or context
-  `onStop`. This component draft records and tests the current enabled no-op
-  branch without duplicating that question.
+  `onStop`. This record covers today's enabled no-op branch without
+  duplicating that question.
 
 ## Content boundary
 

package/src/CheckboxInput/CheckboxInput.tsx

@@ -41,17 +41,18 @@ import {FieldLabel} from '../Field/FieldLabel';
 import {FieldStatus} from '../FieldStatus/FieldStatus';
 import type {IconType} from '../Icon';
 import type {InputStatus} from '../Field/types';
-import {Spinner} from '../Spinner';
-import {useTooltip} from '../Tooltip';
-import {mergeProps, rtlStyles} from '../utils';
+import {Spinner} from '../Spinner/Spinner';
+import {useTooltip} from '../Tooltip/useTooltip';
+import {mergeProps} from '../utils/mergeProps';
+import {rtlStyles} from '../utils/rtlStyles';
 import {indicatorScope} from '../Indicator/indicator.markers.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
-import {useTranslator} from '../i18n';
+import {useTranslator} from '../i18n/useTranslator';
 import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
-import {useIndicator} from '../Indicator';
+import {useIndicator} from '../Indicator/useIndicator';
 import {themeProps} from '../utils/themeProps';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';

package/src/Citation/Citation.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 6
+template_version: 7
 kind: component
 id: component:Citation
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, theming, accessibility, visual]
 verified_by:
@@ -16,6 +16,9 @@ verified_by:
     packages/core/src/utils/safeUrl.test.ts,
     apps/storybook/stories/Citation.stories.tsx,
     apps/storybook/rtl-audit/verified-not-applicable.json,
+    packages/core/src/theme/themingTargets.test.ts,
+    .github/visual-baseline/manifest.json,
+    scripts/check-knowledge.mjs,
   ]
 modules: []
 families: [family:navigation-destinations]
@@ -35,17 +38,17 @@ system_specs: [spec:AST-005]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                 |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | `Citation` is exported from `@astryxdesign/core/Citation`; `source` and `number` are required, and `variant` defaults to `label`.                                                                                                                                                                                        |
-| Behavior                | An accepted source URL renders a native anchor in a new tab. A missing or rejected URL renders the same citation content in an inert span. Label and number variants preserve that navigation decision.                                                                                                                  |
-| End-user impact         | Readers receive a consistent citation label or numbered reference without a blocked destination becoming navigation or a decorative source icon being announced twice.                                                                                                                                                   |
-| Builder impact          | Builders may supply source text, a destination, an image or node icon, neutral DOM props, a root ref, and composed styling without replacing Citation’s navigation or accessibility ownership.                                                                                                                           |
-| Compatibility/readiness | The released defaults, export, theme target, URL behavior, and visual presentation remain unchanged. The inert span now uses a noninteractive naming role so its existing translated label reaches assistive technology.                                                                                                 |
-| Review checks           | Reject a blocked URL that becomes navigation, an accepted URL that loses native anchor affordances, an interactive or reference role on an inert citation, a missing inert accessible name, an announced decorative icon, dropped supported passthrough or ref behavior, or a new public theme target without authority. |
-| Governing rules         | `family:navigation-destinations/FR1,FR3–FR5,FR7–FR8`; `architecture:public-component-api/INV1,INV5,INV6,INV8,INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`.                                                                                 |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `Citation` is exported from `@astryxdesign/core/Citation`; `source` and `number` are required, and `variant` defaults to `label`.                                                                                                                                                                                                                               |
+| Behavior                | An accepted source URL renders a native anchor in a new tab. A missing or rejected URL renders the same citation content in an inert span. Label and number variants preserve that navigation decision.                                                                                                                                                         |
+| End-user impact         | Readers receive a consistent citation label or numbered reference without a blocked destination becoming navigation or a decorative source icon being announced twice.                                                                                                                                                                                          |
+| Builder impact          | A builder's explicit `role` or `aria-label` is meant to reach the root; today the component's role and translated name replace them (FR5 gap).                                                                                                                                                                                                                  |
+| 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 blocked URL that becomes navigation, an accepted URL that loses native anchor affordances, an interactive or reference role that Citation adds to an inert citation, a missing inert accessible name when the caller supplies none, an announced decorative icon, dropped passthrough or ref behavior, or a new public theme target without authority. |
+| Governing rules         | `family:navigation-destinations/FR1,FR3–FR5,FR7–FR8`; `architecture:public-component-api/INV1,INV5,INV6,INV8,INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`.                                                                                                                        |
 
-This table is a review projection; the body below is authoritative only after owner approval.
+This table is a review projection; the body below is authoritative.
 
 ## Intent
 
@@ -53,13 +56,22 @@ Present an inline reference to a source as a readable label or compact number wh
 
 ## Compatibility and migration
 
-- Released default preserved: yes
-- Compatibility class: restorative accessibility semantics plus observational documentation; no public-type, visual, layout, styling, or theme-target change
-- Controlled/uncontrolled behavior: not applicable; Citation owns no state
-- Migration decision: none; the existing package export and source shape remain unchanged
+- Released default preserved: `yes` — `variant="label"`.
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  target, or styling output changes.
+- Controlled/uncontrolled behavior: not applicable; Citation owns no state.
+- Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **Caller `role` and `aria-label` replaced (FR5).** Caller props spread
+  before the component's `role` and `aria-label`, so a caller's explicit
+  values never reach the root, where `architecture:public-component-api` INV5
+  lets a caller's explicit input reach the element. The root-contract test
+  pins the replacement today.
+
 ## Ownership boundary
 
 **Owns**
@@ -85,15 +97,15 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                 | Basis                                                                                     | Draft review state |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------ |
-| FR1 | An accepted `source.url` MUST render a native anchor with the unchanged destination, `target="_blank"`, `rel="noopener noreferrer"`, `role="doc-noteref"`, and the current title and translated accessible name.                                                                                                                                                    | shipped source and tests; `family:navigation-destinations/FR1,FR3–FR5`                    | verify             |
-| FR2 | A missing or rejected destination MUST render the selected citation presentation in a noninteractive span with no navigation or reference role. The span MUST use a supported naming role so its translated label reaches assistive technology. Rejection MUST NOT derive navigation attributes from `source.url`, invent disabled semantics, or hide the citation. | shipped source and tests; `family:navigation-destinations/FR4,FR7`; WAI-ARIA naming rules | verify             |
-| FR3 | The label variant MUST present the source title, optional decorative source icon, and truncation behavior; the number variant MUST present the supplied number as the compact visible reference.                                                                                                                                                                    | shipped source, docs, tests, and stories                                                  | verify             |
-| FR4 | Node icons MUST take precedence over `src`; otherwise `src` MUST take precedence over a legacy string `icon`. Every icon path remains decorative inside an `aria-hidden` wrapper.                                                                                                                                                                                   | shipped compatibility behavior and tests                                                  | verify             |
-| FR5 | Both root branches MUST preserve supported DOM props, `className`, `style`, `xstyle`, `data-*` attributes, and the declared `HTMLElement` ref while keeping the component-owned role and accessible name authoritative.                                                                                                                                             | `architecture:public-component-api/INV5,INV6,INV8`; regression tests                      | verify             |
-| FR6 | Citation MUST keep one public `citation` target on the painted root and MUST NOT expose an internal icon or text target without an approved theming-contract change.                                                                                                                                                                                                | shipped docs/source; `architecture:component-theming-surface/INV3–INV6`                   | verify             |
-| FR7 | Component-owned accessible text MUST remain routed through `useTranslator`; visible source text and numeric content remain caller-supplied data.                                                                                                                                                                                                                    | shipped source and i18n infrastructure                                                    | verify             |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Basis                                                                                     |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| FR1 | An accepted `source.url` renders a native anchor with the unchanged destination, `target="_blank"`, `rel="noopener noreferrer"`, `role="doc-noteref"` unless a caller supplies an explicit `role`, and the translated accessible name unless a caller supplies an explicit `aria-label` (FR5); its `title` is the source title, or the number when there is none.                                                                                                     | shipped source and tests; `family:navigation-destinations/FR1,FR3–FR5`                    |
+| FR2 | A missing or rejected destination renders the selected citation presentation in a noninteractive span; Citation adds no navigation or reference role to it. Unless a caller supplies an explicit `role`, the span uses a supported naming role, so its translated label, or a caller's `aria-label`, reaches assistive technology (FR5). Rejection derives no navigation attributes from `source.url`, invents no disabled semantics, and does not hide the citation. | shipped source and tests; `family:navigation-destinations/FR4,FR7`; WAI-ARIA naming rules |
+| FR3 | The label variant presents the source title, an optional decorative source icon, and truncation; the number variant presents the supplied number as the compact visible reference.                                                                                                                                                                                                                                                                                    | shipped source, docs, tests, and stories                                                  |
+| FR4 | A node icon takes precedence over `src`, and `src` over a legacy string `icon`. Every icon path remains decorative inside an `aria-hidden` wrapper.                                                                                                                                                                                                                                                                                                                   | shipped compatibility behavior and tests                                                  |
+| FR5 | Both root branches preserve supported DOM props, `className`, `style`, `xstyle`, `data-*` attributes, and the declared `HTMLElement` ref, and a caller's explicit `role` or `aria-label` reaches the root (`architecture:public-component-api` INV5). Implementation gap: the component's role and translated name replace a caller's values (Current-state impact).                                                                                                  | `architecture:public-component-api/INV5,INV6,INV8`; regression tests                      |
+| FR6 | Citation keeps one public `citation` target on the painted root, reflecting `variant`, and exposes no internal icon or text target without an approved theming-contract change.                                                                                                                                                                                                                                                                                       | shipped docs/source; `architecture:component-theming-surface/INV3–INV6`                   |
+| FR7 | Component-owned accessible text comes from the translation catalog; visible source text and numeric content remain caller-supplied data.                                                                                                                                                                                                                                                                                                                              | shipped source and i18n infrastructure                                                    |
 
 ### Allowed variation
 
@@ -103,18 +115,18 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Representative states
 
-| State                   | Required invariant                                                                                                       | Allowed variation                     |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
-| linked label            | Native anchor, source title, optional decorative icon, translated accessible name.                                       | Source content and root theme paint.  |
-| linked number           | Native anchor, numeric visible reference, translated accessible name.                                                    | Number and root theme paint.          |
-| missing or rejected URL | Inert span with the same selected presentation, a supported naming role, and no navigation/reference role or attributes. | Source content and root theme paint.  |
-| node or image icon      | Icon remains decorative and appears only in the label variant.                                                           | Caller-owned artwork or source image. |
+| State                   | Required invariant                                                                                                                                            | Allowed variation                     |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| linked label            | Native anchor, source title, optional decorative icon, translated accessible name absent a caller `aria-label`.                                               | Source content and root theme paint.  |
+| linked number           | Native anchor, numeric visible reference, translated accessible name absent a caller `aria-label`.                                                            | Number and root theme paint.          |
+| missing or rejected URL | Inert span with the same selected presentation; absent a caller `role`, a supported naming role; Citation adds no navigation or reference role or attributes. | Source content and root theme paint.  |
+| node or image icon      | Icon remains decorative and appears only in the label variant.                                                                                                | Caller-owned artwork or source image. |
 
 ### Transformation and precedence order
 
 - **ORD1 — Destination.** `source.url` → shared safe-URL decision → native anchor or inert span.
 - **ORD2 — Icon.** Non-string `source.icon` → `source.src` → legacy string `source.icon` → no icon.
-- **ORD3 — Root props.** Caller passthrough → component-owned role, name, test id, and navigation attributes → theme and style composition.
+- **ORD3 — Root props.** Caller passthrough → component-owned test id and navigation attributes, and the component's role and name unless the caller supplies its own (FR5; today the component's replace the caller's, the FR5 gap) → theme and style composition.
 
 ### Performance and resources
 
@@ -123,8 +135,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Accessibility contract
 
-- **AR1 — Linked reference.** An accepted destination exposes one native link with `doc-noteref` and the translated `Citation {number}: {title}` accessible name.
-- **AR2 — Inert reference.** Missing or rejected destinations expose no interactive or navigation role or attributes. The inert span uses `role="group"` so its translated citation label remains an accessible name, including when the visible number has no source text.
+- **AR1 — Linked reference.** An accepted destination exposes one native link with `doc-noteref` absent a caller `role`, and the translated `Citation {number}: {title}` accessible name absent a caller `aria-label` (FR5).
+- **AR2 — Inert reference.** For a missing or rejected destination, Citation adds no interactive or navigation role or attributes; a caller's explicit `role` reaches the span (FR5). Absent a caller `role` (FR5), the inert span uses `role="group"` so its translated citation label remains an accessible name, including when the visible number has no source text.
 - **AR3 — Decorative source mark.** Source image and node icon paint remains hidden from the accessibility tree so it does not duplicate the citation name.
 - **AR4 — Focus ownership.** The native anchor remains the semantic focus owner. Citation adds no focus owner to the inert span.
 
@@ -136,7 +148,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | Source icon      | Presents optional caller-supplied source identity without accessibility semantics. | observed shipped representation                 | decorative               | FR3–FR4, AR3       |
 | Label or number  | Presents the source title or compact index.                                        | observed shipped representation                 | primary citation content | FR3, FR7           |
 
-Citation exposes only the documented `citation` root target. Internal icon and text parts currently have no public target; this observational draft neither adds nor promises one.
+Citation exposes only the documented `citation` root target. Internal icon and text parts have no public target.
 
 ## Family and system relationships
 
@@ -149,15 +161,16 @@ Citation exposes only the documented `citation` root target. Internal icon and t
 
 ## Verification map
 
-| Contract         | Verification                                                                | Representative states                                                        | Mutation or failure expectation                                                                                                                       | Audit section               |
-| ---------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
-| FR1–FR2, AR1–AR2 | `Citation.test.tsx` destination suites and `safeUrl.test.ts` matrix         | accepted, missing, blocked schemes, normalized blocked text                  | A blocked URL creates navigation, an accepted URL loses its destination or native affordances, or an inert reference loses its supported naming role. | `audit:Citation/navigation` |
-| FR3–FR4, AR3     | `Citation.test.tsx` variant and icon suites                                 | label, number, no icon, node icon, `src`, legacy string icon                 | The wrong visible variant renders, icon precedence changes, or decorative source paint reaches the accessibility tree.                                | `audit:Citation/behavior`   |
-| FR5              | `Citation.test.tsx` root-contract suite and strict type/lint validation     | anchor and span roots with ref, DOM props, class, inline style, and `xstyle` | Either root drops supported passthrough or ref behavior, or caller-supplied role/name overrides component ownership.                                  | `audit:Citation/api`        |
-| FR6              | Public docs, source review, and theming-target inventories                  | linked and inert roots; both variants                                        | The root target disappears, moves off the painter, or an undocumented internal target becomes public.                                                 | `audit:Citation/theming`    |
-| FR7              | Existing i18n build and Citation accessible-name assertions                 | linked label and number                                                      | Component-authored accessible text bypasses translation or loses source/number context.                                                               | `audit:Citation/i18n`       |
-| RTL N/A          | `verified-not-applicable.json` source-hashed record                         | label and number stories; linked/inert source paths; icon/no-icon            | A direction-sensitive glyph, physical inline placement, ordering, scrolling, overlay, or horizontal keyboard behavior appears without RTL evidence.   | `audit:Citation/rtl`        |
-| All              | `Citation.stories.tsx`, component tests, typecheck, lint, and exact-head CI | all documented variants and representative source states                     | A required state becomes unreachable or gains a build, accessibility, visual, or test regression.                                                     | `audit:Citation/testing`    |
+| Contract         | Verification                                                            | Representative states                                                        | Mutation or failure expectation                                                                                                                                                                                                   | Audit section               |
+| ---------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| FR1–FR2, AR1–AR2 | `Citation.test.tsx` destination suites and `safeUrl.test.ts` matrix     | accepted, missing, blocked schemes, normalized blocked text                  | A blocked URL creates navigation, an accepted URL loses its destination or native affordances, or an inert reference loses its supported naming role when the caller supplies no `role`.                                          | `audit:Citation/navigation` |
+| FR3–FR4, AR3     | `Citation.test.tsx` variant and icon suites                             | label, number, no icon, node icon, `src`, legacy string icon                 | The wrong visible variant renders, icon precedence changes, or decorative source paint reaches the accessibility tree. Gap: no test covers the label's truncation. Gap: no test covers `src` winning over a legacy string `icon`. | `audit:Citation/behavior`   |
+| FR5              | `Citation.test.tsx` root-contract suite and strict type/lint validation | anchor and span roots with ref, DOM props, class, inline style, and `xstyle` | Either root drops supported passthrough or ref behavior. Gap: the root-contract test asserts that the component's role and name replace a caller's `role` and `aria-label`, which pins the FR5 gap.                               | `audit:Citation/api`        |
+| FR6              | `Citation.test.tsx` class-name tests; `themingTargets.test.ts`          | linked and inert roots; both variants                                        | The root target disappearing from the class-name tests fails. `themingTargets.test.ts` catches only a renamed or undocumented target. Gap: no test asserts the `variant` reflection on the target.                                | `audit:Citation/theming`    |
+| FR7              | `Citation.test.tsx` accessible-name assertions                          | linked label and number                                                      | A name that loses the source or number context fails. Gap: no test runs a non-English catalog, so text that bypasses translation passes.                                                                                          | `audit:Citation/i18n`       |
+| RTL N/A          | `verified-not-applicable.json` source-hashed record                     | label and number stories; linked/inert source paths; icon/no-icon            | A direction-sensitive glyph, physical inline placement, ordering, scrolling, overlay, or horizontal keyboard behavior appears without RTL evidence.                                                                               | `audit:Citation/rtl`        |
+| All              | `Citation.stories.tsx`; stable visual baseline `core-citation--label`   | Documented variants and source states                                        | A changed label citation comes back changed for review.                                                                                                                                                                           | `audit:Citation/testing`    |
+| AR4, PR1, PR2    | Source review                                                           | Linked and inert roots; image icon                                           | Gap: no automated check fails if Citation adds a focus owner to the inert span, state, an effect, or a listener, or emits more than one source image.                                                                             | `audit:Citation/behavior`   |
 
 ## Decision log
 
@@ -172,7 +185,7 @@ Reconsider this mechanism if a supported platform primitive can name inert inlin
 
 ## Open questions
 
-None. This observational draft does not decide a general resource URL policy or add a component-local theming surface.
+None.
 
 ## Content boundary