Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
37.4 KB
Raw Blame

schema_version: 3 template_version: 7 kind: component id: component:FieldLabel authority: current archive_reason: null superseded_by: 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/Field/tests/FieldLabelTap.a11y.chromium.spec.ts, packages/core/src/theme/themingTargets.test.ts, packages/core/src/docPropReferences.test.ts, packages/core/src/docPropLiterals.test.ts, apps/storybook/rtl-audit/verified-not-applicable.json, ] modules: [] families: [] design_specs: [] architecture: [ architecture:public-component-api, architecture:component-theming-surface, architecture:component-test-sufficiency, ] contributing: []

system_specs: [spec:AST-020/FR1]

FieldLabel component contract

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. Help behind the info button opens by pointer, touch, keyboard, and screen reader, and a tap, click, or key press on it never changes the control (DEC-1).
Builder impact Builders provide stable control and description IDs, select group mode when labelling a composite, and wire aria-labelledby or aria-describedby on the controlled surface.
Compatibility/readiness No API or default change; with labelTooltip, the info trigger is an InfoTip button after the label element, and a mouse click on it does not activate the control (FR9, DEC-1). Group mode renders a span while public types promise label props and ref; it is listed under Current-state impact.
Review checks Reject a lost native/group association, nested description in the accessible name, forwarded clicks from group or interactive description content, dropped label-element props/ref, hidden tooltip content, an info trigger inside the label element or one whose press activates the control, or undocumented public prop.
Governing rules Established public interface; HTML label semantics; WCAG 2.2 SC 2.1.1, SC 4.1.2; component:InfoTip; architecture:public-component-api/INV1,INV5–INV9,INV12; architecture:component-theming-surface/INV3–INV7; spec:AST-020/FR1.

This table is a review projection; the body below is authoritative.

Intent

FieldLabel supplies the shared label, description, optionality, icon, and tooltip presentation used by Field and labeled controls such as CheckboxInput and Switch. It owns the label group only; the associated control or group owns value and interaction behavior.

Compatibility and migration

  • Released default preserved: yes.
  • Compatibility class: no public prop, default, or export change. With labelTooltip, the info trigger moves from an icon inside the label element to a component:InfoTip button after it, in one inline-flex row wrapping both, and a press on it, by any pointer or key, does not activate the control (FR9, DEC-1). Callers see that extra wrapper only when labelTooltip is set; their class, xstyle, and ref stay on the label element (FR6).
  • Controlled/uncontrolled behavior: not applicable.
  • Migration decision: DEC-1 needs no caller change; the ref typing is OQ1.

Ownership boundary

Owns

  • Native single-control and non-label group-label element selection.
  • Visible and visually hidden label and description presentation.
  • Optional/required exception indicators from FormLayout optionality context.
  • Safe description-click forwarding for one associated control.
  • The field-label theme target and composition of caller props, styles, and ref on the label element.
  • Whether the optional tooltip trigger is reachable and named for every input modality and assistive-technology path.

Does not own / non-goals

  • 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.
  • The info trigger, its press toggle, and the tooltip surface, which delegate to component:InfoTip and through it to component:Tooltip; FieldLabel owns where the trigger renders, its name, and that its content is exposed.

Public concepts

Concept Closed values or states Meaning Availability by variant/orientation/state Default Owner Stability Invalid-value behavior
label mode single control; group Chooses a native <label htmlFor> or a <span> referenced through aria-labelledby. All uses. single control component:FieldLabel released Boolean-constrained; see OQ1 for root/ref typing.
label visibility visible; visually hidden Keeps label and description accessible while removing their layout space when hidden. Both label modes. visible component:FieldLabel released Boolean-constrained.
optionality marker none; optional; required Shows the localized exception to FormLayout's form-level optionality default. Visible and hidden labels. none component:FieldLabel released When both booleans are true, optional wins visibly, unless FormLayout's default is optional, which suppresses it and shows required.
leading icon absent; icon type; rendered node Adds visual content before the label text. Both label modes. absent component:FieldLabel released Rendered through the shared icon slot.
explanatory tooltip absent; localized string Adds a component:InfoTip after the label element; a tap, click, or key press on it opens or closes the tooltip without activating the control (FR9). Both label modes. absent component:FieldLabel released —
supporting description absent; rendered node with optional explicit ID Keeps supporting content separate from the accessible name and available for description. Both label modes. absent component:FieldLabel released Missing ID leaves association to the caller.
description activation forwarding; non-forwarding For one control, noninteractive description clicks mirror native-label activation. Single mode only. forwarding component:FieldLabel released Group mode and interactive descendants do not forward.

Behavioral and layout contract

ID Invariant Basis
FR1 Single-control mode renders <label htmlFor={inputID}>; group mode renders a non-label element with labelID for caller-owned aria-labelledby. Established public interface; HTML and ARIA semantics
FR2 Visible and hidden labels retain the label text; hidden label and description boxes remain in the accessibility tree and leave no layout slot. Established public interface
FR3 Descriptions remain siblings of the label so they do not enter the control's accessible name. Noninteractive description clicks forward to one eligible control; group labels and interactive descendants do not forward activation. Established public interface; native label behavior
FR4 FormLayout optionality suppresses the matching visible marker; without a form default, the requested marker is localized and shown. When both flags are true, optional wins, except inside a FormLayout whose default is optional, where the optional marker is suppressed and the required marker shows. Established public interface and current tests
FR5 Label icons, tooltip anchors, required/optional text, and description content preserve source order. The label element uses a horizontal flex row; the optional label/description wrapper uses block flow. With labelTooltip, one inline-flex row wraps the label element and the InfoTip that follows it (FR9). All component-owned spacing is logical or direction-neutral. Established public interface and source observation
FR6 Accepted data, ARIA, DOM, class, style, event, and xstyle inputs compose on the label element without replacing the component-owned target or association. When a description renders, the outer wrapper is layout-only and caller props stay on the inner label element; the labelTooltip row (FR9) is layout-only in the same way, so caller class, xstyle, and ref stay on the label element. architecture:public-component-api/INV5–INV7
FR7 The public ref and label-element props MUST describe the element FieldLabel renders in each mode; which root element and public type group mode uses is OQ1. Implementation gap: group mode renders a <span> while the public BaseProps and ref types are fixed to HTMLLabelElement. architecture:public-component-api/INV8,INV9; current runtime/types
FR8 The optional tooltip's explanatory content MUST be reachable by keyboard (WCAG 2.2 SC 2.1.1) and its trigger MUST have an accessible name and role (WCAG 2.2 SC 4.1.2); FR9's InfoTip button meets both. WCAG 2.2 SC 2.1.1, SC 4.1.2; spec:AST-020/FR1
FR9 With labelTooltip, FieldLabel renders component:InfoTip with that content after the label element and outside it, and wraps the label element and the InfoTip in one inline-flex row, as it wraps the label and description, so no button sits inside a <label>; caller class, xstyle, and ref stay on the label element, and the row renders only when labelTooltip is set. With isLabelHidden, the InfoTip is visually hidden with the label, leaves no layout slot (FR2), and while it has keyboard focus, the button takes its place in flow above the control (or in the label cell with horizontal labels), so it is never covered or clipped (WCAG 2.4.7, 2.4.11); the button's name is a localized string that includes the label text ("About Auto-save"). A tap, click, Enter, or Space on the info trigger opens or closes the tooltip (component:Tooltip FR9) and never activates, focuses, or toggles the associated control; hover and focus preview it. DEC-1; HTML label content model; WCAG 2.2 SC 2.1.1, SC 2.4.7, SC 4.1.2

Allowed variation

  • AV1 — Parent layout. Field, CheckboxInput, Switch, and direct consumers may arrange the label group differently without changing its local semantics.
  • AV2 — Label content. Icon, tooltip, optionality text, and description content may be absent independently.
  • AV3 — Control kind. Description activation follows the associated native or custom control's supported click/focus behavior.

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 InfoTip render their owned paint; the InfoTip button follows the label element, is keyboard-reachable and named, and its press never reaches the control (FR8, FR9). Either slot may be absent.

Transformation and precedence order

  • ORD1 — Optionality. The FormLayout default suppresses its matching marker first; then optional wins when both local booleans are true.
  • ORD2 — Label-element composition. Component target and base styles apply before caller xstyle, class, and inline style composition on the label element; association and label-element choice remain component-owned. An optional description, or a labelTooltip row (FR9), adds a layout wrapper without retargeting those inputs.

Performance and resources

  • PR1 — No retained resource. FieldLabel owns no global listener, observer, timer, or external store. Description activation reuses the shared input-container hook with local refs, and a labelTooltip brings InfoTip's, and so Tooltip's, listeners and layer.

Accessibility contract

  • AR1 — Label association. Single controls use native label association; grouped controls use a caller-wired labelled span and never a misleading literal label.
  • 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. Tooltip content MUST be reachable by keyboard (WCAG 2.2 SC 2.1.1) through a named trigger (SC 4.1.2), the InfoTip button that follows the label (FR8, FR9).

Design relationships

No current repository design record governs component-local visual tuning. The implementation uses shared semantic type, color, spacing, and disabled tokens; rendered evidence records the resulting states without turning them into policy.

Family and system relationships

  • architecture:public-component-api owns exports, label-element prop composition, ref accuracy, and released API compatibility.
  • architecture:component-theming-surface owns the anatomy-to-target disposition and target composition.
  • architecture:component-test-sufficiency owns bounded, mutation-sensitive evidence for each critical established public seam.

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
FR1–FR3, AR1–AR4 FieldLabel.test.tsx association, ref, and description-forwarding cases; FieldLabelAudit.a11y.chromium.spec.ts default, custom-theme, RTL, and narrow cases in light and dark Single, group, description, interactive description child A wrong label element, lost association, nested description, or forwarded group or interactive click fails. Evidence gap: no test asserts the hidden label and description leave no layout slot. audit:FieldLabel/accessibility
FR4, ORD1 FieldLabel.test.tsx optional, required, both-set, and i18n cases; FormLayout.test.tsx default-optionality cases through Field Optional, required, both, localized A wrong localized marker, required winning over optional, or a marker that restates the form default fails. audit:FieldLabel/behavior
FR5 FieldLabel.test.tsx label-icon, info-button placement, 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 or with the labelTooltip row. audit:FieldLabel/api
FR7 Evidence gap: no type test pins the public ref and props against the rendered group span — — audit:FieldLabel/api
FR8, AR5 FieldLabelAudit.a11y.chromium.spec.ts tooltip-anchor count Tooltip present The audit asserts one named, focusable InfoTip button after the label element and outside it; an anonymous, unfocusable, or label-nested trigger fails. audit:FieldLabel/accessibility
FR9 FieldLabel.test.tsx info-button placement and name, hidden-label tab stop, finger-tap, pen-tap, mouse-click, and Space checkbox cases and the Switch-label click case; FieldLabelTap.a11y.chromium.spec.ts touch-tap, mouse-click, and Enter text-field cases and the hidden label's focused button on top of the field; evidence gap: no check measures that the hidden label's button takes no layout slot Checkbox, text field, and Switch labels; finger, pen, mouse, Enter, and Space; isLabelHidden with keyboard focus on the InfoTip A tap, click, or key press on the info trigger that activates, focuses, or toggles the control, an info button inside the label element, a trigger without the label in its name, or a hidden label's InfoTip that takes layout space or stays invisible while focused fails. audit:FieldLabel/accessibility
PR1 Evidence gap: no test asserts the absence of retained resources — — audit:FieldLabel/code-health
Documentation docPropLiterals.test.ts; docPropReferences.test.ts Documented props and defaults A documented literal or prop reference that drifts from the source type fails. audit:FieldLabel/docs
RTL applicability apps/storybook/rtl-audit/verified-not-applicable.json entry for core/FieldLabel Checked-in FieldLabel stories A story that gains directional placement or behavior makes the not-applicable entry stale. audit:FieldLabel/i18n-rtl

Current-state impact

  • 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.

Decision log

  • DEC-1 — A press on the info trigger is for its help. A tap, click, Enter, or Space on the label's info trigger opens or closes the help and never activates the label's control, so asking what a setting does never toggles a switch or focuses a field, for any pointer or key. The trigger is component:InfoTip, the info-icon preset over Tooltip's press toggle, after the label element, because a <label> may contain no control other than the one it labels. Rejected: leaving the tap, or a mouse click, to the label.

The label-element and ref typing is OQ1.

Open questions

  • OQ1 — Should isGroupLabel expose a discriminated span-root BaseProps/ref contract, or should FieldLabel use one root element whose public type is stable in both modes? (human-api)

Content boundary

This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.