chore(Page): updated a11y docs to new template #3880
Conversation
thatblindgeye
requested review from
a team and
jessiehuff
and removed request for
a team
thatblindgeye
force-pushed
the
iss3874_pageA11yUpdate
branch
from
ebf0590 to
0bacd76
Compare
|
|
||
| **Screen reader users** should be able to navigate through and interact with the masthead of the page using the same interactions as keyboard users. Elements of a page that do not have visible descriptive text, such as toggle icons, should have alternative text for screen readers. | ||
| - Provide a [skip to content](/components/skip-to-content) if more than one page shares the same heading or sidebar content. | ||
| - Give each `nav` element on the page a unique `aria-label`. |
There was a problem hiding this comment.
I typically only see this guidance when there is more than one nav. I think it might make sense to clarify that in this bullet? I'm just noticing that you do include that verbiage in the testing section below so I think updating this one makes sense
There was a problem hiding this comment.
Ah good catch, agreed we should be consistent in the verbiage.
Though now I'm slightly conflicted, in that I'm wondering if we should say that a nav should have a unique label regardless of amount, i.e. whether there's 7 or only 1. I guess I'm thinking in terms of rotor menus/wherever a list of X element types are listed out (lists, headings, etc). Even with only 1 nav (or list, or whatever) on a page, I feel like providing an aria-label can only help, whereas omitting one could possibly hurt?
For example, if the nav is announced as just "nav' to a user, it could be site navigation, page navigation, breadcrumb navigation, etc. So what the user would be jumping to could be a bit of an unknown.
What do you think, though?
There was a problem hiding this comment.
I think it definitely could be helpful, but I'm wondering if it's fully required. I wonder if we could explain how it can be helpful but say that it's only required when there's multiple? (And maybe we could even give the examples you just stated.)
There was a problem hiding this comment.
Maybe, "If there are multiple nav elements on the page, give each one a unique aria-label." as the checkbox label, then a description of, "You should also consider providing an aria-label when there's only a single nav on the page, if the purpose of that nav is not the primary navigation."
Or something along those lines? Not sure how I feel about "primary navigation"; "primary site navigation", really just wanting to convey "something that isn't the typical navigation for a page"
There was a problem hiding this comment.
Yeah, I think that makes sense! And I think calling it a primary navigation isn't inherently bad. You could even work with those words a bit between both and say something like, "You should also consider providing an aria-label when there's only a single nav on the page, if the purpose of that nav isn't a typical, primary navigation for a page." (To be honest though, I think all of these options are probably fine though and hopefully get the point across.)
| - Provide a [skip to content](/components/skip-to-content) if more than one page shares the same heading or sidebar content. | ||
| - Give each `nav` element on the page a unique `aria-label`. | ||
| - Ensure there is only 1 `main` element on the page. | ||
| - Ensure each page section has an `aria-labelledby` attribute linked to a heading element within the section. |
There was a problem hiding this comment.
This is a really good point, and potentially unrelated to this PR, but are we actually following this recommendation in our Page demos?
There was a problem hiding this comment.
Can't recall off the top of my head but erring on the side of caution I want to say we may not be. That would require a follow up in Core and React, which I can evaluate which, if any, examples/demos need to be updated and create any necessary followups. Probably need to go through Org as well.
You're referring to the last bullet regarding aria-labelledby, correct?
There was a problem hiding this comment.
Right. I'm not sure if we've ever had our sections labelled by the headings. Out of curiosity, what made you think of this one? I'm not sure I'd heard it before, even though it makes a lot of sense.
There was a problem hiding this comment.
I thought it was an MDN docs page but maybe not, it may have been traversing through VO's rotor menu again. Or one of our a11y pages that mention sections shouldn't be used if there's no label/our example of providing a label for scrollable content.
If we do want to keep this it would probably make sense to update it to say use either aria-labelledby or aria-label if no visible text is present, but it may actually make sense to remove (even if for now). I want to say the main reason was rotot menu, though; not having a huge section of content announced in the rotor menu and instead have a descriptive aria label of some kind.
There was a problem hiding this comment.
Yeah, it makes sense to do, and I'm always up for adding more/better context to help users. I just hesitate to make recommendations if we aren't already walking that walk, so to speak. 🙂
There was a problem hiding this comment.
Definitely true. I think my thoughts were get a11y docs up to date and update core/react examples as follow ups according to the updated docs, though it may make more sense to not include stuff that we aren't following yet ourselves.
What do you think about me removing the verbiage about labeling page sections from this PR, opening issues in core/react to add consistent labeling, then once those are closed out we open a followup in Org to add in the verbaige about labeling sections?
There was a problem hiding this comment.
I think that would make sense to me!
thatblindgeye
force-pushed
the
iss3874_pageA11yUpdate
branch
from
0bacd76 to
7490316
Compare
|
@jessiehuff patternfly/patternfly-react#10173 and patternfly/patternfly#6431 regarding convo above, otherwise updates have been made here |
* chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.15 - @patternfly/documentation-framework@5.3.15 * docs(extensions): Updates the extensions landing page to add reference to the component groups extension. (#3849) * (docs(extensions): Updates the extensions landing page to add reference to the component groups extension. * Update packages/documentation-site/patternfly-docs/pages/landing-pages/extensions/extensions-data.json * typo update * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.16 - @patternfly/documentation-framework@5.3.16 * docs(accessibility-design): Adds new documentation to support content audit. (#3781) * docs(accessibility-design): Adds new documentation to support content audit. * Test page name change * Apply suggestions from code review * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md * Remove table * Removes numbers from headings. * Makes content updates and adds images. * Updates to content describing images. * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.17 - @patternfly/documentation-framework@5.3.17 * fix: bump puppeteer to fix core (#3860) * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.18 - @patternfly/documentation-framework@5.3.18 * Update naming for introductory pages across website sections. (#3851) * Update naming for introductory pages across website sections. * Caps change * Adjusts naming for about PatternFly page. * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.19 - @patternfly/documentation-framework@5.3.19 * docs(accessibility-testing): Updates content as part of content audit. (#3776) * docs(accessibility-testing): Updates content as part of content audit. * Apply suggestions from code review Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> * Apply suggestions from code review * Content tweaks in progress. * Works on checkboxes. * Resolves merge conflict. * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> * Content alterations. * Content changes from review feedback. * Updates to buttons point. * Grammar and typo updates. * Update packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> * Merging. --------- Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.20 - @patternfly/documentation-framework@5.3.20 * fix: bump to latest release candidates ahead of 5.2 release (#3862) * fix: bump to latest release candidates ahead of 5.2 release * bump to latest component groups prerelease * bump react to pull in bug fix * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.21 - @patternfly/documentation-framework@5.3.21 * updates to images to make icons black (#3856) * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.22 - @patternfly/documentation-framework@5.3.22 * fix: avoid applying beta tags to nav items for next components (#3868) * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.23 - @patternfly/documentation-framework@5.3.23 * fix(truncate): typos on guidelines (#3872) * docs(capitalization): Updates capitalization guidelines for better consistency and clarity. (#3855) * docs(capitalization): Updates guidance for capitalization. * Continues editing content. * Content updates progress. * Updates content and images. * Content and image updates. * Final content and image updates. * Updates recs per content team decision. * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.24 - @patternfly/documentation-framework@5.3.24 * fix: add drag drop deps and remove unused code editor deps (#3866) * fix: add drag drop deps and remove unused code editor deps * bump react-docs to fix error * bump the prerelease versions * chore(Title): updated a11y docs to template (#3873) * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.25 - @patternfly/documentation-framework@5.3.25 * docs(release-highlights): Adds release highlights for 5.2 release. (#3853) * docs(releases): Adds release highlights for v5.2 * docs(release-highlights): Adds release highlights for 5.2 release. * Update packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com> * Adds more highlights. * Adds coming soon section. * Update packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com> * Update packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com> --------- Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com> * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.26 - @patternfly/documentation-framework@5.3.26 * docs(design): Adds initial information regarding Figma. (#3863) * docs(design): Adds Figma information where Sketch is currently mentioned. * Path update * Update packages/documentation-site/patternfly-docs/content/contribute/design/design.md * Path updates. * Update packages/documentation-site/patternfly-docs/content/contribute/design/design.md * Update packages/documentation-site/patternfly-docs/content/training/design.md * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.3.27 - @patternfly/documentation-framework@5.3.27 * feat: release 5.3 (#3878) * feat: 5.3 release * update release highlights * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.4.0 - @patternfly/documentation-framework@5.4.0 * fix: Bump topology to 5.2.1 (#3881) * fix: toplogy to 5.2.1 * add yarn.lock * update release highlights * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.4.1 - @patternfly/documentation-framework@5.4.1 * Update broken link on develop.md * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.4.2 - @patternfly/documentation-framework@5.4.2 * chore(deps): bump ip from 1.1.5 to 1.1.9 (#3895) Bumps [ip](https://github.com/indutny/node-ip) from 1.1.5 to 1.1.9. - [Commits](indutny/node-ip@v1.1.5...v1.1.9) --- updated-dependencies: - dependency-name: ip dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * add edit modal guidance (#3836) * add edit modal guidance * edits * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.4.3 - @patternfly/documentation-framework@5.4.3 * chore(release): Updated component groups to 5.1.0 release (#3917) * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.4.3 - @patternfly/documentation-framework@5.4.3 chore(component-groups): Updated component groups to 5.1.0 release chore(component-groups): Updated component groups to 5.1.0 release * Updated version.json * feat(deps): version bump for 5.2.1 release (#3913) * feat(deps): version bump for 5.2.1 release * Update packages/documentation-framework/versions.json Co-authored-by: Evan <evan.wilkinson@gmail.com> * Update packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md Co-authored-by: Evan <evan.wilkinson@gmail.com> * Update packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md Co-authored-by: Evan <evan.wilkinson@gmail.com> * Update packages/documentation-framework/versions.json * chore(deps): bump react-charts, react-docs * Update packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> * chore(docs): update release highlights * Update packages/documentation-framework/versions.json --------- Co-authored-by: Evan <evan.wilkinson@gmail.com> Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.5.0 - @patternfly/documentation-framework@5.5.0 * chore(SkipToContent): updated a11y docs to template (#3871) * chore(SkipToContent): updated a11y docs to template * Updated test item description verbiage * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.5.1 - @patternfly/documentation-framework@5.5.1 * feat(deps): version bump and release notes for 5.2.2 patch release (#3919) * feat(deps): version bump and release notes for 5.2.2 patch release * fix(release-highlights): correct listed table version * Update packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> --------- Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.6.0 - @patternfly/documentation-framework@5.6.0 * feat: add pf 6 alpha banner to home page and version switcher (#3896) * feat: add pf 6 alpha banner to home page and version switcher * update wording * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.7.0 - @patternfly/documentation-framework@5.7.0 * feat(templates): add templates package to versions.json (#3902) * feat(templates): add templates package to versions.json for docs build * add support for template inline alert * add to patch version, update wording * update wording * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.8.0 - @patternfly/documentation-framework@5.8.0 * chore(Page): updated a11y docs to new template (#3880) * chore(Page): updated a11y docs to new template * Removed requirement of aria-labelledby on page sections * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.8.1 - @patternfly/documentation-framework@5.8.1 * chore: simplify Babel configuration (#3934) * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.8.2 - @patternfly/documentation-framework@5.8.2 * chore(footer): Restructure new homepage footer (#3870) * Restructure footer * Remove PageSection from footer based on conversations * Rework structure * Fix footer height issue * Update flex * Fix typo * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.8.3 - @patternfly/documentation-framework@5.8.3 * feat(docs): update medium articles (#3950) * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.9.0 - @patternfly/documentation-framework@5.9.0 * docs(release-highlights): Creates release highlights for 5.3 release. (#3941) * docs(release-highlights): Creates release highlights for 5.3 release. * Continues working on content updates. * docs(release-highlights): Adds release highlights for 5.3 release. * Adds more context to menu toggle change. * Update packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md * Update packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md * Adds section for dual list selector. * Updates topology pipeline images. * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.9.1 - @patternfly/documentation-framework@5.9.1 * feat(Templates): add to org site (#3947) * feat(Templates): add to org site * update versions, fix Th * hide prev version, update screenshots * chore(release): releasing packages [ci skip] - @patternfly/ast-helpers@1.10.0 - @patternfly/documentation-framework@5.10.0 * update documentation-framework version and git ignore * remove react-templates untill merged in react * remove 1 featured post --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: patternfly-build <patternfly-build@redhat.com> Co-authored-by: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> Co-authored-by: Nicole Thoen <nthoen@redhat.com> Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com> Co-authored-by: Margot <51165119+mmenestr@users.noreply.github.com> Co-authored-by: Andrew Ronaldson <aronalds@redhat.com> Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Donald Labaj <dlabaj@redhat.com> Co-authored-by: Austin Sullivan <ausulliv@redhat.com> Co-authored-by: Evan <evan.wilkinson@gmail.com> Co-authored-by: kmcfaul <45077788+kmcfaul@users.noreply.github.com> Co-authored-by: Jon Koops <jonkoops@gmail.com> Co-authored-by: Jessie <jhuff@redhat.com> Co-authored-by: Titani <tlabaj@redaht.com>
Closes #3874