fix(many): keep form field messages out of the control's accessible name

git-nandor · claude · git-nandor · commit 409d077a3095 · 2026-07-22T13:23:33.000+02:00
Form control messages (error/hint/success) render inside the wrapping <label>, so they were read as part of the field's accessible name. Point each control's name at the label text via aria-labelledby and reference the messages via aria-describedby, so screen readers announce them as the field's description. Label click-to-focus is preserved. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/packages/ui-checkbox/src/Checkbox/__tests__/Checkbox.test.tsx b/packages/ui-checkbox/src/Checkbox/__tests__/Checkbox.test.tsx
@@ -289,5 +289,35 @@ describe('<Checkbox />', () => {
 
       expect(axeCheck).toBe(true)
     })
+
+    it('associates messages with the checkbox as its description, not its accessible name', async () => {
+      render(
+        <Checkbox
+          label="Accept terms"
+          value="v"
+          messages={[{ type: 'error', text: 'You must accept' }]}
+        />
+      )
+      const input = screen.getByRole('checkbox')
+
+      const describedById = input.getAttribute('aria-describedby')
+      expect(describedById).toBeTruthy()
+      expect(document.getElementById(describedById!)).toHaveTextContent(
+        'You must accept'
+      )
+
+      const labelledById = input.getAttribute('aria-labelledby')
+      expect(labelledById).toBeTruthy()
+      const labelEl = document.getElementById(labelledById!)
+      expect(labelEl).toHaveTextContent('Accept terms')
+      expect(labelEl).not.toHaveTextContent('You must accept')
+    })
+
+    it('does not set aria-labelledby when there are no messages', async () => {
+      render(<Checkbox label="Accept terms" value="v" />)
+      const input = screen.getByRole('checkbox')
+
+      expect(input).not.toHaveAttribute('aria-labelledby')
+    })
   })
 })
diff --git a/packages/ui-checkbox/src/Checkbox/v2/index.tsx b/packages/ui-checkbox/src/Checkbox/v2/index.tsx
@@ -84,8 +84,12 @@ class Checkbox extends Component<CheckboxProps, CheckboxState> {
     }
 
     this._defaultId = props.deterministicId!()
+    this._messagesId = props.deterministicId!('Checkbox-messages')
+    this._labelId = props.deterministicId!('Checkbox-label')
   }
   private readonly _defaultId: string
+  private readonly _messagesId: string
+  private readonly _labelId: string
   private _input: HTMLInputElement | null = null
 
   ref: Element | null = null
@@ -186,6 +190,10 @@ class Checkbox extends Component<CheckboxProps, CheckboxState> {
     )
   }
 
+  get hasMessages() {
+    return !!this.props.messages && this.props.messages.length > 0
+  }
+
   get invalid() {
     return !!this.props.messages?.find(
       (m) => m.type === 'newError' || m.type === 'error'
@@ -217,6 +225,24 @@ class Checkbox extends Component<CheckboxProps, CheckboxState> {
       `[Checkbox] The \`simple\` variant does not support the \`labelPlacement\` property.  Use the \`toggle\` variant instead.`
     )
 
+    // The label text gets its own id so that, when there are messages, the
+    // input's accessible name can point at the label only (via
+    // `aria-labelledby`) instead of also including the message text.
+    const labelContent = (
+      <span id={this._labelId}>
+        {label}
+        {isRequired && label && (
+          <span
+            css={this.invalid ? styles?.requiredInvalid : {}}
+            aria-hidden={true}
+          >
+            {' '}
+            *
+          </span>
+        )}
+      </span>
+    )
+
     if (variant === 'toggle') {
       return (
         <ToggleFacade
@@ -232,16 +258,7 @@ class Checkbox extends Component<CheckboxProps, CheckboxState> {
           themeOverride={themeOverride}
           invalid={this.invalid}
         >
-          {label}
-          {isRequired && label && (
-            <span
-              css={this.invalid ? styles?.requiredInvalid : {}}
-              aria-hidden={true}
-            >
-              {' '}
-              *
-            </span>
-          )}
+          {labelContent}
         </ToggleFacade>
       )
     } else {
@@ -257,16 +274,7 @@ class Checkbox extends Component<CheckboxProps, CheckboxState> {
           themeOverride={themeOverride}
           invalid={this.invalid}
         >
-          {label}
-          {isRequired && label && (
-            <span
-              css={this.invalid ? styles?.requiredInvalid : {}}
-              aria-hidden={true}
-            >
-              {' '}
-              *
-            </span>
-          )}
+          {labelContent}
         </CheckboxFacade>
       )
     }
@@ -286,7 +294,7 @@ class Checkbox extends Component<CheckboxProps, CheckboxState> {
             : styles?.indentedError)
         }
       >
-        <FormFieldMessages messages={messages} />
+        <FormFieldMessages id={this._messagesId} messages={messages} />
       </View>
     ) : null
   }
@@ -338,6 +346,24 @@ class Checkbox extends Component<CheckboxProps, CheckboxState> {
             aria-readonly={readOnly ? true : undefined}
             aria-checked={indeterminate ? 'mixed' : undefined}
             aria-invalid={this.invalid ? 'true' : undefined}
+            // Keep messages in the description so the accessible name contains only the label.
+            aria-labelledby={
+              this.hasMessages
+                ? ((props as Record<string, unknown>)[
+                    'aria-labelledby'
+                  ] as string) || this._labelId
+                : ((props as Record<string, unknown>)['aria-labelledby'] as
+                    | string
+                    | undefined)
+            }
+            aria-describedby={
+              [
+                (props as Record<string, unknown>)['aria-describedby'],
+                this.hasMessages ? this._messagesId : null
+              ]
+                .filter(Boolean)
+                .join(' ') || undefined
+            }
             css={styles?.input}
             onClickCapture={(e) => {
               if (readOnly) {
diff --git a/packages/ui-form-field/src/FormField/v2/props.ts b/packages/ui-form-field/src/FormField/v2/props.ts
@@ -46,6 +46,11 @@ type FormFieldOwnProps = {
    * id for the form field messages
    */
   messagesId?: string
+  /**
+   * id for the label element, so a single form control can reference just the
+   * label text via `aria-labelledby` (keeping messages out of its accessible name)
+   */
+  labelId?: string
   children?: React.ReactNode
   inline?: boolean
   layout?: 'stacked' | 'inline'
@@ -86,6 +91,7 @@ const allowedProps: AllowedPropKeys = [
   'id',
   'messages',
   'messagesId',
+  'labelId',
   'children',
   'inline',
   'layout',
diff --git a/packages/ui-form-field/src/FormFieldLayout/v2/index.tsx b/packages/ui-form-field/src/FormFieldLayout/v2/index.tsx
@@ -48,6 +48,7 @@ const FormFieldLayout = forwardRef<Element, FormFieldLayoutProps>(
       label,
       messages,
       messagesId: messagesIdProp,
+      labelId: labelIdProp,
       children,
       width,
       elementRef,
@@ -69,7 +70,12 @@ const FormFieldLayout = forwardRef<Element, FormFieldLayoutProps>(
     }, [])
 
     const messagesId = messagesIdProp || deterministicId
-    const labelId = deterministicId ? `${deterministicId}-Label` : undefined
+    // The label element gets an id so that single form controls can point their
+    // `aria-labelledby` at the label text only. This keeps `messages` (which
+    // live inside the wrapping <label>) out of the control's accessible name
+    // while preserving the native click-on-label focus behavior.
+    const labelId =
+      labelIdProp || (deterministicId ? `${deterministicId}-Label` : undefined)
 
     // Filter out error and success messages when disabled or readOnly
     const filteredMessages =
@@ -183,7 +189,13 @@ const FormFieldLayout = forwardRef<Element, FormFieldLayoutProps>(
             </legend>
           )
         }
-        return <span css={styles?.formFieldLabel}>{labelContent}</span>
+        // `id` lets single form controls reference just the label text via
+        // `aria-labelledby`, keeping `messages` out of their accessible name.
+        return (
+          <span css={styles?.formFieldLabel} id={labelId}>
+            {labelContent}
+          </span>
+        )
       } else if (label) {
         if (ElementType === 'fieldset') {
           return (
diff --git a/packages/ui-form-field/src/FormFieldLayout/v2/props.ts b/packages/ui-form-field/src/FormFieldLayout/v2/props.ts
@@ -56,6 +56,11 @@ type FormFieldLayoutOwnProps = {
    * id for the form field messages
    */
   messagesId?: string
+  /**
+   * id for the label element, so a single form control can reference just the
+   * label text via `aria-labelledby` (keeping messages out of its accessible name)
+   */
+  labelId?: string
   children?: React.ReactNode
   /**
    * If `true` use an inline layout -- content will flow on the left/right side
@@ -129,6 +134,7 @@ const allowedProps: AllowedPropKeys = [
   'as',
   'messages',
   'messagesId',
+  'labelId',
   'children',
   'inline',
   'layout',
diff --git a/packages/ui-number-input/src/NumberInput/__tests__/NumberInput.test.tsx b/packages/ui-number-input/src/NumberInput/__tests__/NumberInput.test.tsx
@@ -304,4 +304,33 @@ describe('<NumberInput />', () => {
       expect(onDecrement).toHaveBeenCalledTimes(1)
     })
   })
+
+  it('associates messages with the input as its description, not its accessible name', async () => {
+    render(
+      <NumberInput
+        renderLabel="Label"
+        messages={[{ type: 'error', text: 'some error message' }]}
+      />
+    )
+    const input = screen.getByRole('spinbutton')
+
+    const describedById = input.getAttribute('aria-describedby')
+    expect(describedById).toBeTruthy()
+    expect(document.getElementById(describedById!)).toHaveTextContent(
+      'some error message'
+    )
+
+    const labelledById = input.getAttribute('aria-labelledby')
+    expect(labelledById).toBeTruthy()
+    const labelEl = document.getElementById(labelledById!)
+    expect(labelEl).toHaveTextContent('Label')
+    expect(labelEl).not.toHaveTextContent('some error message')
+  })
+
+  it('does not override the accessible name with aria-labelledby when there are no messages', async () => {
+    render(<NumberInput renderLabel="Label" />)
+    const input = screen.getByRole('spinbutton')
+
+    expect(input).not.toHaveAttribute('aria-labelledby')
+  })
 })
diff --git a/packages/ui-number-input/src/NumberInput/v2/index.tsx b/packages/ui-number-input/src/NumberInput/v2/index.tsx
@@ -120,6 +120,14 @@ const NumberInput = forwardRef<NumberInputHandle, NumberInputProps>(
     const success =
       !!messages && messages.some((message) => message.type === 'success')
 
+    // Messages live inside the wrapping <label>. Reference them from the input
+    // via `aria-describedby` and point the accessible name at the label text
+    // only via `aria-labelledby`, so the messages are announced as a
+    // description rather than as part of the control's name.
+    const hasMessages = !!messages && messages.length > 0
+    const messagesId = id ? `${id}-messages` : undefined
+    const labelId = id ? `${id}-label` : undefined
+
     const interaction = getInteraction({ props })
     if (
       interaction === 'disabled' &&
@@ -331,6 +339,8 @@ const NumberInput = forwardRef<NumberInputHandle, NumberInputProps>(
       <FormField
         {...pickProps(props, FormField.allowedProps)}
         label={label}
+        messagesId={messagesId}
+        labelId={labelId}
         inline={display === 'inline-block'}
         id={id}
         elementRef={handleRef}
@@ -346,6 +356,19 @@ const NumberInput = forwardRef<NumberInputHandle, NumberInputProps>(
               {...passedProps}
               css={styles?.input}
               aria-invalid={invalid ? 'true' : undefined}
+              aria-describedby={
+                [
+                  passedProps['aria-describedby'],
+                  hasMessages ? messagesId : null
+                ]
+                  .filter(Boolean)
+                  .join(' ') || undefined
+              }
+              aria-labelledby={
+                hasMessages
+                  ? (passedProps['aria-labelledby'] as string) || labelId
+                  : (passedProps['aria-labelledby'] as string | undefined)
+              }
               id={id}
               type={allowStringValue ? 'text' : 'number'}
               inputMode={inputMode}
diff --git a/packages/ui-range-input/src/RangeInput/__tests__/RangeInput.test.tsx b/packages/ui-range-input/src/RangeInput/__tests__/RangeInput.test.tsx
@@ -211,6 +211,41 @@ describe('<RangeInput />', () => {
       expect(axeCheck).toBe(true)
     })
 
+    it('associates messages with the input as its description, not its accessible name', async () => {
+      const { container } = render(
+        <RangeInput
+          label="Opacity"
+          name="opacity"
+          max={100}
+          min={0}
+          defaultValue={50}
+          messages={[{ type: 'error', text: 'some error message' }]}
+        />
+      )
+      const input = container.querySelector('input')!
+
+      const describedById = input.getAttribute('aria-describedby')
+      expect(describedById).toBeTruthy()
+      expect(document.getElementById(describedById!)).toHaveTextContent(
+        'some error message'
+      )
+
+      const labelledById = input.getAttribute('aria-labelledby')
+      expect(labelledById).toBeTruthy()
+      const labelEl = document.getElementById(labelledById!)
+      expect(labelEl).toHaveTextContent('Opacity')
+      expect(labelEl).not.toHaveTextContent('some error message')
+    })
+
+    it('does not override the accessible name with aria-labelledby when there are no messages', async () => {
+      const { container } = render(
+        <RangeInput label="Opacity" name="opacity" max={100} min={0} />
+      )
+      const input = container.querySelector('input')!
+
+      expect(input).not.toHaveAttribute('aria-labelledby')
+    })
+
     it('formats the aria-valuetext attribute', async () => {
       const { container } = render(
         <RangeInput
diff --git a/packages/ui-range-input/src/RangeInput/v2/index.tsx b/packages/ui-range-input/src/RangeInput/v2/index.tsx
@@ -184,14 +184,27 @@ class RangeInput extends Component<RangeInputProps, RangeInputState> {
   }
 
   render() {
-    const { formatValue, disabled, readOnly } = this.props
+    const { formatValue, disabled, readOnly, messages } = this.props
 
-    const props = omitProps(this.props, RangeInput.allowedProps)
+    const props = omitProps(this.props, RangeInput.allowedProps) as Record<
+      string,
+      unknown
+    >
+
+    // Messages live inside the wrapping <label>. Reference them from the input
+    // via `aria-describedby` and point the accessible name at the label text
+    // only via `aria-labelledby`, so the messages are announced as a
+    // description rather than as part of the control's name.
+    const hasMessages = !!messages && messages.length > 0
+    const messagesId = `${this.id}-messages`
+    const labelId = `${this.id}-label`
 
     return (
       <FormField
         {...pickProps(this.props, FormField.allowedProps)}
         label={this.props.label}
+        messagesId={messagesId}
+        labelId={labelId}
         id={this.id}
         elementRef={this.handleRef}
         data-cid="RangeInput"
@@ -211,6 +224,16 @@ class RangeInput extends Component<RangeInputProps, RangeInputState> {
             {...props}
             disabled={disabled || readOnly}
             aria-disabled={disabled || readOnly ? 'true' : undefined}
+            aria-describedby={
+              [props['aria-describedby'], hasMessages ? messagesId : null]
+                .filter(Boolean)
+                .join(' ') || undefined
+            }
+            aria-labelledby={
+              hasMessages
+                ? (props['aria-labelledby'] as string) || labelId
+                : (props['aria-labelledby'] as string | undefined)
+            }
           />
           {this.renderValue()}
         </div>
diff --git a/packages/ui-text-area/src/TextArea/__tests__/TextArea.test.tsx b/packages/ui-text-area/src/TextArea/__tests__/TextArea.test.tsx
diff --git a/packages/ui-text-area/src/TextArea/v2/index.tsx b/packages/ui-text-area/src/TextArea/v2/index.tsx
diff --git a/packages/ui-text-input/src/TextInput/__tests__/TextInput.test.tsx b/packages/ui-text-input/src/TextInput/__tests__/TextInput.test.tsx
diff --git a/packages/ui-text-input/src/TextInput/v2/index.tsx b/packages/ui-text-input/src/TextInput/v2/index.tsx
