Updating CG writing guidance with example removed from ACT format doc. #2156
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Jym77
requested changes
Feb 15, 2024
pages/design/rule-design.md
Outdated
|
|
||
| > _For example:_ A rule testing that page titles are descriptive should only apply to specific `title` elements and this could be stated as _"This rule applies to the first HTML `title` element that is a descendant of the `html` element of a web page, and contains children that are text nodes that are not only whitespace."_. | ||
|
|
||
| ### Subjectivity in Applicability vs Expectation Example | ||
|
|
||
| The below section contains 2 approaches for writing an ACT rule for testing text contrast. For each example, both the applicability and expectation are included for clarity. Each of these examples follows the ACT rules format, but note that in the first example, the applicability is ended with the phrase "... except if the test target is part of a text node that is purely decorative or does not express anything in human language", while in the second example this phrase is appended to the expectation. Both of these approaches follow the normative ACT rules format and lead to valid ACT rules; however, we recommend including this text in the applicability when possible. When phrases such as this are included in the applicability, some test cases become inapplicable that would otherwise be passed if the phrase was included in the expectation. For example, for a smiling face emoji would be considered inapplicable when using the approach in Example 1, while in Example 2 the smiling face emoji would pass since it is considered an exception to the expectation. |
There was a problem hiding this comment.
I'd rather favour a more blurry language as to where to put the exceptions.
I'm still not 100% sure that exceptions need to be in Applicability all the time, notably because WCAG criteria also have exceptions that feel better suited for Expectations.
Typically, 1.4.3 states:
The visual presentation of text and images of text has a contrast ratio of at least 4.5:1, except for the following:
(…)
Logotypes
Text that is part of a logo or brand name has no contrast requirement.
I agree that the SC doesn't care about "stuff that looks like text but actually isn't" (aka emoji), and thus these should not be applicable. It's less clear whether logotypes should be Inapplicable or Passing (and thus whether a "except if this is a logotype" part should be in Applicability or Expectation).
I'm having even stronger feeling for 2.5.5 where the "essential size" exception sounds like a Expectation one, not an Applicability one. So I'd say that pins on a map should be Applicable, and Passing. They are "targets for pointer input", so 2.5.5 is concerned about them, but give them a special "pass" due to their essential size. While Emojis are not "text [nor] image of text", thus 1.4.3 doesn't even care.
This gets even stronger with 2.5.8, where the minimal spacing is also listed as an exception, but I don't think it would make sense to have the rule apply to "clickable elements, except when they are spaced enough".
So, I totally agree that "exceptions (or any other logical parts) should be where they belong", but I think that "where they belong" can be either Applicability or Expectation, depending on the rule and the SC.
So, I'd favour a more blurry statement that we recommend using this text in the applicability where possible". It is more a matter of "we recommend using this text in the applicability when it makes sense".
But I'm not sure how to phrase this correctly… Maybe with a few more examples.
Maybe the questions that rule authors (and reviewers) need to consider is "if there was a page with only emoji, would I consider that 1.4.3 is relevant for it?", "if there was a page with only a map and clickable pins on it, would I consider that 2.5.5 is relevant for it?", … If the SC is relevant, then the logic should be in the Expectation, if it isn't then it should be in the Applicability.
Co-authored-by: Jean-Yves Moyen <[email protected]>
carlosapaduarte
previously requested changes
Apr 1, 2024
pages/design/rule-design.md
Outdated
| @@ -105,10 +105,26 @@ While optional, this can provide information on authors, previous authors, and o | |||
|
|
|||
| Applicability describes which (elements of) web pages should be tested using the rule. These elements are known as test targets. Applicability must be written in plain language, as well-formed grammatically correct sentences, so that it can be used by QA testers. Applicability must rely on well defined properties of the technologies that are tested. For instance, a rule may be applicable to all `video` elements, but it can not be applicable to all `object` elements used to show video, unless the term "video" is further defined. | |||
|
|
|||
| Use objective, unambiguous definitions within applicability. Finding objective definitions to use in rules can be difficult, if not outright impossible in some cases. The intent here is to ensure repeatability of the rule. Not everything in WCAG testing is entirely repeatable, but when it comes to rule applicability, this is a hard requirement. | |||
| The applicability of a rule must be unambiguous and should be written using objective statements and in plain language. Finding objective definitions to use in rules can be difficult, if not outright impossible in some cases. New in version 1.1 of the ACT rules format is the ability to write rules using a subjective applicability. For rules that include a subjectivity, it is preferred to include a list of features (either in line or as part of a definition) that describes how an element should be evaluated for matching the accessibility (see the "Styled as a Heading" example in the [ACT Rules Format: Applicability](https://www.w3.org/TR/act-rules-format/#applicability)). Additionally, in the past exception statements have been included in the Expectation that can be placed in the applicability, this is the recommended approach when possible (see the "Subjectivity in Applicability vs Expectation" example below). As a reminder, the intent here is to ensure repeatability of the rule. Not everything in WCAG testing is entirely repeatable, but when it comes to rule applicability, this is a hard requirement. | |||
There was a problem hiding this comment.
Suggested change
| The applicability of a rule must be unambiguous and should be written using objective statements and in plain language. Finding objective definitions to use in rules can be difficult, if not outright impossible in some cases. New in version 1.1 of the ACT rules format is the ability to write rules using a subjective applicability. For rules that include a subjectivity, it is preferred to include a list of features (either in line or as part of a definition) that describes how an element should be evaluated for matching the accessibility (see the "Styled as a Heading" example in the [ACT Rules Format: Applicability](https://www.w3.org/TR/act-rules-format/#applicability)). Additionally, in the past exception statements have been included in the Expectation that can be placed in the applicability, this is the recommended approach when possible (see the "Subjectivity in Applicability vs Expectation" example below). As a reminder, the intent here is to ensure repeatability of the rule. Not everything in WCAG testing is entirely repeatable, but when it comes to rule applicability, this is a hard requirement. | |
| The applicability of a rule must be unambiguous and should be written using objective statements and in plain language. Finding objective definitions to use in rules can be difficult, if not outright impossible in some cases. New in version 1.1 of the ACT rules format is the ability to write rules using a subjective applicability. For rules that include subjectivity, it is preferred to include a list of features (either inline or as part of a definition) that describes how an element should be evaluated for matching the accessibility (see the "Styled as a Heading" example in the [ACT Rules Format: Applicability](https://www.w3.org/TR/act-rules-format/#applicability)). Additionally, in the past, exception statements have been included in the Expectation that can be placed in the applicability. This is the recommended approach when possible (see the "Subjectivity in Applicability vs Expectation" example below). As a reminder, the intent here is to ensure the repeatability of the rule. Not everything in WCAG testing is entirely repeatable, but when it comes to rule applicability, this is a hard requirement. |
There was a problem hiding this comment.
Additionally, I'm not sure we should state "This is the recommended approach when possible". Wouldn't it be better to state "This is the recommended approach when the test subject is inapplicable, instead of artificially making it pass the rule by having the subjectivity in the expectation" (or just the shorter version "This is the recommended approach when the test subject is inapplicable")?
There was a problem hiding this comment.
This one seems to have gotten away from me. I have corrected to be a lot more clear in the newest version.
Adding suggestions from Carlos. Co-authored-by: Carlos Duarte <[email protected]>
| When determining the placement of subjectivity in an ACT rule, the main question to answer is whether the S.C. would apply at all to the given content or if the content would satisfy the criteria via a normative exception. For example, | ||
| - For S.C. 1.4.3 Contrast Minimum, non-text content or text that is not expressing something in human language (like an emoji) is not evaluated by the S.C. and so should not be applicable in an ACT rule for 1.4.3 | ||
| - For S.C. 1.4.3 Contrast Minimum, logos are a normative exception to the S.C., so they should be included as a passed exception to the Expectation for an ACT rule testing 1.4.3. | ||
| - For S.C. 2.5.5 Target Size (Enhanced), a link inside of a paragraph of text and a pin on a map would fit the normative exceptions of "Inline" and "Essential" respectively, and so should be included as a passed exception in the Expectation. |
There was a problem hiding this comment.
Suggested change
| - For S.C. 2.5.5 Target Size (Enhanced), a link inside of a paragraph of text and a pin on a map would fit the normative exceptions of "Inline" and "Essential" respectively, and so should be included as a passed exception in the Expectation. | |
| - For S.C. 2.5.5 Target Size (Enhanced), a link inside of a paragraph of text and a pin on a map would fit the normative exceptions of "Inline" and "Essential" respectively, and so should be included as passed exceptions in the Expectation. |
|
|
||
| > _For example:_ A rule testing that page titles are descriptive should only apply to specific `title` elements and this could be stated as _"This rule applies to the first HTML `title` element that is a descendant of the `html` element of a web page, and contains children that are text nodes that are not only whitespace."_. | ||
|
|
||
| ### Subjectivity in Applicability vs Expectation Examples | ||
|
|
||
| With the development of ACT Rules format 1.1, subjectivity is now allowed in both the Applicability and the Expectation. However, depending on the rule, it can be difficult to know if a subjective phrase belongs in the Applicability or the Expectation. While we will continue to rely on the best judgment of the rule authors, most S.C. contain language suggesting where the subjectivity be placed. Lastly, at the bottom of this section, we provide some concrete examples of each of the cases below to help illustrate our point. |
There was a problem hiding this comment.
Suggested change
| With the development of ACT Rules format 1.1, subjectivity is now allowed in both the Applicability and the Expectation. However, depending on the rule, it can be difficult to know if a subjective phrase belongs in the Applicability or the Expectation. While we will continue to rely on the best judgment of the rule authors, most S.C. contain language suggesting where the subjectivity be placed. Lastly, at the bottom of this section, we provide some concrete examples of each of the cases below to help illustrate our point. | |
| With the development of ACT Rules format 1.1, subjectivity is now allowed in both the Applicability and the Expectation. However, depending on the rule, it can be difficult to know if a subjective phrase belongs in the Applicability or the Expectation. While we will continue to rely on the best judgment of the rule authors, most success criteria contain language suggesting where the subjectivity be placed. Lastly, at the bottom of this section, we provide some concrete examples of each of the cases below to help illustrate our point. |
consistent with wording above
Comment on lines
+116
to
+119
| When determining the placement of subjectivity in an ACT rule, the main question to answer is whether the S.C. would apply at all to the given content or if the content would satisfy the criteria via a normative exception. For example, | ||
| - For S.C. 1.4.3 Contrast Minimum, non-text content or text that is not expressing something in human language (like an emoji) is not evaluated by the S.C. and so should not be applicable in an ACT rule for 1.4.3 | ||
| - For S.C. 1.4.3 Contrast Minimum, logos are a normative exception to the S.C., so they should be included as a passed exception to the Expectation for an ACT rule testing 1.4.3. | ||
| - For S.C. 2.5.5 Target Size (Enhanced), a link inside of a paragraph of text and a pin on a map would fit the normative exceptions of "Inline" and "Essential" respectively, and so should be included as a passed exception in the Expectation. |
There was a problem hiding this comment.
Suggested change
| When determining the placement of subjectivity in an ACT rule, the main question to answer is whether the S.C. would apply at all to the given content or if the content would satisfy the criteria via a normative exception. For example, | |
| - For S.C. 1.4.3 Contrast Minimum, non-text content or text that is not expressing something in human language (like an emoji) is not evaluated by the S.C. and so should not be applicable in an ACT rule for 1.4.3 | |
| - For S.C. 1.4.3 Contrast Minimum, logos are a normative exception to the S.C., so they should be included as a passed exception to the Expectation for an ACT rule testing 1.4.3. | |
| - For S.C. 2.5.5 Target Size (Enhanced), a link inside of a paragraph of text and a pin on a map would fit the normative exceptions of "Inline" and "Essential" respectively, and so should be included as a passed exception in the Expectation. | |
| When determining the placement of subjectivity in an ACT rule, the main question to answer is whether the success criterion would apply at all to the given content or if the content would satisfy the criteria via a normative exception. For example, | |
| - For SC 1.4.3 Contrast Minimum, non-text content or text that is not expressing something in human language (like an emoji) is not evaluated by the success criterion and so should not be applicable in an ACT rule for 1.4.3 | |
| - For SC 1.4.3 Contrast Minimum, logos are a normative exception to the success criterion, so they should be included as a passed exception to the Expectation for an ACT rule testing 1.4.3. | |
| - For SC 2.5.5 Target Size (Enhanced), a link inside of a paragraph of text and a pin on a map would fit the normative exceptions of "Inline" and "Essential" respectively, and so should be included as passed exceptions in the Expectation. |
consistent with WCAG acronym (I'm not sure we have best practices as ACT on how to consistently present some common words, but I think this is more appropriate and consitent with WCAG documentation).
| - For S.C. 1.4.3 Contrast Minimum, non-text content or text that is not expressing something in human language (like an emoji) is not evaluated by the S.C. and so should not be applicable in an ACT rule for 1.4.3 | ||
| - For S.C. 1.4.3 Contrast Minimum, logos are a normative exception to the S.C., so they should be included as a passed exception to the Expectation for an ACT rule testing 1.4.3. | ||
| - For S.C. 2.5.5 Target Size (Enhanced), a link inside of a paragraph of text and a pin on a map would fit the normative exceptions of "Inline" and "Essential" respectively, and so should be included as a passed exception in the Expectation. | ||
| - For S.C. 3.3.1: Error Identification, a page should not be applicable for an ACT rule until a form field error indicator exists, thus the presence of a form field error indicator should be included in the rule's applicability. |
There was a problem hiding this comment.
Suggested change
| - For S.C. 3.3.1: Error Identification, a page should not be applicable for an ACT rule until a form field error indicator exists, thus the presence of a form field error indicator should be included in the rule's applicability. | |
| - For SC 3.3.1 Error Identification, a page should not be applicable for an ACT rule until a form field error indicator exists, thus the presence of a form field error indicator should be included in the rule's applicability. |
|
|
||
| When making these determinations, it maybe helpful to consider the following circumstances: | ||
| - If there was a page with only the content in question, would you expect it to be passed or inapplicable for an ACT rule. Passing would indicate the subjectivity belongs in the Expectation while inapplicable suggests it belongs in the Applicability. | ||
| - Does the formulation of applicability and expectation lead to test cases that pass that should be inapplicable? If so, subjectivity likely needs to be added to the Applicability (possibility moved from the Expectation to the Applicability) |
There was a problem hiding this comment.
Suggested change
| - Does the formulation of applicability and expectation lead to test cases that pass that should be inapplicable? If so, subjectivity likely needs to be added to the Applicability (possibility moved from the Expectation to the Applicability) | |
| - Does the formulation of applicability and expectation lead to test cases passing when they should be deemed inapplicable? If so, subjectivity likely needs to be added to the Applicability (possibility moved from the Expectation to the Applicability) |
rewording a little bit to improve clarity
| - For S.C. 2.5.5 Target Size (Enhanced), a link inside of a paragraph of text and a pin on a map would fit the normative exceptions of "Inline" and "Essential" respectively, and so should be included as a passed exception in the Expectation. | ||
| - For S.C. 3.3.1: Error Identification, a page should not be applicable for an ACT rule until a form field error indicator exists, thus the presence of a form field error indicator should be included in the rule's applicability. | ||
|
|
||
| When making these determinations, it maybe helpful to consider the following circumstances: |
There was a problem hiding this comment.
Suggested change
| When making these determinations, it maybe helpful to consider the following circumstances: | |
| When making these determinations, it may be helpful to consider the following circumstances: |
| - If there was a page with only the content in question, would you expect it to be passed or inapplicable for an ACT rule. Passing would indicate the subjectivity belongs in the Expectation while inapplicable suggests it belongs in the Applicability. | ||
| - Does the formulation of applicability and expectation lead to test cases that pass that should be inapplicable? If so, subjectivity likely needs to be added to the Applicability (possibility moved from the Expectation to the Applicability) | ||
|
|
||
| As a final reminder, the end goal of allowing subjectivity in the applicability is allow the writing of rules that were previously impossible and to prevent rules from creating passed test cases that are inapplicable to the S.C. the rule is intended to test. |
There was a problem hiding this comment.
Suggested change
| As a final reminder, the end goal of allowing subjectivity in the applicability is allow the writing of rules that were previously impossible and to prevent rules from creating passed test cases that are inapplicable to the S.C. the rule is intended to test. | |
| As a final reminder, the end goal of allowing subjectivity in the applicability is to allow the creation of rules that were previously impossible and to prevent rules from creating passed examples that are inapplicable to the success criteria the rule is intended to test. |
reworded a little bit to improve clarity
| - For S.C. 3.3.1: Error Identification, a page should not be applicable for an ACT rule until a form field error indicator exists, thus the presence of a form field error indicator should be included in the rule's applicability. | ||
|
|
||
| When making these determinations, it maybe helpful to consider the following circumstances: | ||
| - If there was a page with only the content in question, would you expect it to be passed or inapplicable for an ACT rule. Passing would indicate the subjectivity belongs in the Expectation while inapplicable suggests it belongs in the Applicability. |
There was a problem hiding this comment.
Suggested change
| - If there was a page with only the content in question, would you expect it to be passed or inapplicable for an ACT rule. Passing would indicate the subjectivity belongs in the Expectation while inapplicable suggests it belongs in the Applicability. | |
| - If a page contained only the specific example, would you expect it to pass or be deemed inapplicable for an ACT rule? Passing would imply the subjectivity belongs in the Expectation, while being inapplicable suggests it belongs in the Applicability. |
I think "content in question" should be replaced with "specific example", since "Example" is the word we use for each test case.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Updating writing guidelines documents with an example we originally had in the format but decided was better included in the writing guide. I haven't messed with these documents, so let me know if there is a better place to put the example than inline. I also don't know if this change requires a CFC, so let me know.
Need for Call for Review:
<< choose one of the following and remove the rest >>
<< check Process Document on Call for Review >>
This can be merged with 1 approval << choose reason: editorial changes to website/test code, adding new contributor, other (explain). >>
This will not require a Call for Review << choose reason(s): editorial changes (including to the applicability, expectation or examples section), changes to assumptions, background, accessibility support, change to website/test code (not rule), other (explain). >>
This will require a 1 week Call for Review << small changes affecting a small number of test cases, if in doubt do not use this. >>
This will require a 2 weeks Call for Review << new rule, or substantial changes affecting a large number of test cases, if in doubt, use this. >>
How to Review And Approve