Skip to content
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

Update background and change log #550

Merged
merged 14 commits into from
Nov 30, 2023
Merged

Update background and change log #550

Changes from 9 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
429990b
Update act-rules-format.bs
kengdoj Oct 19, 2023
69b86ec
Update act-rules-format.bs
kengdoj Oct 19, 2023
e9a2f92
Update act-rules-format.bs
kengdoj Oct 26, 2023
07195e0
Update act-rules-format/act-rules-format.bs
kengdoj Oct 26, 2023
c3397cf
Update act-rules-format.bs
kengdoj Oct 26, 2023
c7689e4
Update act-rules-format/act-rules-format.bs
kengdoj Oct 26, 2023
a4f82bb
Update act-rules-format.bs
kengdoj Oct 26, 2023
1ffee3e
Update act-rules-format.bs
kengdoj Nov 6, 2023
37da570
Update act-rules-format.bs
kengdoj Nov 6, 2023
b1465c6
Update act-rules-format/act-rules-format.bs
kengdoj Nov 28, 2023
6b99e91
Apply suggestions from code review
kengdoj Nov 28, 2023
367976d
Apply suggestions from code review
kengdoj Nov 28, 2023
4c39651
Merge branch 'main' into kengdoj-backgroud
kengdoj Nov 28, 2023
183cf2c
Apply suggestions from code review
kengdoj Nov 30, 2023
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
64 changes: 36 additions & 28 deletions act-rules-format/act-rules-format.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,16 +99,18 @@ An ACT Rule <em class="rfc2119">must</em> consist of at least the following item
* [Input Rules](#input-rules) (for composite rules)
* [Applicability](#applicability)
* [Expectations](#expectations)
* [Assumptions](#assumptions)
* [Accessibility Support](#accessibility-support)
* [Background] (#background)
* [Assumptions](#assumptions)
* [Accessibility Support](#accessibility-support)
kengdoj marked this conversation as resolved.
Show resolved Hide resolved
* [Test Cases](#test-cases)
* [Change Log](#change-log)
* [Rule Versions](#rule-versions)
* [Glossary](#glossary)

An ACT Rule MAY also contain:

* [Related Rules](related-rules) (optional) under Background
* [Other Resources](other-resources) (optional) under Background
* [Issues List](#issues-list) (optional)
* [Background](#background) (optional)
* [Acknowledgments](#acknowledgments) (optional)

The ACT Rules format does not prescribe what format ACT Rules can be written in (e.g. HTML, DOCX, PDF, etc.). However, ACT Rules <em class="rfc2119">must</em> be written in a document that conforms to the Web Content Accessibility Guidelines [[WCAG]] or a comparable accessibility standard. This ensures that ACT Rules are accessible to people with disabilities. ACT Rule [test cases](#test-cases) are allowed to contain inaccessible content. If any test case contains accessibility issues listed in [WCAG 2.1 Section 5.2.5 Non-Interference](https://www.w3.org/TR/WCAG21/#cc5), users <em class="rfc2119">must</em> be warned of this in advance. In addition to supporting people with disabilities, using an accessible format also makes internationalization of ACT Rules easier.
Expand Down Expand Up @@ -231,26 +233,26 @@ Some scenarios when a rule will have Secondary requirements include:

**Scenario 1**: the rule is not as strict as a requirement

A rule was designed to test a minimum accessibility requirement and there exists a stricter requirement. The rule’s failed outcomes can determine that the stricter accessibility requirement is not satisfied, and the rule’s passed outcomes may not determine that the stricter requirement is satisfied. It is possible that the accessibility requirement may be not satisfied when the rule's outcomes are passed. The stricter requirement is a Secondary requirement.
A rule was designed to test a minimum accessibility requirement and there exists a stricter requirement. The rule's failed outcomes can determine that the stricter accessibility requirement is not satisfied, and the rule's passed outcomes may not determine that the stricter requirement is satisfied. It is possible that the accessibility requirement may be not satisfied when the rule's outcomes are passed. The stricter requirement is a Secondary requirement.
kengdoj marked this conversation as resolved.
Show resolved Hide resolved

<aside class=example>
<header>Example: a rule that tests if text has minimum contrast</header>
<blockquote>This rule was designed to test Success Criterion 1.4.3 Contrast Minimum (AA). A stricter requirement, Success Criterion 1.4.6 Contrast (Enhanced) (Level AAA), will be not satisfied when the rule outcome is failed, and may be not satisfied when the rule outcomes are passed. This rule’s mapping:
<blockquote>This rule was designed to test Success Criterion 1.4.3 Contrast Minimum (AA). A stricter requirement, Success Criterion 1.4.6 Contrast (Enhanced) (Level AAA), will be not satisfied when the rule outcome is failed, and may be not satisfied when the rule outcomes are passed. This rule's mapping:
kengdoj marked this conversation as resolved.
Show resolved Hide resolved
<ul>
<li>Conformance Requirement: Success Criterion 1.4.3 Contrast (Minimum)</li>
<li>Secondary Requirement: Success Criterion 1.4.6 Contrast (Enhanced)</li>
<ul><li>Background Section: Success Criterion 1.4.6 is mapped as a Secondary requirement because the SC may be [=not satisfied=]when the rule’s outcomes are `passed`. </li></ul>
<ul><li>Background Section: Success Criterion 1.4.6 is mapped as a Secondary requirement because the SC may be [=not satisfied=]when the rule's outcomes are `passed`. </li></ul>
kengdoj marked this conversation as resolved.
Show resolved Hide resolved
</ul>
</blockquote>
</aside>

**Scenario 2**: the rule's failed outcomes require further testing for the accessibility requirement

A rule was designed to test a specific type of solution for an accessibility requirement, but the rule does not cover all solutions that can be used to meet the requirement. In this scenario, the rule’s failed outcomes cannot determine that an accessibility requirement is not satisfied because further testing is needed. The rule’s passed outcomes can determine that an accessibility requirement is satisfied. The accessibility requirement is a Secondary requirement.</li>
A rule was designed to test a specific type of solution for an accessibility requirement, but the rule does not cover all solutions that can be used to meet the requirement. In this scenario, the rule's failed outcomes cannot determine that an accessibility requirement is not satisfied because further testing is needed. The rule's passed outcomes can determine that an accessibility requirement is satisfied. The accessibility requirement is a Secondary requirement.</li>
kengdoj marked this conversation as resolved.
Show resolved Hide resolved

<aside class=example>
<header>Example: a rule that tests if a focusable element has no keyboard trap via standard navigation</header>
<blockquote>This rule was designed to test for a specific solution that can be used to meet Success Criterion 2.1.2: No Keyboard Trap. The rule does not test for other possible solutions, such as the use of non-standard navigation, so its failed outcomes cannot determine that the accessibility requirement is [=not satisfied=]. This rule’s mapping:
<blockquote>This rule was designed to test for a specific solution that can be used to meet Success Criterion 2.1.2: No Keyboard Trap. The rule does not test for other possible solutions, such as the use of non-standard navigation, so its failed outcomes cannot determine that the accessibility requirement is [=not satisfied=]. This rule's mapping:
kengdoj marked this conversation as resolved.
Show resolved Hide resolved
<ul>
<li>Secondary Requirement: Success Criterion 2.1.2: No Keyboard Trap</li>
<ul><li>Background Section: This rule tests for one solution that can meet Success Criterion 2.1.2. SC 2.1.2 is mapped as a Secondary requirement because other solutions (such as use of non-standard navigation to exit a keyboard trap) can be used to meet this SC that are not tested by this rule.</li></ul>
Expand All @@ -260,15 +262,15 @@ A rule was designed to test a specific type of solution for an accessibility req

**Scenario 3**: the rule is stricter than a requirement

A rule was designed to test an accessibility requirement and there exists a less strict accessibility requirement. In this scenario, the rule’s passed outcomes can determine that the less strict requirement is satisfied, and the rule’s failed outcomes may not determine that the less strict requirement is not satisfied. It is possible that the accessibility requirement may be satisfied when the rule’s outcome is failed. The less strict accessibility requirement is a Secondary requirement.</li>
A rule was designed to test an accessibility requirement and there exists a less strict accessibility requirement. In this scenario, the rule's passed outcomes can determine that the less strict requirement is satisfied, and the rule's failed outcomes may not determine that the less strict requirement is not satisfied. It is possible that the accessibility requirement may be satisfied when the rule's outcome is failed. The less strict accessibility requirement is a Secondary requirement.</li>
kengdoj marked this conversation as resolved.
Show resolved Hide resolved

<aside class=example>
<header>Example: a rule that tests Enhanced Contrast</header>
<blockquote>This rule was designed to test Success Criterion 1.4.6 Contrast (Enhanced) (Level AAA). A less strict requirement, Success Criterion 1.4.3 Contrast Minimum (AA), will be satisfied when the rule outcomes are passed, and may be satisfied when the rule outcomes are failed. This rule’s mapping:
<blockquote>This rule was designed to test Success Criterion 1.4.6 Contrast (Enhanced) (Level AAA). A less strict requirement, Success Criterion 1.4.3 Contrast Minimum (AA), will be satisfied when the rule outcomes are passed, and may be satisfied when the rule outcomes are failed. This rule's mapping:
kengdoj marked this conversation as resolved.
Show resolved Hide resolved
<ul>
<li>Conformance Requirement: Success Criterion 1.4.6 Contrast (Enhanced)</li>
<li>Secondary Requirement: Success Criterion 1.4.3 Contrast (Minimum)</li>
<ul><li>Background Section: Success Criterion 1.4.3 is mapped as a Secondary requirement because the SC may be [=satisfied=]when the rule’s outcomes are `failed`.</li></ul>
<ul><li>Background Section: Success Criterion 1.4.3 is mapped as a Secondary requirement because the SC may be [=satisfied=]when the rule's outcomes are `failed`.</li></ul>
kengdoj marked this conversation as resolved.
Show resolved Hide resolved
</aside>


Expand All @@ -278,7 +280,7 @@ A rule was designed to test an accessibility requirement and under certain condi

<aside class=example>
<header>Example 1: a rule that tests if a link has a non-empty accessible name</header>
<blockquote>This rule was designed to test links for accessibility requirements 4.1.2 Name, Role, Value (Level A), 2.4.4 Link Purpose (In Context) (Level A), 2.4.9 Link Purpose (Link Only) (Level AAA). When a &lt;map&gt; element is used with <area> elements to define an image map, this is also a link area. Testing for non-empty accessible name for &lt;area&gt; elements would map to another accessibility requirement 1.1.1 Non-text Content. Because the rule tests for all links and SC 1.1.1 only applies certain links, this rule’s mapping:
<blockquote>This rule was designed to test links for accessibility requirements 4.1.2 Name, Role, Value (Level A), 2.4.4 Link Purpose (In Context) (Level A), 2.4.9 Link Purpose (Link Only) (Level AAA). When a &lt;map&gt; element is used with <area> elements to define an image map, this is also a link area. Testing for non-empty accessible name for &lt;area&gt; elements would map to another accessibility requirement 1.1.1 Non-text Content. Because the rule tests for all links and SC 1.1.1 only applies certain links, this rule's mapping:
kengdoj marked this conversation as resolved.
Show resolved Hide resolved
<ul>
<li>Conformance Requirement: Success Criteria 4.1.2 Name, Role, Value (Level A), 2.4.4 Link Purpose (In Context) (Level A), 2.4.9 Link Purpose (Link Only) (Level AAA)</li>
<li>Secondary Requirement: Success Criterion 1.1.1 Non-text Content</li>
Expand All @@ -289,7 +291,7 @@ A rule was designed to test an accessibility requirement and under certain condi

<aside class=example>
<header>Example 2: A rule that tests that elements that have an explicit role also specify all required states and properties </header>
<blockquote>This rule was designed to test a requirement of WAI-ARIA. In some cases, a failed outcome for this rule may result in WCAG 2 Success Criterion 4.1.2 Name, Role, Value being not satisfied, but not always. This rule’s mapping:
<blockquote>This rule was designed to test a requirement of WAI-ARIA. In some cases, a failed outcome for this rule may result in WCAG 2 Success Criterion 4.1.2 Name, Role, Value being not satisfied, but not always. This rule's mapping:
kengdoj marked this conversation as resolved.
Show resolved Hide resolved
<ul>
<li>Conformance Requirement: WAI-ARIA 1.1</li>
<li>Secondary Requirement: Success Criterion 4.1.2 Name, Role, Value
Expand Down Expand Up @@ -507,9 +509,13 @@ All expectations of a [=composite rule=] <em class="rfc2119">must</em> describe
</ul></blockquote>
</aside>

Background {#background}
-----------------------------------

An ACT Rule's Background <em class="rfc2119">must</em> contain the Assumptions and Accessibility Support sections. Additional information <em class="rfc2119">may</em> be included about the development of the rule, or references to relevant reading in Other Resources, or Related Rules. Whenever a is included in the rule, the relationship to the relevant reading can be specified. Examples of relevant background references for a rule for a [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) [[WCAG]] success criterion could be [WCAG 2.1 Understanding documents](https://www.w3.org/WAI/WCAG21/Understanding/), [WCAG 2.1 Techniques](https://www.w3.org/WAI/WCAG21/Techniques/), or [WAI-ARIA 1.1](https://www.w3.org/TR/wai-aria/), CSS [[css-2018]], or HTML [[HTML]] specifications.
daniel-montalvo marked this conversation as resolved.
Show resolved Hide resolved
kengdoj marked this conversation as resolved.
Show resolved Hide resolved

Assumptions {#assumptions}
--------------------------

### Assumptions ### {#assumptions}

An ACT Rule <em class="rfc2119">must</em> list any known assumptions, limitations or any exceptions for the evaluation, the test environment, technologies being used or the subject being tested. For example, a rule that would partially test [WCAG 2.1 success criterion 1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/quickref/#contrast-minimum) based on the inspection of CSS properties could state that it is only applicable to HTML text content styleable with CSS, and that the rule does not support images of text.

Expand All @@ -518,8 +524,7 @@ Sometimes there are multiple plausible ways that an accessibility requirement ca
While the assumptions <em class="rfc2119">must</em> be included in the ACT Rule, it <em class="rfc2119">may</em> be empty when there are no known assumptions, limitations or exceptions.


Accessibility Support {#accessibility-support}
----------------------------------------------
#### Accessibility Support #### {#accessibility-support}

Content can be designed to rely on the support for particular accessibility features by different assistive technologies and user agents. For example, content using a particular [WAI-ARIA 1.1](https://www.w3.org/TR/wai-aria/) feature relies on that feature to be supported by assistive technologies and user agents. This content would not work for assistive technologies and user agents that do not support WAI-ARIA. See the WCAG definition for [accessibility supported](https://www.w3.org/TR/WCAG21/#dfn-accessibility-supported) use of a web technology.

Expand All @@ -539,6 +544,16 @@ While an accessibility support section <em class="rfc2119">must</em> be included
</div>


#### Related Rules (optional) #### {#related-rules}

Related rules are other rules that test the same accessibility requirement. For example, two related rules of a composite rule can be the two atomic rules that contribute to its outcome. Similarly, each atomic rule in this example can list the other atomic rule and the composite rule as its related rules.


#### Other Resources (optional) #### {#other-resources}

Whenever a resource is included in the rule, the relationship to the relevant reading can be specified. Examples of relevant background references for a rule for a [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) [[WCAG]] success criterion could be [WCAG 2.1 Understanding documents](https://www.w3.org/WAI/WCAG21/Understanding/), [WCAG 2.1 Techniques](https://www.w3.org/WAI/WCAG21/Techniques/), or [WAI-ARIA 1.1](https://www.w3.org/TR/wai-aria/), CSS [[css-2018]], or HTML [[HTML]] specifications.


Test Cases {#test-cases}
------------------------

Expand All @@ -563,16 +578,16 @@ Test cases are (snippets of) content that can be used to validate the implementa
</aside>


Change Log {#change-log}
Rule Versions {#rule-versions}
------------------------

It is important to keep track of changes to the ACT Rules so that users of the rules can understand if changes in test results are due to changes in the rules used when performing the tests, or from changes in the content itself. All changes to an ACT Rule that can change the [=outcomes=] of an evaluation <em class="rfc2119">must</em> be recorded in a change log. The change log can either be part of the rule document itself or be referenced from it.
It is important to keep track of versions of ACT Rules so that users of the rules can understand if changes in test results are due to changes in the rules used when performing the tests, or from changes in the content itself. All previous versions of an ACT Rule <em class="rfc2119">must</em> be recorded either in the rule document or referenced from it.
kengdoj marked this conversation as resolved.
Show resolved Hide resolved


Glossary {#glossary}
--------------------

ACT Rules <em class="rfc2119">must</em> have a glossary section. The glossary <em class="rfc2119">must</em> contain the [=outcome=] definition, as well as any definitions used in [applicability](#applicability) and [expectations](#expectations) sections in the rule. Since changes to the definition change the rule, those definitions cannot be maintained independently of the rule. If a shared glossary is used for rules, any definition changes <em class="rfc2119">must</em> be included in the [change log](#change-log) of all rules that use that definition.
ACT Rules <em class="rfc2119">must</em> have a glossary section. The glossary <em class="rfc2119">must</em> contain the [=outcome=] definition, as well as any definitions used in [applicability](#applicability) and [expectations](#expectations) sections in the rule. Since changes to the definition change the rule, those definitions cannot be maintained independently of the rule. If a shared glossary is used for rules, any definition changes <em class="rfc2119">must</em> result in a new [rule version](#rule-versions) of all rules that use that definition.


Issues List (optional) {#issues-list}
Expand All @@ -582,13 +597,6 @@ An ACT Rule <em class="rfc2119">may</em> include a list or a reference to a list

The issues list serves two purposes. For users of ACT Rules, the issues list gives insight into why an inaccurate result occurred, as well as provide confidence in the result of that rule. For the designer of the rule, the issues list is also useful to plan future updates to the rule. In a new version of the rule, resolved issues would be moved to the change log.


Background (optional) {#background}
-----------------------------------

An ACT Rule <em class="rfc2119">may</em> contain information about the background for the development of the rule, or references to relevant reading. The background information is optional, but whenever it is included in the rule, the relationship to the relevant reading can be specified. Examples of relevant background references for a rule for a [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) [[WCAG]] success criterion could be [WCAG 2.1 Understanding documents](https://www.w3.org/WAI/WCAG21/Understanding/), [WCAG 2.1 Techniques](https://www.w3.org/WAI/WCAG21/Techniques/), or [WAI-ARIA 1.1](https://www.w3.org/TR/wai-aria/), CSS [[css-2018]], or HTML [[HTML]] specifications.


Acknowledgments (optional) {#acknowledgments}
-----------------------------------------------

Expand Down