Skip to content

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

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
wants to merge 26 commits into
base: develop
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
1746bf8
Update links-with-identical-names-and-context-serve-equivalent-purpos…
carlosapaduarte May 13, 2022
2d271ab
Update link-in-context-descriptive-5effbb.md
carlosapaduarte May 13, 2022
0b07c9d
Merge branch 'develop' into include-title-attribute-in-link-context
carlosapaduarte May 19, 2022
3bf682f
Merge branch 'develop' into include-title-attribute-in-link-context
carlosapaduarte May 30, 2022
1f6fcd2
Merge branch 'develop' into include-title-attribute-in-link-context
carlosapaduarte Jun 3, 2022
1918c30
Update _rules/link-in-context-descriptive-5effbb.md
carlosapaduarte Jun 3, 2022
bc72adf
Remove aria-describedby from the programmatically determined link con…
carlosapaduarte Jun 3, 2022
0a576aa
update example description
carlosapaduarte Jun 3, 2022
637c43c
fix order of headings
carlosapaduarte Jun 3, 2022
8df5b30
Update _rules/links-with-identical-names-and-context-serve-equivalent…
carlosapaduarte Jun 6, 2022
b52c6f3
Update _rules/links-with-identical-names-and-context-serve-equivalent…
carlosapaduarte Jun 6, 2022
8b23479
Update _rules/links-with-identical-names-and-context-serve-equivalent…
Jan 4, 2023
16dfe6b
add definition of accessible description
carlosapaduarte Jan 4, 2023
7986cd1
use definition of accessible description
carlosapaduarte Jan 4, 2023
6b141c4
use definition of accessible description
carlosapaduarte Jan 4, 2023
a7f9cec
add example with aria-describedby
carlosapaduarte Jan 4, 2023
29c31b0
Changes from review
carlosapaduarte Feb 8, 2023
1bd8c51
Merge branch 'develop' into include-title-attribute-in-link-context
Feb 8, 2023
91fb0bc
Merge branch 'develop' into include-title-attribute-in-link-context
Mar 3, 2023
4870c48
Apply suggestions from code review
Sep 14, 2023
b32d0b6
Merge branch 'develop' into include-title-attribute-in-link-context
Sep 14, 2023
d1d7cfe
Merge branch 'develop' into include-title-attribute-in-link-context
Jan 24, 2024
3ff697a
Merge branch 'develop' into include-title-attribute-in-link-context
Feb 1, 2024
47f5b1a
Update link-in-context-descriptive-5effbb.md
Feb 1, 2024
b664ffb
Merge branch 'develop' into include-title-attribute-in-link-context
carlosapaduarte Feb 6, 2025
6260db4
Fix repeated inapplicable example number
carlosapaduarte Jun 12, 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
25 changes: 18 additions & 7 deletions _rules/link-in-context-descriptive-5effbb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,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.
Copy link
Member

Choose a reason for hiding this comment

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

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.


## Assumptions

Expand Down Expand Up @@ -104,6 +104,16 @@ The [accessible name][] describes the purpose of the link.

#### Passed Example 3

The [accessible name][] together with the [accessible description][] describes the purpose of the link.

```html
<a href="#desc" title="See the product's description">Product</a>

<p id="desc">This product consists of several web pages.</p>
```

#### Passed Example 4

The [accessible name][] (from the link's text), together with its [programmatically determined link context][] (available from the text in the closest `p` ancestor), describes the purpose of the link.

```html
Expand All @@ -112,7 +122,7 @@ The [accessible name][] (from the link's text), together with its [programmatica
<p id="desc">This product consists of several web pages.</p>
```

#### Passed Example 4
#### Passed Example 5

The [accessible name][] (from the link's text) describes the purpose of the link.

Expand All @@ -122,7 +132,7 @@ The [accessible name][] (from the link's text) describes the purpose of the link
<p id="desc">This product consists of several web pages.</p>
```

#### Passed Example 5
#### Passed Example 6

The [programmatically determined link context][] (provided by the ancestor with a role of `listitem` and text "Ulysses") and the [accessible name][] (from the link's text) describe the purpose of the links.

Expand All @@ -143,7 +153,7 @@ The [programmatically determined link context][] (provided by the ancestor with
</ul>
```

#### Passed Example 6
#### Passed Example 7

The [programmatically determined link context][] (provided by the table header [assigned](https://html.spec.whatwg.org/multipage/tables.html#algorithm-for-assigning-header-cells) to the cell containing the link) and the [accessible name][] (from the link's text) describe the purpose of the links.

Expand All @@ -164,7 +174,7 @@ The [programmatically determined link context][] (provided by the table header [
</table>
```

#### Passed Example 7
#### Passed Example 8

The [accessible name][] describes the purpose of the link.

Expand All @@ -186,7 +196,7 @@ The [accessible name][] describes the purpose of the link.
</main>
```

#### Passed Example 8
#### Passed Example 9

The [programmatically determined link context][] (provided by the cell containing the link) and the [accessible name][] (from the link's text) describe the purpose of the links.

Expand All @@ -207,7 +217,7 @@ The [programmatically determined link context][] (provided by the cell containin
</table>
```

#### Passed Example 9
#### Passed Example 10

The [programmatically determined link context][] (provided by the element referenced by the `aria-describedby` attribute) and the [accessible name][] (from the link's text) describe the purpose of the links.

Expand Down Expand Up @@ -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'
Copy link
Collaborator

Choose a reason for hiding this comment

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

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.

Copy link
Member Author

Choose a reason for hiding this comment

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

Added a definition of accessible description

[included in the accessibility tree]: #included-in-the-accessibility-tree 'Definition of Included in the Accessibility Tree'
[presentational roles conflict resolution]: https://www.w3.org/TR/wai-aria-1.1/#conflict_resolution_presentation_none 'Presentational Roles Conflict Resolution'
[programmatically determined link context]: #programmatically-determined-link-context 'Definition of Programmatically Determined Link Context'
Expand Down
53 changes: 38 additions & 15 deletions _rules/links-with-identical-names-and-context-serve-equivalent-purpose-fd3a94.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,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 [matching][] [accessible descriptions][accessible description]; and
- have the same [programmatically determined link context][].

**Note:** The test target for this rule is the full set of link elements that share the same [matching][] [accessible name][] and [programmatically determined link context][].
**Note:** The test target for this rule is the full set of link elements that share the same [matching][] [accessible name][], [accessible description][] and [programmatically determined link context][].

## Expectation

Expand Down Expand Up @@ -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][].
Copy link
Collaborator

Choose a reason for hiding this comment

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

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

Copy link
Collaborator

Choose a reason for hiding this comment

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

I added it in a couple other spots.


```html
<html lang="en">
Expand All @@ -91,7 +92,7 @@ These two HTML `a` elements have the same [accessible name][] and [context][prog

#### Passed Example 2

These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context], and resolve to the [same resource][] after an instant redirect.
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context], and resolve to the [same resource][] after an instant redirect.

```html
<html lang="en">
Expand All @@ -106,7 +107,7 @@ These two HTML `a` elements have the same [accessible name][] and [context][prog

#### Passed Example 3

These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context], and resolve to identical resources.
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context], and resolve to identical resources.

```html
<html lang="en">
Expand All @@ -122,7 +123,7 @@ These two HTML `a` elements have the same [accessible name][] and [context][prog

#### Passed Example 4

These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context], and resolve to pages that serve the same purpose because the content section is the same.
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context], and resolve to pages that serve the same purpose because the content section is the same.
Copy link
Collaborator

@dan-tripp-siteimprove dan-tripp-siteimprove Feb 6, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

May I suggest that you replace this:
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context], and resolve to pages that serve the same purpose because the content section is the same.
... with this:
These two HTML `a` elements have the same [accessible name][], the same [accessible description][], the same [context][programmatically determined link context], and resolve to pages that serve the same purpose because the content section is the same.

Maybe I'm being overly particular, but I suspect that small changes like this can make sentences a lot easier to parse in the mind of the reader. Personally I am a fan of removing "implied parentheses" in a sentence where I can. In this case the original version of the sentence has "implied parentheses" which apply the words "the same" to three things: 1) accessible name, 2) accessible description, and 3) context. So I need to jump around in the sentence and in my mind.


```html
<html lang="en">
Expand All @@ -138,7 +139,7 @@ These two HTML `a` elements have the same [accessible name][] and [context][prog

#### Passed Example 5

These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context], and go to pages that fulfill the same purpose in relation to the link because they contain the same relevant information.
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context], and go to pages that fulfill the same purpose in relation to the link because they contain the same relevant information.
Copy link
Collaborator

Choose a reason for hiding this comment

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

(Along the same lines as my previous suggestions.)
May I suggest that you change this:
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context], and go to pages that fulfill the same purpose in relation to the link because they contain the same relevant information.
... to this:
These two HTML `a` elements have the same [accessible name][], the same [accessible description][], the same [context][programmatically determined link context], and go to pages that fulfill the same purpose in relation to the link because they contain the same relevant information.


```html
<html lang="en">
Expand All @@ -153,7 +154,7 @@ These two HTML `a` elements have the same [accessible name][] and [context][prog

#### Passed Example 6

These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context], and go to pages that use different layouts but have the same purpose.
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context], and go to pages that use different layouts but have the same purpose.
Copy link
Collaborator

Choose a reason for hiding this comment

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

May I suggest that you change this:
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context], and go to pages that use different layouts but have the same purpose.
... to this:
These two HTML `a` elements have the same [accessible name][], the same [accessible description][], the same [context][programmatically determined link context], and go to pages that use different layouts but have the same purpose.


```html
<html lang="en">
Expand All @@ -169,7 +170,7 @@ These two HTML `a` elements have the same [accessible name][] and [context][prog

#### Passed Example 7

These two HTML `span` elements have an [explicit role][] of link, the same [accessible name][], the same [context][programmatically determined link context], and link to the [same resource][].
These two HTML `span` elements have an [explicit role][] of link, the same [accessible name][], the same [accessible description][], the same [context][programmatically determined link context], and link to the [same resource][].

```html
<html lang="en">
Expand All @@ -195,7 +196,7 @@ These two HTML `span` elements have an [explicit role][] of link, the same [acce

#### Passed Example 8

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

```html
<html lang="en">
Expand All @@ -215,7 +216,7 @@ These two SVG `a` and HTML `a` elements have the same [accessible name][], same

#### Failed Example 1

These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context] but go to different resources.
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context] but go to different resources.
Copy link
Collaborator

Choose a reason for hiding this comment

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

I think we still have the problem where this example is falling into the "ambiguous to users in general" exception of 2.4.4 and therefore shouldn't fail, but this is an unrelated problem.

Copy link
Collaborator

Choose a reason for hiding this comment

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

(Wording, not content.) May I suggest that you change this:
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context] but go to different resources.
... to this:
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.


```html
<html lang="en">
Expand All @@ -229,7 +230,7 @@ These two HTML `a` elements have the same [accessible name][] and [context][prog

#### Failed Example 2

These two HTML `a` elements have the same [accessible name][] and [context][programmatically determined link context]. They link to web pages that are similar, but have different information in their content.
These two HTML `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context]. They link to web pages that are similar, but have different information in their content.

```html
<html lang="en">
Expand All @@ -246,7 +247,7 @@ These two HTML `a` elements have the same [accessible name][] and [context][prog

#### Failed Example 3

These two HTML `span` elements have an [explicit role][] of link, same [accessible name][] and [context][programmatically determined link context], but link to resources that offer different content.
These two HTML `span` elements have an [explicit role][] of link, same [accessible name][], [accessible description][] and [context][programmatically determined link context], but link to resources that offer different content.
Copy link
Collaborator

Choose a reason for hiding this comment

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

May I suggest that you change this:
These two HTML `span` elements have an [explicit role][] of link, same [accessible name][], [accessible description][] and [context][programmatically determined link context], but link to resources that offer different content.
... to this:
These two HTML `span` elements have an [explicit role][] of link, the same [accessible name][], the same [accessible description][], and the same [context][programmatically determined link context], but link to resources that offer different content.


```html
<html lang="en">
Expand All @@ -268,7 +269,7 @@ These two HTML `span` elements have an [explicit role][] of link, same [accessib

#### Failed Example 4

These two SVG `a` elements have the same [accessible name][] and [context][programmatically determined link context] but link to different resources.
These two SVG `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context] but link to different resources.
Copy link
Collaborator

Choose a reason for hiding this comment

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

May I suggest that you change this:
These two SVG `a` elements have the same [accessible name][], [accessible description][] and [context][programmatically determined link context] but link to different resources.
... to this:
These two SVG `a` elements have the same [accessible name][], the same [accessible description][], and the same [context][programmatically determined link context], but link to different resources.


```html
<html lang="en">
Expand All @@ -290,7 +291,7 @@ These two SVG `a` elements have the same [accessible name][] and [context][progr

#### Failed Example 5

These two HTML `a` elements with the same [accessible name][] and [context][programmatically determined link context] resolve to the [same resource][] after redirect, but the redirect is not instant.
These two HTML `a` elements with the same [accessible name][], [accessible description][] and [context][programmatically determined link context] resolve to the [same resource][] after redirect, but the redirect is not instant.
Copy link
Collaborator

Choose a reason for hiding this comment

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

May I suggest that you change this:
These two HTML `a` elements with the same [accessible name][], [accessible description][] and [context][programmatically determined link context] resolve to the [same resource][] after redirect, but the redirect is not instant.
... to this:
These two HTML `a` elements with the same [accessible name][], the same [accessible description][], the same [context][programmatically determined link context], and resolve to the [same resource][] after redirect, but the redirect is not instant.


```html
<html lang="en">
Expand Down Expand Up @@ -335,6 +336,27 @@ These two HTML `a` elements have different [accessible names][accessible name].

#### Inapplicable Example 3

These two HTML `a` elements have the same [accessible names][accessible name] but different [accessible descriptions][accessible description].

```html
<html lang="en">
<p>
<a
href="/test-assets/links-with-identical-names-serve-equivalent-purpose-b20e66/about/contact.html"
title="To learn more about us"
>Contact</a
>
<a
href="/test-assets/links-with-identical-names-serve-equivalent-purpose-b20e66/about/contact.html"
title="To know how to reach us"
>Contact</a
>
</p>
</html>
```

#### Inapplicable Example 4

These two HTML `a` elements have the same [accessible name][] and link to the [same resource][] but different [programmatically determined link contexts][programmatically determined link context].

```html
Expand All @@ -352,7 +374,7 @@ These two HTML `a` elements have the same [accessible name][] and link to the [s
</html>
```

#### Inapplicable Example 4
#### Inapplicable Example 5

These two `span` elements do not have a [semantic role][] of link.

Expand Down Expand Up @@ -397,6 +419,7 @@ These two HTML `a` elements have the same [accessible name][] but different [pro
```

[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'
[document]: https://dom.spec.whatwg.org/#concept-document 'Definition of document'
[explicit role]: #explicit-role 'Definition of explicit role'
[included in the accessibility tree]: #included-in-the-accessibility-tree 'Definition of included in the accessibility tree'
Expand Down