From bde0cb215d1d307c08678abe6623fc0d39f4cf7f Mon Sep 17 00:00:00 2001 From: Eli Chadwick Date: Fri, 14 Jun 2024 20:00:31 +0100 Subject: [PATCH] Move Accessibility section above Examples for html element pages (#34007) move Accessibility section above Examples for html element pages --- files/en-us/web/html/element/a/index.md | 292 +++++++++--------- files/en-us/web/html/element/abbr/index.md | 42 +-- files/en-us/web/html/element/audio/index.md | 78 ++--- files/en-us/web/html/element/br/index.md | 12 +- files/en-us/web/html/element/button/index.md | 18 +- files/en-us/web/html/element/canvas/index.md | 22 +- .../en-us/web/html/element/datalist/index.md | 16 +- files/en-us/web/html/element/del/index.md | 24 +- files/en-us/web/html/element/dialog/index.md | 24 +- files/en-us/web/html/element/div/index.md | 8 +- files/en-us/web/html/element/dl/index.md | 16 +- files/en-us/web/html/element/embed/index.md | 8 +- .../web/html/element/fencedframe/index.md | 26 +- files/en-us/web/html/element/footer/index.md | 12 +- files/en-us/web/html/element/header/index.md | 8 +- .../html/element/heading_elements/index.md | 80 ++--- files/en-us/web/html/element/hgroup/index.md | 8 +- files/en-us/web/html/element/iframe/index.md | 24 +- files/en-us/web/html/element/img/index.md | 88 +++--- .../web/html/element/input/number/index.md | 12 +- files/en-us/web/html/element/ins/index.md | 22 +- files/en-us/web/html/element/label/index.md | 40 +-- files/en-us/web/html/element/main/index.md | 64 ++-- files/en-us/web/html/element/mark/index.md | 60 ++-- files/en-us/web/html/element/output/index.md | 8 +- files/en-us/web/html/element/p/index.md | 28 +- files/en-us/web/html/element/portal/index.md | 20 +- files/en-us/web/html/element/pre/index.md | 2 +- .../en-us/web/html/element/progress/index.md | 22 +- files/en-us/web/html/element/s/index.md | 36 +-- files/en-us/web/html/element/search/index.md | 2 +- files/en-us/web/html/element/select/index.md | 8 +- files/en-us/web/html/element/table/index.md | 64 ++-- files/en-us/web/html/element/title/index.md | 18 +- files/en-us/web/html/element/video/index.md | 72 ++--- 35 files changed, 642 insertions(+), 642 deletions(-) diff --git a/files/en-us/web/html/element/a/index.md b/files/en-us/web/html/element/a/index.md index 1269e1c0fb9857c..ba4d8395e4b457f 100644 --- a/files/en-us/web/html/element/a/index.md +++ b/files/en-us/web/html/element/a/index.md @@ -130,6 +130,152 @@ This element's attributes include the [global attributes](/en-US/docs/Web/HTML/G > **Note:** Use the {{HTMLElement("area")}} element for image maps instead. +## Accessibility + +### Strong link text + +**The content inside a link should indicate where the link goes**, even out of context. + +#### Inaccessible, weak link text + +A sadly common mistake is to only link the words "click here" or "here": + +```html example-bad +

Learn more about our products here.

+``` + +##### Result + +{{EmbedLiveSample('Inaccessible, weak link text')}} + +#### Strong link text + +Luckily, this is an easy fix, and it's actually shorter than the inaccessible version! + +```html example-good +

Learn more about our products.

+``` + +##### Result + +{{EmbedLiveSample('Strong link text')}} + +Assistive software has shortcuts to list all links on a page. However, strong link text benefits all users — the "list all links" shortcut emulates how sighted users quickly scan pages. + +### onclick events + +Anchor elements are often abused as fake buttons by setting their `href` to `#` or `javascript:void(0)` to prevent the page from refreshing, then listening for their `click` events . + +These bogus `href` values cause unexpected behavior when copying/dragging links, opening links in a new tab/window, bookmarking, or when JavaScript is loading, errors, or is disabled. They also convey incorrect semantics to assistive technologies, like screen readers. + +Use a {{HTMLElement("button")}} instead. In general, **you should only use a hyperlink for navigation to a real URL**. + +### External links and linking to non-HTML resources + +Links that open in a new tab/window via `target="_blank"`, or links that point to a download file should indicate what will happen when the link is followed. + +People experiencing low vision conditions, navigating with the aid of screen reading technology, or with cognitive concerns may be confused when a new tab, window, or application opens unexpectedly. Older screen-reading software may not even announce the behavior. + +#### Link that opens a new tab/window + +```html + + Wikipedia (opens in new tab) + +``` + +##### Result + +{{EmbedLiveSample('Link that opens a new tab/window')}} + +#### Link to a non-HTML resource + +```html +2017 Annual Report (PowerPoint) +``` + +If an icon is used to signify link behavior, make sure it has an [_alt text_](/en-US/docs/Web/HTML/Element/img#alt): + +```html + + Wikipedia + (opens in new tab) + + + + 2017 Annual Report + (PowerPoint file) + +``` + +##### Result + +{{EmbedLiveSample('Link to a non-HTML resource')}} + +- [WebAIM: Links and Hypertext - Hypertext Links](https://webaim.org/techniques/hypertext/hypertext_links) +- [MDN / Understanding WCAG, Guideline 3.2](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable#guideline_3.2_—_predictable_make_web_pages_appear_and_operate_in_predictable_ways) +- [G200: Opening new windows and tabs from a link only when necessary](https://www.w3.org/TR/WCAG20-TECHS/G200.html) +- [G201: Giving users advanced warning when opening a new window](https://www.w3.org/TR/WCAG20-TECHS/G201.html) + +### Skip links + +A **skip link** is a link placed as early as possible in {{HTMLElement("body")}} content that points to the beginning of the page's main content. Usually, CSS hides a skip link offscreen until focused. + +```html + + + +
…
+ + +
+ +``` + +```css +.skip-link { + position: absolute; + top: -3em; + background: #fff; +} +.skip-link:focus { + top: 0; +} +``` + +#### Result + +{{EmbedLiveSample('Skip links')}} + +Skip links let keyboard users bypass content repeated throughout multiple pages, such as header navigation. + +Skip links are especially useful for people who navigate with the aid of assistive technology such as switch control, voice command, or mouth sticks/head wands, where the act of moving through repetitive links can be laborious. + +- [WebAIM: "Skip Navigation" Links](https://webaim.org/techniques/skipnav/) +- [How-to: Use Skip Navigation links](https://www.a11yproject.com/posts/skip-nav-links/) +- [MDN / Understanding WCAG, Guideline 2.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.4_%e2%80%94_navigable_provide_ways_to_help_users_navigate_find_content_and_determine_where_they_are) +- [Understanding Success Criterion 2.4.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-skip.html) + +### Size and proximity + +#### Size + +Interactive elements, like links, should provide an area large enough that it is easy to activate them. This helps a variety of people, including those with motor control issues and those using imprecise inputs such as a touchscreen. A minimum size of 44×44 [CSS pixels](https://www.w3.org/TR/WCAG21/#dfn-css-pixels) is recommended. + +Text-only links in prose content are exempt from this requirement, but it's still a good idea to make sure enough text is hyperlinked to be easily activated. + +- [Understanding Success Criterion 2.5.5: Target Size](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html) +- [Target Size and 2.5.5](https://adrianroselli.com/2019/06/target-size-and-2-5-5.html) +- [Quick test: Large touch targets](https://www.a11yproject.com/posts/large-touch-targets/) + +#### Proximity + +Interactive elements, like links, placed in close visual proximity should have space separating them. Spacing helps people with motor control issues, who may otherwise accidentally activate the wrong interactive content. + +Spacing may be created using CSS properties like {{CSSxRef("margin")}}. + +- [Hand tremors and the giant-button-problem](https://axesslab.com/hand-tremors/) + ## Examples ### Linking to an absolute URL @@ -291,152 +437,6 @@ document Using `target="_blank"` without [`rel="noreferrer"`](/en-US/docs/Web/HTML/Attributes/rel/noreferrer) and [`rel="noopener"`](/en-US/docs/Web/HTML/Attributes/rel/noopener) makes the website vulnerable to {{domxref("window.opener")}} API exploitation attacks, although note that, in newer browser versions setting `target="_blank"` implicitly provides the same protection as setting `rel="noopener"`. See [browser compatibility](#browser_compatibility) for details. -## Accessibility concerns - -### Strong link text - -**The content inside a link should indicate where the link goes**, even out of context. - -#### Inaccessible, weak link text - -A sadly common mistake is to only link the words "click here" or "here": - -```html example-bad -

Learn more about our products here.

-``` - -##### Result - -{{EmbedLiveSample('Inaccessible, weak link text')}} - -#### Strong link text - -Luckily, this is an easy fix, and it's actually shorter than the inaccessible version! - -```html example-good -

Learn more about our products.

-``` - -##### Result - -{{EmbedLiveSample('Strong link text')}} - -Assistive software has shortcuts to list all links on a page. However, strong link text benefits all users — the "list all links" shortcut emulates how sighted users quickly scan pages. - -### onclick events - -Anchor elements are often abused as fake buttons by setting their `href` to `#` or `javascript:void(0)` to prevent the page from refreshing, then listening for their `click` events . - -These bogus `href` values cause unexpected behavior when copying/dragging links, opening links in a new tab/window, bookmarking, or when JavaScript is loading, errors, or is disabled. They also convey incorrect semantics to assistive technologies, like screen readers. - -Use a {{HTMLElement("button")}} instead. In general, **you should only use a hyperlink for navigation to a real URL**. - -### External links and linking to non-HTML resources - -Links that open in a new tab/window via `target="_blank"`, or links that point to a download file should indicate what will happen when the link is followed. - -People experiencing low vision conditions, navigating with the aid of screen reading technology, or with cognitive concerns may be confused when a new tab, window, or application opens unexpectedly. Older screen-reading software may not even announce the behavior. - -#### Link that opens a new tab/window - -```html - - Wikipedia (opens in new tab) - -``` - -##### Result - -{{EmbedLiveSample('Link that opens a new tab/window')}} - -#### Link to a non-HTML resource - -```html -2017 Annual Report (PowerPoint) -``` - -If an icon is used to signify link behavior, make sure it has an [_alt text_](/en-US/docs/Web/HTML/Element/img#alt): - -```html - - Wikipedia - (opens in new tab) - - - - 2017 Annual Report - (PowerPoint file) - -``` - -##### Result - -{{EmbedLiveSample('Link to a non-HTML resource')}} - -- [WebAIM: Links and Hypertext - Hypertext Links](https://webaim.org/techniques/hypertext/hypertext_links) -- [MDN / Understanding WCAG, Guideline 3.2](/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable#guideline_3.2_—_predictable_make_web_pages_appear_and_operate_in_predictable_ways) -- [G200: Opening new windows and tabs from a link only when necessary](https://www.w3.org/TR/WCAG20-TECHS/G200.html) -- [G201: Giving users advanced warning when opening a new window](https://www.w3.org/TR/WCAG20-TECHS/G201.html) - -### Skip links - -A **skip link** is a link placed as early as possible in {{HTMLElement("body")}} content that points to the beginning of the page's main content. Usually, CSS hides a skip link offscreen until focused. - -```html - - - -
…
- - -
- -``` - -```css -.skip-link { - position: absolute; - top: -3em; - background: #fff; -} -.skip-link:focus { - top: 0; -} -``` - -#### Result - -{{EmbedLiveSample('Skip links')}} - -Skip links let keyboard users bypass content repeated throughout multiple pages, such as header navigation. - -Skip links are especially useful for people who navigate with the aid of assistive technology such as switch control, voice command, or mouth sticks/head wands, where the act of moving through repetitive links can be laborious. - -- [WebAIM: "Skip Navigation" Links](https://webaim.org/techniques/skipnav/) -- [How-to: Use Skip Navigation links](https://www.a11yproject.com/posts/skip-nav-links/) -- [MDN / Understanding WCAG, Guideline 2.4 explanations](/en-US/docs/Web/Accessibility/Understanding_WCAG/Operable#guideline_2.4_%e2%80%94_navigable_provide_ways_to_help_users_navigate_find_content_and_determine_where_they_are) -- [Understanding Success Criterion 2.4.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-skip.html) - -### Size and proximity - -#### Size - -Interactive elements, like links, should provide an area large enough that it is easy to activate them. This helps a variety of people, including those with motor control issues and those using imprecise inputs such as a touchscreen. A minimum size of 44×44 [CSS pixels](https://www.w3.org/TR/WCAG21/#dfn-css-pixels) is recommended. - -Text-only links in prose content are exempt from this requirement, but it's still a good idea to make sure enough text is hyperlinked to be easily activated. - -- [Understanding Success Criterion 2.5.5: Target Size](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html) -- [Target Size and 2.5.5](https://adrianroselli.com/2019/06/target-size-and-2-5-5.html) -- [Quick test: Large touch targets](https://www.a11yproject.com/posts/large-touch-targets/) - -#### Proximity - -Interactive elements, like links, placed in close visual proximity should have space separating them. Spacing helps people with motor control issues, who may otherwise accidentally activate the wrong interactive content. - -Spacing may be created using CSS properties like {{CSSxRef("margin")}}. - -- [Hand tremors and the giant-button-problem](https://axesslab.com/hand-tremors/) - ## Technical summary diff --git a/files/en-us/web/html/element/abbr/index.md b/files/en-us/web/html/element/abbr/index.md index 3bc5bb169161e91..92e9ff68a084e04 100644 --- a/files/en-us/web/html/element/abbr/index.md +++ b/files/en-us/web/html/element/abbr/index.md @@ -42,6 +42,27 @@ The purpose of this element is purely for the convenience of the author and all Some browsers add a dotted underline to the content of the element. Others add a dotted underline while converting the contents to small caps. Others may not style it differently than a {{HTMLElement("span")}} element. To control this styling, use {{cssxref('text-decoration')}} and {{cssxref('font-variant')}}. +## Accessibility + +Spelling out the acronym or abbreviation in full the first time it is used on a page is beneficial for helping people understand it, especially if the content is technical or industry jargon. + +Only include a `title` if expanding the abbreviation or acronym in the text is not possible. Having a difference between the announced word or phrase and what is displayed on the screen, especially if it's technical jargon the reader may not be familiar with, can be jarring. + +#### HTML + +```html +

+ JavaScript Object Notation (JSON) is a lightweight + data-interchange format. +

+``` + +#### Result + +{{EmbedLiveSample("Accessibility_concerns")}} + +This is especially helpful for people who are unfamiliar with the terminology or concepts discussed in the content, people who are new to the language, and people with cognitive concerns. + ## Examples ### Marking up an abbreviation semantically @@ -117,27 +138,6 @@ You can use `` in tandem with {{HTMLElement("dfn")}} to more formally defi {{EmbedLiveSample("Defining_an_abbreviation", 600, 120)}} -### Accessibility concerns - -Spelling out the acronym or abbreviation in full the first time it is used on a page is beneficial for helping people understand it, especially if the content is technical or industry jargon. - -Only include a `title` if expanding the abbreviation or acronym in the text is not possible. Having a difference between the announced word or phrase and what is displayed on the screen, especially if it's technical jargon the reader may not be familiar with, can be jarring. - -#### HTML - -```html -

- JavaScript Object Notation (JSON) is a lightweight - data-interchange format. -

-``` - -#### Result - -{{EmbedLiveSample("Accessibility_concerns")}} - -This is especially helpful for people who are unfamiliar with the terminology or concepts discussed in the content, people who are new to the language, and people with cognitive concerns. - ## Technical summary
diff --git a/files/en-us/web/html/element/audio/index.md b/files/en-us/web/html/element/audio/index.md index 2f1a5f99589bf9d..86c173b64b3dace 100644 --- a/files/en-us/web/html/element/audio/index.md +++ b/files/en-us/web/html/element/audio/index.md @@ -307,45 +307,7 @@ This code watches for audio tracks to be added to and removed from the element, You can also use {{domxref("EventTarget.addEventListener", "addEventListener()")}} to listen for the {{domxref("AudioTrackList/addtrack_event", "addtrack")}} and {{domxref("AudioTrackList/removetrack_event", "removetrack")}} events. -## Examples - -### Basic usage - -The following example shows simple usage of the `
diff --git a/files/en-us/web/html/element/br/index.md b/files/en-us/web/html/element/br/index.md index 60f50bac58635ed..505f0ef02912a8b 100644 --- a/files/en-us/web/html/element/br/index.md +++ b/files/en-us/web/html/element/br/index.md @@ -30,6 +30,12 @@ The `
` element has a single, well-defined purpose — to create a line break You can set a {{cssxref("margin")}} on `
` elements themselves to increase the spacing between the lines of text in the block, but this is a bad practice — you should use the {{cssxref("line-height")}} property that was designed for that purpose. +## Accessibility + +Creating separate paragraphs of text using `
` is not only bad practice, it is problematic for people who navigate with the aid of screen reading technology. Screen readers may announce the presence of the element, but not any content contained within `
`s. This can be a confusing and frustrating experience for the person using the screen reader. + +Use `

` elements, and use CSS properties like {{cssxref("margin")}} to control their spacing. + ## Examples ### Simple br @@ -48,12 +54,6 @@ USA
{{ EmbedLiveSample('Simple_br', 640, 120) }} -## Accessibility concerns - -Creating separate paragraphs of text using `
` is not only bad practice, it is problematic for people who navigate with the aid of screen reading technology. Screen readers may announce the presence of the element, but not any content contained within `
`s. This can be a confusing and frustrating experience for the person using the screen reader. - -Use `

` elements, and use CSS properties like {{cssxref("margin")}} to control their spacing. - ## Technical summary

diff --git a/files/en-us/web/html/element/button/index.md b/files/en-us/web/html/element/button/index.md index 0f1cd6190264b2d..af566eb09abc330 100644 --- a/files/en-us/web/html/element/button/index.md +++ b/files/en-us/web/html/element/button/index.md @@ -106,15 +106,7 @@ If your buttons are not for submitting form data to a server, be sure to set the While ` -``` - -{{ EmbedLiveSample('Example', 200, 64) }} - -## Accessibility concerns +## Accessibility ### Icon buttons @@ -183,6 +175,14 @@ Color contrast ratio is determined by comparing the luminosity of the button tex Whether clicking on a {{HTMLElement("button")}} or {{HTMLElement("input")}} button types causes it to (by default) become focused varies by browser and OS. Most browsers do give focus to a button being clicked, but [Safari does not, by design](https://webkit.org/b/22261). +## Examples + +```html + +``` + +{{ EmbedLiveSample('Example', 200, 64) }} + ## Technical summary
diff --git a/files/en-us/web/html/element/canvas/index.md b/files/en-us/web/html/element/canvas/index.md index 385f545519d48bb..49a2c8c8cb5a7ae 100644 --- a/files/en-us/web/html/element/canvas/index.md +++ b/files/en-us/web/html/element/canvas/index.md @@ -49,6 +49,17 @@ The benefit is that a [worker thread](/en-US/docs/Web/API/Web_Workers_API/Using_ By parallelizing work, other UI elements of your web application will remain responsive even if you are running complex graphics on an offscreen canvas. For more information, see the {{domxref("OffscreenCanvas")}} API documentation. +## Accessibility + +### Alternative content + +The `` element on its own is just a bitmap and does not provide information about any drawn objects. Canvas content is not exposed to accessibility tools as semantic HTML is. In general, you should avoid using canvas in an accessible website or app. The following guides can help to make it more accessible. + +- [Canvas accessibility use cases](https://www.w3.org/WAI/PF/HTML/wiki/Canvas_Accessibility_Use_Cases) +- [Canvas element accessibility issues](https://www.w3.org/html/wg/wiki/AddedElementCanvas) +- [HTML Canvas Accessibility in Firefox 13 – by Steve Faulkner](https://www.tpgi.com/html5-canvas-accessibility-in-firefox-13/) +- [Best practices for interactive canvas elements](https://html.spec.whatwg.org/multipage/scripting.html#best-practices) + ## Examples ### HTML @@ -77,17 +88,6 @@ ctx.fillRect(10, 10, 100, 100); {{EmbedLiveSample('Examples', 600, 150)}} -## Accessibility concerns - -### Alternative content - -The `` element on its own is just a bitmap and does not provide information about any drawn objects. Canvas content is not exposed to accessibility tools as semantic HTML is. In general, you should avoid using canvas in an accessible website or app. The following guides can help to make it more accessible. - -- [Canvas accessibility use cases](https://www.w3.org/WAI/PF/HTML/wiki/Canvas_Accessibility_Use_Cases) -- [Canvas element accessibility issues](https://www.w3.org/html/wg/wiki/AddedElementCanvas) -- [HTML Canvas Accessibility in Firefox 13 – by Steve Faulkner](https://www.tpgi.com/html5-canvas-accessibility-in-firefox-13/) -- [Best practices for interactive canvas elements](https://html.spec.whatwg.org/multipage/scripting.html#best-practices) - ## Technical summary
diff --git a/files/en-us/web/html/element/datalist/index.md b/files/en-us/web/html/element/datalist/index.md index 4d9b384b0c819a4..b6ef766c4bdf59a 100644 --- a/files/en-us/web/html/element/datalist/index.md +++ b/files/en-us/web/html/element/datalist/index.md @@ -20,6 +20,14 @@ Only certain types of {{HTMLElement("input")}} support this behavior, and it can This element has no other attributes than the [global attributes](/en-US/docs/Web/HTML/Global_attributes), common to all elements. +## Accessibility + +When deciding to use the `` element, here are some accessibility issues to be mindful of: + +- The font size of the data list's options does not zoom, always remaining the same size. The contents of the autosuggest do not grow or shrink when the rest of the contents are zoomed in or out. +- As targeting the list of options with CSS is very limited to non-existent, rendering can not be styled for high-contrast mode. +- Some screen reader/browser combinations, including NVDA and Firefox, do not announce the contents of the autosuggest popup. + ## Examples ### Textual types @@ -107,14 +115,6 @@ The specification allows linking `` with a {{HTMLElement("input/passwo {{EmbedLiveSample("Password_type", 600, 40)}} -## Accessibility concerns - -When deciding to use the `` element, here are some accessibility issues to be mindful of: - -- The font size of the data list's options does not zoom, always remaining the same size. The contents of the autosuggest do not grow or shrink when the rest of the contents are zoomed in or out. -- As targeting the list of options with CSS is very limited to non-existent, rendering can not be styled for high-contrast mode. -- Some screen reader/browser combinations, including NVDA and Firefox, do not announce the contents of the autosuggest popup. - ## Technical summary
diff --git a/files/en-us/web/html/element/del/index.md b/files/en-us/web/html/element/del/index.md index b9731263a89c23c..e16b4481d650584 100644 --- a/files/en-us/web/html/element/del/index.md +++ b/files/en-us/web/html/element/del/index.md @@ -22,18 +22,7 @@ This element's attributes include the [global attributes](/en-US/docs/Web/HTML/G - `datetime` - : This attribute indicates the time and date of the change and must be a valid date string with an optional time. If the value cannot be parsed as a date with an optional time string, the element does not have an associated timestamp. For the format of the string without a time, see [Date strings](/en-US/docs/Web/HTML/Date_and_time_formats#date_strings). The format of the string if it includes both date and time is covered in [Local date and time strings](/en-US/docs/Web/HTML/Date_and_time_formats#local_date_and_time_strings). -## Examples - -```html -

This text has been deleted, here is the rest of the paragraph.

-

This paragraph has been deleted.

 -``` - -### Result - -{{EmbedLiveSample("Examples")}} - -## Accessibility concerns +## Accessibility The presence of the `del` element is not announced by most screen reading technology in its default configuration. It can be made to be announced by using the CSS {{cssxref("content")}} property, along with the {{cssxref("::before")}} and {{cssxref("::after")}} pseudo-elements. @@ -63,6 +52,17 @@ Some people who use screen readers deliberately disable announcing content that - [Short note on making your mark (more accessible) | The Paciello Group](https://www.tpgi.com/short-note-on-making-your-mark-more-accessible/) - [Tweaking Text Level Styles | Adrian Roselli](https://adrianroselli.com/2017/12/tweaking-text-level-styles.html) +## Examples + +```html +

This text has been deleted, here is the rest of the paragraph.

+

This paragraph has been deleted.

 +``` + +### Result + +{{EmbedLiveSample("Examples")}} + ## Technical summary
diff --git a/files/en-us/web/html/element/dialog/index.md b/files/en-us/web/html/element/dialog/index.md index 681cc3f0c89f624..770ea623eb9ae70 100644 --- a/files/en-us/web/html/element/dialog/index.md +++ b/files/en-us/web/html/element/dialog/index.md @@ -33,6 +33,18 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib - The [`autofocus`](/en-US/docs/Web/HTML/Global_attributes/autofocus) attribute should be added to the element the user is expected to interact with immediately upon opening a modal dialog. If no other element involves more immediate interaction, it is recommended to add `autofocus` to the close button inside the dialog, or the dialog itself if the user is expected to click/activate it to dismiss. - Do not add the `tabindex` property to the `` element as it is not interactive and does not receive focus. The dialog's contents, including the close button contained in the dialog, can receive focus and be interactive. +## Accessibility + +When implementing a dialog, it is important to consider the most appropriate place to set user focus. When using {{domxref("HTMLDialogElement.showModal()")}} to open a ``, focus is set on the first nested focusable element. Explicitly indicating the initial focus placement by using the [`autofocus`](/en-US/docs/Web/HTML/Global_attributes/autofocus) attribute will help ensure initial focus is set on the element deemed the best initial focus placement for any particular dialog. When in doubt, as it may not always be known where initial focus could be set within a dialog, particularly for instances where a dialog's content is dynamically rendered when invoked, the `` element itself may provide the best initial focus placement. + +Ensure a mechanism is provided to allow users to close the dialog. The most robust way to ensure that all users can close the dialog is to include an explicit button to do so, such as a confirmation, cancellation, or close button. + +By default, a dialog invoked by the `showModal()` method can be dismissed by pressing the Esc key. A non-modal dialog does not dismiss via the Esc key by default, and depending on what the non-modal dialog represents, it may not be desired for this behavior. Keyboard users expect the Esc key to close modal dialogs; ensure that this behavior is implemented and maintained. If multiple modal dialogs are open, pressing the Esc key should close only the last shown dialog. When using ``, this behavior is provided by the browser. + +While dialogs can be created using other elements, the native `` element provides usability and accessibility features that must be replicated if you use other elements for a similar purpose. If you're creating a custom dialog implementation, ensure that all expected default behaviors are supported and proper labeling recommendations are followed. + +The `` element is exposed by browsers in a manner similar to custom dialogs that use the ARIA [role="dialog"](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) attribute. `` elements invoked by the `showModal()` method implicitly have [aria-modal="true"](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal), whereas `` elements invoked by the `show()` method or displayed using the `open` attribute or by changing the default `display` of a `` are exposed as `[aria-modal="false"]`. When implementing modal dialogs, everything other than the `` and its contents should be rendered inert using the [`inert`](/en-US/docs/Web/HTML/Global_attributes/inert) attribute. When using `` along with the `HTMLDialogElement.showModal()` method, this behavior is provided by the browser. + ## Examples ### HTML-only dialog @@ -496,18 +508,6 @@ The code renders as follows: {{ EmbedLiveSample("dialog keyframe animations", "100%", "200") }} -## Accessibility concerns - -When implementing a dialog, it is important to consider the most appropriate place to set user focus. When using {{domxref("HTMLDialogElement.showModal()")}} to open a ``, focus is set on the first nested focusable element. Explicitly indicating the initial focus placement by using the [`autofocus`](/en-US/docs/Web/HTML/Global_attributes/autofocus) attribute will help ensure initial focus is set on the element deemed the best initial focus placement for any particular dialog. When in doubt, as it may not always be known where initial focus could be set within a dialog, particularly for instances where a dialog's content is dynamically rendered when invoked, the `` element itself may provide the best initial focus placement. - -Ensure a mechanism is provided to allow users to close the dialog. The most robust way to ensure that all users can close the dialog is to include an explicit button to do so, such as a confirmation, cancellation, or close button. - -By default, a dialog invoked by the `showModal()` method can be dismissed by pressing the Esc key. A non-modal dialog does not dismiss via the Esc key by default, and depending on what the non-modal dialog represents, it may not be desired for this behavior. Keyboard users expect the Esc key to close modal dialogs; ensure that this behavior is implemented and maintained. If multiple modal dialogs are open, pressing the Esc key should close only the last shown dialog. When using ``, this behavior is provided by the browser. - -While dialogs can be created using other elements, the native `` element provides usability and accessibility features that must be replicated if you use other elements for a similar purpose. If you're creating a custom dialog implementation, ensure that all expected default behaviors are supported and proper labeling recommendations are followed. - -The `` element is exposed by browsers in a manner similar to custom dialogs that use the ARIA [role="dialog"](/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role) attribute. `` elements invoked by the `showModal()` method implicitly have [aria-modal="true"](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal), whereas `` elements invoked by the `show()` method or displayed using the `open` attribute or by changing the default `display` of a `` are exposed as `[aria-modal="false"]`. When implementing modal dialogs, everything other than the `` and its contents should be rendered inert using the [`inert`](/en-US/docs/Web/HTML/Global_attributes/inert) attribute. When using `` along with the `HTMLDialogElement.showModal()` method, this behavior is provided by the browser. - ## Technical summary
diff --git a/files/en-us/web/html/element/div/index.md b/files/en-us/web/html/element/div/index.md index ab921e8a5483ba1..6984c820c7185c4 100644 --- a/files/en-us/web/html/element/div/index.md +++ b/files/en-us/web/html/element/div/index.md @@ -23,6 +23,10 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib - The `
` element should be used only when no other semantic element (such as {{HTMLElement("article")}} or {{HTMLElement("nav")}}) is appropriate. +## Accessibility + +The `
` element has [an implicit role of `generic`](https://www.w3.org/TR/wai-aria-1.2/#generic), and not none. This may affect certain ARIA combination declarations that expect a direct descendant element with a certain role to function properly. + ## Examples ### A simple example @@ -67,10 +71,6 @@ This example creates a shadowed box by applying a style to the `
` using CSS {{EmbedLiveSample("A_styled_example", 650, 120)}} -## Accessibility concerns - -The `
` element has [an implicit role of `generic`](https://www.w3.org/TR/wai-aria-1.2/#generic), and not none. This may affect certain ARIA combination declarations that expect a direct descendant element with a certain role to function properly. - ## Technical summary
diff --git a/files/en-us/web/html/element/dl/index.md b/files/en-us/web/html/element/dl/index.md index 462c9d599ede947..a8612e119699493 100644 --- a/files/en-us/web/html/element/dl/index.md +++ b/files/en-us/web/html/element/dl/index.md @@ -15,6 +15,14 @@ The **`
`** [HTML](/en-US/docs/Web/HTML) element represents a description lis This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). +## Accessibility + +Each screen reader exposes `
` content differently, including total count, terms/definitions context, and navigation methods. These differences are not necessarily bugs. +As of iOS 14, VoiceOver will announce that `
` content is a list when navigating with the virtual cursor (not via the read-all command). VoiceOver does not support list navigation commands with `
`. Be careful applying ARIA `term` and `definition` roles to `
` constructs as VoiceOver (macOS and iOS) will adjust how they are announced. + +- [VoiceOver on iOS 14 Supports Description Lists](https://adrianroselli.com/2020/09/voiceover-on-ios-14-supports-description-lists.html) +- [Brief Note on Description List Support](https://adrianroselli.com/2022/12/brief-note-on-description-list-support.html) + ## Examples ### Single term and description @@ -145,14 +153,6 @@ Do not use this element (nor {{HTMLElement("ul")}} elements) to merely create in To change the indentation of a description term, use the [CSS](/en-US/docs/Web/CSS) {{cssxref("margin")}} property. -## Accessibility concerns - -Each screen reader exposes `
` content differently, including total count, terms/definitions context, and navigation methods. These differences are not necessarily bugs. -As of iOS 14, VoiceOver will announce that `
` content is a list when navigating with the virtual cursor (not via the read-all command). VoiceOver does not support list navigation commands with `
`. Be careful applying ARIA `term` and `definition` roles to `
` constructs as VoiceOver (macOS and iOS) will adjust how they are announced. - -- [VoiceOver on iOS 14 Supports Description Lists](https://adrianroselli.com/2020/09/voiceover-on-ios-14-supports-description-lists.html) -- [Brief Note on Description List Support](https://adrianroselli.com/2022/12/brief-note-on-description-list-support.html) - ## Technical summary
diff --git a/files/en-us/web/html/element/embed/index.md b/files/en-us/web/html/element/embed/index.md index 0f9dbad1dad9aa4..d72a7dfcf474801 100644 --- a/files/en-us/web/html/element/embed/index.md +++ b/files/en-us/web/html/element/embed/index.md @@ -32,6 +32,10 @@ This element's attributes include the [global attributes](/en-US/docs/Web/HTML/G You can use the {{cssxref("object-position")}} property to adjust the positioning of the embedded object within the element's frame, and the {{cssxref("object-fit")}} property to control how the object's size is adjusted to fit within the frame. +## Accessibility + +Use the [`title` attribute](/en-US/docs/Web/HTML/Global_attributes/title) on an `embed` element to label its content so that people navigating with assistive technology such as a screen reader can understand what it contains. The title's value should concisely describe the embedded content. Without a title, they may not be able to determine what its embedded content is. This context shift can be confusing and time-consuming, especially if the `embed` element contains interactive content like video or audio. + ## Examples ```html @@ -43,10 +47,6 @@ You can use the {{cssxref("object-position")}} property to adjust the positionin title="Title of my video" /> ``` -## Accessibility concerns - -Use the [`title` attribute](/en-US/docs/Web/HTML/Global_attributes/title) on an `embed` element to label its content so that people navigating with assistive technology such as a screen reader can understand what it contains. The title's value should concisely describe the embedded content. Without a title, they may not be able to determine what its embedded content is. This context shift can be confusing and time-consuming, especially if the `embed` element contains interactive content like video or audio. - ## Technical summary
diff --git a/files/en-us/web/html/element/fencedframe/index.md b/files/en-us/web/html/element/fencedframe/index.md index 2034ce057b5662a..cf58a3d427a4de0 100644 --- a/files/en-us/web/html/element/fencedframe/index.md +++ b/files/en-us/web/html/element/fencedframe/index.md @@ -64,6 +64,19 @@ As a [replaced element](/en-US/docs/Web/CSS/Replaced_element), the position, ali The size of the embedded content may be set by internal `contentWidth` and `contentHeight` properties of the ``'s {{domxref("HTMLFencedFrameElement.config", "config")}} object. In such cases, changing the `width` or `height` of the `` will change the size of the embedded container on the page, but the document inside the container will be visually scaled to fit. The reported width and height of the embedded document (i.e. {{domxref("Window.innerWidth")}} and {{domxref("Window.innerHeight")}}) will be unchanged. +## Accessibility + +People navigating with assistive technology such as a screen reader can use the [`title` attribute](/en-US/docs/Web/HTML/Global_attributes/title) on an `` to label its content. The title's value should concisely describe the embedded content: + +```html + +``` + +Without this title, they have to navigate into the ` +``` + +Without this title, they have to navigate into the ` -``` - -Without this title, they have to navigate into the `