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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 9bb0ea446d..a267826ad8 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -2435,6 +2435,37 @@ jobs:retention-days: 30if-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 evidencediff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex 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.tsxnew file mode 100644index 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.jsonindex 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.mjsindex 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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([]);+});