Skip to content

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

TypeScript

docs(FieldLabel): expose complete label contract (#7727)

Cindy Zhang0da784d3cc59
diff --git a/.changeset/field-label-audit-docs.md b/.changeset/field-label-audit-docs.md
new file mode 100644
index 0000000000..d4a5948fa2
--- /dev/null
+++ b/.changeset/field-label-audit-docs.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] Document FieldLabel's complete public prop surface, group-label semantics, and supporting descriptions.
+
+@cixzhang
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9bb0ea446d..a267826ad8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2435,6 +2435,37 @@ jobs:
retention-days: 30
if-no-files-found: error
+ # FieldLabel owns native and group labelling, hidden text, optionality,
+ # descriptions, and delegated icon/tooltip presentation. Its audit lane
+ # keeps those states bound to exact-head themes, direction, and viewport.
+ - name: Run FieldLabel audit browser evidence
+ if: ${{ !cancelled() && github.event_name == 'pull_request' && startsWith(github.event.pull_request.title, '[Component Audit] FieldLabel:') }}
+ env:
+ ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+ run: |
+ status=0
+ node .github/scripts/accessibility-audit.js \
+ --storybook-dir apps/storybook/dist \
+ --output field-label-a11y-report.json \
+ --components FieldLabel \
+ --baseline .github/a11y-baseline.json \
+ --fail-on-new || status=1
+ pnpm exec playwright test \
+ packages/core/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts \
+ --project chromium || status=1
+ exit "$status"
+
+ - name: Upload FieldLabel audit evidence
+ if: always() && github.event_name == 'pull_request' && startsWith(github.event.pull_request.title, '[Component Audit] FieldLabel:')
+ uses: actions/upload-artifact@v7
+ with:
+ name: field-label-audit-evidence-${{ needs.build-storybook.outputs.short_hash }}
+ path: |
+ field-label-a11y-report.json
+ field-label-audit-evidence/
+ retention-days: 30
+ if-no-files-found: error
+
# Component-owned metadata fixtures retain exact-head browser receipts on
# audit PRs, including failed pre-fix cases for before/after comparison.
- name: Run ChatMessageMetadata audit browser evidence
diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index 7e60aa5a9b..d924ddd116 100644
--- a/apps/storybook/rtl-audit/verified-not-applicable.json
+++ b/apps/storybook/rtl-audit/verified-not-applicable.json
@@ -16,6 +16,15 @@
"component": "core/Field",
"reason": "The Core/Field stories use block-flow labels, controls, descriptions, and status text without directional icons, side-specific placement, order, scrolling, dragging, overlays, or keyboard behavior."
},
+ {
+ "component": "core/FieldLabel",
+ "reason": "FieldLabel owns a horizontal flex label row inside an optional block-flow label/description group. Inline spacing and hidden positioning use logical or direction-neutral properties. Its built-in info icon is radially symmetric and its tooltip uses block-axis placement above the label; caller-supplied label icons retain caller ownership. The component has no side-specific placement, reordering, horizontal scroll or drag action, or horizontal keyboard behavior. The exact-head story covers native, group, hidden, description, optionality, disabled, icon, and tooltip-trigger states without adding a component-owned RTL dimension.",
+ "evidence": {
+ "apps/storybook/stories/FieldLabel.stories.tsx": "sha256:22ea61ef92c7242241fe49715714e2802592534c9466c42a3f3787773e176d0c",
+ "packages/core/src/Field/FieldLabel.tsx": "sha256:e1473a8a0d255536bab7719342cf27a1dbcfbf6792f00782f4ca1606abb28ff0",
+ "packages/core/src/Field/index.ts": "sha256:4e7788b82f7987a991ac62a1f519989027abb639353a1da3884dd9e2a09e98f4"
+ }
+ },
{
"component": "core/EmptyState",
"reason": "EmptyState is a centered block-flow status region. Its icon, text group, and action group stack only on the block axis; spacing is block-axis or logical, and text is centered. The component owns no directional glyph, contextual separator, side-specific placement or ordering, horizontal scrolling or dragging, overlay, or directional keyboard behavior. Caller-supplied icons and action controls retain their own RTL ownership."
diff --git a/apps/storybook/stories/FieldLabel.stories.tsx b/apps/storybook/stories/FieldLabel.stories.tsx
new file mode 100644
index 0000000000..cac2c17692
--- /dev/null
+++ b/apps/storybook/stories/FieldLabel.stories.tsx
@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {FieldLabel} from '@astryxdesign/core/Field';
+import {Icon} from '@astryxdesign/core/Icon';
+
+const meta: Meta<typeof FieldLabel> = {
+ title: 'Core/FieldLabel',
+ component: FieldLabel,
+ tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof FieldLabel>;
+
+const groupStyle = {
+ display: 'grid',
+ gap: 6,
+};
+
+/**
+ * One bounded fixture for every component-owned FieldLabel state. The associated
+ * controls make label, group, hidden-label, and description semantics observable
+ * without turning each prop into a permanent story.
+ */
+export const States: Story = {
+ render: () => (
+ <div style={{display: 'grid', gap: 24, maxWidth: 480}}>
+ <div style={groupStyle}>
+ <FieldLabel label="Email" inputID="field-label-default" />
+ <input id="field-label-default" defaultValue="[email protected]" />
+ </div>
+
+ <div style={groupStyle}>
+ <FieldLabel
+ label="Workspace"
+ inputID="field-label-description"
+ description="Shown in navigation and invitations."
+ descriptionID="field-label-description-help"
+ />
+ <input
+ id="field-label-description"
+ aria-describedby="field-label-description-help"
+ />
+ </div>
+
+ <div style={groupStyle}>
+ <FieldLabel
+ label="Owner"
+ inputID="field-label-required"
+ isRequired
+ labelIcon={<Icon icon="info" />}
+ />
+ <input id="field-label-required" required />
+ </div>
+
+ <div style={groupStyle}>
+ <FieldLabel
+ label="Nickname"
+ inputID="field-label-optional"
+ isOptional
+ labelTooltip="This name is shown to collaborators."
+ />
+ <input id="field-label-optional" />
+ </div>
+
+ <div style={groupStyle}>
+ <FieldLabel
+ label="Archived field"
+ inputID="field-label-disabled"
+ isDisabled
+ />
+ <input id="field-label-disabled" disabled />
+ </div>
+
+ <div style={groupStyle}>
+ <FieldLabel
+ label="Visibility"
+ inputID="field-label-group"
+ labelID="field-label-group-label"
+ isGroupLabel
+ />
+ <div
+ id="field-label-group"
+ role="radiogroup"
+ aria-labelledby="field-label-group-label">
+ <label>
+ <input type="radio" name="visibility" defaultChecked /> Private
+ </label>{' '}
+ <label>
+ <input type="radio" name="visibility" /> Public
+ </label>
+ </div>
+ </div>
+
+ <div style={groupStyle}>
+ <FieldLabel
+ label="Search"
+ inputID="field-label-hidden"
+ description="Search every workspace."
+ descriptionID="field-label-hidden-help"
+ isLabelHidden
+ />
+ <input
+ id="field-label-hidden"
+ aria-describedby="field-label-hidden-help"
+ placeholder="Search every workspace"
+ />
+ </div>
+ </div>
+ ),
+};
diff --git a/packages/cli/test/core-prop-docs.known-drift.json b/packages/cli/test/core-prop-docs.known-drift.json
index 48cbe1ccb4..205bc8c4f2 100644
--- a/packages/cli/test/core-prop-docs.known-drift.json
+++ b/packages/cli/test/core-prop-docs.known-drift.json
@@ -31,10 +31,6 @@
"src/DropdownMenu/DropdownMenuSubMenu.doc.mjs DropdownMenuSubMenu.children required_mismatch",
"src/DropdownMenu/DropdownMenuSubMenu.doc.mjs DropdownMenuSubMenu.label required_mismatch",
"src/DropdownMenu/DropdownMenuSubMenu.doc.mjs DropdownMenuSubMenu.menuDataTestId not_in_doc",
- "src/Field/FieldLabel.doc.mjs FieldLabel.description not_in_doc",
- "src/Field/FieldLabel.doc.mjs FieldLabel.descriptionID not_in_doc",
- "src/Field/FieldLabel.doc.mjs FieldLabel.isGroupLabel not_in_doc",
- "src/Field/FieldLabel.doc.mjs FieldLabel.labelID not_in_doc",
"src/FieldStatus/FieldStatus.doc.mjs FieldStatus.variant type_mismatch",
"src/Grid/Grid.doc.mjs Grid.rowHeight not_in_doc",
"src/HoverCard/HoverCard.doc.mjs HoverCard.children required_mismatch",
diff --git a/packages/core/src/Field/FieldLabel.doc.mjs b/packages/core/src/Field/FieldLabel.doc.mjs
index 3b8efeb4e2..0246259854 100644
--- a/packages/core/src/Field/FieldLabel.doc.mjs
+++ b/packages/core/src/Field/FieldLabel.doc.mjs
@@ -7,12 +7,13 @@ export const docs = {
subComponentOf: 'Field',
displayName: 'Field Label',
isHiddenFromOverview: true,
- description: 'Standalone label component with optional/required indicators and tooltip support.',
+ description:
+ 'Standalone label group for one control or a caller-labelled group, with optional supporting text, optionality indicators, icon, and tooltip.',
props: [
{
name: 'label',
type: 'string',
- description: 'Label text.',
+ description: 'Label text, always rendered for accessibility.',
required: true,
},
{
@@ -21,39 +22,92 @@ export const docs = {
description: 'ID of the input this label is for.',
required: true,
},
+ {
+ name: 'labelID',
+ type: 'string',
+ description:
+ 'ID applied to the label element itself. Use it with `aria-labelledby` when `isGroupLabel` is true.',
+ },
+ {
+ name: 'isGroupLabel',
+ type: 'boolean',
+ description:
+ 'Render a span that can name a group instead of a native label for one control.',
+ default: 'false',
+ },
{
name: 'isLabelHidden',
type: 'boolean',
- description: 'Visually hide the label.',
+ description:
+ 'Visually hide the label and description while keeping both available to assistive technology.',
default: 'false',
},
{
name: 'isDisabled',
type: 'boolean',
- description: 'Whether the associated input is disabled.',
+ description:
+ 'Use disabled label presentation for the associated control.',
default: 'false',
},
{
name: 'isOptional',
type: 'boolean',
- description: 'Show "Optional" indicator.',
+ description:
+ "Show the localized optional indicator unless it matches FormLayout's default optionality.",
default: 'false',
},
{
name: 'isRequired',
type: 'boolean',
- description: 'Show "Required" indicator.',
+ description:
+ "Show the localized required indicator unless it matches FormLayout's default optionality.",
default: 'false',
},
{
name: 'labelIcon',
- type: 'IconType',
- description: 'Icon before the label text. See `astryx docs icons` for valid semantic names.',
+ type: 'ReactNode | IconType',
+ description:
+ 'Icon or rendered icon content before the label text. See `astryx docs icons` for semantic names.',
},
{
name: 'labelTooltip',
type: 'string',
- description: 'Tooltip text for info icon at end of label.',
+ description: 'Tooltip text for the info icon after the label.',
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description:
+ "Supporting content displayed below the label and kept separate from the control's accessible name.",
+ },
+ {
+ name: 'descriptionID',
+ type: 'string',
+ description:
+ 'ID applied to the supporting description for caller-owned `aria-describedby` wiring.',
+ },
+ {
+ name: 'ref',
+ type: 'React.Ref<HTMLLabelElement>',
+ description:
+ 'Ref forwarded to the label element. Group mode currently renders a span.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles applied to the label element after its base and state styles.',
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'CSS class name appended to the label element.',
+ },
+ {
+ name: 'style',
+ type: 'React.CSSProperties',
+ description:
+ 'Inline styles applied to the label element after StyleX inline styles.',
},
],
};
@@ -62,12 +116,13 @@ export const docsZh = {
name: 'FieldLabel',
isHiddenFromOverview: true,
displayName: 'Field Label',
- description: '独立的标签组件,支持可选/必填指示器和工具提示。',
+ description:
+ '独立标签组,可标记单个控件或调用方命名的控件组,并支持说明文本、可选/必填指示器、图标和工具提示。',
props: [
{
name: 'label',
type: 'string',
- description: '标签文本。',
+ description: '标签文本,始终为辅助技术保留。',
required: true,
},
{
@@ -76,39 +131,82 @@ export const docsZh = {
description: '此标签关联的输入框 ID。',
required: true,
},
+ {
+ name: 'labelID',
+ type: 'string',
+ description:
+ '应用到标签元素本身的 ID。isGroupLabel 为 true 时用于 aria-labelledby。',
+ },
+ {
+ name: 'isGroupLabel',
+ type: 'boolean',
+ description:
+ '渲染用于命名控件组的 span,而不是关联单个控件的原生 label。',
+ default: 'false',
+ },
{
name: 'isLabelHidden',
type: 'boolean',
- description: '视觉隐藏标签。',
+ description: '视觉隐藏标签和说明,同时为辅助技术保留。',
default: 'false',
},
{
name: 'isDisabled',
type: 'boolean',
- description: '关联的输入框是否禁用。',
+ description: '使用关联控件的禁用标签样式。',
default: 'false',
},
{
name: 'isOptional',
type: 'boolean',
- description: '显示"Optional"指示器。',
+ description: '当其不匹配 FormLayout 默认值时显示本地化的可选指示器。',
default: 'false',
},
{
name: 'isRequired',
type: 'boolean',
- description: '显示"Required"指示器。',
+ description: '当其不匹配 FormLayout 默认值时显示本地化的必填指示器。',
default: 'false',
},
{
name: 'labelIcon',
- type: 'IconType',
- description: '标签文本前的图标。',
+ type: 'ReactNode | IconType',
+ description: '标签文本前的图标或已渲染图标内容。',
},
{
name: 'labelTooltip',
type: 'string',
- description: '标签末尾信息图标的工具提示文本。',
+ description: '标签后信息图标的工具提示文本。',
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: '标签下方的说明内容,与控件的无障碍名称保持分离。',
+ },
+ {
+ name: 'descriptionID',
+ type: 'string',
+ description: '应用到说明内容的 ID,供调用方连接 aria-describedby。',
+ },
+ {
+ name: 'ref',
+ type: 'React.Ref<HTMLLabelElement>',
+ description: '转发到标签元素的 ref。控件组模式当前渲染 span。',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: '在基础和状态样式之后应用到标签元素的 StyleX 样式。',
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: '追加到标签元素的 CSS 类名。',
+ },
+ {
+ name: 'style',
+ type: 'React.CSSProperties',
+ description: '在 StyleX 内联样式之后应用到标签元素的内联样式。',
},
],
};
@@ -117,15 +215,24 @@ export const docsDense = {
name: 'FieldLabel',
isHiddenFromOverview: true,
displayName: 'Field Label',
- description: 'Standalone label w/ optional/required indicators + tooltip support.',
+ description:
+ 'label group for one control or a caller-labelled group; supporting text, optionality, icon, tooltip',
propDescriptions: {
label: 'Label text.',
- inputID: 'ID of input this label is for.',
- isLabelHidden: 'Visually hide label.',
- isDisabled: 'Associated input disabled.',
- isOptional: 'Show "Optional" indicator.',
- isRequired: 'Show "Required" indicator.',
- labelIcon: 'Icon before label text.',
- labelTooltip: 'Tooltip text for info icon at end of label.',
+ inputID: 'ID of the associated control.',
+ labelID: 'ID of the label element for caller-owned aria-labelledby.',
+ isGroupLabel: 'Render a group-label span instead of a native label.',
+ isLabelHidden: 'Visually hide label and description.',
+ isDisabled: 'Use disabled label presentation.',
+ isOptional: 'Show localized optional exception indicator.',
+ isRequired: 'Show localized required exception indicator.',
+ labelIcon: 'Icon type or rendered icon content before label text.',
+ labelTooltip: 'Tooltip text for the info icon after the label.',
+ description: 'Supporting content outside the accessible name.',
+ descriptionID: 'ID for caller-owned aria-describedby wiring.',
+ ref: 'Ref forwarded to the label element; group mode renders a span.',
+ xstyle: 'StyleX styles for the label element.',
+ className: 'CSS class name for the label element.',
+ style: 'Inline styles for the label element.',
},
};
diff --git a/packages/core/src/Field/FieldLabel.spec.md b/packages/core/src/Field/FieldLabel.spec.md
new file mode 100644
index 0000000000..286ee234c7
--- /dev/null
+++ b/packages/core/src/Field/FieldLabel.spec.md
@@ -0,0 +1,172 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:FieldLabel
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/Field/FieldLabel.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,
+ ]
+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. 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`. |
+
+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: observational only; this draft changes no public prop, default, or behavior.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none; OQ1 requires a separate public-type decision. The tooltip accessibility defect remains open.
+
+## 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.
+- Tooltip surface behavior and icon rendering, which delegate to `component: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. |
+
+## 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 |
+
+### 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 Tooltip render their owned paint; the current tooltip anchor remains 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.
+- **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.
+
+## 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.** The current anonymous, nonfocusable tooltip anchor does not expose its explanatory content to keyboard or screen-reader users; this remains an objective conformance gap.
+
+## 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` 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` |
+
+## 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.
+
+## 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 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.
diff --git a/packages/core/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts b/packages/core/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..b673298685
--- /dev/null
+++ b/packages/core/src/Field/__tests__/FieldLabelAudit.a11y.chromium.spec.ts
@@ -0,0 +1,296 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FieldLabelAudit.a11y.chromium.spec.ts
+ * @input Exact-head FieldLabel story across semantics, themes, direction, and viewport sizes
+ * @output Screenshots and fail-closed sensor receipts for the FieldLabel whole-component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a FieldLabel audit pull request
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve('field-label-audit-evidence');
+const WIDE = {width: 1024, height: 900};
+const NARROW = {width: 320, height: 900};
+
+type Mode = 'light' | 'dark';
+type Direction = 'ltr' | 'rtl';
+type Theme = 'neutral' | 'butter';
+
+type AuditCase = {
+ key: string;
+ mode: Mode;
+ direction: Direction;
+ theme: Theme;
+ viewport: {width: number; height: number};
+};
+
+type AuditReceipt = {
+ passed: boolean;
+ expected: Record<string, unknown>;
+};
+
+const cases: AuditCase[] = [];
+function addPair(
+ key: string,
+ options: Partial<Omit<AuditCase, 'key' | 'mode'>> = {},
+) {
+ for (const mode of ['light', 'dark'] as const) {
+ cases.push({
+ key: `${key}-${mode}`,
+ mode,
+ direction: options.direction ?? 'ltr',
+ theme: options.theme ?? 'neutral',
+ viewport: options.viewport ?? WIDE,
+ });
+ }
+}
+
+addPair('default');
+addPair('custom-theme', {theme: 'butter'});
+addPair('rtl', {direction: 'rtl'});
+addPair('narrow', {viewport: NARROW});
+
+test.describe.configure({mode: 'serial', retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+function storyUrl(item: AuditCase) {
+ return `${server.origin}/iframe.html?id=core-fieldlabel--states&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;
+}
+
+async function settle(page: Page) {
+ await holdMotionStill(page);
+ await page.evaluate(async () => document.fonts.ready);
+ await page.waitForTimeout(40);
+}
+
+test.beforeAll(async () => {
+ fs.rmSync(OUTPUT, {recursive: true, force: true});
+ fs.mkdirSync(OUTPUT, {recursive: true});
+ checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+ encoding: 'utf8',
+ }).trim();
+ const expected = process.env.ASTRYX_HEAD_SHA;
+ if (expected && expected !== checkoutSha) {
+ throw new Error(
+ `checkout ${checkoutSha} does not match expected head ${expected}`,
+ );
+ }
+ server = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+ const response = await fetch(`${server.origin}/astryx-build-sha.txt`);
+ if (!response.ok) {
+ throw new Error(`Storybook build has no SHA stamp (${response.status})`);
+ }
+ storybookSha = (await response.text()).trim();
+ if (storybookSha !== checkoutSha) {
+ throw new Error(
+ `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,
+ );
+ }
+});
+
+test.afterAll(async () => {
+ await server?.close();
+});
+
+for (const item of cases) {
+ test(item.key, async ({browser}) => {
+ const context = await browser.newContext({
+ viewport: item.viewport,
+ colorScheme: item.mode,
+ reducedMotion: 'reduce',
+ });
+ const page = await context.newPage();
+ const pageErrors: string[] = [];
+ page.on('pageerror', error => pageErrors.push(String(error)));
+ await page.goto(storyUrl(item), {waitUntil: 'load'});
+ await page.locator('#storybook-root').waitFor();
+
+ const targets = page.locator('.astryx-field-label');
+ await expect(targets).toHaveCount(7);
+ await expect(page.locator('label[for="field-label-default"]')).toHaveText(
+ 'Email',
+ );
+ const description = page.locator('#field-label-description-help');
+ await expect(description).toHaveText(
+ 'Shown in navigation and invitations.',
+ );
+ await expect(description.locator('xpath=ancestor::label')).toHaveCount(0);
+ await expect(page.locator('#field-label-group-label')).toHaveJSProperty(
+ 'tagName',
+ 'SPAN',
+ );
+ await expect(
+ page.getByRole('radiogroup', {name: 'Visibility'}),
+ ).toBeVisible();
+ await expect(page.getByText(/Required/)).toBeVisible();
+ await expect(page.getByText(/Optional/)).toBeVisible();
+ await expect(page.getByLabel('Search')).toBeVisible();
+ const tooltipAnchor = page
+ .locator('label[for="field-label-optional"] [aria-describedby]')
+ .first();
+ await expect(tooltipAnchor).toHaveCount(1);
+
+ await settle(page);
+ const observed = await page.evaluate(() => {
+ const labels = Array.from(
+ document.querySelectorAll<HTMLElement>('.astryx-field-label'),
+ ).map(label => {
+ const style = getComputedStyle(label);
+ const box = label.getBoundingClientRect();
+ return {
+ text: label.textContent?.replace(/\s+/g, ' ').trim(),
+ tagName: label.tagName,
+ htmlFor: label.getAttribute('for'),
+ color: style.color,
+ cursor: style.cursor,
+ geometry: {x: box.x, y: box.y, width: box.width, height: box.height},
+ };
+ });
+ const hidden = document.querySelector<HTMLElement>(
+ 'label[for="field-label-hidden"]',
+ );
+ const hiddenBox = hidden?.getBoundingClientRect();
+ const firstLabel = document.querySelector<HTMLElement>(
+ '.astryx-field-label',
+ );
+ const currentTooltipAnchor = document.querySelector<HTMLElement>(
+ 'label[for="field-label-optional"] [aria-describedby]',
+ );
+ return {
+ theme: document
+ .querySelector('[data-astryx-theme]')
+ ?.getAttribute('data-astryx-theme'),
+ mode: document.documentElement.getAttribute('data-theme'),
+ direction: firstLabel ? getComputedStyle(firstLabel).direction : null,
+ viewport: {width: innerWidth, height: innerHeight},
+ reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+ horizontalOverflow:
+ document.documentElement.scrollWidth > innerWidth + 1,
+ fonts: document.fonts.status,
+ labels,
+ hiddenGeometry: hiddenBox
+ ? {width: hiddenBox.width, height: hiddenBox.height}
+ : null,
+ tooltipAnchor: currentTooltipAnchor
+ ? {
+ ariaHidden: currentTooltipAnchor.getAttribute('aria-hidden'),
+ ariaLabel: currentTooltipAnchor.getAttribute('aria-label'),
+ describedBy:
+ currentTooltipAnchor.getAttribute('aria-describedby'),
+ tabIndex: currentTooltipAnchor.getAttribute('tabindex'),
+ }
+ : null,
+ };
+ });
+
+ const semanticsPass =
+ observed.labels.length === 7 &&
+ observed.labels.filter(label => label.tagName === 'SPAN').length === 1 &&
+ observed.labels.every(label => label.geometry.width > 0) &&
+ observed.hiddenGeometry?.width === 1 &&
+ observed.hiddenGeometry.height === 1;
+ const knownTooltipGapObserved =
+ observed.tooltipAnchor?.ariaHidden === 'true' &&
+ observed.tooltipAnchor.ariaLabel == null &&
+ observed.tooltipAnchor.tabIndex == null;
+
+ const png = await page.screenshot({animations: 'disabled', fullPage: true});
+ const image = `${item.key}.png`;
+ const receipt = {
+ schemaVersion: 1,
+ expected: {
+ build: checkoutSha,
+ storyId: 'core-fieldlabel--states',
+ mode: item.mode,
+ direction: item.direction,
+ theme: item.theme,
+ viewport: item.viewport,
+ targetCount: 7,
+ groupLabelTag: 'SPAN',
+ hiddenGeometry: {width: 1, height: 1},
+ knownGap:
+ 'the tooltip anchor is anonymous and nonfocusable on this audited head',
+ },
+ observed: {
+ build: storybookSha,
+ ...observed,
+ pageErrors,
+ },
+ image: {
+ file: image,
+ sha256: createHash('sha256').update(png).digest('hex'),
+ width: png.readUInt32BE(16),
+ height: png.readUInt32BE(20),
+ },
+ checks: {semanticsPass, knownTooltipGapObserved},
+ passed:
+ storybookSha === checkoutSha &&
+ pageErrors.length === 0 &&
+ observed.theme === item.theme &&
+ observed.mode === item.mode &&
+ observed.direction === item.direction &&
+ observed.viewport.width === item.viewport.width &&
+ observed.viewport.height === item.viewport.height &&
+ observed.reducedMotion &&
+ !observed.horizontalOverflow &&
+ observed.fonts === 'loaded' &&
+ semanticsPass,
+ };
+ fs.writeFileSync(path.join(OUTPUT, image), png);
+ fs.writeFileSync(
+ path.join(OUTPUT, `${item.key}.sensors.json`),
+ `${JSON.stringify(receipt, null, 2)}\n`,
+ );
+ await context.close();
+ });
+}
+
+test('manifest is complete', async () => {
+ const receiptFiles = fs
+ .readdirSync(OUTPUT)
+ .filter(file => file.endsWith('.sensors.json'));
+ const receipts = receiptFiles.map(
+ (file): AuditReceipt =>
+ JSON.parse(
+ fs.readFileSync(path.join(OUTPUT, file), 'utf8'),
+ ) as AuditReceipt,
+ );
+ fs.writeFileSync(
+ path.join(OUTPUT, 'manifest.json'),
+ `${JSON.stringify(
+ {
+ schemaVersion: 1,
+ component: 'core/FieldLabel',
+ build: checkoutSha,
+ frames: cases.map(item => ({
+ key: item.key,
+ image: `${item.key}.png`,
+ receipt: `${item.key}.sensors.json`,
+ })),
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ expect(receiptFiles).toHaveLength(cases.length);
+ expect(
+ receipts
+ .filter(receipt => !receipt.passed)
+ .map(receipt => receipt.expected),
+ ).toEqual([]);
+});