act-rules · Jym77 · Feb 13, 2020 · Sep 17, 2019 · Sep 17, 2019 · Sep 19, 2019
diff --git a/__tests__/spelling-ignore.yml b/__tests__/spelling-ignore.yml
diff --git a/_rules/form-control-label-descriptive-cc0f0a.md b/_rules/form-control-label-descriptive-cc0f0a.md
@@ -15,17 +15,19 @@ input_aspects:
   - CSS Styling
 acknowledgements:
   authors:
+    - Jean-Yves Moyen
+    - Wilco Fiers
+  previous_authors:
     - Dagfinn Rømen
     - Geir Sindre Fossøy
-    - Wilco Fiers
 ---
 
 ## Applicability
 
-This rule applies to any HTML `label` element or other element referenced by `aria-labelledby` that, is [visible][] and is programmatically associated with an HTML element that has one of the following [semantic roles][semantic role]:
+This rule applies to any [programmatic label][] of an element which has one of the following [semantic roles][semantic role]:
 
 - `checkbox`
-- `combobox` (`select` elements)
+- `combobox`
 - `listbox`
 - `menuitemcheckbox`
 - `menuitemradio`
@@ -36,31 +38,39 @@ This rule applies to any HTML `label` element or other element referenced by `ar
 - `switch`
 - `textbox`
 
-**Note**: The list of form field roles is derived by taking all the roles from [WAI-ARIA Specifications](#wai-aria-specifications) that:
+and where both the element and the [programmatic label][] are [visible][].
+
+**Note**: The list of applicable [semantic roles][semantic role] is derived by taking all the roles from [WAI-ARIA Specifications][] that:
 
-- have a [semantic role][] that inherits from the [abstract](https://www.w3.org/TR/wai-aria/#abstract_roles) `input` or `select` role, and
-- does not have a [required context](https://www.w3.org/TR/wai-aria/#scope) role that itself inherits from one of those roles.
-- The `option` role is not part of the list of applicable roles, because it does not meet the definition of a [User interface component](https://www.w3.org/TR/WCAG21/#dfn-user-interface-components). This means [WCAG 2.1](https://www.w3.org/TR/WCAG21/) does not require it to have an [accessible name](#accessible-name).
+- inherit from the [abstract][] `input` or `select` role; and
+- do not have a [required context](https://www.w3.org/TR/wai-aria/#scope) role that itself inherits from one of those roles.
 
-**Note**: This rule is a partial check for WCAG 2.1 success criterion 2.4.6, which applies to all labels. "Label" is used in its general sense and includes text or other components with a text alternative that is presented to a user to identify a component within Web content.
+**Note:** The `option` role is not part of the list of applicable roles, because it has a required context role that inherits from the `select` role. Furthermore, `option` does not meet the definition of a [User interface component](https://www.w3.org/TR/WCAG21/#dfn-user-interface-components). This means that [WCAG 2.1][wcag21] does not require it to have an [accessible name][].
+
+**Note**: [Labels][label] in WCAG are not restricted to the `label` element of HTML and can be any element. This rule is only concerned about actual `label` elements, and elements that are programmatically marked as [labels][label] via the `aria-labelledby` attribute.
 
 ## Expectation
 
-Each target element describes the purpose of the associated form field element.
+Each test target, together with its [visual context][], describes the purpose of the associated element.
+
+**Note**: It is possible for an element to have an [accessible name][] but still having a non-descriptive `label` element (and even a non-descriptive [label][]). In that case, it would pass [Success Criterion 4.1.2: Name, Role and Value][sc412] but still fail this rule and [Success Criterion 2.4.6: Heading and Labels][sc246].
 
-**Note**: Labels do not need to be lengthy. A word, or even a single character, may suffice.
+**Note**: Having a [label][] which is not included in the [accessible name][] is a violation of [Success Criterion 2.5.3: Label in Name][sc253] but not of this rule nor of [Success Criterion 2.4.6: Heading and Labels][sc246].
 
 ## Assumptions
 
-This rule assumes that the [label](https://www.w3.org/TR/WCAG21/#dfn-labels) is intended for sighted users, and that hiding a visible label from assistive technologies, is a failure of [Success Criterion 4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG21/#name-role-value), but not of [Success Criterion 2.4.6 Headings and Labels](https://www.w3.org/TR/WCAG21/#headings-and-labels).
+- This rule assumes that [labels][label] are intended for sighted users, and that hiding a [visible][] [label][] from assistive technologies, is a failure of [Success Criterion 4.1.2: Name, Role and Value][sc412], but not of [Success Criterion 2.4.6: Heading and Labels][sc246].
+- This rule assumes that the [programmatic labels][programmatic label] of an element are also part of its [visual context][].
 
 ## Accessibility Support
 
 _There are no major accessibility support issues known for this rule._
 
 ## Background
 
-- [Understanding Success Criterion 2.4.6: Headings and Labels](https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels.html)
+- [Accessible Rich Internet Applications (WAI-ARIA) 1.1][aria11]
+- [Understanding Success Criterion 2.4.6: Headings and Labels][usc246]
+- [Understanding Success Criterion 4.1.2: Name, Role and Value][usc412]
 - [G131: Providing descriptive labels](https://www.w3.org/WAI/WCAG21/Techniques/general/G131)
 - [H44: Using label elements to associate text labels with form controls](https://www.w3.org/WAI/WCAG21/Techniques/html/H44)
 - [ARIA16: Using aria-labelledby to provide a name for user interface controls](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA16)
@@ -71,114 +81,161 @@ _There are no major accessibility support issues known for this rule._
 
 #### Passed Example 1
 
-Label that is coded with the `label` element and describes the purpose of the associated element.
+The `label` element is a [programmatic label][] of the `input` element and describes it.
 
 ```html
-<label for="fname">First name:</label> <input id="fname" type="text" name="fname" />
+<label>First name:<input id="fname" type="text" name="fname"/></label>
 ```
 
 #### Passed Example 2
 
-Label that is coded with the `p` element and associated by the aria-labelledby attribute. The label describes the purpose of the associated element.
+The `label` element is a [programmatic label][] of the `input` element and describes it.
 
 ```html
-<p id="label_fname">First name:</p>
-<input aria-labelledby="label_fname" type="text" name="fname" />
+<label for="fname">First name:</label> <input id="fname" type="text" name="fname" />
 ```
 
 #### Passed Example 3
 
-Implicit label that is coded with the `label` element and describes the purpose of the associated element.
+The `p` element is a [programmatic label][] of the `input` element and describes it.
 
 ```html
-<label>First name:<input id="fname" type="text" name="fname"/></label>
+<p id="label_fname">First name:</p>
+<input aria-labelledby="label_fname" type="text" name="fname" />
 ```
 
 #### Passed Example 4
 
-Label is [visible][], but not included in accessibility tree
+The `p` element is a [programmatic label][] of the `input` element and describes it. The [programmatic label][] does not need to be [included in the accessibility tree][] for this rule to apply.
 
 ```html
 <p id="label_fname" aria-hidden="true">First name:</p>
 <input aria-labelledby="label_fname" type="text" name="fname" />
 ```
 
+#### Passed Example 5
+
+The `label` elements are [programmatic labels][programmatic label] of their respective `input` elements. The `label` elements, are not descriptive enough (because they are repeated over several fields). However, the headings provide a [visual context][] that differentiates the purpose of the otherwise identically named form fields. Within their [visual context][], the `label` elements are descriptive of their respective `input` elements.
+
+```html
+<h2>Shipping address</h2>
+<label>Name<input id="shipping-name" type="text" name="name"/></label>
+<label>Street<input id="shipping-street" type="text" name="street"/></label>
+
+<h2>Billing address</h2>
+<label>Name<input id="billing-name" type="text" name="name"/></label>
+<label>Street<input id="billing-street" type="text" name="street"/></label>
+```
+
+#### Passed Example 6
+
+Both the `div` and the `span` elements are [programmatic labels][programmatic label] of the `input` element. Each of them, within the [visual context][] formed by the other one, is descriptive.
+
+```html
+<div id="shipping">Shipping address</div>
+<span id="name">Name</span>
+<input id="shipping-name" type="text" name="name" aria-labelledby="shipping name" />
+```
+
 ### Failed
 
 #### Failed Example 1
 
-Label that is coded with the `label` element and does not describe the purpose of the associated element.
+The `label` element is a [programmatic label][] of the `input` element but does not describe it.
 
 ```html
-<label for="fname">Menu</label> <input id="fname" type="text" name="fname" />
+<label>Menu<input id="fname" type="text" name="fname"/></label>
 ```
 
 #### Failed Example 2
 
-Label that is coded with the `p` element and associated by the aria-labelledby attribute. The label does not describe the purpose of the associated element.
+The `label` element is a [programmatic label][] of the `input` element but does not describe it.
 
 ```html
-<p id="label_fname">Menu</p>
-<input aria-labelledby="label_fname" type="text" name="fname" />
+<label for="fname">Menu</label> <input id="fname" type="text" name="fname" />
 ```
 
 #### Failed Example 3
 
-Implicit label that is coded with the `label` element and does not describe the purpose of the associated element.
+The `span` element is a [programmatic label][] of the `input` element but does not describe it.
 
 ```html
-<label>Menu<input id="fname" type="text" name="fname"/></label>
+<p id="label_fname">Menu</p>
+<input aria-labelledby="label_fname" type="text" name="fname" />
 ```
 
 #### Failed Example 4
 
-Label is [visible][], but not included in accessibility tree, and does not describe the purpose of the associated element.
+The `label` elements are [programmatic labels][programmatic label] of their respective `input` elements. The `label` elements, are not descriptive enough (because they are repeated over several fields). The headings are not [visible][]. Therefore, they do not provide [visual context][].
 
 ```html
-<p id="label_fname" aria-hidden="true">Menu</p>
-<input aria-labelledby="label_fname" type="text" name="fname" />
+<h2 style="position: absolute; top: -9999px; left: -9999px;">Shipping address</h2>
+<input aria-label="Name" id="shipping-name" type="text" name="name" />
+<input aria-label="Street" id="shipping-street" type="text" name="street" />
+
+<h2 style="position: absolute; top: -9999px; left: -9999px;">Billing address</h2>
+<input aria-label="Name" id="billing-name" type="text" name="name" />
+<input aria-label="Street" id="billing-street" type="text" name="street" />
+```
+
+#### Failed Example 5
+
+Both the `div` and the `span` elements are [programmatic labels][programmatic label] of the `input` element, but only the `div` is [visible][]. It has no [visual context][], and is not descriptive.
+
+```html
+<div id="shipping">Shipping address</div>
+<span id="name" style="display: none">Name</span>
+<input id="shipping-name" type="text" name="name" aria-labelledby="shipping name" />
 ```
 
 ### Inapplicable
 
 #### Inapplicable Example 1
 
-`Label` that is not [visible][] to users.
+The `label` element is not a [programmatic label][] of any element.
 
 ```html
-<div style="display:none">
-	<label for="bad_label">Menu:</label>
-	<input id="fname" type="text" name="bad_label" />
-</div>
+<label for="fname">First name:</label>
+<p id="fname"></p>
 ```
 
 #### Inapplicable Example 2
 
-Programmatically associated `p` element that is not [visible][].
+The `label` element is not [visible][].
 
 ```html
-<div style="display:none">
-	<p id="bad_label">menu</p>
-	<input aria-labelledby="bad_label" type="text" name="fname" />
-</div>
+<label for="fname" style="display:none;">First name:</label> <input id="fname" type="text" name="fname" />
 ```
 
 #### Inapplicable Example 3
 
-The `label` element is associated with an HTML element that does not have a form field semantic role.
+The `label` is a [visible][] [programmatic label][] of the `input` element. However, the `input` is not [visible][], hence this rule does not apply.
 
 ```html
-<label for="fname">First name</label>
-<p id="fname">bob</p>
+<label>First name: <input style="position: absolute; top: -9999px; left: -9999px;" type="text" name="fname"/></label>
 ```
 
 #### Inapplicable Example 4
 
-The element with `aria-labelledby` is not a form field.
+The `span` element is not a [programmatic label][] of any element.
 
 ```html
-<i id="smile">Smile</i> <button aria-labelledby="smile">:-)</button>
+<span>First name:</span><input type="text" name="fname" />
 ```
 
+[abstract]: https://www.w3.org/TR/wai-aria/#abstract_roles 'List of abstract roles'
+[accessible name]: #accessible-name 'Definition of accessible name'
+[aria11]: https://www.w3.org/TR/wai-aria-1.1/ 'Accessible Rich Internet Applications 1.1'
+[included in the accessibility tree]: #included-in-the-accessibility-tree 'Definition of included in the accessibility tree'
+[label]: https://www.w3.org/TR/WCAG21/#dfn-labels 'Definition of label'
+[programmatic label]: #programmatic-label 'Definition of programmatic label'
+[sc246]: https://www.w3.org/WAI/WCAG21/#headings-and-labels.html 'Success Criterion 2.4.6: Heading and Labels'
+[sc253]: https://www.w3.org/WAI/WCAG21/label-in-name 'Success Criterion 2.5.3: Label in Name'
+[sc412]: https://www.w3.org/WAI/WCAG21/#name-role-value 'Success Criterion 4.1.2: Name, Role and Value'
 [semantic role]: #semantic-role 'Definition of semantic role'
+[usc246]: https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels.html 'Understanding SC 2.4.6: Heading and Labels'
+[usc412]: https://www.w3.org/WAI/WCAG21/Understanding/name-role-value 'Understanding SC 4.1.2: Name, Role and Value'
 [visible]: #visible 'Definition of visible'
+[visual context]: #visual-context 'Definition of visual context'
+[wai-aria specifications]: #wai-aria-specifications 'Definition of WAI-ARIA specifications'
+[wcag21]: https://www.w3.org/TR/WCAG21/ 'Web Content Accessibility Guidelines 2.1'
diff --git a/pages/glossary/programmatic-label.md b/pages/glossary/programmatic-label.md
@@ -0,0 +1,63 @@
+---
+name: programmatic label
+key: programmatic-label
+---
+
+Element L is a _programmatic label_ of target element T if either:
+
+- T is a [labeled control][] of L; or
+- L is referenced by ID in the `aria-labelledby` attribute of T.
+
+**Note**: a given element may have more than one programmatic label.
+
+#### Examples
+
+The `input` element is a [labeled control][] of the `label` element (implicit label). Therefore the `label` element is a programmatic label of the `input` element.
+
+```html
+<label>Full name: <input type="text" name="full_name" /> </label>
+```
+
+The `input` element is a [labeled control][] of the `label` element (explicit label). Therefore the `label` element is a programmatic label of the `input` element.
+
+```html
+<label for="fname">Full name:</label> <input type="text" id="fname" name="full_name" />
+```
+
+The `span` element is referenced by the `aria-labelledby` attribute on the `input` element. Therefore, the `span` element is a programmatic label of the `input` element.
+
+```html
+<span id="label_fname">Full name:</span> <input type="text" name="full_name" aria-labelledby="label_fname" />
+```
+
+Both `span` elements are referenced by the `aria-labelledby` attribute on the `input` element. Therefore, each `span` element is a programmatic label of the `input` element.
+
+```html
+<span id="billing">Billing</span>
+<span id="address">address</span>
+<input type="text" name="billing_address" aria-labelledby="billing address" />
+```
+
+The `span` element is referenced by the `aria-labelledby` attribute on the `input` element and the `input` element is a [labeled control][] of the `label`. Therefore, the `span` element and the `label` are each a programmatic label of the `input` element.
+
+```html
+<span id="label_fname">Full name:</span>
+<label>Full name: <input type="text" name="full_name" aria-labelledby="label_fname"/></label>
+```
+
+The `div` element is not [labelable][]. Therefore, it is not a [labeled control][] for the `label` element and the `label` element is **not** a programmatic label for the `div` element.
+
+```html
+<label for="bond">Full name</label>
+<div id="bond">My name is Bond. James Bond.</div>
+```
+
+The `span` element is referenced by the `aria-labelledby` attribute on the `div` element. Therefore, the `span` element is a programmatic label of the `div` element. Note that the `aria-labelledby` attribute works on any element, not just on the [labelable][] elements.
+
+```html
+<span id="label_fname">Full name:</span>
+<div aria-labelledby="label_fname">My name is Bond. James Bond.</div>
+```
+
+[labelable]: https://html.spec.whatwg.org/multipage/forms.html#category-label 'Definition of labelable elements'
+[labeled control]: https://html.spec.whatwg.org/multipage/forms.html#labeled-control 'Definition of labeled control'
diff --git a/pages/glossary/visual-context.md b/pages/glossary/visual-context.md
@@ -0,0 +1,14 @@
+---
+title: Visual context
+key: visual-context
+---
+
+The _visual context_ of a node is everything that is visually or logically located near it when the [document](https://dom.spec.whatwg.org/#concept-document) containing it is rendered. Only [visible](#visible) information may be part of the visual context.
+
+The logical distance is the distance in the structure of the document: either the tree distance within the DOM tree, or the semantic relation. For example, headings are logically near the content that follows (until the next heading of the same or higher level) even though they might be far away visually or in the DOM tree.
+
+The visual context may include, but is not limited to, headings, text in the same sentence or paragraph.
+
+**Note**: As a rule of thumb, visual context should be close enough to be displayed on the device at the same time as the element it relates to. Because device sizes vary wildly and content can further be zoomed and moved around, this is however not a strong requirement.
+
+**Note**: Visual context that is located before (in reading order) the element it relates to is often more useful than visual context located after. Indeed, it is easier for users to use context that they have already read than context that is yet to be read.