Semantics headingLeveldoc update #179999
Merged
Semantics headingLeveldoc update #179999
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for SemanticsProperties.headingLevel to include its effect on Android, which is a great improvement for accuracy. I've suggested a further enhancement to also include its effect on iOS and clarify the meaning of a headingLevel of 0, making the documentation even more comprehensive.
Comment on lines
+2159
to
+2167
| /// The heading level in the document structure. | ||
| /// | ||
| /// Screen readers will use this value to determine which part of the page | ||
| /// structure this heading represents. A level 1 heading, indicated | ||
| /// with aria-level="1", usually indicates the main heading of a page, | ||
| /// a level 2 heading, defined with aria-level="2" the first subsection, | ||
| /// structure this heading represents. A level 1 heading usually indicates | ||
| /// the main heading of a page, a level 2 heading the first subsection, | ||
| /// a level 3 is a subsection of that, and so on. | ||
| /// | ||
| /// On web, this sets the `aria-level` attribute (e.g., `aria-level="1"`). | ||
| /// On Android, this sets the `isHeading` property for accessibility. |
Contributor
There was a problem hiding this comment.
This documentation update is a good improvement. To make it even more comprehensive, I suggest also mentioning its effect on iOS and clarifying the meaning of a headingLevel of 0, similar to the documentation for SemanticsData.headingLevel.
On iOS, setting headingLevel to a value greater than 0 applies the UIAccessibilityTraitHeader trait. A headingLevel of 0 indicates that the node is not a heading.
/// The heading level in the document structure.
///
/// A value of 0 indicates that this node is not a heading. The value should be
/// a number between 1 and 6, indicating the hierarchical level as a heading.
///
/// Screen readers will use this value to determine which part of the page
/// structure this heading represents. A level 1 heading usually indicates
/// the main heading of a page, a level 2 heading the first subsection,
/// a level 3 is a subsection of that, and so on.
///
/// On the web, this sets the 'aria-level' attribute (e.g., 'aria-level="1"').
/// On Android, this sets the 'isHeading' property for accessibility.
/// On iOS, this sets the 'UIAccessibilityTraitHeader' trait.
Contributor
There was a problem hiding this comment.
in iOS header translate to header trait, it has a different api https://developer.apple.com/documentation/swiftui/view/accessibilityheading(_:) to handle heading level, but we didn't wire it up
|
Golden file changes have been found for this pull request. Click here to view and triage (e.g. because this is an intentional change). If you are still iterating on this change and are not ready to resolve the images on the Flutter Gold dashboard, consider marking this PR as a draft pull request above. You will still be able to view image results on the dashboard, commenting will be silenced, and the check will not try to resolve itself until marked ready for review. For more guidance, visit Writing a golden file test for Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. |
chunhtai
approved these changes
Dec 17, 2025
Contributor
chunhtai
left a comment
There was a problem hiding this comment.
LGTM, thanks for fixing the doc!
Comment on lines
+2159
to
+2167
| /// The heading level in the document structure. | ||
| /// | ||
| /// Screen readers will use this value to determine which part of the page | ||
| /// structure this heading represents. A level 1 heading, indicated | ||
| /// with aria-level="1", usually indicates the main heading of a page, | ||
| /// a level 2 heading, defined with aria-level="2" the first subsection, | ||
| /// structure this heading represents. A level 1 heading usually indicates | ||
| /// the main heading of a page, a level 2 heading the first subsection, | ||
| /// a level 3 is a subsection of that, and so on. | ||
| /// | ||
| /// On web, this sets the `aria-level` attribute (e.g., `aria-level="1"`). | ||
| /// On Android, this sets the `isHeading` property for accessibility. |
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 20, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 20, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 21, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 21, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 21, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 22, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 22, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 22, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 23, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 23, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 23, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 23, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 23, 2025
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Dec 23, 2025
auto-submit bot
pushed a commit
to flutter/packages
that referenced
this pull request
Dec 23, 2025
Manual roll Flutter from 57c3f8b to 6ff7f30 (83 revisions) Manual roll requested by stuartmorgan@google.com flutter/flutter@57c3f8b...6ff7f30 2025-12-23 engine-flutter-autoroll@skia.org Roll Packages from f28cf2e to 5e3a766 (3 revisions) (flutter/flutter#180232) 2025-12-23 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from CmFPyvSc-K8_WDd5p... to 5EgkVbjGVZmCFPdtR... (flutter/flutter#180230) 2025-12-23 engine-flutter-autoroll@skia.org Roll Skia from db7ec9a14905 to bdb147ae3040 (2 revisions) (flutter/flutter#180222) 2025-12-23 bruno.leroux@gmail.com Add SnackBarTheme (flutter/flutter#180001) 2025-12-23 engine-flutter-autoroll@skia.org Roll Skia from 0b1ba3920f1c to db7ec9a14905 (1 revision) (flutter/flutter#180219) 2025-12-23 engine-flutter-autoroll@skia.org Roll Dart SDK from 31e9f619e18a to 94b05f717ba3 (1 revision) (flutter/flutter#180216) 2025-12-23 engine-flutter-autoroll@skia.org Roll Skia from a3e4f7b9d5f3 to 0b1ba3920f1c (1 revision) (flutter/flutter#180214) 2025-12-23 engine-flutter-autoroll@skia.org Roll Skia from b8517d1e25f7 to a3e4f7b9d5f3 (2 revisions) (flutter/flutter#180211) 2025-12-23 dkwingsmt@users.noreply.github.com [Engine] iOS style blurring (flutter/flutter#175458) 2025-12-23 engine-flutter-autoroll@skia.org Roll Dart SDK from 2243e91acaf2 to 31e9f619e18a (1 revision) (flutter/flutter#180210) 2025-12-22 36861262+QuncCccccc@users.noreply.github.com Add error description for nbsp character(\u202f) (flutter/flutter#178895) 2025-12-22 engine-flutter-autoroll@skia.org Roll Skia from 98c01ea504d7 to b8517d1e25f7 (1 revision) (flutter/flutter#180207) 2025-12-22 116356835+AbdeMohlbi@users.noreply.github.com Small clean up in `LocalizationPlugin` (flutter/flutter#180053) 2025-12-22 engine-flutter-autoroll@skia.org Roll Skia from c5beca8fa90b to 98c01ea504d7 (2 revisions) (flutter/flutter#180202) 2025-12-22 engine-flutter-autoroll@skia.org Roll Dart SDK from cff33b09b24d to 2243e91acaf2 (1 revision) (flutter/flutter#180199) 2025-12-22 116356835+AbdeMohlbi@users.noreply.github.com Remove usages of Android's `AsyncTask` in favor of `java.util.concurrent` (flutter/flutter#180050) 2025-12-22 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from 18ZvfJB61p7Z8HAaC... to CmFPyvSc-K8_WDd5p... (flutter/flutter#180193) 2025-12-22 engine-flutter-autoroll@skia.org Roll Skia from 7b7083ed9d57 to c5beca8fa90b (5 revisions) (flutter/flutter#180187) 2025-12-22 engine-flutter-autoroll@skia.org Roll Dart SDK from 38812d17127d to cff33b09b24d (1 revision) (flutter/flutter#180185) 2025-12-22 engine-flutter-autoroll@skia.org Roll Skia from 0eef18a0e2e6 to 7b7083ed9d57 (1 revision) (flutter/flutter#180184) 2025-12-22 engine-flutter-autoroll@skia.org Roll Dart SDK from 66c8013acbff to 38812d17127d (1 revision) (flutter/flutter#180179) 2025-12-21 engine-flutter-autoroll@skia.org Roll Skia from 6fbc6c75b9bb to 0eef18a0e2e6 (2 revisions) (flutter/flutter#180176) 2025-12-21 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from kGnnY1-fTWwYAnk8e... to 18ZvfJB61p7Z8HAaC... (flutter/flutter#180173) 2025-12-21 engine-flutter-autoroll@skia.org Roll Skia from 1a4ca755288a to 6fbc6c75b9bb (1 revision) (flutter/flutter#180167) 2025-12-20 engine-flutter-autoroll@skia.org Roll Skia from 2ad7452bd9d1 to 1a4ca755288a (1 revision) (flutter/flutter#180160) 2025-12-20 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from oe10epXkqGnv21AbZ... to kGnnY1-fTWwYAnk8e... (flutter/flutter#180158) 2025-12-20 engine-flutter-autoroll@skia.org Roll Skia from b01ad49ea807 to 2ad7452bd9d1 (1 revision) (flutter/flutter#180155) 2025-12-20 engine-flutter-autoroll@skia.org Roll Dart SDK from 8fb1c0c0a8ae to 66c8013acbff (1 revision) (flutter/flutter#180154) 2025-12-20 737941+loic-sharma@users.noreply.github.com Remove unnecessary RadioGroup migration TODOs (flutter/flutter#180105) 2025-12-20 98614782+auto-submit[bot]@users.noreply.github.com Reverts "[reland] Unify canvas creation and Surface code in Skwasm and CanvasKit (#179473)" (flutter/flutter#180152) 2025-12-20 engine-flutter-autoroll@skia.org Roll Skia from 3cc7e81928f0 to b01ad49ea807 (1 revision) (flutter/flutter#180151) 2025-12-20 engine-flutter-autoroll@skia.org Roll Dart SDK from ac95c6e8a31d to 8fb1c0c0a8ae (1 revision) (flutter/flutter#180148) 2025-12-19 137456488+flutter-pub-roller-bot@users.noreply.github.com Roll pub packages (flutter/flutter#180146) 2025-12-19 engine-flutter-autoroll@skia.org Roll Skia from fa4434632ce6 to 3cc7e81928f0 (4 revisions) (flutter/flutter#180142) 2025-12-19 1961493+harryterkelsen@users.noreply.github.com [reland] Unify canvas creation and Surface code in Skwasm and CanvasKit (flutter/flutter#179473) 2025-12-19 engine-flutter-autoroll@skia.org Roll Skia from ae5dd72b3591 to fa4434632ce6 (2 revisions) (flutter/flutter#180136) 2025-12-19 45459898+RamonFarizel@users.noreply.github.com Semantics headingLeveldoc update (flutter/flutter#179999) 2025-12-19 matt.kosarek@canonical.com Fix an issue where the semantics announce event may be encoded as either an int32_t or an int64_t depending on its value (flutter/flutter#180071) 2025-12-19 bkonyi@google.com [ Web ] Pass `--enable-experimental-ffi` when compiling WASM tests (flutter/flutter#180127) 2025-12-19 engine-flutter-autoroll@skia.org Roll Dart SDK from cfc117d10d36 to ac95c6e8a31d (1 revision) (flutter/flutter#180130) 2025-12-19 58529443+srujzs@users.noreply.github.com Pass canaryFeatures to BuildSettings (flutter/flutter#180108) 2025-12-19 engine-flutter-autoroll@skia.org Roll Skia from fe2be289c9fe to ae5dd72b3591 (1 revision) (flutter/flutter#180129) 2025-12-19 engine-flutter-autoroll@skia.org Roll Packages from 6f392aa to f28cf2e (1 revision) (flutter/flutter#180124) 2025-12-19 94012149+richardexfo@users.noreply.github.com Set text input purpose and hints on Linux platform (flutter/flutter#180013) ...
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
headingLevel updated to indicate that it also affects Android.
Fix: #179998
Pre-launch Checklist
///).If you need help, consider asking for advice on the #hackers-new channel on Discord.
Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the
gemini-code-assistbot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.