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

[git-nandor]

INSTUI-4724

Summary

Form control messages render inside the wrapping , so screen readers were reading them as part of the field's accessible name (e.g. "Password Password must be at least 6 characters") instead of as a description.

Each single form control now points its accessible name at the label text only (aria-labelledby) and references the messages as its description (aria-describedby), so a screen reader announces the label first, then the messages. The wrapping is unchanged, so click-on-label focus is preserved.

Test plan

Tab through the given exaple and verify in DevTools Accessibility tab that the Name and Description values are correct. With a screen reader enabled, confirm that the label is announced as the field name, followed by a brief pause before the description is announced.

const messages = [{ type: 'error', text: 'This field has an error' }]

render(
  <View as="div" display="block" width="24rem">
    <Text as="p">
      Tab through and verify in DevTools Accessibility tab that the Name and Description values are correct. With a screen reader enabled, confirm that the label is announced as the field name, followed by a brief pause before the description is announced.
    </Text>

    <View as="div" margin="medium 0 0">
      <TextInput renderLabel="Text Input" messages={messages} />
    </View>
    <View as="div" margin="medium 0 0">
      <NumberInput renderLabel="Number Input" messages={messages} />
    </View>
    <View as="div" margin="medium 0 0">
      <TextArea label="Text Area" messages={messages} />
    </View>
    <View as="div" margin="medium 0 0">
      <Checkbox label="Checkbox (simple)" value="c1" messages={messages} />
    </View>
    <View as="div" margin="medium 0 0">
      <Checkbox
        label="Checkbox (toggle)"
        variant="toggle"
        value="c2"
        messages={messages}
      />
    </View>
    <View as="div" margin="medium 0 0">
      <RangeInput
        label="Range Input"
        name="range"
        min={0}
        max={100}
        defaultValue={50}
        messages={messages}
      />
    </View>
  </View>
)

Co-Authored-By: 🤖 Claude

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://instructure.design/pr-preview/pr-2625/
Built to branch gh-pages at 2026-07-17 07:11 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Visual regression report

✅ No changes.

Status	Count
Unchanged	32
Changed	0
New	0
Removed	0

📊 View full report

_{Baselines come from the visual-baselines branch. They refresh on every merge to master.}

[ToMESSKa]

I think the Select's pill handling doesn't use aria-labelledby anymore see #2616 (comment) so this is not a relevant example

[git-nandor]

Thanks, modified

[ToMESSKa]

A vitest test is failing, can you please check?

[matyasf]

• dateTimeInput is wrong, see the example in the /forms page: aria-describedby and aria-labelledby reference nothing.
• While it works, I generally dislike this component structure. All this mess is needed, because we wrap everything in a , the nice way would be not to do so. I think its OK for now, but we need to completely revamp this in the future. (also support SSR better, now the layout falls apart when loading)
• see my other comments

[matyasf]

looks good, just a small nitpick

[matyasf]

Please make a bit more brief comments. Claude can be very very verbose and this just makes the code hard to read. For example this comment is totally unnecessary IMO, the code is pretty self-explanatory

[matyasf]

Again, way too verbose. I'd just write:

"Use the contents of the messages field as ARIA label; user supplied value takes precedence"