Split hint from label and expose it via aria-description or aria-describedby#169157

Merged

flutter-zl merged 28 commits intoflutter:masterfrom

flutter-zl:hint_0520

May 27, 2025

Contributor

flutter-zl commented May 20, 2025 •

edited

Loading

Summary
This PR improves web accessibility in Flutter by separating hint from label in the semantics engine and exposing them via ARIA attributes. The hint is set using aria-description (or aria-describedby as a fallback for browsers that do not support aria-description).

Details
Hint separation:
The hint is exposed via aria-description if supported, or via aria-describedby with a hidden node as a fallback.
Browser compatibility:
Uses feature detection to choose between aria-description and aria-describedby.
Test coverage:
Added/updated tests to verify correct ARIA attribute behavior and fallback logic.

How to verify
All relevant tests pass (semantics_test.dart, semantics_text_test.dart).

Motivation
This change brings Flutter web closer to accessibility best practices and ARIA standards, improving the experience for users of assistive technologies.

Before/After Change
before: https://before-change-hint.web.app/
after: https://after-change-hint.web.app/
after(fallback to aria-describedby): https://after-change-hint-fallback.web.app/

Issues fixed
#162140

Note
Some focus-related tests (e.g., incrementable sends focus events) are failing, but these failures are also present on the main branch and are unrelated to the ARIA label/hint changes in this PR.

Pre-launch Checklist

I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
I read the [Tree Hygiene] wiki page, which explains my responsibilities.
I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement].
I signed the [CLA].
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is [test-exempt].
I followed the [breaking change policy] and added [Data Driven Fixes] where supported.
All existing and new tests are passing.

flutter-zl added 3 commits

May 20, 2025 10:28


          first commit

51b1764


          Split hint from label and expose it via aria-description in AriaLabel…

0b5f0f2

…Representation


          Split hint from label and expose it via aria-description in AriaLabel…

54ba102

…Representation

github-actions bot added engine a: accessibility platform-web labels

flutter-zl requested review from mdebbar and yjbanov

May 21, 2025 05:01

flutter-zl mentioned this pull request

Refactor Flutter Web semantics to use ARIA attributes and clean up tests #168653

Closed

9 tasks

flutter-zl marked this pull request as ready for review

May 21, 2025 05:15

flutter-zl added 3 commits

May 20, 2025 22:15


          Merge branch 'master' into hint_0520

cf73aa4


          Refactor ARIA describedBy fallback: attach hidden span as child, clea…

2d6feb5

…n up on dispose


          Merge branch 'master' into hint_0520

214d9a3

flutter-zl requested a review from chunhtai

May 21, 2025 16:37

flutter-zl added 3 commits

May 21, 2025 10:20


          fix dart analyze complaints

ac9076e


          Merge branch 'master' into hint_0520

9cf9e83


          Merge branch 'master' into hint_0520

d7d5612

flutter-zl marked this pull request as draft

May 21, 2025 19:50

flutter-dashboard bot commented May 21, 2025

This pull request has been changed to a draft. The currently pending flutter-gold status will not be able to resolve until a new commit is pushed or the change is marked ready for review again.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

flutter-zl added 4 commits

May 21, 2025 13:22


          add aria-description to LabelAndValue

c5e21f2


          Merge branch 'master' into hint_0520

a387ec5


          add test cases

8e6b267


          Merge branch 'master' into hint_0520

b7af1cd

flutter-zl changed the title ~~Split hint from label and expose it via aria-description in AriaLabelRepresentation~~ Split hint from label and expose it via aria-description or aria-describedby

flutter-zl marked this pull request as ready for review

May 22, 2025 06:10

flutter-zl added 2 commits

May 22, 2025 10:02


          Merge branch 'master' into hint_0520

d74484e


          Merge branch 'master' into hint_0520

35ccbc7

chunhtai reviewed

View reviewed changes

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart

                   }
                   _getEffectiveRepresentation().update(computedLabel);
+                  _updateHintDescription(semanticsObject.hint);

Contributor

chunhtai May 22, 2025

somewhere in the doc of this class should mention hint translate to description

Contributor Author

flutter-zl May 22, 2025

Updated.

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart

+                void _updateHintDescription(String? hint) {
+                  owner.removeAttribute('aria-description');
+                  owner.removeAttribute('aria-describedby');
+                  if (hint != null && hint.trim().isNotEmpty) {

Contributor

chunhtai May 22, 2025

Suggested change

      
                if (hint != null && hint.trim().isNotEmpty) {
          
                if (hint?.trim().isNotEmpty ?? false) {

Contributor

chunhtai May 22, 2025

ignore this if this doesn't promote the hint to non-null.

Contributor Author

flutter-zl May 22, 2025

it does not promote hint to non-null inside the block, so hint is still of type String?, but _setAriaDescriptionOrDescribedBy expects a non-nullable String.

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart

+                }
+                @visibleForTesting
+                static set supportsAriaDescriptionForTest(bool? value) {

Contributor

chunhtai May 22, 2025

why nullable value?

Contributor Author

flutter-zl May 22, 2025

Passing null resets _supportsAriaDescription to an uninitialized state.
The backing field _supportsAriaDescription is also nullable (bool?).
This setter is used for testing, to override the browser-detected value.

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart Outdated

                 /// instead.
                 LabelRepresentation preferredRepresentation;
+                String? _describedById;

Contributor

chunhtai May 22, 2025

maybe convert this to a getter so we we don't need to keep them in sync?

String? get _describedById => _describedBySpan?.id

Contributor Author

flutter-zl May 22, 2025

Good idea. Updated.

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart Outdated

+                  _describedBySpan!.setAttribute('hidden', '');
+                  _describedBySpan!.text = hint;
+                  // Attach as a child of the semantics element, not document.body
+                  if (_describedBySpan!.isConnected != true) {

Contributor

chunhtai May 22, 2025

I remember a lint would suggest to use ?? instead of equality for checking nullable boolean

Suggested change

      
                if (_describedBySpan!.isConnected != true) {
          
                if (!(_describedBySpan?.isConnected ?? false)) {

Contributor Author

flutter-zl May 22, 2025

Updated.

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart Outdated

+                  _describedBySpan = null;
+                  _describedById = null;
+                  final String hintId = 'hint-${semanticsObject.id}';
+                  domDocument.getElementById(hintId)?.remove();

Contributor

chunhtai May 22, 2025

what is this for?

Contributor Author

flutter-zl May 22, 2025 •

edited

Loading

Updated the logic and remove dead code a bit.

_describedBySpan?.remove() and _describedBySpan = null; removes our aria-describedby span and clears the reference.

mdebbar reviewed

View reviewed changes

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart Outdated

Comment on lines +551 to +569

+                  if (isSafari) {
+                    final RegExp safariRegexp = RegExp(r'Version\/([0-9]+)\.([0-9]+)');
+                    final RegExpMatch? match = safariRegexp.firstMatch(ui_web.browser.userAgent);
+                    if (match != null) {
+                      final int majorVersion = int.parse(match.group(1)!);
+                      final int minorVersion = int.parse(match.group(2)!);
+                      return majorVersion > 17 || (majorVersion == 17 && minorVersion >= 4);
+                    }
+                    return false;
+                  }
+                  if (isFirefox) {
+                    final RegExp firefoxRegexp = RegExp(r'Firefox\/([0-9]+)');
+                    final RegExpMatch? match = firefoxRegexp.firstMatch(ui_web.browser.userAgent);
+                    if (match != null) {
+                      final int version = int.parse(match.group(1)!);
+                      return version >= 119;
+                    }
+                    return false;
+                  }

Contributor

mdebbar May 22, 2025

In the past, we usually put detection logic in the engine/browser_detection.dart file and expose booleans from there.

You could, for example, introduce a isSafari174OrNewer and isFirefox119OrNewer in engine/browser_detection.dart.

Contributor Author

flutter-zl May 23, 2025

Great suggestion. updated.

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart Outdated

Comment on lines +506 to +510

+                  owner.removeAttribute('aria-description');
+                  owner.removeAttribute('aria-describedby');
+                  if (hint != null && hint.trim().isNotEmpty) {
+                    _setAriaDescriptionOrDescribedBy(hint);
+                  }

Contributor

mdebbar May 22, 2025

Can we avoid removing the attributes when not necessary?

Something like this might work:

Suggested change

      
                owner.removeAttribute('aria-description');
          
                owner.removeAttribute('aria-describedby');
          
                if (hint != null && hint.trim().isNotEmpty) {
          
                  _setAriaDescriptionOrDescribedBy(hint);
          
                }
          
                if (hint != null && hint.trim().isNotEmpty) {
          
                  _setAriaDescriptionOrDescribedBy(hint);
          
                } else {
          
                  owner.removeAttribute('aria-description');
          
                  owner.removeAttribute('aria-describedby');
          
                }

Contributor Author

flutter-zl May 23, 2025

Great suggestion. updated.

flutter-zl force-pushed the hint_0520 branch from 54c6a51 to 35ccbc7 Compare

May 22, 2025 22:07

Merged via the queue into flutter:master with commit 768932e

178 of 179 checks passed

flutter-zl deleted the hint_0520 branch

May 27, 2025 16:24

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request


          768932e Split hint from label and expose it via aria-description or a…

9535aa8

…ria-describedby (flutter/flutter#169157)

This was referenced May 27, 2025

Roll Flutter from 4372bfbc6c23 to 768932e97299 (14 revisions) flutter/packages#9325

Closed

Roll Flutter from 4372bfbc6c23 to 184835f7d8f5 (15 revisions) flutter/packages#9326

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request


          768932e Split hint from label and expose it via aria-description or a…

ae790a0

…ria-describedby (flutter/flutter#169157)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request


          768932e Split hint from label and expose it via aria-description or a…

a030d5b

…ria-describedby (flutter/flutter#169157)

This was referenced May 27, 2025

Roll Flutter from 4372bfbc6c23 to 973701688c46 (17 revisions) flutter/packages#9327

Closed

Roll Flutter from 4372bfbc6c23 to 5d013c73baa7 (26 revisions) flutter/packages#9333

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request


          768932e Split hint from label and expose it via aria-description or a…

23e086a

…ria-describedby (flutter/flutter#169157)

engine-flutter-autoroll mentioned this pull request

Roll Flutter from 4372bfbc6c23 to 0e536eb9fe4b (27 revisions) flutter/packages#9334

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request


          768932e Split hint from label and expose it via aria-description or a…

567e734

…ria-describedby (flutter/flutter#169157)

auto-submit bot pushed a commit to flutter/packages that referenced this pull request


          Roll Flutter from 4372bfb to 0e536eb (27 revisions) (#9334)

325f0fc

flutter/flutter@4372bfb...0e536eb

2025-05-28 [email protected] Introduces FlutterPluginRegistrant protocol. (flutter/flutter#169399)
2025-05-28 98614782+auto-submit[bot]@users.noreply.github.com Reverts "Initialize `default-flavor` in `FlutterCommand`, adds integration test. (#169298)" (flutter/flutter#169581)
2025-05-28 [email protected] Initialize `default-flavor` in `FlutterCommand`, adds integration test. (flutter/flutter#169298)
2025-05-28 [email protected] Update DEPS to  add dart-lang/ai repo (flutter/flutter#169540)
2025-05-28 [email protected] Roll Skia from 92311f2ba0b7 to 82d326fc2148 (1 revision) (flutter/flutter#169552)
2025-05-28 [email protected] dev/bots: improve service worker test code (flutter/flutter#169231)
2025-05-28 [email protected] Make Android team platform view TESTOWNERS (flutter/flutter#169297)
2025-05-28 [email protected] Roll Skia from 044f58f78a73 to 92311f2ba0b7 (9 revisions) (flutter/flutter#169542)
2025-05-27 [email protected] Roll Skia from 443f5257f382 to 044f58f78a73 (16 revisions) (flutter/flutter#169530)
2025-05-27 [email protected] [web] Fix unresponsive input above SelectionArea in Safari and Firefox. (flutter/flutter#167275)
2025-05-27 [email protected] Set pause_isolates_on_start flag if --start-paused (flutter/flutter#169392)
2025-05-27 [email protected] Roll Packages from af0b9a9 to 6eebe72 (24 revisions) (flutter/flutter#169514)
2025-05-27 [email protected] Roll Fuchsia Linux SDK from 5mpmPsuD8rpeiJizT... to nC9hLWjYVlChDTEPh... (flutter/flutter#169498)
2025-05-27 [email protected] Split hint from label and expose it via aria-description or aria-describedby (flutter/flutter#169157)
2025-05-26 [email protected] 🐛 Normalize generated file paths for the l10n generator (flutter/flutter#169467)
2025-05-26 [email protected] Roll Dart SDK from d811152316e4 to 6aeb798bdbe2 (2 revisions) (flutter/flutter#169478)
2025-05-26 [email protected] [Cupertino] Apply RSuperellipse to most Cupertino widgets (flutter/flutter#167784)
2025-05-26 [email protected] Roll `package:dds` to 5.0.2 (flutter/flutter#169471)
2025-05-26 [email protected] Use `.flutter-plugins-dependencies` for crash reporting. (flutter/flutter#169319)
2025-05-26 [email protected] Remove now disabled code that would generate `.flutter-plugins`. (flutter/flutter#169320)
2025-05-26 [email protected] Roll Dart SDK from 7dab9bffe1f7 to d811152316e4 (1 revision) (flutter/flutter#169473)
2025-05-26 [email protected] Precise browser resizing with integration_test and driver (flutter/flutter#160678)
2025-05-26 [email protected] Add `/coverage/` to `.gitignore.tmp` (flutter/flutter#169387)
2025-05-26 [email protected] Make test output with encoded `dart-defines=...` human readable. (flutter/flutter#169353)
2025-05-26 [email protected] Use at most `PROC~/2` tasks to transform assets. (flutter/flutter#169386)
2025-05-26 [email protected] Forward exit code from dart test to flutter test (flutter/flutter#168604)
2025-05-26 [email protected] Fix warning when building for macOS desktop (flutter/flutter#165996)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected],[email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

FMorschel pushed a commit to FMorschel/packages that referenced this pull request


          Roll Flutter from 4372bfb to 0e536eb (27 revisions) (flutter#9334)

cfa0dbd

flutter/flutter@4372bfb...0e536eb

2025-05-28 [email protected] Introduces FlutterPluginRegistrant protocol. (flutter/flutter#169399)
2025-05-28 98614782+auto-submit[bot]@users.noreply.github.com Reverts "Initialize `default-flavor` in `FlutterCommand`, adds integration test. (#169298)" (flutter/flutter#169581)
2025-05-28 [email protected] Initialize `default-flavor` in `FlutterCommand`, adds integration test. (flutter/flutter#169298)
2025-05-28 [email protected] Update DEPS to  add dart-lang/ai repo (flutter/flutter#169540)
2025-05-28 [email protected] Roll Skia from 92311f2ba0b7 to 82d326fc2148 (1 revision) (flutter/flutter#169552)
2025-05-28 [email protected] dev/bots: improve service worker test code (flutter/flutter#169231)
2025-05-28 [email protected] Make Android team platform view TESTOWNERS (flutter/flutter#169297)
2025-05-28 [email protected] Roll Skia from 044f58f78a73 to 92311f2ba0b7 (9 revisions) (flutter/flutter#169542)
2025-05-27 [email protected] Roll Skia from 443f5257f382 to 044f58f78a73 (16 revisions) (flutter/flutter#169530)
2025-05-27 [email protected] [web] Fix unresponsive input above SelectionArea in Safari and Firefox. (flutter/flutter#167275)
2025-05-27 [email protected] Set pause_isolates_on_start flag if --start-paused (flutter/flutter#169392)
2025-05-27 [email protected] Roll Packages from af0b9a9 to 6eebe72 (24 revisions) (flutter/flutter#169514)
2025-05-27 [email protected] Roll Fuchsia Linux SDK from 5mpmPsuD8rpeiJizT... to nC9hLWjYVlChDTEPh... (flutter/flutter#169498)
2025-05-27 [email protected] Split hint from label and expose it via aria-description or aria-describedby (flutter/flutter#169157)
2025-05-26 [email protected] 🐛 Normalize generated file paths for the l10n generator (flutter/flutter#169467)
2025-05-26 [email protected] Roll Dart SDK from d811152316e4 to 6aeb798bdbe2 (2 revisions) (flutter/flutter#169478)
2025-05-26 [email protected] [Cupertino] Apply RSuperellipse to most Cupertino widgets (flutter/flutter#167784)
2025-05-26 [email protected] Roll `package:dds` to 5.0.2 (flutter/flutter#169471)
2025-05-26 [email protected] Use `.flutter-plugins-dependencies` for crash reporting. (flutter/flutter#169319)
2025-05-26 [email protected] Remove now disabled code that would generate `.flutter-plugins`. (flutter/flutter#169320)
2025-05-26 [email protected] Roll Dart SDK from 7dab9bffe1f7 to d811152316e4 (1 revision) (flutter/flutter#169473)
2025-05-26 [email protected] Precise browser resizing with integration_test and driver (flutter/flutter#160678)
2025-05-26 [email protected] Add `/coverage/` to `.gitignore.tmp` (flutter/flutter#169387)
2025-05-26 [email protected] Make test output with encoded `dart-defines=...` human readable. (flutter/flutter#169353)
2025-05-26 [email protected] Use at most `PROC~/2` tasks to transform assets. (flutter/flutter#169386)
2025-05-26 [email protected] Forward exit code from dart test to flutter test (flutter/flutter#168604)
2025-05-26 [email protected] Fix warning when building for macOS desktop (flutter/flutter#165996)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected],[email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

flutter-zl mentioned this pull request

Flutter Web: aria-describedby must be an available property on all component types (Accessibility) #162140

Closed

Ortes pushed a commit to Ortes/packages that referenced this pull request


          Roll Flutter from 4372bfb to 0e536eb (27 revisions) (flutter#9334)

flutter/flutter@4372bfb...0e536eb

2025-05-28 [email protected] Introduces FlutterPluginRegistrant protocol. (flutter/flutter#169399)
2025-05-28 98614782+auto-submit[bot]@users.noreply.github.com Reverts "Initialize `default-flavor` in `FlutterCommand`, adds integration test. (#169298)" (flutter/flutter#169581)
2025-05-28 [email protected] Initialize `default-flavor` in `FlutterCommand`, adds integration test. (flutter/flutter#169298)
2025-05-28 [email protected] Update DEPS to  add dart-lang/ai repo (flutter/flutter#169540)
2025-05-28 [email protected] Roll Skia from 92311f2ba0b7 to 82d326fc2148 (1 revision) (flutter/flutter#169552)
2025-05-28 [email protected] dev/bots: improve service worker test code (flutter/flutter#169231)
2025-05-28 [email protected] Make Android team platform view TESTOWNERS (flutter/flutter#169297)
2025-05-28 [email protected] Roll Skia from 044f58f78a73 to 92311f2ba0b7 (9 revisions) (flutter/flutter#169542)
2025-05-27 [email protected] Roll Skia from 443f5257f382 to 044f58f78a73 (16 revisions) (flutter/flutter#169530)
2025-05-27 [email protected] [web] Fix unresponsive input above SelectionArea in Safari and Firefox. (flutter/flutter#167275)
2025-05-27 [email protected] Set pause_isolates_on_start flag if --start-paused (flutter/flutter#169392)
2025-05-27 [email protected] Roll Packages from af0b9a9 to 6eebe72 (24 revisions) (flutter/flutter#169514)
2025-05-27 [email protected] Roll Fuchsia Linux SDK from 5mpmPsuD8rpeiJizT... to nC9hLWjYVlChDTEPh... (flutter/flutter#169498)
2025-05-27 [email protected] Split hint from label and expose it via aria-description or aria-describedby (flutter/flutter#169157)
2025-05-26 [email protected] 🐛 Normalize generated file paths for the l10n generator (flutter/flutter#169467)
2025-05-26 [email protected] Roll Dart SDK from d811152316e4 to 6aeb798bdbe2 (2 revisions) (flutter/flutter#169478)
2025-05-26 [email protected] [Cupertino] Apply RSuperellipse to most Cupertino widgets (flutter/flutter#167784)
2025-05-26 [email protected] Roll `package:dds` to 5.0.2 (flutter/flutter#169471)
2025-05-26 [email protected] Use `.flutter-plugins-dependencies` for crash reporting. (flutter/flutter#169319)
2025-05-26 [email protected] Remove now disabled code that would generate `.flutter-plugins`. (flutter/flutter#169320)
2025-05-26 [email protected] Roll Dart SDK from 7dab9bffe1f7 to d811152316e4 (1 revision) (flutter/flutter#169473)
2025-05-26 [email protected] Precise browser resizing with integration_test and driver (flutter/flutter#160678)
2025-05-26 [email protected] Add `/coverage/` to `.gitignore.tmp` (flutter/flutter#169387)
2025-05-26 [email protected] Make test output with encoded `dart-defines=...` human readable. (flutter/flutter#169353)
2025-05-26 [email protected] Use at most `PROC~/2` tasks to transform assets. (flutter/flutter#169386)
2025-05-26 [email protected] Forward exit code from dart test to flutter test (flutter/flutter#168604)
2025-05-26 [email protected] Fix warning when building for macOS desktop (flutter/flutter#165996)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected],[email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request


          768932e Split hint from label and expose it via aria-description or a…

327425d

…ria-describedby (flutter/flutter#169157)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request


          768932e Split hint from label and expose it via aria-description or a…

06f1fca

…ria-describedby (flutter/flutter#169157)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request


          768932e Split hint from label and expose it via aria-description or a…

52ac350

…ria-describedby (flutter/flutter#169157)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request


          768932e Split hint from label and expose it via aria-description or a…

bea8ad4

…ria-describedby (flutter/flutter#169157)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request


          768932e Split hint from label and expose it via aria-description or a…

9fa0344

…ria-describedby (flutter/flutter#169157)

yuan-kuan commented Dec 23, 2025

Not sure if this is the right place. I came here from #162140. I was unable to reopen the issue for investigation. I think this is not the right fix.

is not superseded by

In term of accesibility, especially in context of WCAG 2.2, we still need describedby to correctly semantically link the form control to the error message. describedby takes an element's ID, not a String.

@flutter-zl @chunhtai @mdebbar. Please advice how best we can steer this to the correct course.

flutter-zl mentioned this pull request

[web] Form validation errors not linked to inputs via aria-describedby (WCAG 2.2 compliance) #180496

Open

Contributor Author

flutter-zl commented Jan 5, 2026

Not sure if this is the right place. I came here from #162140. I was unable to reopen the issue for investigation. I think this is not the right fix.

describedby

is not superseded by

description

In term of accesibility, especially in context of WCAG 2.2, we still need describedby to correctly semantically link the form control to the error message. describedby takes an element's ID, not a String.

@flutter-zl @chunhtai @mdebbar. Please advice how best we can steer this to the correct course.

I believe this PR is correct for its intended scope (hint text). For form validation error linking, I created a specific feature request in #180496.

This was referenced Jan 6, 2026

[web] Pass form validation errors to screen readers via aria-description #180556

Merged

[web] Pass form validation errors to screen readers via aria-description #180791

Closed

github-merge-queue bot pushed a commit that referenced this pull request


          [web] Pass form validation errors to screen readers via aria-descript…

c023e5b

…ion (#180556)

Fixes part of #180496

## Summary
Pass form validation errors to screen readers via `aria-description` on
text fields.

**Before:** 
https://flutter-demo-04-before.web.app/

**After:** 
https://flutter-demo-04-after.web.app/

## Limitations & Future Work

This handles **string-based errors** (`errorText`). For more complex
cases(brought in
#180496 (comment)),
a follow-up implementation using `aria-describedby` with element IDs is
tracked in #180496:

- Custom error widgets (`InputDecoration.error`)
- Errors outside `InputDecoration`
- Custom announcement ordering

The `aria-description` approach (current) and `aria-describedby`
approach (future) can coexist per ARIA specifications.

## Related
- Related discussion: #169157 comments

rickhohler pushed a commit to rickhohler/flutter that referenced this pull request


          [web] Pass form validation errors to screen readers via aria-descript…

842e20f

…ion (flutter#180556)

Fixes part of flutter#180496

## Summary
Pass form validation errors to screen readers via `aria-description` on
text fields.

**Before:** 
https://flutter-demo-04-before.web.app/

**After:** 
https://flutter-demo-04-after.web.app/

## Limitations & Future Work

This handles **string-based errors** (`errorText`). For more complex
cases(brought in
flutter#180496 (comment)),
a follow-up implementation using `aria-describedby` with element IDs is
tracked in flutter#180496:

- Custom error widgets (`InputDecoration.error`)
- Errors outside `InputDecoration`
- Custom announcement ordering

The `aria-description` approach (current) and `aria-describedby`
approach (future) can coexist per ARIA specifications.

## Related
- Related discussion: flutter#169157 comments

ahmedsameha1 pushed a commit to ahmedsameha1/flutter that referenced this pull request


          [web] Pass form validation errors to screen readers via aria-descript…

1a5abcf

…ion (flutter#180556)

Fixes part of flutter#180496

## Summary
Pass form validation errors to screen readers via `aria-description` on
text fields.

**Before:** 
https://flutter-demo-04-before.web.app/

**After:** 
https://flutter-demo-04-after.web.app/

## Limitations & Future Work

This handles **string-based errors** (`errorText`). For more complex
cases(brought in
flutter#180496 (comment)),
a follow-up implementation using `aria-describedby` with element IDs is
tracked in flutter#180496:

- Custom error widgets (`InputDecoration.error`)
- Errors outside `InputDecoration`
- Custom announcement ordering

The `aria-description` approach (current) and `aria-describedby`
approach (future) can coexist per ARIA specifications.

## Related
- Related discussion: flutter#169157 comments

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

a: accessibility engine platform-web