Skip to content

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.md
index 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: 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.
diff --git a/packages/core/src/Field/FieldLabel.spec.md b/packages/core/src/Field/FieldLabel.spec.md
index 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: 3
template_version: 7
kind: component
id: component:FieldLabel
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-28
owners: [cixzhang]
review_triggers: [public-api, behavior, layout, theming, accessibility]
verified_by:
[
packages/core/src/Field/FieldLabel.test.tsx,
+ packages/core/src/FormLayout/FormLayout.test.tsx,
packages/core/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts,
packages/core/src/theme/themingTargets.test.ts,
packages/core/src/docPropReferences.test.ts,
packages/core/src/docPropLiterals.test.ts,
+ apps/storybook/rtl-audit/verified-not-applicable.json,
]
modules: []
families: []
@@ -35,15 +37,15 @@ system_specs: [spec:AST-020/FR1]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `FieldLabel` renders a visible or visually hidden label group for one control or a caller-labelled group, with optional description, optionality indicator, icon, tooltip, label-element BaseProps, and label-element ref. |
-| Behavior | Single-control mode uses a native label; group mode uses a labelled span. A description adds a wrapper div, while caller props and ref stay on the inner label element. Description clicks forward only to one associated control. |
-| End-user impact | People can identify a control or group, hear supporting text separately from its name, and activate eligible controls from the complete visible label area. The current tooltip remains unavailable to keyboard and screen-reader users. |
-| Builder impact | Builders provide stable control and description IDs, select group mode when labelling a composite, and wire `aria-labelledby` or `aria-describedby` on the controlled surface. |
-| Compatibility/readiness | This draft records released behavior and changes no API. Two gaps remain: group mode renders a span while public types promise label props/ref, and the anonymous tooltip icon exposes its content only to a pointer. |
-| Review checks | Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, or undocumented public prop. |
-| Governing rules | Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1; `architecture:public-component-api/INV1,INV5–INV9,INV12`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR1`. |
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `FieldLabel` renders a visible or visually hidden label group for one control or a caller-labelled group, with optional description, optionality indicator, icon, tooltip, label-element BaseProps, and label-element ref. |
+| Behavior | Single-control mode uses a native label; group mode uses a labelled span. A description adds a wrapper div, while caller props and ref stay on the inner label element. Description clicks forward only to one associated control. |
+| End-user impact | People can identify a control or group, hear supporting text separately from its name, and activate eligible controls from the complete visible label area. The current tooltip remains unavailable to keyboard and screen-reader users. |
+| Builder impact | Builders provide stable control and description IDs, select group mode when labelling a composite, and wire `aria-labelledby` or `aria-describedby` on the controlled surface. |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Group mode renders a span while public types promise label props and ref, and the tooltip icon exposes its content only to a pointer; both are listed under Current-state impact. |
+| Review checks | Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, or undocumented public prop. |
+| Governing rules | Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1, SC 4.1.2; `architecture:public-component-api/INV1,INV5–INV9,INV12`; `architecture:component-theming-surface/INV3–INV7`; `spec:AST-020/FR1`. |
This table is a review projection; the body below is authoritative.
@@ -54,9 +56,9 @@ This table is a review projection; the body below is authoritative.
## Compatibility and migration
- Released default preserved: yes.
-- Compatibility class: observational only; this draft changes no public prop, default, or behavior.
+- Compatibility class: records shipped behavior; no public prop, default, export, or DOM change.
- Controlled/uncontrolled behavior: not applicable.
-- Migration decision: none; OQ1 requires a separate public-type decision. The tooltip accessibility defect remains open.
+- Migration decision: none; the ref typing is OQ1.
## Ownership boundary
@@ -73,34 +75,32 @@ This table is a review projection; the body below is authoritative.
- The associated control or group's value, disabled semantics, focus model, keyboard behavior, and ARIA wiring beyond the label's own IDs.
- The caller's layout around the label group.
-- Tooltip surface behavior and icon rendering, which delegate to `component:Tooltip` and `component:Icon`; FieldLabel still owns whether its chosen trigger exposes that content.
+- Tooltip surface behavior and icon rendering, which delegate to Tooltip and `component:Icon`; FieldLabel still owns whether its chosen trigger exposes that content.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ---------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ---------------------- | ------------------------- | ------------------------------------------------------------------------- |
-| label mode | single control; group | Chooses a native `<label htmlFor>` or a `<span>` referenced through `aria-labelledby`. | All uses. | single control | `component:FieldLabel` | released | Boolean-constrained; see OQ1 for root/ref typing. |
-| label visibility | visible; visually hidden | Keeps label and description accessible while removing their layout space when hidden. | Both label modes. | visible | `component:FieldLabel` | released | Boolean-constrained. |
-| optionality marker | none; optional; required | Shows the localized exception to FormLayout's form-level optionality default. | Visible and hidden labels. | none | `component:FieldLabel` | released | When both booleans are true, optional wins visibly. |
-| leading icon | absent; icon type; rendered node | Adds visual content before the label text. | Both label modes. | absent | `component:FieldLabel` | released | Rendered through the shared icon slot. |
-| explanatory tooltip | absent; localized string | Adds the shared info-icon anchor and tooltip surface after the label. | Both label modes. | absent | `component:FieldLabel` | released; conformance gap | The current anonymous, nonfocusable icon leaves the content pointer-only. |
-| supporting description | absent; rendered node with optional explicit ID | Keeps supporting content separate from the accessible name and available for description. | Both label modes. | absent | `component:FieldLabel` | released | Missing ID leaves association to the caller. |
-| description activation | forwarding; non-forwarding | For one control, noninteractive description clicks mirror native-label activation. | Single mode only. | forwarding | `component:FieldLabel` | released | Group mode and interactive descendants do not forward. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| label mode | single control; group | Chooses a native `<label htmlFor>` or a `<span>` referenced through `aria-labelledby`. | All uses. | single control | `component:FieldLabel` | released | Boolean-constrained; see OQ1 for root/ref typing. |
+| label visibility | visible; visually hidden | Keeps label and description accessible while removing their layout space when hidden. | Both label modes. | visible | `component:FieldLabel` | released | Boolean-constrained. |
+| optionality marker | none; optional; required | Shows the localized exception to FormLayout's form-level optionality default. | Visible and hidden labels. | none | `component:FieldLabel` | released | When both booleans are true, optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required. |
+| leading icon | absent; icon type; rendered node | Adds visual content before the label text. | Both label modes. | absent | `component:FieldLabel` | released | Rendered through the shared icon slot. |
+| explanatory tooltip | absent; localized string | Adds the shared info-icon anchor and tooltip surface after the label. | Both label modes. | absent | `component:FieldLabel` | released | The anchor is pointer-only (FR8 gap). |
+| supporting description | absent; rendered node with optional explicit ID | Keeps supporting content separate from the accessible name and available for description. | Both label modes. | absent | `component:FieldLabel` | released | Missing ID leaves association to the caller. |
+| description activation | forwarding; non-forwarding | For one control, noninteractive description clicks mirror native-label activation. | Single mode only. | forwarding | `component:FieldLabel` | released | Group mode and interactive descendants do not forward. |
## Behavioral and layout contract
-Draft requirements identify their basis so observed code is not mistaken for an intentional decision.
-
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------- |
-| FR1 | Single-control mode renders `<label htmlFor={inputID}>`; group mode renders a non-label element with `labelID` for caller-owned `aria-labelledby`. | Established public interface; HTML and ARIA semantics | settled observation |
-| FR2 | Visible and hidden labels retain the label text; hidden label and description boxes remain in the accessibility tree and leave no layout slot. | Established public interface | settled observation |
-| FR3 | Descriptions remain siblings of the label so they do not enter the control's accessible name. Noninteractive description clicks forward to one eligible control; group labels and interactive descendants do not forward activation. | Established public interface; native label behavior | settled observation |
-| FR4 | FormLayout optionality suppresses the matching visible marker; without a form default, the requested marker is localized and shown. When both flags are true, optional wins. | Established public interface and current tests | settled observation |
-| FR5 | Label icons, tooltip anchors, required/optional text, and description content preserve source order. The label element uses a horizontal flex row; the optional label/description wrapper uses block flow. All component-owned spacing is logical or direction-neutral. | Established public interface and source observation | settled observation |
-| FR6 | Accepted data, ARIA, DOM, class, style, event, and `xstyle` inputs compose on the label element without replacing the component-owned target or association. When a description renders, the outer wrapper is layout-only and caller props stay on the inner label element. | `architecture:public-component-api/INV5–INV7` | settled observation for single mode |
-| FR7 | The public ref reaches the label element. Group mode currently renders a span while the public BaseProps/ref type is fixed to `HTMLLabelElement`. | `architecture:public-component-api/INV8,INV9`; current runtime/types | human decision (OQ1) |
-| FR8 | The optional tooltip currently anchors to an anonymous, nonfocusable info icon, so its explanatory content is unavailable by keyboard and is not announced with the associated field. | WCAG 2.2 SC 2.1.1; `spec:AST-020/FR1`; current runtime | objective conformance gap |
+| ID | Invariant | Basis |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| FR1 | Single-control mode renders `<label htmlFor={inputID}>`; group mode renders a non-label element with `labelID` for caller-owned `aria-labelledby`. | Established public interface; HTML and ARIA semantics |
+| FR2 | Visible and hidden labels retain the label text; hidden label and description boxes remain in the accessibility tree and leave no layout slot. | Established public interface |
+| FR3 | Descriptions remain siblings of the label so they do not enter the control's accessible name. Noninteractive description clicks forward to one eligible control; group labels and interactive descendants do not forward activation. | Established public interface; native label behavior |
+| FR4 | FormLayout optionality suppresses the matching visible marker; without a form default, the requested marker is localized and shown. When both flags are true, optional wins, except inside a FormLayout whose default is optional, where the optional marker is suppressed and the required marker shows. | Established public interface and current tests |
+| FR5 | Label icons, tooltip anchors, required/optional text, and description content preserve source order. The label element uses a horizontal flex row; the optional label/description wrapper uses block flow. All component-owned spacing is logical or direction-neutral. | Established public interface and source observation |
+| FR6 | Accepted data, ARIA, DOM, class, style, event, and `xstyle` inputs compose on the label element without replacing the component-owned target or association. When a description renders, the outer wrapper is layout-only and caller props stay on the inner label element. | `architecture:public-component-api/INV5–INV7` |
+| FR7 | The public ref and label-element props MUST describe the element FieldLabel renders in each mode; which root element and public type group mode uses is OQ1. Implementation gap: group mode renders a `<span>` while the public BaseProps and ref types are fixed to `HTMLLabelElement`. | `architecture:public-component-api/INV8,INV9`; current runtime/types |
+| FR8 | The optional tooltip's explanatory content MUST be reachable by keyboard (WCAG 2.2 SC 2.1.1) and its trigger MUST have an accessible name and role (WCAG 2.2 SC 4.1.2). Implementation gap: it anchors to an anonymous, nonfocusable info icon, so the content is pointer-only. | WCAG 2.2 SC 2.1.1, SC 4.1.2; `spec:AST-020/FR1` |
### Allowed variation
@@ -110,23 +110,23 @@ Draft requirements identify their basis so observed code is not mistaken for an
### Representative states
-| State | Required invariant | Allowed variation |
-| --------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| single label | Native label association reaches the one control. | Visible or visually hidden. |
-| group label | Label element is not a literal label and is referenceable by `labelID`. | Caller owns group role and `aria-labelledby`. |
-| description | Supporting content remains outside the label and may expose `descriptionID`. | Text or structured content. |
-| optional or required | One localized exception marker follows label text. | Suppressed when it matches FormLayout's default. |
-| disabled presentation | Label uses disabled text treatment and no pointer cursor. | Associated control owns actual disabled state. |
-| icon and tooltip | Shared Icon and Tooltip render their owned paint; the current tooltip anchor remains nonfocusable and unnamed. | Either slot may be absent. |
+| State | Required invariant | Allowed variation |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
+| single label | Native label association reaches the one control. | Visible or visually hidden. |
+| group label | Label element is not a literal label and is referenceable by `labelID`. | Caller owns group role and `aria-labelledby`. |
+| description | Supporting content remains outside the label and may expose `descriptionID`. | Text or structured content. |
+| optional or required | One localized exception marker follows label text. | Suppressed when it matches FormLayout's default. |
+| disabled presentation | Label uses disabled text treatment and no pointer cursor. | Associated control owns actual disabled state. |
+| icon and tooltip | Shared Icon and Tooltip render their owned paint; the tooltip trigger is keyboard-reachable and named (FR8). Implementation gap: the anchor is nonfocusable and unnamed. | Either slot may be absent. |
### Transformation and precedence order
-- **ORD1 — Optionality.** Optional wins when both local booleans are true; otherwise the FormLayout default suppresses its matching marker.
+- **ORD1 — Optionality.** The FormLayout default suppresses its matching marker first; then optional wins when both local booleans are true.
- **ORD2 — Label-element composition.** Component target and base styles apply before caller `xstyle`, class, and inline style composition on the label element; association and label-element choice remain component-owned. An optional description adds a layout wrapper without retargeting those inputs.
### Performance and resources
-- **PR1 — No retained resource.** FieldLabel owns no global listener, observer, timer, or external store. Description activation reuses the shared input-container hook with local refs.
+- **PR1 — No retained resource.** FieldLabel owns no global listener, observer, timer, or external store. Description activation reuses the shared input-container hook with local refs, and a `labelTooltip` brings the shared Tooltip's listeners and layer.
## Accessibility contract
@@ -134,7 +134,8 @@ Draft requirements identify their basis so observed code is not mistaken for an
- **AR2 — Description separation.** Description content stays outside the label so it is not duplicated in the accessible name and exposes an ID for caller-owned `aria-describedby`.
- **AR3 — Hidden labels.** Visually hidden label and description content remain programmatically available.
- **AR4 — Activation boundary.** Description activation never hijacks interactive descendants and never forwards from a group label to one control.
-- **AR5 — Tooltip reachability.** The current anonymous, nonfocusable tooltip anchor does not expose its explanatory content to keyboard or screen-reader users; this remains an objective conformance gap.
+- **AR5 — Tooltip reachability.** Tooltip content MUST be reachable by keyboard
+ (WCAG 2.2 SC 2.1.1) through a named trigger (SC 4.1.2) (FR8). Implementation gap: the anonymous, nonfocusable anchor exposes it only to a pointer.
## Design relationships
@@ -148,20 +149,29 @@ No current repository design record governs component-local visual tuning. The i
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| -------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| FR1–FR3, AR1–AR4 | `FieldLabel.test.tsx` plus exact-head axe and Chromium sensor receipts | single, group, description, hidden, interactive description child | Wrong label element, lost association, nested description, missing hidden text, or forwarded group/interactive click fails. | `audit:FieldLabel/accessibility` |
-| FR4–FR5, ORD1 | focused DOM tests, i18n catalog checks, and exact-head light/dark/custom-theme frames | optional, required, both, form default, icon, tooltip, disabled | Wrong localized marker, order, visibility, or tokenized state is exposed. | `audit:FieldLabel/behavior` |
-| FR6, ORD2 | BaseProps lint, focused composition tests, theming-target tests, and browser target inventory | class, style, xstyle, data, event, target; with and without description wrapper | Consumer input is dropped, retargeted to the wrapper, or the `field-label` target disappears. | `audit:FieldLabel/api` |
-| FR7 | Public type review against the runtime single-label and group-span branches | single label; group span | Public ref/prop types claim a different label element than runtime. | `audit:FieldLabel/api` |
-| FR8, AR5 | focused source/DOM review plus exact-head sensor receipt for the tooltip anchor | tooltip absent; tooltip present | The known anonymous, nonfocusable anchor disappears from the audit record before an accessible path replaces it. | `audit:FieldLabel/accessibility` |
-| Documentation | docs typecheck, CLI readback, prop-literal/reference tests, and knowledge validation | every public prop and default | Docs omit or misstate a public input or default. | `audit:FieldLabel/docs` |
-| RTL applicability | source/story inspection and verified-N/A registry | all component-owned states | A directional glyph, physical inline property, inline-side placement, order, scroll/drag, inline-side overlay placement, or horizontal arrow key makes N/A stale. | `audit:FieldLabel/i18n-rtl` |
-| Responsive rendering | exact-head 320px Chromium sensor receipts | visible, hidden, description, group, optionality, icon, tooltip | The story overflows horizontally or a visible/hidden label loses its relationship. | `audit:FieldLabel/responsive` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1–FR3, AR1–AR4 | `FieldLabel.test.tsx` association, ref, and description-forwarding cases; `FieldLabelAudit.a11y.chromium.spec.ts` default, custom-theme, RTL, and narrow cases in light and dark | Single, group, description, interactive description child | A wrong label element, lost association, nested description, or forwarded group or interactive click fails. Evidence gap: no test asserts the hidden label and description leave no layout slot. | `audit:FieldLabel/accessibility` |
+| FR4, ORD1 | `FieldLabel.test.tsx` optional, required, both-set, and i18n cases; `FormLayout.test.tsx` default-optionality cases through Field | Optional, required, both, localized | A wrong localized marker, required winning over optional, or a marker that restates the form default fails. | `audit:FieldLabel/behavior` |
+| FR5 | `FieldLabel.test.tsx` label-icon, tooltip, and tooltip-with-optional cases | Icon, tooltip, optionality | A missing icon or tooltip anchor fails. Evidence gap: no test asserts source order, the flex row, or logical spacing. | `audit:FieldLabel/layout` |
+| FR6, ORD2 | `FieldLabel.test.tsx` ref, layout-item, and label-target cases; `themingTargets.test.ts` | Ref; composed target; with a description wrapper | A dropped ref or a lost `field-label` target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts caller class, style, `xstyle`, data, and event props on the inner label element with a description wrapper. | `audit:FieldLabel/api` |
+| FR7 | Evidence gap: no type test pins the public ref and props against the rendered group span | — | — | `audit:FieldLabel/api` |
+| FR8, AR5 | `FieldLabelAudit.a11y.chromium.spec.ts` tooltip-anchor count | Tooltip present | The audit records the one anonymous, nonfocusable anchor; it changes when the FR8 gap closes. | `audit:FieldLabel/accessibility` |
+| PR1 | Evidence gap: no test asserts the absence of retained resources | — | — | `audit:FieldLabel/code-health` |
+| Documentation | `docPropLiterals.test.ts`; `docPropReferences.test.ts` | Documented props and defaults | A documented literal or prop reference that drifts from the source type fails. | `audit:FieldLabel/docs` |
+| RTL applicability | `apps/storybook/rtl-audit/verified-not-applicable.json` entry for `core/FieldLabel` | Checked-in FieldLabel stories | A story that gains directional placement or behavior makes the not-applicable entry stale. | `audit:FieldLabel/i18n-rtl` |
+
+## Current-state impact
+
+- **Group-mode typing (FR7).** Group mode renders a `<span>` while the public
+ props and ref are typed for `HTMLLabelElement`, against
+ `architecture:public-component-api` INV8 and INV9; the fix is OQ1.
+- **Tooltip reachability (FR8, AR5).** The label tooltip is pointer-only,
+ against WCAG 2.2 SC 2.1.1 and 4.1.2.
## Decision log
-No component-local decision is asserted. This draft records shipped behavior, retains the objective tooltip-accessibility gap, and leaves the polymorphic label-element/ref contract in OQ1.
+No component-local decision. The label-element and ref typing is OQ1.
## Open questions
@@ -169,4 +179,5 @@ No component-local decision is asserted. This draft records shipped behavior, re
## Content boundary
-This draft records verified shipped behavior, the objective tooltip-accessibility gap, and the released label-element type/runtime mismatch. It does not choose a ref migration, add a theme target, duplicate consumer prop tables, or store audit scores and run evidence.
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.