Move secondary requirement texts out of the background (#2060)

* Move secondary requirement texts out of the background * Apply suggestions from code review * fix test * Fix failing test * Secondary reqs on ARIA rules * Update all secondary requirements * Typos * Fix failing tests * Update _rules/link-non-empty-accessible-name-c487ae.md Co-authored-by: Trevor R. Bostic <[email protected]> * Tweaked the language some more * Update rule design info for secondary requirements * Fix tests * Apply suggestions from code review Co-authored-by: Kathy Eng <[email protected]> * Apply suggestions from code review Co-authored-by: Jean-Yves Moyen <[email protected]> --------- Co-authored-by: Trevor R. Bostic <[email protected]> Co-authored-by: Kathy Eng <[email protected]> Co-authored-by: Jean-Yves Moyen <[email protected]>
act-rules · Oct 13, 2023 · 4f72c9f · 4f72c9f
1 parent d8b9923
commit 4f72c9f
Show file tree

Hide file tree

Showing 25 changed files with 69 additions and 103 deletions.
diff --git a/__tests__/frontmatter.js b/__tests__/frontmatter.js
@@ -95,8 +95,11 @@ function validateRuleFrontmatter({ frontmatter }, metaData) {
 		 */
 		const accRequirementValues = Object.values(accessibility_requirements)
 		test.each(accRequirementValues)('has expected keys for accessibility requirement: `%p`', accReq => {
-			if (accReq.secondary) {
-				expect(accReq.secondary).toBeTrue()
+			if (!accReq) {
+				return
+			} else if (accReq.secondary) {
+				// Note; empty strings & false won't get here, and so aren't allowed
+				expect(['string', 'boolean']).toContain(typeof accReq.secondary)
 				return
 			}
 

diff --git a/__tests__/link-to-glossary-term-valid.js b/__tests__/link-to-glossary-term-valid.js
@@ -14,6 +14,7 @@ const whitelist = [
 	/^#expectation(-[1-9][0-9]*)?$/,
 	/^#assumptions$/,
 	/^#accessibility-support$/,
+	/^#accessibility-requirements-mapping$/,
 	/^#background$/,
 	/^#test-cases$/,
 	/^#passed(-example-[1-9][0-9]*)?$/,

diff --git a/__tests__/spelling-ignore.yml b/__tests__/spelling-ignore.yml
@@ -86,6 +86,7 @@
 - RFC
 - rfc
 - webauthn
+- customizable
 
 # spell checker checks against strict casing & hence some repeated words here
 - Autocomplete

diff --git a/_rules/aria-attr-defined-5f99a7.md b/_rules/aria-attr-defined-5f99a7.md
@@ -6,9 +6,9 @@ description: |
   This rule checks that each `aria-` attribute specified is defined in ARIA 1.2.
 accessibility_requirements:
   wcag20:1.3.1: # Info and Relationships (A)
-    secondary: true
+    secondary: This success criterion is **less strict** than this rule. This is because the rule does not ignore irrelevant ARIA properties. Some of the failed examples satisfy this success criterion.
   wcag20:4.1.2: # Name, Role, Value (A)
-    secondary: true
+    secondary: This success criterion is **less strict** than this rule. This is because the rule does not ignore irrelevant ARIA properties. Some of the failed examples satisfy this success criterion.
 input_aspects:
   - DOM Tree
 acknowledgments:
@@ -36,7 +36,7 @@ There are no accessibility support issues known.
 
 ## Background
 
-The presence of unknown ARIA attributes is often the result of a typo or other developer error. These attributes are ignored by browsers and other assistive technologies. This often means that a state or property which should exist is missing. This can cause issues under [success criterion 1.3.1 Info and Relationships][sc131] or [4.1.2 Name, Rule Value][sc412].
+The presence of unknown ARIA attributes is often the result of a typo or other developer error. These attributes are ignored by browsers and other assistive technologies. This often means that a state or property which should exist is missing.
 
 ### Bibliography
 
@@ -122,5 +122,3 @@ This `canvas` element does not have an `aria-` attribute specified.
 ```
 
 [wai-aria specifications]: #wai-aria-specifications 'Definition of WAI-ARIA specifications'
-[sc131]: https://www.w3.org/TR/WCAG21/#info-and-relationships
-[sc412]: https://www.w3.org/TR/WCAG21/#name-role-value
diff --git a/_rules/aria-state-or-property-permitted-5c01ea.md b/_rules/aria-state-or-property-permitted-5c01ea.md
@@ -17,9 +17,9 @@ accessibility_requirements:
     passed: satisfied
     inapplicable: satisfied
   wcag20:1.3.1: # Info and Relationships (A)
-    secondary: true
+    secondary: This success criterion is **less strict** than this rule. This is because the rule does not ignore irrelevant ARIA properties. Some of the failed examples satisfy this success criterion.
   wcag20:4.1.2: # Name, Role, Value (A)
-    secondary: true
+    secondary: This success criterion is **less strict** than this rule. This is because the rule does not ignore irrelevant ARIA properties. Some of the failed examples satisfy this success criterion.
 input_aspects:
   - Accessibility Tree
   - CSS styling
@@ -60,7 +60,7 @@ Implementation of [Presentational Roles Conflict Resolution][] varies from one b
 
 ## Background
 
-The presence of prohibited ARIA attributes is often the result of a developer using an incorrect role, or a misunderstanding of the attribute. These attributes are ignored by browsers and other assistive technologies. This often means that a state or property which should exist is missing. This can cause issues under [success criterion 1.3.1 Info and Relationships][sc131] or [4.1.2 Name, Rule Value][sc412].
+The presence of prohibited ARIA attributes is often the result of a developer using an incorrect role, or a misunderstanding of the attribute. These attributes are ignored by browsers and other assistive technologies. This often means that a state or property which should exist is missing.
 
 In HTML, there are language features that do not have corresponding implicit WAI-ARIA semantics. As per [ARIA in HTML](https://www.w3.org/TR/html-aria/), those elements can have [global states or properties][global]. Some of those elements can also have [inherited][], [supported][], or [required][] [states][state] or [properties][property] that correspond to a [WAI-ARIA role](https://www.w3.org/TR/wai-aria-1.2/#introroles). For example, the `audio` element has no corresponding ARIA semantics but it can have [inherited][], [supported][], or [required][] [states][state] or [properties][property] of the [`application` role](https://www.w3.org/TR/wai-aria-1.2/#application).
 
@@ -233,5 +233,3 @@ This `div` element is not [included in the accessibility tree][], hence its [WAI
 [wai-aria state or property]: https://www.w3.org/TR/wai-aria-1.2/#state_prop_def 'Definition of ARIA States and Properties'
 [namespaced element]: #namespaced-element
 [prohibited]: https://www.w3.org/TR/wai-aria-1.2/#prohibitedattributes 'WAI-ARIA 1.2 Definition of Prohibited States and Properties'
-[sc131]: https://www.w3.org/TR/WCAG21/#info-and-relationships
-[sc412]: https://www.w3.org/TR/WCAG21/#name-role-value
diff --git a/_rules/aria-state-or-property-valid-value-6a7281.md b/_rules/aria-state-or-property-valid-value-6a7281.md
@@ -12,9 +12,9 @@ accessibility_requirements:
     passed: satisfied
     inapplicable: satisfied
   wcag20:1.3.1: # Info and Relationships (A)
-    secondary: true
+    secondary: This success criterion is **less strict** than this rule. This is because the rule does not ignore irrelevant ARIA properties. Some of the failed examples satisfy this success criterion.
   wcag20:4.1.2: # Name, Role, Value (A)
-    secondary: true
+    secondary: This success criterion is **less strict** than this rule. This is because the rule does not ignore irrelevant ARIA properties. Some of the failed examples satisfy this success criterion.
 input_aspects:
   - DOM Tree
   - CSS Styling
@@ -46,7 +46,7 @@ Some user agents treat the value of `aria-*` attribute as case-sensitive (even w
 
 ## Background
 
-Using invalid ARIA attribute values is often the result of a typo or other developer error. These attributes are then either ignored, or a default value is assumed by browsers and assistive technologies. This often means that a state or property which should exist is missing or has an unexpected value. This can cause issues under [success criterion 1.3.1 Info and Relationships][sc131] or [4.1.2 Name, Rule Value][sc412]. If the default value for invalid attribute values happens to match the author's intention for the value, there will not be an accessibility issue.
+Using invalid ARIA attribute values is often the result of a typo or other developer error. These attributes are then either ignored, or a default value is assumed by browsers and assistive technologies. This often means that a state or property which should exist is missing or has an unexpected value. If the default value for invalid attribute values happens to match the author's intention for the value, there will not be an accessibility issue.
 
 This rule does not require the target of an `ID Reference` to exist. This is because referencing an element that does not exist, and not having the reference at all has the same end result. A common use case for using `ID Reference` for a non-existing ID is to use a static `aria-errormessage` on an `input` element, and to only insert the element with the error message if there is an actual error. There are some cases in which ID references are required. These are tested in a separate rule.
 
@@ -242,7 +242,5 @@ The `aria-hidden` attribute is not on an [HTML or SVG element][].
 ```
 
 [html or svg element]: #namespaced-element
-[sc131]: https://www.w3.org/TR/WCAG21/#info-and-relationships
-[sc412]: https://www.w3.org/TR/WCAG21/#name-role-value
 [value type]: https://www.w3.org/TR/wai-aria-1.2/#propcharacteristic_value
 [wai-aria state or property]: https://www.w3.org/TR/wai-aria-1.2/#state_prop_def
diff --git a/_rules/image-no-text-0va7u6.md b/_rules/image-no-text-0va7u6.md
@@ -12,7 +12,6 @@ accessibility_requirements:
     inapplicable: further testing needed
   wcag20:1.4.9: # Images of Text (No Exception) (AAA)
     forConformance: true
-    secondary: true
     failed: not satisfied
     passed: further testing needed
     inapplicable: further testing needed
@@ -56,7 +55,7 @@ There are no accessibility support issues known.
 
 ## Background
 
-This rule is designed specifically for [SC 1.4.5 Images of Text][sc1.4.5] which includes exceptions to the images it applies to that are not part of [SC 1.4.9 Images of Text (No Exception)][sc1.4.9]. Therefore, some images that are inapplicable for this rule can be applicable to [SC 1.4.9 Images of Text (No Exception)][sc1.4.9].
+This rule is designed specifically for [SC 1.4.5 Images of Text][sc1.4.5]. There are however only minimal differences between this criterion and [SC 1.4.9 Images of Text (No Exception)][sc1.4.9]. The two differences are that customizable images of text are allowed, and that images of text are allowed when the presentation cannot otherwise be achieved. These scenarios are so rare the rule ignores them as part of the assumptions, and so the [accessibility requirements mapping](#accessibility-requirements-mapping) of these two criteria is the same.
 
 ### Bibliography
 
@@ -210,10 +209,13 @@ This image resource referenced by the `img` element contains text that provides
 This `img` element loads an SVG with text as an image resource. Because the SVG is loaded as an image resource, instead of being embedded in HTML the text cannot be selected or customized.
 
 ```html
-<img alt="WCAG Rocks" src="data:image/svg+xml;utf8,
+<img
+	alt="WCAG Rocks"
+	src="data:image/svg+xml;utf8,
 <svg xmlns='http://www.w3.org/2000/svg' height='20px' width='80px'>
   <text x='0' y='15'>WCAG Rocks</text>
-</svg>" />
+</svg>"
+/>
 ```
 
 ### Inapplicable

diff --git a/_rules/link-in-context-descriptive-5effbb.md b/_rules/link-in-context-descriptive-5effbb.md
@@ -11,11 +11,7 @@ accessibility_requirements:
     passed: further testing needed
     inapplicable: further testing needed
   wcag20:2.4.9: # Link Purpose (Link Only) (AAA)
-    forConformance: true
-    secondary: true
-    failed: not satisfied
-    passed: further testing needed
-    inapplicable: further testing needed
+    secondary: This success criterion is **more strict** than this rule. This is because the rule also considers the context of the link, in addition to the link text. Some of the passed examples do not satisfy this success criterion.
 input_aspects:
   - Accessibility Tree
   - DOM Tree
@@ -53,8 +49,6 @@ The [accessible name][] of each target element together with its [programmatical
 
 ## Background
 
-This rule is designed specifically for [2.4.4 Link Purpose (In Context)][sc244], which requires the purpose to be clear within the context of a link. Because links that do not have this, also are not clear without that context, this rule maps to [2.4.9 Link Purpose (Link only)][sc249] as well. In order to adequately test the [expectation](#expectation), some of the passed examples do not satisfy [2.4.9 Link Purpose (Link only)][sc249].
-
 ### Related rules
 
 - [Link has non-empty accessible name](https://www.w3.org/WAI/standards-guidelines/act/rules/c487ae/)

diff --git a/_rules/link-non-empty-accessible-name-c487ae.md b/_rules/link-non-empty-accessible-name-c487ae.md
@@ -17,7 +17,6 @@ accessibility_requirements:
     inapplicable: further testing needed
   wcag20:2.4.9: # Link Purpose (Link Only) (AAA)
     forConformance: true
-    secondary: true
     failed: not satisfied
     passed: further testing needed
     inapplicable: further testing needed
@@ -27,7 +26,7 @@ accessibility_requirements:
     passed: further testing needed
     inapplicable: further testing needed
   wcag20:1.1.1: # Non-text content (A)
-    secondary: true
+    secondary: This success criterion is **related** to this rule. This is because HTML `area` elements are both links and non-text content. Most failed examples satisfy this success criterion.
 input_aspects:
   - Accessibility Tree
   - DOM Tree
@@ -66,8 +65,6 @@ The rule assumes that all links are [user interface components](https://www.w3.o
 
 ## Background
 
-The HTML `area` element is both a link and non-text content. When this rule fails on `area` elements [success criterion 1.1.1 Non-text content][sc111] is not satisfied.
-
 ### Related rules
 
 - [Link in context is descriptive](https://www.w3.org/WAI/standards-guidelines/act/rules/5effbb/proposed/)
@@ -365,4 +362,3 @@ This `a` element does not have the role of link because it does not have an `hre
 [semantic role]: #semantic-role 'Definition of Semantic Role'
 [attribute value]: #attribute-value 'Definition of Attribute value'
 [html element]: #namespaced-element
-[sc111]: https://www.w3.org/TR/WCAG21/#non-text-content
diff --git a/_rules/links-identical-name-equivalent-purpose-b20e66.md b/_rules/links-identical-name-equivalent-purpose-b20e66.md
@@ -11,7 +11,7 @@ accessibility_requirements:
     passed: further testing needed
     inapplicable: further testing needed
 wcag20:2.4.4: # Link Purpose (In Context) (A)
-secondary: true
+secondary: This success criterion is **less strict** than this rule. This is because the rule does not consider the context of the link. Some of the failed examples satisfy this success criterion.
 input_aspects:
   - Accessibility Tree
   - DOM Tree
@@ -57,8 +57,6 @@ When followed, the links in each set of target elements resolve to the [same res
 
 ## Background
 
-This rule is closely related to [success criterion 2.4.4 Link Purpose (In Context)][sc244]. Because this rule is stricter, links that pass this rule satisfy 2.4.4 Link Purpose (In Context).
-
 ### Bibliography
 
 - [CSS Scoping Module Level 1 (editor's draft)](https://drafts.csswg.org/css-scoping/)
@@ -389,7 +387,6 @@ These `span` elements do not have a [semantic role][] of `link`. They are not va
 [presentational roles conflict resolution]: https://www.w3.org/TR/wai-aria-1.1/#conflict_resolution_presentation_none 'Presentational Roles Conflict Resolution'
 [same resource]: #same-resource 'Definition of same resource'
 [sc249]: https://www.w3.org/TR/WCAG21/#link-purpose-link-only 'Success Criterion 2.4.9: Link Purpose (Link Only)'
-[sc244]: https://www.w3.org/TR/WCAG21/#link-purpose-in-context 'Success Criterion 2.4.4: Link Purpose (In Context)'
 [semantic role]: #semantic-role 'Definition of semantic role'
 [shadow tree]: https://dom.spec.whatwg.org/#shadow-tree 'Definition of shadow tree'
 [web page (html)]: #web-page-html 'Definition of web page (HTML)'

diff --git a/_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md b/_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md
@@ -11,11 +11,7 @@ accessibility_requirements:
     passed: further testing needed
     inapplicable: further testing needed
   wcag20:2.4.9: # Link Purpose (Link Only) (AAA)
-    forConformance: true
-    secondary: true
-    failed: not satisfied
-    passed: further testing needed
-    inapplicable: further testing needed
+    secondary: This success criterion is **more strict** than this rule. This is because the rule also considers the context of the link, in addition to the link text. Some of the passed examples do not satisfy this success criterion.
 input_aspects:
   - DOM Tree
   - CSS Styling
@@ -64,9 +60,7 @@ There are no accessibility support issues known.
 
 ## Background
 
-This rule is designed specifically for [2.4.4 Link Purpose (In Context)][sc244], which requires the purpose to be clear within the context of a link. Because links that do not have this, also are not clear without that context, this rule maps to [2.4.9 Link Purpose (Link only)][sc249] as well. In order to adequately test the [expectation](#expectation), some of the passed examples do not satisfy [2.4.9 Link Purpose (Link only)][sc249].
-
-There is a difference between two contexts being the *same* and being *identical*. This rule specifically targets links within the *same* context. The same context means exactly the same set of DOM nodes. Identical (but not the same) contexts might have a different set of DOM nodes, but those DOM nodes have equivalent content - such as text content, attribute values, and so on. This difference is similar to the difference in some programming languages between pointer equivalence and deep object equivalence. Links with identical name that are in identical (but not the same) contexts also fail [2.4.4 Link Purpose (In Context)][sc244]. However, defining "identical context" unambiguously has been deemed infeasible at this time, and so has been left out of this rule.
+There is a difference between two contexts being the _same_ and being _identical_. This rule specifically targets links within the _same_ context. The same context means exactly the same set of DOM nodes. Identical (but not the same) contexts might have a different set of DOM nodes, but those DOM nodes have equivalent content - such as text content, attribute values, and so on. This difference is similar to the difference in some programming languages between pointer equivalence and deep object equivalence. Links with identical name that are in identical (but not the same) contexts also fail [2.4.4 Link Purpose (In Context)][sc244]. However, defining "identical context" unambiguously has been deemed infeasible at this time, and so has been left out of this rule.
 
 ### Bibliography
 
@@ -374,7 +368,7 @@ These two `span` elements do not have a [semantic role][] of link.
 
 #### Inapplicable Example 5
 
-These two HTML `a` elements have the same [accessible name][] and link to the [same resource][] but different [programmatically determined link contexts][programmatically determined link context]. Even though the two contexts in this example are *identical*, they are not the *same*. That is: even though they have equivalent content, they do not consist of the same DOM elements.
+These two HTML `a` elements have the same [accessible name][] and link to the [same resource][] but different [programmatically determined link contexts][programmatically determined link context]. Even though the two contexts in this example are _identical_, they are not the _same_. That is: even though they have equivalent content, they do not consist of the same DOM elements.
 
 ```html
 <html lang="en">
@@ -407,7 +401,6 @@ These two HTML `a` elements have the same [accessible name][] but different [pro
 [programmatically determined link context]: #programmatically-determined-link-context 'Definition of programmatically determined link context'
 [same resource]: #same-resource 'Definition of same resource'
 [sc244]: https://www.w3.org/TR/WCAG21/#link-purpose-in-context 'Success Criterion 2.4.4: Link Purpose (In Context)'
-[sc249]: https://www.w3.org/TR/WCAG21/#link-purpose-link-only 'Success Criterion 2.4.9: Link Purpose (Link Only)'
 [semantic role]: #semantic-role 'Definition of semantic role'
 [shadow tree]: https://dom.spec.whatwg.org/#shadow-tree 'Definition of shadow tree'
 [web page (html)]: #web-page-html 'Definition of web page (HTML)'