@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/EmptyState/EmptyState.spec.md

@@ -26,7 +26,8 @@ architecture:
     architecture:component-test-sufficiency,
   ]
 contributing: []
-system_specs: [spec:AST-020/FR1, spec:AST-029/FR3]
+system_specs:
+  [spec:AST-020/FR1, spec:AST-029/FR3, spec:AST-086/FR2, spec:AST-086/FR11]
 ---
 
 # EmptyState component contract
@@ -35,11 +36,11 @@ system_specs: [spec:AST-020/FR1, spec:AST-029/FR3]
 
 | Area                    | Contract                                                                                                                                                                                         |
 | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | `EmptyState` renders a required title plus optional description, decorative icon, and caller-owned actions in one status region; callers choose heading level and compact layout.                |
+| 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 | The released default is preserved. This draft observes shipped behavior plus the narrow scalar-slot remediation; it adds no API, default, or compatibility promise.                              |
+| 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.             |
 | 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.          |
 
@@ -52,10 +53,10 @@ context, optional decorative visual, and optional caller-owned next actions.
 
 ## Compatibility and migration
 
-- Released default preserved: yes
-- Compatibility class: observational and additive documentation; runtime remediation removes wrappers for nullish, boolean, and empty-string optional values
+- 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
 - Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
+- 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)
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -63,7 +64,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- the status-region root, content order, heading element, and default/compact layout;
+- the root, content order, heading element, and default/compact layout;
 - hiding the icon slot from assistive technology as decorative; and
 - whether optional slots create component-owned wrappers and spacing.
 
@@ -91,11 +92,11 @@ intentional decision. A `current` contract contains no unresolved rows.
 
 | ID  | Candidate invariant                                                                                                                                                                     | Basis                                                                                | Draft review state |
 | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
-| FR1 | The component MUST render one status-region root containing the icon, text group, and actions in that reading order when present.                                                       | Current implementation and consumer docs; WCAG 2.2 SC 1.3.2 and SC 4.1.3             | verify             |
+| 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 status-region root.                                                               | `architecture:public-component-api` INV5–INV8                                        | 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             |
 
 ### Allowed variation
@@ -109,7 +110,7 @@ intentional decision. A `current` contract contains no unresolved rows.
 
 | State                         | Required invariant                                        | Allowed variation                      |
 | ----------------------------- | --------------------------------------------------------- | -------------------------------------- |
-| title only                    | status root and selected heading level remain present     | message wording                        |
+| title only                    | root and selected heading level remain present            | message wording                        |
 | description                   | supporting text follows the title                         | text length and wrapping               |
 | decorative icon               | visual precedes text and is hidden from assistive tech    | artwork supplied by the caller         |
 | actions                       | caller controls follow the text group                     | one or more caller-owned controls      |
@@ -120,7 +121,8 @@ intentional decision. A `current` contract contains no unresolved rows.
 
 - **ORD1 — Root composition.** Component semantics and theme metadata combine
   with component styles, then consumer `xstyle`, `className`, and `style` under
-  the shared merge contract; component-owned `role="status"` remains authoritative.
+  the shared merge contract. The component sets no role, so a caller's `role`
+  reaches the root unchanged.
 
 ### Performance and resources
 
@@ -132,8 +134,14 @@ intentional decision. A `current` contract contains no unresolved rows.
 - **AR1 — Heading semantics.** The title is a heading at the caller-selected level.
 - **AR2 — Decorative visual.** The icon slot is hidden from assistive technology;
   callers keep all necessary meaning in the title or description.
-- **AR3 — Status exposure.** The root exposes the empty message as a status region
-  without moving focus; action controls keep their own names, roles, and behavior.
+- **AR3 — No live region; announced when it appears.** EmptyState adds no live
+  role or `aria-live` to the root and does not move focus. Rendered or changed
+  before the document finished loading (or while hydrating), it announces
+  nothing. When it appears, or its message changes, later, it announces its
+  message once through the shared polite channel (`spec:AST-086` FR2, FR11).
+  The message is the title and description, without content hidden from
+  assistive technology; action labels are not part of it. Action controls keep
+  their own names, roles, and behavior.
 
 ## Design relationships
 
@@ -170,7 +178,7 @@ No current family record owns EmptyState-specific behavior.
 
 | 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, status, or decorative treatment regresses            | `audit:EmptyState/a11y`   |
+| 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`   |

package/src/EmptyState/EmptyState.test.tsx

@@ -117,14 +117,13 @@ describe('EmptyState', () => {
     expect(divs).toHaveLength(2); // container + text group
   });
 
-  it('has role="status" on the container', () => {
-    render(<EmptyState title="No results" />);
-    expect(screen.getByRole('status')).toBeInTheDocument();
+  it('does not make the root a live region', () => {
+    const {container} = render(<EmptyState title="No results" />);
+    expect(container.querySelector('[role], [aria-live]')).toBeNull();
   });
 
   it('renders compact variant', () => {
     render(<EmptyState title="No results" isCompact />);
-    expect(screen.getByRole('status')).toBeInTheDocument();
     expect(screen.getByText('No results')).toBeInTheDocument();
   });
 
@@ -143,7 +142,7 @@ describe('EmptyState', () => {
     const {container} = render(
       <EmptyState title="No results" description="" icon={false} actions="" />,
     );
-    const root = screen.getByRole('status');
+    const root = container.firstElementChild as HTMLElement;
     expect(root).toHaveTextContent('No results');
     expect(root).toHaveTextContent(/^No results$/);
     expect(root.children).toHaveLength(1);
@@ -153,7 +152,7 @@ describe('EmptyState', () => {
     ).toBeNull();
   });
 
-  it('composes root props and keeps component semantics authoritative', () => {
+  it('composes root props, including a caller role', () => {
     const onClick = vi.fn();
     const expectedXstyleClass = stylex.props(testStyles.root).className;
     if (expectedXstyleClass == null) {
@@ -171,7 +170,7 @@ describe('EmptyState', () => {
       />,
     );
 
-    const root = screen.getByRole('status');
+    const root = screen.getByRole('region');
     expect(root).toHaveClass('astryx-empty-state', 'consumer-class');
     expect(root).toHaveClass(expectedXstyleClass);
     expect(root).toHaveAttribute('data-owner', 'consumer');
@@ -188,10 +187,11 @@ describe('EmptyState', () => {
         icon={<span data-testid="icon">Icon</span>}
         actions={<button type="button">Retry</button>}
         isCompact
+        data-testid="empty-state"
       />,
     );
 
-    const root = screen.getByRole('status');
+    const root = screen.getByTestId('empty-state');
     expect(root).toHaveAttribute('data-variant', 'compact');
     expect(root.children).toHaveLength(3);
     expect(root.children[0]).toContainElement(screen.getByTestId('icon'));

package/src/EmptyState/EmptyState.tsx

@@ -2,7 +2,7 @@
 
 /**
  * @file EmptyState.tsx
- * @input Uses React, HTMLAttributes
+ * @input Uses React, HTMLAttributes, AnnounceRenderedText
  * @output Exports EmptyState component, EmptyStateProps type
  * @position Core implementation; consumed by index.ts
  *
@@ -23,6 +23,7 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
+import {AnnounceRenderedText} from '../hooks/AnnounceRenderedText';
 import {isRenderable, mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
@@ -123,7 +124,9 @@ export interface EmptyStateProps extends BaseProps<HTMLDivElement> {
  * An empty state placeholder for content areas with no data.
  * Displays an icon or illustration, title, optional description, and action buttons.
  *
- * Uses `role="status"` to announce content to screen readers.
+ * Not a live region. Its title and description are announced once when they
+ * appear or change after the page loaded, never when the page first renders
+ * with them (`spec:AST-086` FR2).
  * Styles use Astryx theme tokens via StyleX. Wrap your app in <Theme> to apply a theme.
  *
  * @example
@@ -158,7 +161,6 @@ export function EmptyState({
     <div
       ref={ref}
       {...props}
-      role="status"
       {...mergeProps(
         themeProps('empty-state', {variant: isCompact ? 'compact' : null}),
         stylex.props(
@@ -170,7 +172,7 @@ export function EmptyState({
         style,
       )}>
       {isRenderable(icon) && <div aria-hidden="true">{icon}</div>}
-      <div {...stylex.props(styles.textGroup)}>
+      <AnnounceRenderedText {...stylex.props(styles.textGroup)}>
         {createElement(
           HeadingTag,
           mergeProps(
@@ -195,7 +197,7 @@ export function EmptyState({
             {description}
           </div>
         )}
-      </div>
+      </AnnounceRenderedText>
       {isRenderable(actions) && (
         <div
           {...stylex.props(styles.actions, isCompact && styles.actionsCompact)}>

package/src/Field/Field.spec.md

@@ -3,24 +3,25 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:Field
-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/Field.test.tsx,
+    packages/core/src/FormLayout/FormLayout.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
     packages/core/src/docPropLiterals.test.ts,
     packages/core/src/docPropReferences.test.ts,
+    apps/storybook/rtl-audit/verified-not-applicable.json,
   ]
 modules: []
 families: [family:input-fields]
-design_specs:
-  [design:spatial-hierarchy, design:typography-hierarchy, design:system-states]
+design_specs: []
 architecture:
   [
     architecture:public-component-api,
@@ -42,7 +43,7 @@ system_specs:
 | Behavior                | Single controls use a native label association; groups use a labelled span. Status messages receive stable IDs and use persistent live regions. Horizontal-label mode exposes one protected `data-layout` theme axis.                                           |
 | End-user impact         | People can identify a custom control, hear its description and changing status, and keep label/control/status relationships together across ordinary and horizontal form layouts.                                                                               |
 | Builder impact          | Builders provide the control and its ID, wire descriptions/status IDs to that control, choose group semantics when needed, and use a status placement that is safe for the wrapped surface.                                                                     |
-| Compatibility/readiness | This draft records released behavior. It adds no API or policy. The released default `statusVariant="attached"` for arbitrary children conflicts with the capability boundary in `family:input-fields/FR8` and remains open.                                    |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The default `statusVariant="attached"` for arbitrary children conflicts with `family:input-fields/FR8`; listed under Current-state impact, with the migration open (OQ1).                             |
 | Review checks           | Reject a lost label/group association, dropped root props, caller replacement of `data-layout`, duplicate/missing status announcement, escaped local z-index, undocumented public literals, or a claim that all custom controls safely support attached status. |
 | Governing rules         | Established public `Field` interface; `family:input-fields` shared ownership and FR8; `architecture:public-component-api/INV5–INV8`; `spec:AST-027/FR1–FR3`; HTML label and ARIA naming/description semantics.                                                  |
 
@@ -55,7 +56,7 @@ This table is a review projection; the body below is authoritative.
 ## Compatibility and migration
 
 - Released default preserved: yes; `statusVariant` still defaults to `attached` in the current implementation.
-- 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: caller-owned and unchanged.
 - Migration decision: none; resolving OQ1 requires a separate compatibility decision.
 
@@ -78,31 +79,29 @@ This table is a review projection; the body below is authoritative.
 
 ## 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>` named through `aria-labelledby`.                | All layouts.                                                           | single control                 | `component:Field`     | released                  | Type-constrained                      |
-| label visibility       | visible; visually hidden                          | Hides label and description visually while preserving them for assistive technology.             | All layouts.                                                           | visible                        | `component:Field`     | released                  | Type-constrained                      |
-| optionality marker     | none; optional; required                          | Shows the localized exception to FormLayout's optionality default.                               | Label presentation.                                                    | none                           | `component:Field`     | released                  | Both set warns; optional wins visibly |
-| status placement       | `attached`; `detached`; `tooltip`                 | Places a status box behind the control, below it, or leaves visible tooltip affordance to input. | Message required for a rendered box; tooltip still announces messages. | `attached` (see OQ1)           | `family:input-fields` | released; conformance gap | Type-constrained                      |
-| width                  | absent; number; CSS size string                   | Sizes the complete ordinary field box.                                                           | Ordinary box layout; horizontal-label mode uses `display: contents`.   | containing layout              | `component:Field`     | released                  | Type-constrained                      |
-| field layout           | ordinary box; `horizontal-labels` from FormLayout | Stacks content or projects label and input group into the parent grid.                           | Resolved from `FormLayoutContext`.                                     | ordinary box                   | `component:Field`     | released                  | Context-constrained                   |
-| description/status IDs | explicit; generated from `inputID`; absent        | Names stable description and message elements for caller-owned `aria-describedby` wiring.        | Generated only when the corresponding text is present.                 | generated when text is present | `component:Field`     | released                  | Empty text omits output               |
+| 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>` named through `aria-labelledby`.                | All layouts.                                                           | single control                 | `component:Field`     | released                  | Type-constrained                                                                                                        |
+| label visibility       | visible; visually hidden                          | Hides label and description visually while preserving them for assistive technology.             | All layouts.                                                           | visible                        | `component:Field`     | released                  | Type-constrained                                                                                                        |
+| optionality marker     | none; optional; required                          | Shows the localized exception to FormLayout's optionality default.                               | Label presentation.                                                    | none                           | `component:Field`     | released                  | Both set warns; optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required. |
+| status placement       | `attached`; `detached`; `tooltip`                 | Places a status box behind the control, below it, or leaves visible tooltip affordance to input. | Message required for a rendered box; tooltip still announces messages. | `attached` (see OQ1)           | `family:input-fields` | released; conformance gap | Type-constrained                                                                                                        |
+| width                  | absent; number; CSS size string                   | Sizes the complete ordinary field box.                                                           | Ordinary box layout; horizontal-label mode uses `display: contents`.   | containing layout              | `component:Field`     | released                  | Type-constrained                                                                                                        |
+| field layout           | ordinary box; `horizontal-labels` from FormLayout | Stacks content or projects label and input group into the parent grid.                           | Resolved from `FormLayoutContext`.                                     | ordinary box                   | `component:Field`     | released                  | Context-constrained                                                                                                     |
+| description/status IDs | explicit; generated from `inputID`; absent        | Names stable description and message elements for caller-owned `aria-describedby` wiring.        | Generated only when the corresponding text is present.                 | generated when text is present | `component:Field`     | released                  | Empty text omits output                                                                                                 |
 
 ## 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 | A single-control label renders as `<label htmlFor={inputID}>`; a group label renders as a non-label element with `labelID` for caller-owned `aria-labelledby`.                                                                                               | Established public interface; HTML and ARIA semantics                  | settled observation                 |
-| FR2 | Visually hidden labels and descriptions remain in the DOM and out of layout flow.                                                                                                                                                                            | Established public interface and accessibility behavior                | settled observation                 |
-| FR3 | Description and status IDs use explicit values when supplied and otherwise resolve to `${inputID}-desc` and `${inputID}-status` only when text exists.                                                                                                       | Established public interface                                           | settled observation                 |
-| FR4 | Error status messages announce assertively and warning/success messages politely through persistent live regions; tooltip placement renders no `FieldStatus` box but preserves the announcement.                                                             | Existing tests; family ownership                                       | settled observation                 |
-| FR5 | Ordinary layout orders label, control, then optional status. Horizontal-label mode places the label wrapper before one description/control/status group and reflects `data-layout="horizontal-labels"`; caller props cannot replace that owned theme marker. | Established layout interface; `architecture:public-component-api/INV5` | settled observation                 |
-| FR6 | `width` applies to the ordinary root field box; it does not style the caller-owned control and has no box to target in horizontal-label mode.                                                                                                                | Established public interface; `family:input-fields` shared owner       | settled observation                 |
-| FR7 | Root ref, data/ARIA/DOM inputs, events, `xstyle`, class name, and inline style reach or compose on the root without replacing component-owned semantics.                                                                                                     | `architecture:public-component-api/INV5–INV8`                          | settled observation                 |
-| FR8 | The Field root isolates every local attached-status paint relationship without assigning the root a page-level z-index.                                                                                                                                      | `spec:AST-027/FR1–FR3`, `FR11`                                         | settled observation                 |
-| FR9 | Attached status is safe only for an opaque, bordered, fixed-height control with reliable size reflection; custom, tall, wrapped, translucent, or non-bordered controls use detached or component-owned placement.                                            | `family:input-fields/FR8`; current default mismatch                    | human decision for released default |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                                                                  |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| FR1 | A single-control label renders as `<label htmlFor={inputID}>`; a group label renders as a non-label element with `labelID` for caller-owned `aria-labelledby`.                                                                                                                                                                                                                                                                                          | Established public interface; HTML and ARIA semantics                  |
+| FR2 | Visually hidden labels and descriptions remain in the DOM and out of layout flow.                                                                                                                                                                                                                                                                                                                                                                       | Established public interface and accessibility behavior                |
+| FR3 | Description and status IDs use explicit values when supplied and otherwise resolve to `${inputID}-desc` and `${inputID}-status` only when text exists.                                                                                                                                                                                                                                                                                                  | Established public interface                                           |
+| FR4 | Error status messages announce assertively and warning/success messages politely through persistent live regions; tooltip placement renders no `FieldStatus` box but preserves the announcement.                                                                                                                                                                                                                                                        | Existing tests; family ownership                                       |
+| FR5 | Ordinary layout orders label, control, then optional status. Horizontal-label mode places the label wrapper before one description/control/status group and reflects `data-layout="horizontal-labels"`; caller props cannot replace that owned theme marker.                                                                                                                                                                                            | Established layout interface; `architecture:public-component-api/INV5` |
+| FR6 | `width` applies to the ordinary root field box; it does not style the caller-owned control and has no box to target in horizontal-label mode.                                                                                                                                                                                                                                                                                                           | Established public interface; `family:input-fields` shared owner       |
+| FR7 | Root ref, data/ARIA/DOM inputs, events, `xstyle`, class name, and inline style reach or compose on the root without replacing component-owned semantics.                                                                                                                                                                                                                                                                                                | `architecture:public-component-api/INV5–INV8`                          |
+| FR8 | The Field root isolates every local attached-status paint relationship without assigning the root a page-level z-index.                                                                                                                                                                                                                                                                                                                                 | `spec:AST-027/FR1–FR3`, `FR11`                                         |
+| FR9 | Field MUST give attached placement only to an opaque, bordered, fixed-height control with reliable size reflection; tall, wrapped, translucent, non-bordered, or otherwise ineligible controls, as custom controls normally are, use detached or component-owned placement. Implementation gap: `statusVariant` defaults to `attached` for every child, so an ineligible control receives attached placement unless the caller chooses otherwise (OQ1). | `family:input-fields/FR8`                                              |
 
 ### Allowed variation
 
@@ -125,11 +124,11 @@ Draft requirements identify their basis so observed code is not mistaken for an
 
 - **ORD1 — Root props.** Caller DOM/data/event props are forwarded first; Field-owned visual-state reflection is applied afterward; StyleX, caller class, and caller inline style compose in the documented order.
 - **ORD2 — IDs.** Explicit description/status ID wins; otherwise text presence derives an ID from `inputID`; absent text produces no ID-bearing element.
-- **ORD3 — Optionality.** FormLayout default optionality suppresses the matching visible marker; if both local booleans are true, Field warns and the optional marker wins visibly.
+- **ORD3 — Optionality.** FormLayout default optionality suppresses the matching visible marker; if both local booleans are true, Field warns and the optional marker wins visibly, unless FormLayout's default is optional, which suppresses it so the required marker shows.
 
 ### Performance and resources
 
-- **PR1 — No per-field global resource.** Field owns no listener, observer, timer, or external store. Status announcement delegates to the shared persistent live-region runtime.
+- **PR1 — No per-field global resource.** Field owns no listener, observer, timer, or external store. Status announcement delegates to the shared persistent live-region runtime, and a `labelTooltip` brings the shared Tooltip's listeners and layer.
 
 ## Accessibility contract
 
@@ -140,11 +139,9 @@ Draft requirements identify their basis so observed code is not mistaken for an
 
 ## Design relationships
 
-| Anatomy or state              | Design requirement                                       | Representation authority                               | Hierarchy role            | Component contract |
-| ----------------------------- | -------------------------------------------------------- | ------------------------------------------------------ | ------------------------- | ------------------ |
-| Label and description         | `design:typography-hierarchy/DR4`, `DR6`                 | prescribed roles; exact tuning remains token-owned     | label and supporting text | FR1–FR3            |
-| Label/control/status grouping | `design:spatial-hierarchy` local and group relationships | prescribed relationship; exact gap remains token-owned | one field group           | FR5                |
-| Semantic status               | `design:system-states/DR2`                               | delegated to FieldStatus and wrapped input             | supporting feedback       | FR4, FR9           |
+No current repository design record governs component-local visual tuning.
+The label, description, and status use shared semantic type, color, and
+spacing tokens.
 
 ### Theming anatomy
 
@@ -193,20 +190,31 @@ The ordinary description remains stable consumer anatomy without a Field-owned t
 
 ## Verification map
 
-| Contract                 | Verification                                                                           | Representative states                                                                                | Mutation or failure expectation                                                                                                | Audit section               |
-| ------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
-| FR1–FR3, AR1–AR2, AR4    | `Field.test.tsx` DOM/accessibility tests                                               | single control, group, visible/hidden label, explicit/generated IDs                                  | A lost association, wrong element, missing hidden text, or wrong ID fails.                                                     | `audit:Field/accessibility` |
-| FR4, AR3                 | `Field.test.tsx` announcement tests plus exact-head browser accessibility evidence     | first mount, update, repeat, error, warning, attached, detached, tooltip                             | A missing, duplicate, stale, or wrong-urgency announcement fails.                                                              | `audit:Field/accessibility` |
-| FR5–FR7, ORD1            | `Field.test.tsx`, BaseProps lint, theming-target tests, and exact-head visual evidence | ordinary/horizontal layout; class/style/xstyle/data/event/ref; description/status                    | Dropped caller input, replaceable layout marker, wrong order, or lost target fails.                                            | `audit:Field/api`           |
-| FR8                      | computed-style tests and exact-head browser rendering                                  | attached, detached, tooltip, no status                                                               | Removing isolation or ranking the root outside its parent fails.                                                               | `audit:Field/code-health`   |
-| FR9                      | family contract review and component-owned visual evidence                             | eligible bordered control; custom/tall/non-bordered control                                          | Attached placement on an ineligible surface remains visible as the current conformance gap.                                    | `audit:Field/behavior`      |
-| Theming anatomy          | knowledge validation and theming-target tests                                          | Field root, label, description, caller control, status, shared input affordances, indicator, tooltip | Missing, duplicate, or wrongly owned dispositions fail.                                                                        | `audit:Field/theming`       |
-| Documentation projection | docs typecheck and prop literal/reference tests                                        | labelIcon; all status placements; anatomy and usage guidance                                         | Docs omit or misstate a public type/literal/owner and validation fails or review rejects it.                                   | `audit:Field/docs`          |
-| RTL applicability        | exact-head RTL audit and verified-N/A registry                                         | all checked-in Field stories and source                                                              | A directional glyph, physical inline placement, order, scroll/drag, overlay, or directional keyboard behavior makes N/A stale. | `audit:Field/i18n-rtl`      |
+| Contract                     | Verification                                                                                                           | Representative states                                                                                | Mutation or failure expectation                                                                                                                                 | Audit section               |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| FR1–FR3, ORD2, AR1, AR2, AR4 | `Field.test.tsx` label-element, group-label, hidden label and description, description-ID, and generated-ID cases      | Single control, group, visible and hidden label, explicit and generated IDs                          | A lost association, wrong element, missing hidden text, or wrong ID fails.                                                                                      | `audit:Field/accessibility` |
+| FR4, AR3                     | `Field.test.tsx` announcement and tooltip-placement cases                                                              | First mount, update, repeat, error, warning, tooltip, no message                                     | A missing, duplicate, stale, or wrong-urgency announcement fails.                                                                                               | `audit:Field/accessibility` |
+| FR5, FR6, ORD1               | `Field.test.tsx` horizontal-labels, width, and narrow-row cases                                                        | Ordinary and horizontal layout; string and number width; narrow row                                  | A replaceable layout marker, wrong grid grouping, or width on the inner control fails. Evidence gap: no test asserts the ordinary label, control, status order. | `audit:Field/layout`        |
+| FR7                          | `Field.test.tsx` ref and horizontal-labels root-props cases                                                            | Ref; class, style, data, and event props in horizontal mode                                          | A dropped ref or caller-replaced layout marker fails. Evidence gap: no test asserts root `xstyle`, class, style, and event props in the ordinary layout.        | `audit:Field/api`           |
+| ORD3                         | `Field.test.tsx` optional, required, and both-set cases; `FormLayout.test.tsx` default-optionality cases through Field | Optional; required; both; form default                                                               | A missing marker, no warning when both are set, or a marker that restates the form default fails.                                                               | `audit:Field/behavior`      |
+| FR8                          | `Field.test.tsx` attached-layer and local-stacking cases                                                               | Attached, no status, custom control                                                                  | Removing isolation or ranking the root outside its parent fails.                                                                                                | `audit:Field/code-health`   |
+| FR9                          | `Field.test.tsx` attached-layer case for a custom control                                                              | Custom control with an attached status                                                               | The test pins the current attached default, so it changes when the FR9 gap closes.                                                                              | `audit:Field/behavior`      |
+| PR1                          | Evidence gap: no test asserts the absence of per-field global resources                                                | —                                                                                                    | —                                                                                                                                                               | `audit:Field/code-health`   |
+| Theming anatomy              | `scripts/check-knowledge.mjs`; `themingTargets.test.ts`                                                                | Field root, label, description, caller control, status, shared input affordances, indicator, tooltip | Invalid dispositions, or a rendered class absent from the documented targets, fails.                                                                            | `audit:Field/theming`       |
+| Documentation projection     | `docPropLiterals.test.ts`; `docPropReferences.test.ts`                                                                 | Status placements, `labelIcon`, and other documented props                                           | A documented literal or prop reference that drifts from the source type fails.                                                                                  | `audit:Field/docs`          |
+| RTL applicability            | `apps/storybook/rtl-audit/verified-not-applicable.json` entry for `core/Field`                                         | Checked-in Field stories                                                                             | A story that gains directional placement or behavior makes the not-applicable entry stale.                                                                      | `audit:Field/i18n-rtl`      |
+
+## Current-state impact
+
+- **Attached default (FR9).** Field defaults `statusVariant` to `attached` for
+  every child, against `family:input-fields/FR8`; how to migrate the default is
+  OQ1.
+- **Label tooltip (FieldLabel FR8).** A `labelTooltip` is reachable only by
+  pointer, as `component:FieldLabel` FR8 records, against WCAG 2.2 SC 2.1.1.
 
 ## Decision log
 
-No component-local decision is asserted. This draft records released behavior and leaves the current family-owned status-placement conflict in OQ1.
+No component-local decision. Field applies `family:input-fields` and `spec:AST-027`.
 
 ## Open questions
 
@@ -214,4 +222,5 @@ No component-local decision is asserted. This draft records released behavior an
 
 ## Content boundary
 
-This draft records verified shipped behavior and the current family-owned conformance gap. It does not approve a new default, migration, theme target, or compatibility promise, and it does not duplicate audit scores or 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/Field.tsx

@@ -29,7 +29,7 @@ import type {IconType} from '../Icon';
 import {mergeProps} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
-import {Text} from '../Text';
+import {Text} from '../Text/Text';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {themeProps} from '../utils/themeProps';