docs: Document how to propose axe-core rules (#507)

* docs: Document how to propose axe-core rules

* fix(rule-proposal): Added best practice and rule help

README.md

@@ -92,6 +92,8 @@ To create a new translation for aXe, start by running `grunt translate --lang=<l
 
 ## Contributing
 
+Read the [Proposing Axe-core Rules guide ](./doc/rule-proposal.md)
+
 Read the [documentation on the architecture](./doc/developer-guide.md)
 
 Read the [documentation on contributing](CONTRIBUTING.md)

doc/act-rules-format.md

@@ -0,0 +1,35 @@
+# W3C Standardized Rules
+
+Deque Systems is one of leading organizations in the development of standardized accessibility conformance testing rules. The [axe-core rules proposal format](./rule-proposal.md) is an adaptation of the [Accessibility Conformance Testing Rules Format](https://www.w3.org/TR/act-rules-format/).
+
+There are two ways a rule written in the axe-core rule format can be transformed into the ACT Rules format:
+
+## Method 1: Create a single rule
+
+This method is useful for rules with a small number of checks. 
+
+1. Add the test input type to it: `rendered page`
+2. Add an `assumptions` section, add possible assumptions to it
+3. Add an `outcomes` section, describing the different possible outcomes of the rule
+4. Add a `Validation Tests` section, that links to the integration tests
+5. Update the check to return pass/fail/cantTell instead of true/false/undefined
+6. Add control flow to the checks:
+  - `any` checks should only return `fail` in the last step. All steps leading up to it either return `pass` or say `continue to the next step`.
+  - `all` and `none` checks should only return `pass` in the last step. All steps leading up to it either return `fail` or say `continue to the next step`.
+7. Rename `checks` to `steps` and add a `step X` (where X is the step number) to the heading with the check name.
+8. Replace the `tags` section with a `Accessibility Requirements`. The requirements can be determined based on the `wcag###` tags.
+
+## Method 2: Create a rule group
+
+This method is useful for larger rules with `any` checks. This effectively turns every check into its own rule, and turns the rule into a rule group.
+
+1. Copy each check into a new document
+2. Add a `steps` heading
+3. Add the test input type to it: `rendered page`
+4. Add an `assumptions` section, add possible assumptions to it
+5. Add an `outcomes` section, describing the different possible outcomes of the rule
+6. Copy the `selector` section from the original rule into the new rule documents
+7. Update the check to return pass/fail/cantTell instead of true/false/undefined
+8. Add a `Validation Tests` section, that links to only those integration tests relevant for this check (now a new rule).
+9. Indicate that the new rule is part of a group, using the original axe-core rule ID as the group name.
+10. Replace the `tags` section with a `Accessibility Requirements`. The requirements can be determined based on the `wcag###` tags.

doc/developer-guide.md

@@ -150,8 +150,8 @@ Occasionally, you may want to add additional information about why a Check passe
 }
 ```
 
-See [rules.md](./rules.md) for more information on writing rules and checks,
-including incomplete results.
+See [Developing Axe-core Rules](./rule-development.md) for more information
+on writing rules and checks, including incomplete results.
 
 #### CheckResult
 

doc/rules.md → doc/rule-development.md

@@ -1,4 +1,6 @@
-# Writing Axe-core Rules
+# Developing Axe-core Rules
+
+Before you start writing axe-core rules, be sure to create a proposal for them in a github issue. Read [Proposing Axe-core rules](./rule-proposal.md) for details.
 
 A rule is a JSON Object that defines a test for aXe-core to run. At a high level, think of a rule as doing two things. First it finds all elements that it should test, and after that it runs a number of checks to see if those selected elements pass or fail the rule.
 

doc/rule-proposal.md

@@ -0,0 +1,102 @@
+# Proposing Axe-core Rules
+
+This document outlines the process of proposing a rule. For a technical description on how to build a rule, read [Developing Axe-core Rules](./rule-development.md)
+
+Before you start coding a new rule for axe-core, you *must* create a Github issue to document the rule you want to create. There are many considerations to writing a good rule. It must have no false positives, which is difficult, because there are always many many edge cases to consider. Additionally, a known problem of accessibility testing, is that not all testers hold the same interpretation of the accessibility guidelines. All rules *must* be consistent with the interpretation of Deque Systems, the developer behind Axe-core. 
+
+In addition to giving the axe-core development team an opportunity to provide feedback on the proposed rule, the Github Issue will serve as documentation of that rule for the future.
+
+## Rules Format
+
+All Github issues that propose a rule must be tagged as *rule*, and must use the following format:
+
+### Intro
+
+In one sentence, describe what the rule does.
+
+Example: "Ensures ARIA attributes are allowed for an element's role"\
+
+#### Rule help
+
+In one sentence, describe how to resolve the issue.
+
+Example: "Elements must only use allowed ARIA attributes"
+
+#### Tags
+
+Indicate which tags the rule should use.
+
+Example: wcag2a, wcag211, cat.keyboard
+
+### Selector
+
+If possible using a CSS selector, otherwise describe in one sentence using plain language what elements the rule selects.
+
+Example 1: `input[type=checkbox][name]`
+
+Example 2: Select each node that has an attribute starting with `aria-`.
+
+### Checks:
+
+Make each check a subheading of `checks`. Give the check name in the heading, and indicate if the check type is `any`, `all` or `none`.
+
+In short sentences, using plain language, describe what conditions will lead to the check returning false, true or undefined. Keep the steps simple and short. You don't have to write out all the logic. Preferably not, just give the high level view of what the check does.
+
+**Example 1:**
+
+`###` aria/allow-attr (any)
+
+1. Look up the element role
+2. Look up a list of aria attributes allowed for that role
+3. Return false if the element has aria attributes not in the list
+4. Otherwise return true
+
+**Example 2:**
+
+`###` keyboard/focusable-no-name (none)
+
+1. If the element is not focusable, return false
+2. If the element has an accessible name, return false
+3. Otherwise return true
+
+## Best practices
+
+For rule design, consider the following as best practices:
+
+1. Rules should only have one `none` check so that the error message is specific
+2. Rules should not combine `any` and `none`, these should be broken out into separate rules
+3. Checks should each only test a single specific case (either a passing technique or a single failing test)
+
+## Template
+
+Use this template when creating the issue:
+
+```markdown
+# {{ Rule name }}
+
+{{ Rule description }}
+
+{{ Rule help }}
+
+**Tags:** {{ tag, tag, tag }}
+
+## Selector
+
+{{ selector }}
+
+## Checks
+
+### {{ Check name 1 }} ( any / all / none )
+
+1. 
+
+### {{ Check name 2, optional }} ( any / all / none )
+
+1. 
+```
+
+## W3C Standardized Rules
+
+Deque Systems is one of leading organizations in the development of standardized accessibility conformance testing rules. The above format is an adaptation of the [Accessibility Conformance Testing Rules Format](https://www.w3.org/TR/act-rules-format/).
+
+For details on how the above format maps to the ACT Rules format, see [act-rules-format.md](./act-rules-format.md).