@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Field/FieldLabel.spec.md

@@ -3,20 +3,22 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:FieldLabel
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-28
 owners: [cixzhang]
 review_triggers: [public-api, behavior, layout, theming, accessibility]
 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/theme/themingTargets.test.ts,
     packages/core/src/docPropReferences.test.ts,
     packages/core/src/docPropLiterals.test.ts,
+    apps/storybook/rtl-audit/verified-not-applicable.json,
   ]
 modules: []
 families: []
@@ -35,15 +37,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 | This draft records released behavior and changes no API. Two gaps remain: group mode renders a span while public types promise label props/ref, and the anonymous tooltip icon exposes its content only to a pointer.                    |
-| 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; `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. 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`.                          |
 
 This table is a review projection; the body below is authoritative.
 
@@ -54,9 +56,9 @@ This table is a review projection; the body below is authoritative.
 ## Compatibility and migration
 
 - Released default preserved: yes.
-- Compatibility class: observational only; this draft changes no public prop, default, or behavior.
+- Compatibility class: records shipped behavior; no public prop, default, export, or DOM change.
 - Controlled/uncontrolled behavior: not applicable.
-- Migration decision: none; OQ1 requires a separate public-type decision. The tooltip accessibility defect remains open.
+- Migration decision: none; the ref typing is OQ1.
 
 ## Ownership boundary
 
@@ -73,34 +75,32 @@ 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 `component:Tooltip` and `component:Icon`; FieldLabel still owns whether its chosen trigger exposes that content.
+- Tooltip surface behavior and icon rendering, which delegate to Tooltip and `component:Icon`; FieldLabel still owns whether its chosen trigger exposes that content.
 
 ## 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.                       |
-| 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; conformance gap | The current anonymous, nonfocusable icon leaves the content pointer-only. |
-| 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 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.                                                                               |
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an intentional decision.
-
-| ID  | Candidate invariant                                                                                                                                                                                                                                                         | Basis                                                                | Draft review state                  |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------- |
-| 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                | settled observation                 |
-| 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                                         | settled observation                 |
-| 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                  | settled observation                 |
-| 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.                                                                                                | Established public interface and current tests                       | settled observation                 |
-| 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                  | settled 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`                        | settled observation for single mode |
-| FR7 | The public ref reaches the label element. Group mode currently renders a span while the public BaseProps/ref type is fixed to `HTMLLabelElement`.                                                                                                                           | `architecture:public-component-api/INV8,INV9`; current runtime/types | human decision (OQ1)                |
-| FR8 | The optional tooltip currently anchors to an anonymous, nonfocusable info icon, so its explanatory content is unavailable by keyboard and is not announced with the associated field.                                                                                       | WCAG 2.2 SC 2.1.1; `spec:AST-020/FR1`; current runtime               | objective conformance gap           |
+| 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`                      |
 
 ### Allowed variation
 
@@ -110,23 +110,23 @@ Draft requirements identify their basis so observed code is not mistaken for an
 
 ### 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 current tooltip anchor remains 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 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.                       |
 
 ### Transformation and precedence order
 
-- **ORD1 — Optionality.** Optional wins when both local booleans are true; otherwise the FormLayout default suppresses its matching marker.
+- **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.
 
 ### 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.
+- **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.
 
 ## Accessibility contract
 
@@ -134,7 +134,8 @@ Draft requirements identify their basis so observed code is not mistaken for an
 - **AR2 — Description separation.** Description content stays outside the label so it is not duplicated in the accessible name and exposes an ID for caller-owned `aria-describedby`.
 - **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.** The current anonymous, nonfocusable tooltip anchor does not expose its explanatory content to keyboard or screen-reader users; this remains an objective conformance gap.
+- **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.
 
 ## Design relationships
 
@@ -148,20 +149,29 @@ 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` plus exact-head axe and Chromium sensor receipts                        | single, group, description, hidden, interactive description child               | Wrong label element, lost association, nested description, missing hidden text, or forwarded group/interactive click fails.                                       | `audit:FieldLabel/accessibility` |
-| FR4–FR5, ORD1        | focused DOM tests, i18n catalog checks, and exact-head light/dark/custom-theme frames         | optional, required, both, form default, icon, tooltip, disabled                 | Wrong localized marker, order, visibility, or tokenized state is exposed.                                                                                         | `audit:FieldLabel/behavior`      |
-| FR6, ORD2            | BaseProps lint, focused composition tests, theming-target tests, and browser target inventory | class, style, xstyle, data, event, target; with and without description wrapper | Consumer input is dropped, retargeted to the wrapper, or the `field-label` target disappears.                                                                     | `audit:FieldLabel/api`           |
-| FR7                  | Public type review against the runtime single-label and group-span branches                   | single label; group span                                                        | Public ref/prop types claim a different label element than runtime.                                                                                               | `audit:FieldLabel/api`           |
-| FR8, AR5             | focused source/DOM review plus exact-head sensor receipt for the tooltip anchor               | tooltip absent; tooltip present                                                 | The known anonymous, nonfocusable anchor disappears from the audit record before an accessible path replaces it.                                                  | `audit:FieldLabel/accessibility` |
-| Documentation        | docs typecheck, CLI readback, prop-literal/reference tests, and knowledge validation          | every public prop and default                                                   | Docs omit or misstate a public input or default.                                                                                                                  | `audit:FieldLabel/docs`          |
-| RTL applicability    | source/story inspection and verified-N/A registry                                             | all component-owned states                                                      | A directional glyph, physical inline property, inline-side placement, order, scroll/drag, inline-side overlay placement, or horizontal arrow key makes N/A stale. | `audit:FieldLabel/i18n-rtl`      |
-| Responsive rendering | exact-head 320px Chromium sensor receipts                                                     | visible, hidden, description, group, optionality, icon, tooltip                 | The story overflows horizontally or a visible/hidden label loses its relationship.                                                                                | `audit:FieldLabel/responsive`    |
+| 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`      |
+
+## Current-state impact
+
+- **Group-mode typing (FR7).** Group mode renders a `<span>` while the public
+  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.
 
 ## Decision log
 
-No component-local decision is asserted. This draft records shipped behavior, retains the objective tooltip-accessibility gap, and leaves the polymorphic label-element/ref contract in OQ1.
+No component-local decision. The label-element and ref typing is OQ1.
 
 ## Open questions
 
@@ -169,4 +179,5 @@ No component-local decision is asserted. This draft records shipped behavior, re
 
 ## Content boundary
 
-This draft records verified shipped behavior, the objective tooltip-accessibility gap, and the released label-element type/runtime mismatch. It does not choose a ref migration, add a theme target, duplicate consumer prop tables, or store audit scores and run evidence.
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/Field/FieldLabel.tsx

@@ -32,7 +32,7 @@ import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Tooltip} from '../Tooltip';
 import {useTranslator} from '../i18n';
 import {themeProps} from '../utils/themeProps';
-import {useInputContainer} from '../hooks';
+import {useInputContainer} from '../hooks/useInputContainer';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 
 const styles = stylex.create({

package/src/Field/PanelSearchInput.tsx

@@ -41,6 +41,7 @@
 
 import {useCallback, useState, type Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
 import {Icon} from '../Icon';
 import {InputClearButton} from './InputClearButton';
 import {mergeProps} from '../utils';
@@ -177,6 +178,14 @@ export interface PanelSearchInputProps extends Omit<
    * handler of its own.
    */
   onContainerKeyDown?: React.KeyboardEventHandler<HTMLDivElement>;
+
+  /**
+   * Styles for the field box itself (the rounded row that draws the focus
+   * ring), as opposed to `xstyle`, which lands on the outer gutter. A panel
+   * whose rows are taller than a dropdown's — a touch sheet — uses it to grow
+   * the field to the same height as its rows.
+   */
+  fieldXstyle?: StyleXStyles;
 }
 
 /**
@@ -199,6 +208,7 @@ export function PanelSearchInput({
   onFocus,
   onBlur,
   onContainerKeyDown,
+  fieldXstyle,
   xstyle,
   className,
   style,
@@ -232,19 +242,18 @@ export function PanelSearchInput({
     (e?: React.MouseEvent<HTMLButtonElement>) => {
       onValueChange('');
       // Clearing puts the caret back where the user was typing, matching
-      // TextInput's built-in clear. Defer focus restoration past the button's
-      // unmount task so touch browsers don't jump page scroll on tap, while
-      // preserving synchronous focus for keyboard users.
-      if (!e || e.detail === 0) {
-        if (typeof ref === 'object' && ref?.current) {
-          ref.current.focus();
-        }
-      } else {
-        requestAnimationFrame(() => {
-          if (typeof ref === 'object' && ref?.current) {
-            ref.current.focus({preventScroll: true});
-          }
-        });
+      // TextInput's built-in clear, and it does so inside the tap: iOS raises
+      // the software keyboard only for a focus made while the browser is
+      // still dispatching the person's tap, and a UIKit search field's clear
+      // button makes the field first responder, keyboard and all (measured on
+      // iOS 26.2). A frame later the focus came with no keyboard. When the
+      // input already has focus, the clear button's pressed state never takes
+      // it, so this is a no-op and the keyboard stays where it is.
+      // `preventScroll` keeps a pointer tap from scrolling the page.
+      if (typeof ref === 'object' && ref?.current) {
+        ref.current.focus(
+          e == null || e.detail === 0 ? undefined : {preventScroll: true},
+        );
       }
     },
     [onValueChange, ref],
@@ -259,6 +268,7 @@ export function PanelSearchInput({
         {...stylex.props(
           styles.field,
           isKeyboardFocus && styles.fieldKeyboardFocus,
+          fieldXstyle,
         )}>
         <Icon icon="search" size="sm" color="secondary" xstyle={styles.icon} />
         <input

package/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y audit FieldLabel
 
 /**
  * @file FieldLabelAudit.a11y.chromium.spec.ts

package/src/Field/inputDisabledFocus.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file inputDisabledFocus.ts
+ * @input Uses StyleX and theme tokens
+ * @output inputDisabledFocusStyles (internal; not re-exported from Field/index.ts)
+ * @position Field wrapper style shared by TextInput and TextArea
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+
+export const inputDisabledFocusStyles = stylex.create({
+  // The shared disabled style drops the focus ring; restore it while the field's
+  // own control, a direct child, has keyboard focus (`spec:AST-085` FR6), so a
+  // focused status button keeps only its own outline.
+  ring: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':has(> [aria-disabled="true"]:focus-visible)':
+        colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
+});

package/src/Field/inputStyles.stylex.ts

@@ -79,13 +79,13 @@ export const inputWrapperStyles = stylex.create({
  */
 export const inputStatusBorderStyles = stylex.create({
   warning: {
-    borderColor: colorVars['--color-warning'],
+    borderColor: colorVars['--color-border-warning'],
   },
   error: {
-    borderColor: colorVars['--color-error'],
+    borderColor: colorVars['--color-border-error'],
   },
   success: {
-    borderColor: colorVars['--color-success'],
+    borderColor: colorVars['--color-border-success'],
   },
 });
 
@@ -131,20 +131,20 @@ export const inputStatusHoverShadowStyles = stylex.create({
 export const inputStatusFocusWithinStyles = stylex.create({
   warning: {
     borderColor: {
-      default: colorVars['--color-warning'],
-      ':focus-within': colorVars['--color-warning'],
+      default: colorVars['--color-border-warning'],
+      ':focus-within': colorVars['--color-border-warning'],
     },
   },
   error: {
     borderColor: {
-      default: colorVars['--color-error'],
-      ':focus-within': colorVars['--color-error'],
+      default: colorVars['--color-border-error'],
+      ':focus-within': colorVars['--color-border-error'],
     },
   },
   success: {
     borderColor: {
-      default: colorVars['--color-success'],
-      ':focus-within': colorVars['--color-success'],
+      default: colorVars['--color-border-success'],
+      ':focus-within': colorVars['--color-border-success'],
     },
   },
 });
@@ -157,20 +157,20 @@ export const inputStatusFocusWithinStyles = stylex.create({
 export const inputStatusFocusStyles = stylex.create({
   warning: {
     borderColor: {
-      default: colorVars['--color-warning'],
-      ':focus': colorVars['--color-warning'],
+      default: colorVars['--color-border-warning'],
+      ':focus': colorVars['--color-border-warning'],
     },
   },
   error: {
     borderColor: {
-      default: colorVars['--color-error'],
-      ':focus': colorVars['--color-error'],
+      default: colorVars['--color-border-error'],
+      ':focus': colorVars['--color-border-error'],
     },
   },
   success: {
     borderColor: {
-      default: colorVars['--color-success'],
-      ':focus': colorVars['--color-success'],
+      default: colorVars['--color-border-success'],
+      ':focus': colorVars['--color-border-success'],
     },
   },
 });

package/src/FieldStatus/FieldStatus.test.tsx

@@ -14,6 +14,7 @@ import {render, screen, waitFor} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
 import {FieldStatus} from './FieldStatus';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {getForcedColorsRules} from '../__tests__/forcedColors';
 
 const testStyles = stylex.create({
   custom: {color: 'rebeccapurple'},
@@ -468,3 +469,14 @@ describe('FieldStatus', () => {
     expect(FieldStatus.displayName).toBe('FieldStatus');
   });
 });
+
+// jsdom cannot emulate forced colors, so this asserts the compiled rule the
+// status fill relies on (architecture:theme-tokens INV11).
+describe('FieldStatus forced colors', () => {
+  it('keeps a visible boundary on the status fill', () => {
+    render(<FieldStatus type="error" message="Required" />);
+    const css = getForcedColorsRules();
+    expect(css).toContain('outline-style: solid;');
+    expect(css).toContain('outline-color: canvastext;');
+  });
+});

package/src/FieldStatus/FieldStatus.tsx

@@ -51,6 +51,15 @@ const ATTACHED_OVERLAP = `var(--_field-status-overlap, ${spacingVars['--spacing-
 
 const styles = stylex.create({
   base: {
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
     fontFamily: typographyVars['--font-family-body'],
     fontSize: typeScaleVars['--text-supporting-size'],
     lineHeight: typeScaleVars['--text-supporting-leading'],
@@ -91,15 +100,15 @@ const styles = stylex.create({
 const colorStyles = stylex.create({
   warning: {
     backgroundColor: colorVars['--color-warning-muted'],
-    color: colorVars['--color-text-yellow'],
+    color: colorVars['--color-on-warning-muted'],
   },
   error: {
     backgroundColor: colorVars['--color-error-muted'],
-    color: colorVars['--color-text-red'],
+    color: colorVars['--color-on-error-muted'],
   },
   success: {
     backgroundColor: colorVars['--color-success-muted'],
-    color: colorVars['--color-text-green'],
+    color: colorVars['--color-on-success-muted'],
   },
 });
 

package/src/FieldStatus/__tests__/StatusMessage.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file StatusMessage.a11y.chromium.spec.ts

package/src/FileInput/FileInput.doc.mjs

@@ -196,7 +196,7 @@ export const docs = {
       {name: 'Upload icon', required: false, description: 'An upload-to-tray icon in the drop zone hinting at the upload action.'},
       {name: 'Placeholder', required: false, description: 'Hint text shown when no files are selected.'},
       {name: 'File name display', required: false, description: 'Shows the name(s) of selected files.'},
-      {name: 'Clear button', required: false, description: 'A close button that removes selected files and returns focus to the input.'},
+      {name: 'Clear button', required: false, description: 'A close button that removes selected files and returns focus to the file-selection trigger.'},
       {name: 'Spinner', required: false, description: 'Loading indicator that appears during async upload actions.'},
       {name: 'Status message', required: false, description: 'Validation feedback showing error, warning, or success with a message.'},
     ],