An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): Field records its shipped contract as current (#8809)
Cindy Zhang75fa3c9ea3e6
diff --git a/packages/core/src/Field/Field.spec.md b/packages/core/src/Field/Field.spec.mdindex 6dfcd16fb7..46ff575a47 100644--- a/packages/core/src/Field/Field.spec.md+++ b/packages/core/src/Field/Field.spec.md@@ -3,24 +3,25 @@ schema_version: 3template_version: 7kind: componentid: component:Field-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-28owners: [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.diff --git a/packages/core/src/Field/FieldLabel.spec.md b/packages/core/src/Field/FieldLabel.spec.mdindex 286ee234c7..48b84addf7 100644--- a/packages/core/src/Field/FieldLabel.spec.md+++ b/packages/core/src/Field/FieldLabel.spec.md@@ -3,20 +3,22 @@ schema_version: 3template_version: 7kind: componentid: component:FieldLabel-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-28owners: [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.