Consider accessible description in the rules that use link context (5effbb, fd3a94) #1845

carlosapaduarte · 2022-05-13T17:21:35Z

Update rules that use link context to consider the title attribute. Although the original resolution in #1766 requested the changes to be made on the "Programmatically Determined Link Context" definition, given that this specifies a set of elements, it does not seem doable. As an alternative, I've added the accessible description to the expectation of "Link in context is descriptive" and to the applicability of "Links with identical accessible names and context serve equivalent purpose"

Closes issue(s):

closes Should rules about link's name (b20e66, 5effbb, aizyf1, fd3a94) consider the title attribute? #1766

Need for Call for Review:
This will require a 2 weeks Call for Review

How to Review And Approve

Go to the “Files changed” tab
Here you will have the option to leave comments on different lines.
Once the review is completed, find the “Review changes” button in the top right, select “Approve” (if you are really confident in the rule) or "Request changes" and click “Submit review”.
Make sure to also review the proposed Call for Review period. In case of disagreement, the longer period wins.

…e-fd3a94.md

Jym77

I feel it would be cleaner to remove aria-describedby from "Programmatically determined link context". Since the rules now explicitly mention the accessible description, that already includes aria-describedby references (and actually a few more things such as children of aria-describedby references, if I get the accessible name computation correctly).

So, the PDLC would be some set of elements defined by some DOM tree relationship, and rules about context would look at PDLC + accessible description.
(it would also means that aria-describedby="foo bar" and aria-describedby="bar foo" would be considered as different accessible descriptions while they are currently the same PDLC, which sounds bad)

kengdoj

Minor suggestions made.

_rules/link-in-context-descriptive-5effbb.md

kengdoj · 2022-06-01T22:43:58Z

_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md

@@ -77,7 +78,7 @@ This rule is designed specifically for [2.4.4 Link Purpose (In Context)][sc244],

 #### Passed Example 1

-These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context] and link to the [same resource][].
+These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context] and link to the [same resource][].


Would be helpful to say "same non-empty accessible name, empty accessible description..."?

I added it in a couple other spots.

WilcoFiers

I like Kathy's suggestions on these, would like to see them made.

carlosapaduarte · 2022-06-03T18:15:24Z

I feel it would be cleaner to remove aria-describedby from "Programmatically determined link context". Since the rules now explicitly mention the accessible description, that already includes aria-describedby references (and actually a few more things such as children of aria-describedby references, if I get the accessible name computation correctly).

So, the PDLC would be some set of elements defined by some DOM tree relationship, and rules about context would look at PDLC + accessible description. (it would also means that aria-describedby="foo bar" and aria-describedby="bar foo" would be considered as different accessible descriptions while they are currently the same PDLC, which sounds bad)

Good suggestion. I'm updating the definition accordingly.

Co-authored-by: Kathy Eng <[email protected]>

…text definition

updates made

_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md

…-purpose-fd3a94.md Co-authored-by: Kathy Eng <[email protected]>

Jym77 · 2022-06-09T08:54:33Z

_rules/link-in-context-descriptive-5effbb.md

@@ -337,6 +347,7 @@ This `a` element is not a [semantic][semantic role] `link`, because it has no `h
 ```

 [accessible name]: #accessible-name 'Definition of Accessible Name'
+[accessible description]: https://www.w3.org/TR/wai-aria-1.2/#dfn-accessible-description 'Definition of accessible description'


Should we have our own def of it (like for accessible name?), I'm notably thinking we should link it to the "accessible name and description computation" document.

Added a definition of accessible description

_rules/link-in-context-descriptive-5effbb.md

_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md

WilcoFiers · 2024-01-31T10:43:02Z

_rules/link-in-context-descriptive-5effbb.md

@@ -35,7 +35,7 @@ This rule applies to any [inheriting semantic][] `link` for which all the follow

 ## Expectation

-The [accessible name][] of each target element together with its [programmatically determined link context][] describes the purpose of the link.
+The [accessible name][] of each target element together with its [accessible description][] and [programmatically determined link context][] describes the purpose of the link.


I'm not sure this is obviously correct. The SC talks about link text and programmatically determined context. Its probably worth putting in the assumption that we're using "link text" from WCAG to mean accessible name and description. Links that fail label in name could have visible text that isn't considered "link text" in this rule. I think that should be in the assumption.

Assumption added

CLAassistant · 2025-02-06T14:40:07Z

All committers have signed the CLA.

carlosapaduarte · 2025-06-12T17:10:06Z

Closing and reopening to trigger checks

netlify · 2025-06-12T17:15:49Z

✅ Deploy Preview for act-rules ready!

Name	Link
🔨 Latest commit	`618edff`
🔍 Latest deploy log	https://app.netlify.com/projects/act-rules/deploys/685d6812aae365000840d34e
😎 Deploy Preview	https://deploy-preview-1845--act-rules.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

carlosapaduarte · 2025-06-26T16:03:29Z

Call for review ends July 10

giacomo-petri · 2025-07-25T06:55:09Z

pages/glossary/accessible-description.md

+
+For native markup languages, such as HTML and SVG, additional information on how to calculate the accessible description can be found in [HTML Accessibility API Mappings 1.0, Accessible Name and Description Computation (working draft)](https://www.w3.org/TR/html-aam/#accessible-name-and-description-computation) and [SVG Accessibility API Mappings, Name and Description (working draft)](https://www.w3.org/TR/svg-aam/#mapping_additional).
+
+**Note:** As per the [accessible name and description computation][], each element with the 'aria-describedby' property always has an accessible description.


Suggested change

**Note:** As per the [accessible name and description computation][], each element with the 'aria-describedby' property always has an accessible description.

**Note:** As per the [accessible name and description computation][], each element with the 'aria-describedby' property pointing to an existing element which content is not the empty string, always has an accessible description.

giacomo-petri · 2025-07-25T06:59:13Z

_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md

@@ -220,7 +221,7 @@ These two SVG `a` and HTML `a` elements have the same [accessible name][], same

 #### Passed Example 9

-These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context], but resolve to different resources. However, the purpose of these links is [ambiguous to users in general](https://www.w3.org/TR/WCAG22/#dfn-ambiguous-to-users-in-general). Thus all readers are unsure about the destination and the person with a disability is not at any disadvantage.
+These two HTML `a` elements have the same [accessible name][], the same [accessible description][], and the same [context][programmatically determined link context], but go to different resources. However, there is no visual information to let users know that both links resolve to non-equivalent resources. 


Starting with this example, we began using "the same accessible description", whereas in previous cases we used "empty accessible description". I recommend maintaining consistency throughout. It might also be helpful to include examples that uses title or aria-describedby attributes both in passed and failed for comparison.

giacomo-petri · 2025-07-25T07:00:07Z

_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md

@@ -40,9 +40,10 @@ This rule applies to any set of two or more [HTML or SVG elements][] for which a
 - the elements are in the same [web page (HTML)][]; and
 - the elements are [included in the accessibility tree][included in the accessibility tree]; and
 - the elements have [matching][] [accessible names][accessible name] that are not empty (`""`); and
- the elements have the same [programmatically determined link context][].
+- the elements have [matching][] [accessible descriptions][accessible description]; and
+- have the same [programmatically determined link context][].


Suggested change

- have the same [programmatically determined link context][].

- the elements have the same [programmatically determined link context][].

consistent with bullets above

WilcoFiers · 2025-08-21T12:12:39Z

_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md

@@ -220,7 +221,7 @@ These two SVG `a` and HTML `a` elements have the same [accessible name][], same

 #### Passed Example 9

-These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context], but resolve to different resources. However, the purpose of these links is [ambiguous to users in general](https://www.w3.org/TR/WCAG22/#dfn-ambiguous-to-users-in-general). Thus all readers are unsure about the destination and the person with a disability is not at any disadvantage.
+These two HTML `a` elements have the same [accessible name][], the same [accessible description][], and the same [context][programmatically determined link context], but go to different resources. However, there is no visual information to let users know that both links resolve to non-equivalent resources. 


Suggested change

These two HTML `a` elements have the same [accessible name][], the same [accessible description][], and the same [context][programmatically determined link context], but go to different resources. However, there is no visual information to let users know that both links resolve to non-equivalent resources.

These two HTML `a` elements have the same [accessible name][], empty [accessible description][], and the same [context][programmatically determined link context], but go to different resources. However, there is no visual information to let users know that both links resolve to non-equivalent resources.

WilcoFiers · 2025-08-21T12:17:36Z

_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md

@@ -84,7 +85,7 @@ There are no accessibility support issues known.

 #### Passed Example 1

-These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context] and link to the [same resource][].
+These two HTML `a` elements have the same non-empty [accessible name][], empty [accessible description][], the same [context][programmatically determined link context], and resolve to the [same resource][].


I think these texts are gettin pretty verbose. Not a blocker if people prefer this language, but I would suggest this:

Suggested change

These two HTML `a` elements have the same non-empty [accessible name][], empty [accessible description][], the same [context][programmatically determined link context], and resolve to the [same resource][].

These two links with the same [name][]accessible name], [description][]accessible description] and [context][programmatically determined link context] resolve to the [same resource][].

The same for other example descriptions.

WilcoFiers

There are a couple editorial suggestions to consider

carlosapaduarte added 2 commits May 13, 2022 18:10

Update links-with-identical-names-and-context-serve-equivalent-purpos…

1746bf8

…e-fd3a94.md

Update link-in-context-descriptive-5effbb.md

2d271ab

carlosapaduarte added Rule Update Use this label for an existing rule that is being updated reviewers wanted labels May 13, 2022

carlosapaduarte self-assigned this May 13, 2022

Jym77 reviewed May 19, 2022

View reviewed changes

WilcoFiers requested review from WilcoFiers and kengdoj May 19, 2022 13:16

carlosapaduarte added 2 commits May 19, 2022 17:39

Merge branch 'develop' into include-title-attribute-in-link-context

0b07c9d

Merge branch 'develop' into include-title-attribute-in-link-context

3bf682f

kengdoj reviewed Jun 1, 2022

View reviewed changes

WilcoFiers previously requested changes Jun 3, 2022

View reviewed changes

Merge branch 'develop' into include-title-attribute-in-link-context

1f6fcd2

carlosapaduarte and others added 3 commits June 3, 2022 19:17

Update _rules/link-in-context-descriptive-5effbb.md

1918c30

Co-authored-by: Kathy Eng <[email protected]>

Remove aria-describedby from the programmatically determined link con…

bc72adf

…text definition

update example description

0a576aa

carlosapaduarte requested review from Jym77 and kengdoj June 3, 2022 18:21

carlosapaduarte requested a review from WilcoFiers June 3, 2022 18:22

fix order of headings

637c43c

kengdoj reviewed Jun 3, 2022

View reviewed changes

_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md Outdated Show resolved Hide resolved

kengdoj reviewed Jun 3, 2022

View reviewed changes

_rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md Outdated Show resolved Hide resolved

carlosapaduarte and others added 2 commits June 6, 2022 09:50

Update _rules/links-with-identical-names-and-context-serve-equivalent…

8df5b30

…-purpose-fd3a94.md Co-authored-by: Kathy Eng <[email protected]>

Update _rules/links-with-identical-names-and-context-serve-equivalent…

b52c6f3

…-purpose-fd3a94.md Co-authored-by: Kathy Eng <[email protected]>

carlosapaduarte requested a review from kengdoj June 6, 2022 08:50

Jym77 changed the title ~~Consider the title attribute in the rules that use link context (5effbb, fd3a94)~~ Consider accessible description in the rules that use link context (5effbb, fd3a94) Jun 9, 2022

Jym77 previously requested changes Jun 9, 2022

View reviewed changes

Jym77 mentioned this pull request Jun 23, 2022

"Links with identical accessible names and context serve equivalent purpose" [fd3a94]: precise that the rule only looks for "same" context #1864

Merged

7 tasks

carlosapaduarte requested review from tbostic32, HelenBurge and giacomo-petri January 24, 2024 09:07

HelenBurge approved these changes Jan 25, 2024

View reviewed changes

WilcoFiers previously requested changes Jan 31, 2024

View reviewed changes

carlosapaduarte added 2 commits February 1, 2024 07:42

Merge branch 'develop' into include-title-attribute-in-link-context

3ff697a

Update link-in-context-descriptive-5effbb.md

47f5b1a

carlosapaduarte requested a review from WilcoFiers February 1, 2024 08:03

Merge branch 'develop' into include-title-attribute-in-link-context

b664ffb

HelenBurge requested a review from Jym77 May 29, 2025 14:20

HelenBurge removed request for Jym77 and tbostic32 June 12, 2025 14:37

kengdoj approved these changes Jun 12, 2025

View reviewed changes

carlosapaduarte closed this Jun 12, 2025

carlosapaduarte reopened this Jun 12, 2025

Fix repeated inapplicable example number

6260db4

Merge branch 'develop' into include-title-attribute-in-link-context

618edff

HelenBurge added Review call 2 weeks Call for review for new rules and big changes and removed reviewers wanted labels Jul 7, 2025

giacomo-petri reviewed Jul 25, 2025

View reviewed changes

WilcoFiers reviewed Aug 21, 2025

View reviewed changes

WilcoFiers requested changes Aug 21, 2025

View reviewed changes


		For native markup languages, such as HTML and SVG, additional information on how to calculate the accessible description can be found in [HTML Accessibility API Mappings 1.0, Accessible Name and Description Computation (working draft)](https://www.w3.org/TR/html-aam/#accessible-name-and-description-computation) and [SVG Accessibility API Mappings, Name and Description (working draft)](https://www.w3.org/TR/svg-aam/#mapping_additional).

		Note: As per the [accessible name and description computation][], each element with the 'aria-describedby' property always has an accessible description.

	- have the same [programmatically determined link context][].
	- the elements have the same [programmatically determined link context][].

	These two HTML `a` elements have the same [accessible name][], the same [accessible description][], and the same [context][programmatically determined link context], but go to different resources. However, there is no visual information to let users know that both links resolve to non-equivalent resources.
	These two HTML `a` elements have the same [accessible name][], empty [accessible description][], and the same [context][programmatically determined link context], but go to different resources. However, there is no visual information to let users know that both links resolve to non-equivalent resources.

	These two HTML `a` elements have the same non-empty [accessible name][], empty [accessible description][], the same [context][programmatically determined link context], and resolve to the [same resource][].
	These two links with the same [name][]accessible name], [description][]accessible description] and [context][programmatically determined link context] resolve to the [same resource][].

Consider accessible description in the rules that use link context (5effbb, fd3a94) #1845

Are you sure you want to change the base?

Consider accessible description in the rules that use link context (5effbb, fd3a94) #1845

Conversation

carlosapaduarte commented May 13, 2022

How to Review And Approve

Uh oh!

Jym77 left a comment

Choose a reason for hiding this comment

Uh oh!

kengdoj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WilcoFiers left a comment

Choose a reason for hiding this comment

Uh oh!

carlosapaduarte commented Jun 3, 2022

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CLAassistant commented Feb 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

carlosapaduarte commented Jun 12, 2025

Uh oh!

netlify bot commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for act-rules ready!

Uh oh!

carlosapaduarte commented Jun 26, 2025

Uh oh!

giacomo-petri Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WilcoFiers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

CLAassistant commented Feb 6, 2025 •

edited

Loading

netlify bot commented Jun 12, 2025 •

edited

Loading

giacomo-petri Jul 25, 2025 •

edited

Loading