Skip to content

Updating CG writing guidance with example removed from ACT format doc. #2156

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tbostic32 wants to merge 11 commits into
base: develop
Choose a base branch
from
Open

Updating CG writing guidance with example removed from ACT format doc. #2156

Changes from 1 commit
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
513d49f
Updating CG writing guidance with example removed from ACT format doc.
tbostic32 Feb 1, 2024
796f219
Apply suggestions from code review
tbostic32 Mar 6, 2024
b1ebf1b
Changing writing of subjectivity in applicabilty guide.
tbostic32 Mar 6, 2024
451d891
Fixing spelling issues.
tbostic32 Mar 27, 2024
c606ac7
Updating bad sentence.
tbostic32 Apr 4, 2024
2e0b30a
Apply suggestions from code review
tbostic32 Apr 4, 2024
9574e35
Clarifying text.
tbostic32 Apr 4, 2024
276c443
Spelling error.
tbostic32 Apr 4, 2024
0f5e02d
Merge branch 'develop' into tbostic/subjective_writing_guidance
Jym77 Apr 18, 2024
9230b3d
Apply suggestions from code review
WilcoFiers May 29, 2025
5fee2e3
Merge branch 'develop' into tbostic/subjective_writing_guidance
WilcoFiers May 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion pages/design/rule-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,10 +105,23 @@ 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 unambigious 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 defintion) 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.

> _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.
Copy link
Collaborator

@Jym77 Jym77 Feb 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


**Example 1 of Text Contrast**
- Applicability: This rule applies to any visible character in a text node that is a child in the flat tree of an HTML element, except if the test target is part of a text node that is purely decorative or does not express anything in human language.
- Expectation: For each test target, the highest possible contrast between the foreground colors and background colors is at least 3.0:1 for large scale text and 4.5:1 for other texts.

**Example 2 of Text Contrast**
- Applicability: This rule applies to any visible character in a text node that is a child in the flat tree of an HTML element
- Expectation: For each test target, the highest possible contrast between the foreground colors and background colors is at least 3.0:1 for large scale text and 4.5:1 for other texts, except if the test target is part of a text node that is purely decorative or does not express anything in human language.


For more details, see [ACT Rules Format: Applicability](https://www.w3.org/TR/act-rules-format/#applicability).

## Expectations
Expand Down