docs(material/stepper): expand a11y section #23617

amysorto · 2021-09-22T15:59:31Z

No description provided.

crisbeto · 2021-09-22T17:04:55Z

src/material/stepper/stepper.md

@@ -222,3 +222,19 @@ is given `role="tab"`, and the content that can be expanded upon selection is gi
 step content is automatically set based on step selection change.

 The stepper and each step should be given a meaningful label via `aria-label` or `aria-labelledby`.
+
+When a stepper is used on a smaller screen, verical steppers are preferred over


verical -> vertical

Prefer vertical steppers when building for small screen sizes, as horizontal steppers typically take up significantly more horizontal space, thus introducing horizontal scrolling. Applications with multiple scrolling dimensions make content harder to consume for some users. See the [Responsive Stepper section](#responsive-stepper) above for an example on building a stepper that adjusts its layout based on viewport size.

Eliminates passive voice (e.g. "stepper is used", "steppers are preferred")

Adds some context on why folks would want to be careful with horizontal steppers on small screens

Links to the example above

crisbeto · 2021-09-22T17:05:26Z

src/material/stepper/stepper.md

@@ -222,3 +222,19 @@ is given `role="tab"`, and the content that can be expanded upon selection is gi
 step content is automatically set based on step selection change.

 The stepper and each step should be given a meaningful label via `aria-label` or `aria-labelledby`.
+
+When a stepper is used on a smaller screen, verical steppers are preferred over
+horizontal steppers because the text in the header will be more visible.


Might be worth mentioning here that there's an example of a responsive stepper further up in the doc.

crisbeto · 2021-09-22T17:05:41Z

src/material/stepper/stepper.md

+horizontal steppers because the text in the header will be more visible.
+
+#### Forms
+Steppers often have forms inside of it. It's best practice for form fields to


inside of it -> inside of them

Suggested change

Steppers often have forms inside of it. It's best practice for form fields to

Steppers often contain forms and form controls. If validation errors inside of a stepper's form prevents moving to another step, make sure that your form controls communicate error messages to assistive technology. This helps the user know why they can't advance to another step. You can accomplish this by using `<mat-error>` with `<mat-form-field>`, or by using an ARIA live region.

Changes for passive voice and grammar

Clarify that <mat-error> is one possible way to communicate updates

crisbeto · 2021-09-22T17:06:15Z

src/material/stepper/stepper.md

+
+#### Forms
+Steppers often have forms inside of it. It's best practice for form fields to
+have `<mat-error>` for fields that can be incorrect and throw an error.


nit: I'm not sure that "throw an error" is the correct terminology here since it sounds like there was an actual runtime error, whereas these are validation errors.

jelbourn · 2021-09-22T18:13:34Z

src/material/stepper/stepper.md

@@ -222,3 +222,19 @@ is given `role="tab"`, and the content that can be expanded upon selection is gi
 step content is automatically set based on step selection change.

 The stepper and each step should be given a meaningful label via `aria-label` or `aria-labelledby`.
+
+When a stepper is used on a smaller screen, verical steppers are preferred over


Prefer vertical steppers when building for small screen sizes, as horizontal steppers typically take up significantly more horizontal space, thus introducing horizontal scrolling. Applications with multiple scrolling dimensions make content harder to consume for some users. See the [Responsive Stepper section](#responsive-stepper) above for an example on building a stepper that adjusts its layout based on viewport size.

Eliminates passive voice (e.g. "stepper is used", "steppers are preferred")

Adds some context on why folks would want to be careful with horizontal steppers on small screens

Links to the example above

jelbourn · 2021-09-22T18:19:50Z

src/material/stepper/stepper.md

+horizontal steppers because the text in the header will be more visible.
+
+#### Forms
+Steppers often have forms inside of it. It's best practice for form fields to


Suggested change

Steppers often have forms inside of it. It's best practice for form fields to

Steppers often contain forms and form controls. If validation errors inside of a stepper's form prevents moving to another step, make sure that your form controls communicate error messages to assistive technology. This helps the user know why they can't advance to another step. You can accomplish this by using `<mat-error>` with `<mat-form-field>`, or by using an ARIA live region.

Changes for passive voice and grammar

Clarify that <mat-error> is one possible way to communicate updates

jelbourn · 2021-09-22T18:27:39Z

src/material/stepper/stepper.md

+When you navigate away from a step with an error in a non-linear stepper, the
+error message appears in the step header. Announcing the error with
+`liveAnnouncer` will help screen reader users know that the step they just
+navigated away from has an error.


Suggested change

When you navigate away from a step with an error in a non-linear stepper, the

error message appears in the step header. Announcing the error with

`liveAnnouncer` will help screen reader users know that the step they just

navigated away from has an error.

When a step contains a forms validation error, `MatStepper` will display the error in the step's header. For non-linear steppers, you should use an ARIA live region to announce error messages when users navigate away from a step with an error message.

Is this accurate to what you're trying to get across?

amysorto · 2021-09-23T00:18:49Z

Thanks for the comments!

jelbourn

lgtm aside from one typo (which probably came from me)

you can mark this PR as "merge ready" when done

jelbourn · 2021-09-23T16:41:46Z

src/material/stepper/stepper.md

@@ -222,3 +222,23 @@ is given `role="tab"`, and the content that can be expanded upon selection is gi
 step content is automatically set based on step selection change.

 The stepper and each step should be given a meaningful label via `aria-label` or `aria-labelledby`.
+
+Prefer verticl steppers when building for small screen sizes, as horizontal
+steppers typically take up significantly more horizontal space thus introducing


Suggested change

steppers typically take up significantly more horizontal space thus introducing

steppers typically take up significantly more horizontal space thus introduce

(cherry picked from commit 8c81fb7)

angular-automatic-lock-bot · 2021-10-24T00:02:42Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

amysorto added P2 The issue is important to a large percentage of users, with a workaround Accessibility This issue is related to accessibility (a11y) docs This issue is related to documentation target: patch This PR is targeted for the next patch release area: material/stepper labels Sep 22, 2021

amysorto requested review from jelbourn and zarend September 22, 2021 15:59

amysorto requested a review from mmalerba as a code owner September 22, 2021 15:59

google-cla bot added the cla: yes PR author has agreed to Google's Contributor License Agreement label Sep 22, 2021

crisbeto reviewed Sep 22, 2021

View reviewed changes

jelbourn reviewed Sep 22, 2021

View reviewed changes

amysorto force-pushed the stepper-a11y-docs branch from 4788383 to 264dee4 Compare September 23, 2021 00:17

jelbourn approved these changes Sep 23, 2021

View reviewed changes

jelbourn added the merge safe label Sep 23, 2021

docs(material/stepper): expand a11y section

d3325bf

amysorto force-pushed the stepper-a11y-docs branch from 264dee4 to d3325bf Compare September 23, 2021 17:19

amysorto added the action: merge The PR is ready for merge by the caretaker label Sep 23, 2021

amysorto merged commit 8c81fb7 into angular:master Sep 23, 2021

amysorto added a commit that referenced this pull request Sep 23, 2021

docs(material/stepper): expand a11y section (#23617)

bab8bf9

(cherry picked from commit 8c81fb7)

sync-by-unito bot mentioned this pull request Oct 1, 2021

build(deps): bump @angular/material from 12.2.4 to 12.2.8 numbersprotocol/capture-lite#925

Closed

angular-automatic-lock-bot bot locked and limited conversation to collaborators Oct 24, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(material/stepper): expand a11y section #23617

docs(material/stepper): expand a11y section #23617

amysorto commented Sep 22, 2021

crisbeto Sep 22, 2021

jelbourn Sep 22, 2021

crisbeto Sep 22, 2021

crisbeto Sep 22, 2021

jelbourn Sep 22, 2021

crisbeto Sep 22, 2021

jelbourn Sep 22, 2021

jelbourn Sep 22, 2021

jelbourn Sep 22, 2021

amysorto commented Sep 23, 2021

jelbourn left a comment

jelbourn Sep 23, 2021

angular-automatic-lock-bot bot commented Oct 24, 2021

	Steppers often have forms inside of it. It's best practice for form fields to
	Steppers often contain forms and form controls. If validation errors inside of a stepper's form prevents moving to another step, make sure that your form controls communicate error messages to assistive technology. This helps the user know why they can't advance to another step. You can accomplish this by using `<mat-error>` with `<mat-form-field>`, or by using an ARIA live region.

	steppers typically take up significantly more horizontal space thus introducing
	steppers typically take up significantly more horizontal space thus introduce

docs(material/stepper): expand a11y section #23617

docs(material/stepper): expand a11y section #23617

Conversation

amysorto commented Sep 22, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amysorto commented Sep 23, 2021

jelbourn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

angular-automatic-lock-bot bot commented Oct 24, 2021