@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/src/EmptyState/EmptyState.spec.md

@@ -3,16 +3,19 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:EmptyState
-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, layout, theming, accessibility, testing]
 verified_by:
   [
     packages/core/src/EmptyState/EmptyState.test.tsx,
+    packages/core/src/EmptyState/EmptyState.announce.test.tsx,
+    .github/visual-baseline/manifest.json,
+    scripts/check-knowledge.mjs,
     packages/core/src/theme/themingTargets.test.ts,
     packages/core/src/docPropReferences.test.ts,
   ]
@@ -27,7 +30,7 @@ architecture:
   ]
 contributing: []
 system_specs:
-  [spec:AST-020/FR1, spec:AST-029/FR3, spec:AST-086/FR2, spec:AST-086/FR11]
+  [spec:AST-009, spec:AST-020/FR1, spec:AST-086/FR2, spec:AST-086/FR11]
 ---
 
 # EmptyState component contract
@@ -39,8 +42,8 @@ system_specs:
 | Public contract         | `EmptyState` renders a required title plus optional description, decorative icon, and caller-owned actions in one root without a live role; callers choose heading level and compact layout.     |
 | Behavior                | Null, undefined, boolean, and empty-string optional values create no slot wrapper. Rendered content follows icon, text, then actions order; compact layout reduces spacing and stacks actions.   |
 | End-user impact         | A person reaches a named empty-content message and any next action without blank gaps from shallow-empty optional values; the title fits the surrounding document outline.                       |
-| Builder impact          | Callers supply content and actions, select heading semantics, and may compose supported root props and styling. No additional setup is required.                                                 |
-| Compatibility/readiness | No live role on the root; an EmptyState that appears after load announces once (`spec:AST-086` FR2). Otherwise this draft observes shipped behavior and the scalar-slot remediation.             |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                     |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                                                                       |
 | Review checks           | Reject a missing heading, an informative icon hidden as decorative, a shallow-empty optional scalar that still changes layout, a dropped root prop/ref/style, or a theme target without anatomy. |
 | Governing rules         | `architecture:public-component-api` INV1 and INV5–INV9; `architecture:component-theming-surface` INV2–INV6; `architecture:component-test-sufficiency` INV1–INV7, INV10–INV11; WCAG 2.2.          |
 
@@ -53,10 +56,12 @@ context, optional decorative visual, and optional caller-owned next actions.
 
 ## Compatibility and migration
 
-- Released default preserved: no; EmptyState adds no live role to the root
-- Compatibility class: observational and additive documentation; runtime remediation removes wrappers for nullish, boolean, and empty-string optional values and removes the root's live role
+- Released default preserved: `yes` — heading level 3, default layout, no
+  live role on the root.
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  target, or styling output changes.
 - Controlled/uncontrolled behavior: not applicable
-- Migration decision: none; an EmptyState rendered with the page announces nothing, and one that appears later announces its message once through the shared polite channel, so apps need no change (`spec:AST-086` FR2)
+- Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -87,17 +92,14 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision. A `current` contract contains no unresolved rows.
-
-| ID  | Candidate invariant                                                                                                                                                                     | Basis                                                                                | Draft review state |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
-| FR1 | The component MUST render one root containing the icon, text group, and actions in that reading order when present. The component MUST NOT add a live role or `aria-live` to the root.  | Current implementation and consumer docs; `spec:AST-086` FR2; WCAG 2.2 SC 1.3.2      | verify             |
-| FR2 | The required title MUST render at the caller-selected heading level without changing the component's visual type role.                                                                  | Current implementation, tests, and consumer docs; WCAG 2.2 SC 1.3.1 and SC 2.4.6     | verify             |
-| FR3 | Null, undefined, boolean, and empty-string optional values MUST NOT create a wrapper, layout gap, or assistive-technology node; containers that are shallowly non-empty remain wrapped. | React's direct-child rendering semantics; established public optional-slot interface | verify             |
-| FR4 | The decorative icon wrapper MUST be absent when the slot is absent and hidden from assistive technology when rendered.                                                                  | Current implementation and tests; WCAG 2.2 SC 1.1.1                                  | verify             |
-| FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the root.                                                                             | `architecture:public-component-api` INV5–INV8                                        | verify             |
-| FR6 | Compact layout MUST reduce component spacing and stack the actions slot while preserving content order and root semantics.                                                              | Current implementation, tests, and consumer docs                                     | verify             |
+| ID  | Invariant                                                                                                                                                                               | Basis                                                                                |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| FR1 | The component MUST render one root containing the icon, text group, and actions in that reading order when present. The component MUST NOT add a live role or `aria-live` to the root.  | Current implementation and consumer docs; `spec:AST-086` FR2; WCAG 2.2 SC 1.3.2      |
+| FR2 | The required title MUST render at the caller-selected heading level without changing the component's visual type role.                                                                  | Current implementation, tests, and consumer docs; WCAG 2.2 SC 1.3.1 and SC 2.4.6     |
+| FR3 | Null, undefined, boolean, and empty-string optional values MUST NOT create a wrapper, layout gap, or assistive-technology node; containers that are shallowly non-empty remain wrapped. | React's direct-child rendering semantics; established public optional-slot interface |
+| FR4 | The decorative icon wrapper MUST be absent when the slot is absent and hidden from assistive technology when rendered.                                                                  | Current implementation and tests; WCAG 2.2 SC 1.1.1                                  |
+| FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the root.                                                                             | `architecture:public-component-api` INV5–INV8                                        |
+| FR6 | Compact layout MUST reduce component spacing and stack the actions slot while preserving content order and root semantics.                                                              | Current implementation, tests, and consumer docs                                     |
 
 ### Allowed variation
 
@@ -126,8 +128,9 @@ intentional decision. A `current` contract contains no unresolved rows.
 
 ### Performance and resources
 
-- **PR1 — Render-only surface.** EmptyState owns no retained state, listener,
-  observer, timer, or external resource.
+- **PR1 — No resources of its own.** EmptyState holds no state, listener,
+  observer, or timer of its own; the shared announcement wrapper around its
+  text owns the observation that announces it (`spec:AST-086`).
 
 ## Accessibility contract
 
@@ -176,16 +179,19 @@ No current family record owns EmptyState-specific behavior.
 
 ## Verification map
 
-| Contract       | Verification                                                        | Representative states                             | Mutation or failure expectation                                      | Audit section             |
-| -------------- | ------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------- | ------------------------- |
-| FR1–FR4, AR1–3 | focused DOM tests plus required exact-head accessibility evidence   | title only, all slots, absent/shallow-empty slots | order, heading, live role, or decorative treatment regresses         | `audit:EmptyState/a11y`   |
-| FR5, ORD1      | focused root composition tests plus shared API guards               | DOM/data/event/style inputs, ref, root target     | accepted input is dropped or component semantics/styles are replaced | `audit:EmptyState/api`    |
-| FR6            | compact target/DOM tests plus required exact-head rendered evidence | default and compact, wide and narrow              | compact state, spacing, or action direction no longer applies        | `audit:EmptyState/layout` |
-| PR1            | source review                                                       | every render path                                 | a retained resource appears without a named owner                    | `audit:EmptyState/code`   |
+| Contract            | Verification                                                                                                                           | Representative states                                                                                                                 | Mutation or failure expectation                                                                                                                                                                                                                                                                           | Audit section              |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, FR3, FR4, AR2  | `EmptyState.test.tsx` slot, order, decorative-icon, empty-slot, and live-role tests; stable visual baseline `core-emptystate--default` | Title only; all slots; absent and shallow-empty slots                                                                                 | A wrapper for an absent or shallow-empty slot, a changed slot order, an icon not hidden from assistive technology, or a live role on the root fails; a changed default layout comes back changed for review. Gap: no accessibility-tree check proves the hidden icon or the heading (`spec:AST-009` FR3). | `audit:EmptyState/a11y`    |
+| FR2, AR1            | `EmptyState.test.tsx` heading tests                                                                                                    | Default level 3; every level                                                                                                          | A title that is not the selected heading element fails. Gap: no check that the title keeps one type style at every heading level.                                                                                                                                                                         | `audit:EmptyState/a11y`    |
+| AR3                 | `EmptyState.announce.test.tsx`                                                                                                         | Render with the page; appear later; iframe; inside a live container; message change; server render and hydration; hidden and revealed | An announcement during load or hydration, a missing or repeated announcement when it appears or changes later, hidden text in the message, or an announcement inside a live container fails. Gap: no test asserts that focus stays where it was when EmptyState appears.                                  | `audit:EmptyState/a11y`    |
+| FR5, ORD1           | `EmptyState.test.tsx` ref, `data-testid`, and root-composition tests                                                                   | DOM, data, event, style inputs; caller role; ref                                                                                      | A dropped input, a replaced caller role, or a ref that is not a `div` fails. Gap: the ref test checks only that the ref is a `div`, not that it is the root. No test asserts that caller `xstyle` follows the component styles.                                                                           | `audit:EmptyState/api`     |
+| FR6                 | `EmptyState.test.tsx` compact and theming-target tests                                                                                 | Default and compact                                                                                                                   | A compact layout that is not reflected on the root, title, and description, or that changes slot order, fails. Gap: the reduced spacing and stacked actions have no automated check.                                                                                                                      | `audit:EmptyState/layout`  |
+| PR1                 | Source review                                                                                                                          | Every render path                                                                                                                     | Gap: no automated check fails if EmptyState adds state, a listener, or a timer of its own.                                                                                                                                                                                                                | `audit:EmptyState/code`    |
+| Theming anatomy map | `scripts/check-knowledge.mjs`; `themingTargets.test.ts`                                                                                | Consumer anatomy and current targets                                                                                                  | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                             | `audit:EmptyState/theming` |
 
 ## Decision log
 
-No component-local decision is approved in this draft.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 

package/src/EmptyState/EmptyState.tsx

@@ -24,7 +24,8 @@ import {
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {AnnounceRenderedText} from '../hooks/AnnounceRenderedText';
-import {isRenderable, mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({

package/src/Field/Field.doc.mjs

@@ -120,7 +120,8 @@ export const docs = {
     {
       name: 'labelTooltip',
       type: 'string',
-      description: 'Tooltip text to display in an info icon at the end of the label.',
+      description:
+        'Tooltip text to display in an info icon at the end of the label. Hover shows it; on a touch screen a tap on the icon opens it without focusing the field, while a mouse click on the icon focuses the field like the rest of the label.',
     },
     {
       name: 'status',

package/src/Field/Field.tsx

@@ -22,7 +22,6 @@ import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {FieldLabel} from './FieldLabel';
 import {FieldStatus} from '../FieldStatus/FieldStatus';
-import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
 import {useFieldStatusAnnouncement} from '../FieldStatus/useFieldStatusAnnouncement';
 import {spacingVars, borderVars, sizeVars} from '../theme/tokens.stylex';
 import type {IconType} from '../Icon';
@@ -32,6 +31,7 @@ import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {Text} from '../Text/Text';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
+import type {FieldStatusPlacement} from './fieldStatusPlacement';
 
 const styles = stylex.create({
   container: {
@@ -187,7 +187,7 @@ export interface FieldProps extends Omit<
    * - 'tooltip': No message box; the input surfaces status through a tooltip on its on-field icon
    * @default 'attached'
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
    * (e.g. `'100%'`). Sizes the whole field — label, control, and status — so

package/src/Field/FieldLabel.doc.mjs

@@ -72,7 +72,8 @@ export const docs = {
     {
       name: 'labelTooltip',
       type: 'string',
-      description: 'Tooltip text for the info icon after the label.',
+      description:
+        'Tooltip text for the info icon after the label. Hover shows it; on a touch screen a tap on the icon opens it without focusing the field or toggling the control, while a mouse click on the icon activates the control like the rest of the label.',
     },
     {
       name: 'description',
@@ -176,7 +177,8 @@ export const docsZh = {
     {
       name: 'labelTooltip',
       type: 'string',
-      description: '标签后信息图标的工具提示文本。',
+      description:
+        '标签后信息图标的工具提示文本。悬停即可显示；在触摸屏上点按图标即可打开，不会聚焦字段或切换控件；用鼠标点击图标则与点击标签其他部分一样激活控件。',
     },
     {
       name: 'description',

package/src/Field/FieldLabel.spec.md

@@ -15,6 +15,7 @@ verified_by:
     packages/core/src/Field/FieldLabel.test.tsx,
     packages/core/src/FormLayout/FormLayout.test.tsx,
     packages/core/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts,
+    packages/core/src/Field/__tests__/FieldLabelTap.a11y.chromium.spec.ts,
     packages/core/src/theme/themingTargets.test.ts,
     packages/core/src/docPropReferences.test.ts,
     packages/core/src/docPropLiterals.test.ts,
@@ -37,15 +38,15 @@ system_specs: [spec:AST-020/FR1]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                    |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `FieldLabel` renders a visible or visually hidden label group for one control or a caller-labelled group, with optional description, optionality indicator, icon, tooltip, label-element BaseProps, and label-element ref.                  |
-| Behavior                | Single-control mode uses a native label; group mode uses a labelled span. A description adds a wrapper div, while caller props and ref stay on the inner label element. Description clicks forward only to one associated control.          |
-| End-user impact         | People can identify a control or group, hear supporting text separately from its name, and activate eligible controls from the complete visible label area. The current tooltip remains unavailable to keyboard and screen-reader users.    |
-| Builder impact          | Builders provide stable control and description IDs, select group mode when labelling a composite, and wire `aria-labelledby` or `aria-describedby` on the controlled surface.                                                              |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Group mode renders a span while public types promise label props and ref, and the tooltip icon exposes its content only to a pointer; both are listed under Current-state impact. |
-| Review checks           | Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, or undocumented public prop.    |
-| Governing rules         | Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1, SC 4.1.2; `architecture:public-component-api/INV1,INV5–INV9,INV12`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR1`.                          |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `FieldLabel` renders a visible or visually hidden label group for one control or a caller-labelled group, with optional description, optionality indicator, icon, tooltip, label-element BaseProps, and label-element ref.                                                                                                                                                                                                          |
+| Behavior                | Single-control mode uses a native label; group mode uses a labelled span. A description adds a wrapper div, while caller props and ref stay on the inner label element. Description clicks forward only to one associated control.                                                                                                                                                                                                  |
+| End-user impact         | People can identify a control or group, hear supporting text separately from its name, and activate eligible controls from the complete visible label area. Help behind the info button opens by pointer, touch, keyboard, and screen reader, and a tap, click, or key press on it never changes the control (DEC-1); the shipped icon stays pointer-only, and a mouse click on it still activates the control, until FR9 is built. |
+| Builder impact          | Builders provide stable control and description IDs, select group mode when labelling a composite, and wire `aria-labelledby` or `aria-describedby` on the controlled surface.                                                                                                                                                                                                                                                      |
+| Compatibility/readiness | No API or default change; with `labelTooltip`, the info trigger becomes an InfoTip button after the label element, and a mouse click on it stops activating the control (FR9, DEC-1; not yet built). Group mode renders a span while public types promise label props and ref, and the shipped tooltip icon exposes its content only to a pointer; both are listed under Current-state impact.                                      |
+| Review checks           | Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, an info trigger inside the label element or one whose press activates the control, or undocumented public prop.                                                                                                         |
+| Governing rules         | Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1, SC 4.1.2; `component:InfoTip`; `architecture:public-component-api/INV1,INV5–INV9,INV12`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR1`.                                                                                                                                                                                             |
 
 This table is a review projection; the body below is authoritative.
 
@@ -56,9 +57,9 @@ This table is a review projection; the body below is authoritative.
 ## Compatibility and migration
 
 - Released default preserved: yes.
-- Compatibility class: records shipped behavior; no public prop, default, export, or DOM change.
+- Compatibility class: no public prop, default, or export change. With `labelTooltip`, the info trigger moves from an icon inside the label element to a `component:InfoTip` button after it, in one inline-flex row wrapping both, and a press on it, by any pointer or key, does not activate the control (FR9, DEC-1). Callers see that extra wrapper only when `labelTooltip` is set; their class, `xstyle`, and ref stay on the label element (FR6).
 - Controlled/uncontrolled behavior: not applicable.
-- Migration decision: none; the ref typing is OQ1.
+- Migration decision: DEC-1 needs no caller change; the ref typing is OQ1.
 
 ## Ownership boundary
 
@@ -75,32 +76,33 @@ This table is a review projection; the body below is authoritative.
 
 - The associated control or group's value, disabled semantics, focus model, keyboard behavior, and ARIA wiring beyond the label's own IDs.
 - The caller's layout around the label group.
-- Tooltip surface behavior and icon rendering, which delegate to Tooltip and `component:Icon`; FieldLabel still owns whether its chosen trigger exposes that content.
+- The info trigger, its press toggle, and the tooltip surface, which delegate to `component:InfoTip` and through it to `component:Tooltip`; FieldLabel owns where the trigger renders, its name, and that its content is exposed.
 
 ## Public concepts
 
-| Concept                | Closed values or states                         | Meaning                                                                                   | Availability by variant/orientation/state | Default        | Owner                  | Stability | Invalid-value behavior                                                                                                               |
-| ---------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| label mode             | single control; group                           | Chooses a native `<label htmlFor>` or a `<span>` referenced through `aria-labelledby`.    | All uses.                                 | single control | `component:FieldLabel` | released  | Boolean-constrained; see OQ1 for root/ref typing.                                                                                    |
-| label visibility       | visible; visually hidden                        | Keeps label and description accessible while removing their layout space when hidden.     | Both label modes.                         | visible        | `component:FieldLabel` | released  | Boolean-constrained.                                                                                                                 |
-| optionality marker     | none; optional; required                        | Shows the localized exception to FormLayout's form-level optionality default.             | Visible and hidden labels.                | none           | `component:FieldLabel` | released  | When both booleans are true, optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required. |
-| leading icon           | absent; icon type; rendered node                | Adds visual content before the label text.                                                | Both label modes.                         | absent         | `component:FieldLabel` | released  | Rendered through the shared icon slot.                                                                                               |
-| explanatory tooltip    | absent; localized string                        | Adds the shared info-icon anchor and tooltip surface after the label.                     | Both label modes.                         | absent         | `component:FieldLabel` | released  | The anchor is pointer-only (FR8 gap).                                                                                                |
-| supporting description | absent; rendered node with optional explicit ID | Keeps supporting content separate from the accessible name and available for description. | Both label modes.                         | absent         | `component:FieldLabel` | released  | Missing ID leaves association to the caller.                                                                                         |
-| description activation | forwarding; non-forwarding                      | For one control, noninteractive description clicks mirror native-label activation.        | Single mode only.                         | forwarding     | `component:FieldLabel` | released  | Group mode and interactive descendants do not forward.                                                                               |
+| Concept                | Closed values or states                         | Meaning                                                                                                                                                | Availability by variant/orientation/state | Default        | Owner                  | Stability | Invalid-value behavior                                                                                                               |
+| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| label mode             | single control; group                           | Chooses a native `<label htmlFor>` or a `<span>` referenced through `aria-labelledby`.                                                                 | All uses.                                 | single control | `component:FieldLabel` | released  | Boolean-constrained; see OQ1 for root/ref typing.                                                                                    |
+| label visibility       | visible; visually hidden                        | Keeps label and description accessible while removing their layout space when hidden.                                                                  | Both label modes.                         | visible        | `component:FieldLabel` | released  | Boolean-constrained.                                                                                                                 |
+| optionality marker     | none; optional; required                        | Shows the localized exception to FormLayout's form-level optionality default.                                                                          | Visible and hidden labels.                | none           | `component:FieldLabel` | released  | When both booleans are true, optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required. |
+| leading icon           | absent; icon type; rendered node                | Adds visual content before the label text.                                                                                                             | Both label modes.                         | absent         | `component:FieldLabel` | released  | Rendered through the shared icon slot.                                                                                               |
+| explanatory tooltip    | absent; localized string                        | Adds a `component:InfoTip` after the label element; a tap, click, or key press on it opens or closes the tooltip without activating the control (FR9). | Both label modes.                         | absent         | `component:FieldLabel` | released  | The shipped anchor is pointer-only until FR9 is built (FR8 gap).                                                                     |
+| supporting description | absent; rendered node with optional explicit ID | Keeps supporting content separate from the accessible name and available for description.                                                              | Both label modes.                         | absent         | `component:FieldLabel` | released  | Missing ID leaves association to the caller.                                                                                         |
+| description activation | forwarding; non-forwarding                      | For one control, noninteractive description clicks mirror native-label activation.                                                                     | Single mode only.                         | forwarding     | `component:FieldLabel` | released  | Group mode and interactive descendants do not forward.                                                                               |
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                 | Basis                                                                |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| FR1 | Single-control mode renders `<label htmlFor={inputID}>`; group mode renders a non-label element with `labelID` for caller-owned `aria-labelledby`.                                                                                                                                                        | Established public interface; HTML and ARIA semantics                |
-| FR2 | Visible and hidden labels retain the label text; hidden label and description boxes remain in the accessibility tree and leave no layout slot.                                                                                                                                                            | Established public interface                                         |
-| FR3 | Descriptions remain siblings of the label so they do not enter the control's accessible name. Noninteractive description clicks forward to one eligible control; group labels and interactive descendants do not forward activation.                                                                      | Established public interface; native label behavior                  |
-| FR4 | FormLayout optionality suppresses the matching visible marker; without a form default, the requested marker is localized and shown. When both flags are true, optional wins, except inside a FormLayout whose default is optional, where the optional marker is suppressed and the required marker shows. | Established public interface and current tests                       |
-| FR5 | Label icons, tooltip anchors, required/optional text, and description content preserve source order. The label element uses a horizontal flex row; the optional label/description wrapper uses block flow. All component-owned spacing is logical or direction-neutral.                                   | Established public interface and source observation                  |
-| FR6 | Accepted data, ARIA, DOM, class, style, event, and `xstyle` inputs compose on the label element without replacing the component-owned target or association. When a description renders, the outer wrapper is layout-only and caller props stay on the inner label element.                               | `architecture:public-component-api/INV5–INV7`                        |
-| FR7 | The public ref and label-element props MUST describe the element FieldLabel renders in each mode; which root element and public type group mode uses is OQ1. Implementation gap: group mode renders a `<span>` while the public BaseProps and ref types are fixed to `HTMLLabelElement`.                  | `architecture:public-component-api/INV8,INV9`; current runtime/types |
-| FR8 | The optional tooltip's explanatory content MUST be reachable by keyboard (WCAG 2.2 SC 2.1.1) and its trigger MUST have an accessible name and role (WCAG 2.2 SC 4.1.2). Implementation gap: it anchors to an anonymous, nonfocusable info icon, so the content is pointer-only.                           | WCAG 2.2 SC 2.1.1, SC 4.1.2; `spec:AST-020/FR1`                      |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                                                                  |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| FR1 | Single-control mode renders `<label htmlFor={inputID}>`; group mode renders a non-label element with `labelID` for caller-owned `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Established public interface; HTML and ARIA semantics                  |
+| FR2 | Visible and hidden labels retain the label text; hidden label and description boxes remain in the accessibility tree and leave no layout slot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Established public interface                                           |
+| FR3 | Descriptions remain siblings of the label so they do not enter the control's accessible name. Noninteractive description clicks forward to one eligible control; group labels and interactive descendants do not forward activation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Established public interface; native label behavior                    |
+| FR4 | FormLayout optionality suppresses the matching visible marker; without a form default, the requested marker is localized and shown. When both flags are true, optional wins, except inside a FormLayout whose default is optional, where the optional marker is suppressed and the required marker shows.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Established public interface and current tests                         |
+| FR5 | Label icons, tooltip anchors, required/optional text, and description content preserve source order. The label element uses a horizontal flex row; the optional label/description wrapper uses block flow. With `labelTooltip`, one inline-flex row wraps the label element and the InfoTip that follows it (FR9). All component-owned spacing is logical or direction-neutral.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Established public interface and source observation                    |
+| FR6 | Accepted data, ARIA, DOM, class, style, event, and `xstyle` inputs compose on the label element without replacing the component-owned target or association. When a description renders, the outer wrapper is layout-only and caller props stay on the inner label element; the `labelTooltip` row (FR9) is layout-only in the same way, so caller class, `xstyle`, and ref stay on the label element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `architecture:public-component-api/INV5–INV7`                          |
+| FR7 | The public ref and label-element props MUST describe the element FieldLabel renders in each mode; which root element and public type group mode uses is OQ1. Implementation gap: group mode renders a `<span>` while the public BaseProps and ref types are fixed to `HTMLLabelElement`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `architecture:public-component-api/INV8,INV9`; current runtime/types   |
+| FR8 | The optional tooltip's explanatory content MUST be reachable by keyboard (WCAG 2.2 SC 2.1.1) and its trigger MUST have an accessible name and role (WCAG 2.2 SC 4.1.2); FR9's InfoTip button meets both. Implementation gap: the shipped trigger is an anonymous, nonfocusable info icon, so the content is pointer-only until FR9 is built.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | WCAG 2.2 SC 2.1.1, SC 4.1.2; `spec:AST-020/FR1`                        |
+| FR9 | With `labelTooltip`, FieldLabel renders `component:InfoTip` with that content after the label element and outside it, and wraps the label element and the InfoTip in one inline-flex row, as it wraps the label and description, so no button sits inside a `<label>`; caller class, `xstyle`, and ref stay on the label element, and the row renders only when `labelTooltip` is set. With `isLabelHidden`, the InfoTip is visually hidden with the label, leaves no layout slot (FR2), and becomes visible while it has keyboard focus (WCAG 2.4.7); the button's name is a localized string that includes the label text ("About Auto-save"). A tap, click, Enter, or Space on the info trigger opens or closes the tooltip (`component:Tooltip` FR9) and never activates, focuses, or toggles the associated control; hover and focus preview it. Implementation gap: the shipped icon sits inside the label element; a tap by finger or pen opens or closes the tooltip without activating the control, but a mouse click on it also activates the control (Current-state impact). | DEC-1; HTML label content model; WCAG 2.2 SC 2.1.1, SC 2.4.7, SC 4.1.2 |
 
 ### Allowed variation
 
@@ -110,23 +112,23 @@ This table is a review projection; the body below is authoritative.
 
 ### Representative states
 
-| State                 | Required invariant                                                                                                                                                       | Allowed variation                                |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
-| single label          | Native label association reaches the one control.                                                                                                                        | Visible or visually hidden.                      |
-| group label           | Label element is not a literal label and is referenceable by `labelID`.                                                                                                  | Caller owns group role and `aria-labelledby`.    |
-| description           | Supporting content remains outside the label and may expose `descriptionID`.                                                                                             | Text or structured content.                      |
-| optional or required  | One localized exception marker follows label text.                                                                                                                       | Suppressed when it matches FormLayout's default. |
-| disabled presentation | Label uses disabled text treatment and no pointer cursor.                                                                                                                | Associated control owns actual disabled state.   |
-| icon and tooltip      | Shared Icon and Tooltip render their owned paint; the tooltip trigger is keyboard-reachable and named (FR8). Implementation gap: the anchor is nonfocusable and unnamed. | Either slot may be absent.                       |
+| State                 | Required invariant                                                                                                                                                                                                                                                          | Allowed variation                                |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| single label          | Native label association reaches the one control.                                                                                                                                                                                                                           | Visible or visually hidden.                      |
+| group label           | Label element is not a literal label and is referenceable by `labelID`.                                                                                                                                                                                                     | Caller owns group role and `aria-labelledby`.    |
+| description           | Supporting content remains outside the label and may expose `descriptionID`.                                                                                                                                                                                                | Text or structured content.                      |
+| optional or required  | One localized exception marker follows label text.                                                                                                                                                                                                                          | Suppressed when it matches FormLayout's default. |
+| disabled presentation | Label uses disabled text treatment and no pointer cursor.                                                                                                                                                                                                                   | Associated control owns actual disabled state.   |
+| icon and tooltip      | Shared Icon and InfoTip render their owned paint; the InfoTip button follows the label element, is keyboard-reachable and named, and its press never reaches the control (FR8, FR9). Implementation gap: the shipped anchor is nonfocusable, unnamed, and inside the label. | Either slot may be absent.                       |
 
 ### Transformation and precedence order
 
 - **ORD1 — Optionality.** The FormLayout default suppresses its matching marker first; then optional wins when both local booleans are true.
-- **ORD2 — Label-element composition.** Component target and base styles apply before caller `xstyle`, class, and inline style composition on the label element; association and label-element choice remain component-owned. An optional description adds a layout wrapper without retargeting those inputs.
+- **ORD2 — Label-element composition.** Component target and base styles apply before caller `xstyle`, class, and inline style composition on the label element; association and label-element choice remain component-owned. An optional description, or a `labelTooltip` row (FR9), adds a layout wrapper without retargeting those inputs.
 
 ### Performance and resources
 
-- **PR1 — No retained resource.** FieldLabel owns no global listener, observer, timer, or external store. Description activation reuses the shared input-container hook with local refs, and a `labelTooltip` brings the shared Tooltip's listeners and layer.
+- **PR1 — No retained resource.** FieldLabel owns no global listener, observer, timer, or external store. Description activation reuses the shared input-container hook with local refs, and a `labelTooltip` brings InfoTip's, and so Tooltip's, listeners and layer.
 
 ## Accessibility contract
 
@@ -135,7 +137,9 @@ This table is a review projection; the body below is authoritative.
 - **AR3 — Hidden labels.** Visually hidden label and description content remain programmatically available.
 - **AR4 — Activation boundary.** Description activation never hijacks interactive descendants and never forwards from a group label to one control.
 - **AR5 — Tooltip reachability.** Tooltip content MUST be reachable by keyboard
-  (WCAG 2.2 SC 2.1.1) through a named trigger (SC 4.1.2) (FR8). Implementation gap: the anonymous, nonfocusable anchor exposes it only to a pointer.
+  (WCAG 2.2 SC 2.1.1) through a named trigger (SC 4.1.2), the InfoTip button
+  that follows the label (FR8, FR9). Implementation gap: until FR9 is built,
+  the anonymous, nonfocusable anchor exposes it only to a pointer.
 
 ## Design relationships
 
@@ -149,17 +153,18 @@ No current repository design record governs component-local visual tuning. The i
 
 ## Verification map
 
-| Contract          | Verification                                                                                                                                                                     | Representative states                                     | Mutation or failure expectation                                                                                                                                                                                                                          | Audit section                    |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| FR1–FR3, AR1–AR4  | `FieldLabel.test.tsx` association, ref, and description-forwarding cases; `FieldLabelAudit.a11y.chromium.spec.ts` default, custom-theme, RTL, and narrow cases in light and dark | Single, group, description, interactive description child | A wrong label element, lost association, nested description, or forwarded group or interactive click fails. Evidence gap: no test asserts the hidden label and description leave no layout slot.                                                         | `audit:FieldLabel/accessibility` |
-| FR4, ORD1         | `FieldLabel.test.tsx` optional, required, both-set, and i18n cases; `FormLayout.test.tsx` default-optionality cases through Field                                                | Optional, required, both, localized                       | A wrong localized marker, required winning over optional, or a marker that restates the form default fails.                                                                                                                                              | `audit:FieldLabel/behavior`      |
-| FR5               | `FieldLabel.test.tsx` label-icon, tooltip, and tooltip-with-optional cases                                                                                                       | Icon, tooltip, optionality                                | A missing icon or tooltip anchor fails. Evidence gap: no test asserts source order, the flex row, or logical spacing.                                                                                                                                    | `audit:FieldLabel/layout`        |
-| FR6, ORD2         | `FieldLabel.test.tsx` ref, layout-item, and label-target cases; `themingTargets.test.ts`                                                                                         | Ref; composed target; with a description wrapper          | A dropped ref or a lost `field-label` target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts caller class, style, `xstyle`, data, and event props on the inner label element with a description wrapper. | `audit:FieldLabel/api`           |
-| FR7               | Evidence gap: no type test pins the public ref and props against the rendered group span                                                                                         | —                                                         | —                                                                                                                                                                                                                                                        | `audit:FieldLabel/api`           |
-| FR8, AR5          | `FieldLabelAudit.a11y.chromium.spec.ts` tooltip-anchor count                                                                                                                     | Tooltip present                                           | The audit records the one anonymous, nonfocusable anchor; it changes when the FR8 gap closes.                                                                                                                                                            | `audit:FieldLabel/accessibility` |
-| PR1               | Evidence gap: no test asserts the absence of retained resources                                                                                                                  | —                                                         | —                                                                                                                                                                                                                                                        | `audit:FieldLabel/code-health`   |
-| Documentation     | `docPropLiterals.test.ts`; `docPropReferences.test.ts`                                                                                                                           | Documented props and defaults                             | A documented literal or prop reference that drifts from the source type fails.                                                                                                                                                                           | `audit:FieldLabel/docs`          |
-| RTL applicability | `apps/storybook/rtl-audit/verified-not-applicable.json` entry for `core/FieldLabel`                                                                                              | Checked-in FieldLabel stories                             | A story that gains directional placement or behavior makes the not-applicable entry stale.                                                                                                                                                               | `audit:FieldLabel/i18n-rtl`      |
+| Contract          | Verification                                                                                                                                                                                                                                                                                   | Representative states                                                                                                             | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                    | Audit section                    |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
+| FR1–FR3, AR1–AR4  | `FieldLabel.test.tsx` association, ref, and description-forwarding cases; `FieldLabelAudit.a11y.chromium.spec.ts` default, custom-theme, RTL, and narrow cases in light and dark                                                                                                               | Single, group, description, interactive description child                                                                         | A wrong label element, lost association, nested description, or forwarded group or interactive click fails. Evidence gap: no test asserts the hidden label and description leave no layout slot.                                                                                                                                                                                                                   | `audit:FieldLabel/accessibility` |
+| FR4, ORD1         | `FieldLabel.test.tsx` optional, required, both-set, and i18n cases; `FormLayout.test.tsx` default-optionality cases through Field                                                                                                                                                              | Optional, required, both, localized                                                                                               | A wrong localized marker, required winning over optional, or a marker that restates the form default fails.                                                                                                                                                                                                                                                                                                        | `audit:FieldLabel/behavior`      |
+| FR5               | `FieldLabel.test.tsx` label-icon, tooltip, and tooltip-with-optional cases                                                                                                                                                                                                                     | Icon, tooltip, optionality                                                                                                        | A missing icon or tooltip anchor fails. Evidence gap: no test asserts source order, the flex row, or logical spacing; and, until FR9 is built, the `labelTooltip` row with the InfoTip after the label element.                                                                                                                                                                                                    | `audit:FieldLabel/layout`        |
+| FR6, ORD2         | `FieldLabel.test.tsx` ref, layout-item, and label-target cases; `themingTargets.test.ts`                                                                                                                                                                                                       | Ref; composed target; with a description wrapper                                                                                  | A dropped ref or a lost `field-label` target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts caller class, style, `xstyle`, data, and event props on the inner label element with a description wrapper, or, until FR9 is built, with the `labelTooltip` row.                                                                                                      | `audit:FieldLabel/api`           |
+| FR7               | Evidence gap: no type test pins the public ref and props against the rendered group span                                                                                                                                                                                                       | —                                                                                                                                 | —                                                                                                                                                                                                                                                                                                                                                                                                                  | `audit:FieldLabel/api`           |
+| FR8, AR5          | `FieldLabelAudit.a11y.chromium.spec.ts` tooltip-anchor count                                                                                                                                                                                                                                   | Tooltip present                                                                                                                   | The audit records the one anonymous, nonfocusable anchor; once FR9 is built it asserts one named InfoTip button outside the label element.                                                                                                                                                                                                                                                                         | `audit:FieldLabel/accessibility` |
+| FR9               | `FieldLabel.test.tsx` finger-tap, pen-tap, and mouse-click checkbox cases; `FieldLabelTap.a11y.chromium.spec.ts` touch-tap and mouse-click text-field cases; evidence gap until built: Enter and Space on the InfoTip button, the button's place outside the label, and the hidden-label cases | Checkbox, text field, and Switch labels; finger, pen, mouse, Enter, and Space; `isLabelHidden` with keyboard focus on the InfoTip | A tap that toggles or focuses the control fails today. Until FR9 is built the mouse-click cases assert the shipped activation; once built, a click or key press on the info trigger that activates, focuses, or toggles the control, an info button inside the label element, a trigger without the label in its name, or a hidden label's InfoTip that takes layout space or stays invisible while focused fails. | `audit:FieldLabel/accessibility` |
+| PR1               | Evidence gap: no test asserts the absence of retained resources                                                                                                                                                                                                                                | —                                                                                                                                 | —                                                                                                                                                                                                                                                                                                                                                                                                                  | `audit:FieldLabel/code-health`   |
+| Documentation     | `docPropLiterals.test.ts`; `docPropReferences.test.ts`                                                                                                                                                                                                                                         | Documented props and defaults                                                                                                     | A documented literal or prop reference that drifts from the source type fails.                                                                                                                                                                                                                                                                                                                                     | `audit:FieldLabel/docs`          |
+| RTL applicability | `apps/storybook/rtl-audit/verified-not-applicable.json` entry for `core/FieldLabel`                                                                                                                                                                                                            | Checked-in FieldLabel stories                                                                                                     | A story that gains directional placement or behavior makes the not-applicable entry stale.                                                                                                                                                                                                                                                                                                                         | `audit:FieldLabel/i18n-rtl`      |
 
 ## Current-state impact
 
@@ -167,11 +172,23 @@ No current repository design record governs component-local visual tuning. The i
   props and ref are typed for `HTMLLabelElement`, against
   `architecture:public-component-api` INV8 and INV9; the fix is OQ1.
 - **Tooltip reachability (FR8, AR5).** The label tooltip is pointer-only,
-  against WCAG 2.2 SC 2.1.1 and 4.1.2.
+  against WCAG 2.2 SC 2.1.1 and 4.1.2, until FR9's InfoTip is built.
+- **A mouse click on the info icon activates the control (FR9).** The shipped
+  icon sits inside the label element; a finger or pen tap opens its help
+  without activating the control, but a mouse click on it also focuses or
+  toggles the control.
 
 ## Decision log
 
-No component-local decision. The label-element and ref typing is OQ1.
+- **DEC-1 — A press on the info trigger is for its help.** A tap, click,
+  Enter, or Space on the label's info trigger opens or closes the help and
+  never activates the label's control, so asking what a setting does never
+  toggles a switch or focuses a field, for any pointer or key. The trigger is
+  `component:InfoTip`, the info-icon preset over Tooltip's press toggle, after
+  the label element, because a `<label>` may contain no control other than the
+  one it labels. Rejected: leaving the tap, or a mouse click, to the label.
+
+The label-element and ref typing is OQ1.
 
 ## Open questions
 

package/src/Field/FieldLabel.tsx

@@ -19,7 +19,7 @@
 import {use, useMemo, useRef, type ReactNode, type RefObject} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 
 import {
   colorVars,
@@ -28,9 +28,11 @@ import {
   typographyVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {Icon, renderIconSlot, type IconType} from '../Icon';
-import {Tooltip} from '../Tooltip';
-import {useTranslator} from '../i18n';
+import {Icon, renderIconSlot} from '../Icon/Icon';
+import type {IconType} from '../Icon';
+import {Tooltip} from '../Tooltip/Tooltip';
+import {useTapStop} from '../Layer/useTouchTrigger';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
@@ -255,6 +257,12 @@ export function FieldLabel({
   // a ref-shaped object, since FieldLabel points at the control by id rather
   // than holding a ref to it.
   const descriptionRef = useRef<HTMLSpanElement>(null);
+  // A tap on the info icon asks for the help, so it stops there: it does not
+  // go on to activate the label's control, as a press anywhere else on the
+  // label would (focus the field, toggle a switch). A mouse click on the icon
+  // keeps that native activation, and hover shows the help.
+  const {onPointerDown: handleIconPointerDown, onClick: handleIconClick} =
+    useTapStop('click');
   const controlRef = useMemo<RefObject<HTMLElement | null>>(
     () => ({
       get current() {
@@ -284,8 +292,17 @@ export function FieldLabel({
         </span>
       )}
       {labelTooltip && (
-        <Tooltip content={labelTooltip} placement="above">
-          <Icon icon="info" size="sm" color="inherit" />
+        // The icon's one job is to reveal the help, so a tap on it opens or
+        // closes the help (`touchTrigger="tap"`), although it sits inside a
+        // `<label>`.
+        <Tooltip content={labelTooltip} placement="above" touchTrigger="tap">
+          <Icon
+            icon="info"
+            size="sm"
+            color="inherit"
+            onPointerDown={handleIconPointerDown}
+            onClick={handleIconClick}
+          />
         </Tooltip>
       )}
     </>

package/src/Field/InputClearButton.tsx

@@ -18,9 +18,9 @@
 
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Button} from '../Button';
-import {Icon} from '../Icon';
-import {useTranslator} from '../i18n';
+import {Button} from '../Button/Button';
+import {Icon} from '../Icon/Icon';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({