Merge branch 'develop' of https://github.com/dan-tripp-siteimprove/act-rules.github.io into develop

Author: dan-tripp-siteimprove

_rules/presentational-children-no-focusable-content-307n5z.md

@@ -67,7 +67,7 @@ None of these `button` elements has [descendants][] that are included in [sequen
 
 #### Passed Example 2
 
-This element with `checkbox` role has no [descendants][] that are included in [sequential focus navigation][]. Instead the link to the terms of service is adjacent, and `aria-labelledby` is used to provide its [accessible name][].
+This element with the `checkbox` role has no [descendants][] that are included in [sequential focus navigation][]. Instead the link to the terms of service is adjacent, and `aria-labelledby` is used to provide its [accessible name][].
 
 ```html
 <p id="terms">
@@ -80,7 +80,7 @@ This element with `checkbox` role has no [descendants][] that are included in [s
 
 #### Passed Example 3
 
-This element with `menuitemcheckbox` role has an `input` element as a descendant. Because the `input` is disabled it is not included in [sequential focus navigation][].
+This element with the `menuitemcheckbox` role has an `input` element as a descendant. Because the `input` is disabled it is not included in [sequential focus navigation][].
 
 **Note**: The `input` checkbox has a `role` [attribute value][] of `none` to ensure it is ignored by browsers that do not support [presentational children][].
 
@@ -93,6 +93,15 @@ This element with `menuitemcheckbox` role has an `input` element as a descendant
 </ul>
 ```
 
+#### Passed Example 4
+
+This `<button>` element has an `<a>` element as a [child][].  The `<a>` element has no `href` attribute, so it isn't included in [sequential focus navigation][].  So this `<button>` element passes the rule.
+
+```html
+<button><a>button/link</a></button>
+```
+
+
 ### Failed
 
 #### Failed Example 1
@@ -108,15 +117,15 @@ This `button` element has a [child][] `span` element. Because the `span` element
 
 #### Failed Example 2
 
-This element with `checkbox` role has an `a` element as a [child][]. Because the `a` element has an `href` attribute, it is included in [sequential focus navigation][].
+This element with the `checkbox` role has an `a` element as a [child][]. Because the `a` element has an `href` attribute, it is included in [sequential focus navigation][].
 
 ```html
 <p role="checkbox" aria-checked="false" tabindex="0">I agree to the <a href="/terms">terms of service</a></p>
 ```
 
 #### Failed Example 3
 
-This element with `menuitemcheckbox` role has a checkbox as a child. Because the checkbox is not disabled, it is included in [sequential focus navigation][].
+This element with the `menuitemcheckbox` role has a checkbox as a child. Because the checkbox is not disabled, it is included in [sequential focus navigation][].
 
 ```html
 <ul role="menu">
@@ -127,16 +136,93 @@ This element with `menuitemcheckbox` role has a checkbox as a child. Because the
 </ul>
 ```
 
+#### Failed Example 4
+
+This element with the `tab` role contains an `<a>` element.  The `tab` role has [presentational children][].  The `a` element is included in [sequential focus navigation][].  So the element with the `tab` role fails the rule.  (This tablist implementation is non-functional for users.  It's not meant to function - it's only meant to show roles.)
+
+```html
+<ul role="tablist">
+	<li role="tab">
+		<a href="#">Tab 1</a>
+	</li>
+</ul>
+```
+
+#### Failed Example 5
+
+This element with the `img` role contains an `<a>` element.  The `img` role has [presentational children][].  The `<a>` element is included in [sequential focus navigation][].  So the element with the `img` role fails the rule.  (Interestingly, no similar failure is possible with a standard HTML `<img>` element, because according to the HTML specification, the `<img>` element has no closing tag.  So it's impossible to put anything inside of an `<img>` element.)
+
+```html
+<span role="img" aria-label="some ASCII art">****** This ASCII art ******* <a href="#">contains a link.</a></span>
+```
+
 ### Inapplicable
 
 #### Inapplicable Example 1
 
-This element has a `link` role which does not have [presentational children][].
+None of the roles involved in this semantic table have [presentational children][].  (The roles are `table`, `row`, and `cell`, respectively, for the `<table>`, `<tr>`, and `<td>` elements.)  So this rule does not apply.
 
 ```html
-<a href="https://w3.org">W3C Website</a>
+<table>
+		<thead>
+				<tr>
+						<th colspan="2">semantic table header</th>
+				</tr>
+		</thead>
+		<tbody>
+				<tr>
+						<td><button>button in semantic table - no problem</button></td>
+						<td><a href="#">anchor in semantic table - no problem</a></td>
+				</tr>
+		</tbody>
+</table>
 ```
 
+#### Inapplicable Example 2
+
+This `<a>` element has a `link` role, which does not have [presentational children][].  So this element - perhaps surprisingly - does not fail this rule, because it's inapplicable.  This is the case even though it's invalid HTML.  Any time there's a link as the <i>outer</i> element, that will be inapplicable under this rule.  (If the elements were switched - that is, if the `<button>` element contained the `<a>` element - then that would fail this rule.)
+
+```html
+<a href="https://w3.org"><button>W3C Website</button></a>
+```
+
+#### Inapplicable Example 3
+
+The applicability of this rule does not include elements with an <i>explicit</i> role of `presentation`.  Only <i>implicit</i> (through roles with [presentational children][]).  This example shows that. 
+
+```html
+<ul>
+	<li role="presentation">
+		<a href="#">inapplicable</a>
+	</li>
+</ul>
+```
+
+#### Inapplicable Example 4
+
+The applicability of this rule does not include hidden elements.  It only includes <i>presentational</i> elements (through roles with [presentational children][]).  These two terms - "hidden" and "presentational" - are often confused.  When an element is "hidden", that means that it is completely omitted from the accessibility tree.  When an element is "presentational", that means that its semantic role is omitted from the accessibility tree, but its content remains.
+
+The [ARIA 1.2 specification]https://www.w3.org/TR/wai-aria-1.2/#presentation) mentions this confusion:
+<ul>
+<li>
+<q>Many individuals erroneously consider role="presentation" to be synonymous with aria-hidden="true"</q>
+</li>
+<li>
+<q>... the presentation role causes a given element to be treated as having no role or to be removed from the accessibility tree, but does not cause the content contained within the element to be removed from the accessibility tree.</q>
+</li>
+</ul>
+
+Adding to this confusion is a third term: "decorative".  The words "decorative" and "presentational" are often used interchangeably, but that usage is inaccurate.  The word "decorative" often appears in a sentence such as "marking an image as decorative" - that is, by adding `alt=""` to an `<img>` element.  "Decorative" in that context <i>does</i> mean "hidden" - and "hidden", again, is different from "presentational" - so using "decorative" and "presentational" interchangeably is inaccurate.  At the time of writing (August 2023), the ACT definition of "[marked as decorative][]" unfortunately encourages this inaccurate usage: it states that <q>An element is marked as decorative if ... it has an explicit role of none or presentation</q>.
+
+At any rate: this example shows that this rule does not apply to hidden elements.
+
+```html
+<button aria-hidden="true">
+	<a href="#">inapplicable</a>
+</button>
+```
+
+
 [accessible name]: #accessible-name 'Definition of Accessible name'
 [attribute value]: #attribute-value 'Definition of Attribute value'
 [semantic role]: #semantic-role 'Definition of Semantic role'
@@ -147,3 +233,4 @@ This element has a `link` role which does not have [presentational children][].
 [sequential focus navigation]: https://html.spec.whatwg.org/#sequential-focus-navigation 'HTML sequential focus navigation, 2020/10/21'
 [flat tree]: https://drafts.csswg.org/css-scoping/#flat-tree 'CSS Scoping definition of Flat tree, working draft'
 [html or svg element]: #namespaced-element
+[marked as decorative]: /glossary/#marked-as-decorative