Rule 2ee8b8 ("Visible label is part of accessible name"): introducing a new "label in name algorithm". by dan-tripp-siteimprove · Pull Request #2075 · act-rules/act-rules.github.io

dan-tripp-siteimprove · 2023-06-22T00:53:18Z

<< Describe the changes >>

Closes issue(s):

closes Visible label is part of accessible name (2ee8b8): screen reader pronunciation help in name that is not in label #2051, closes Visible label is part of accessible name (2ee8b8): symbolic text should not be considered a visible label #1989, closes Visible label is part of accessible name (2ee8b8): should common abrevations be accepted? #1619, closes Visible label is part of accessible name (2ee8b8): extra spaces in name might be OK. #1615, closes Visible label is part of accessible name (2ee8b8): Expectation seems to have unintended consequences #1458
does not handle: "Visible label is part of accessible name" [2ee8b8]: does the "label" necessarily contains all the visible text content? #2040 Visible label is part of accessible name indicates that inputs are not applicable because the label is not contained in the input #1500 "label and name from content mismatch" needs to also fail split up labels [2ee8b8] #451

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

Pull Request Etiquette

When creating PR:

[ x] Make sure you're requesting to pull a branch (right side) to the develop branch (left side).
[x ] Make sure you do not remove the "How to Review and Approve" section in your pull request description

After creating PR:

[ x] Add yourself (and co-authors) as "Assignees" for PR.
[ x] Add label to indicate if it's a Rule, Definition or Chore.
[x ] Link the PR to any issue it solves. This will be done automatically by referencing the issue at the top of this comment in the indicated place.
[ x] Optionally request feedback from anyone in particular by assigning them as "Reviewers".

When merging a PR:

Close any issue that the PR resolves. This will happen automatically upon merging if the PR was correctly linked to the issue, e.g. by referencing the issue at the top of this comment.

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.

…l in name algorithm". It's intended mostly to handle whitespace and punctuation.

WilcoFiers · 2023-07-20T13:52:12Z

@dan-tripp-siteimprove Since this is being worked on still by @kengdoj, can we set this to draft?

dan-tripp-siteimprove · 2023-07-20T21:20:46Z

@dan-tripp-siteimprove Since this is being worked on still by @kengdoj, can we set this to draft?

Done

…307n5z

…t-rules.github.io into develop

Jym77

This looks good. I like the details and the many new examples that explicit the decisions we've taken.

Jym77 · 2023-11-09T09:19:52Z

+
+The <dfn id="for-text">visible inner text of a [text node][]</dfn> is:
+-   if the [text node][] is [visible][], its visible inner text is its [data][];
+-   if the [text node][] is not-[visible][], [rendered][], and contains only [whitespace][], its visible inner text is the string `" "` (a single ASCII whitespace);


The conditional here sounds a bit weird 🤔
Notably, a text node that is not visible, rendered, and contains more than whitespace (e.g. in Hello) would not trigger it and therefore have an empty string as visible inner text (rather than a whitespace).

Interesting question. I don't know the answer. But I'll note that I copied this definition from sanshikan so if it needs fixing here, it probably needs fixing there too.

OK, doing some archaeology, this is due to the fact that whitespace are not visible per our definition…

<button aria-label="hello world">hello world</button>

The span#space is not visible (and neither is its child text node). So the first bullet doesn't apply. Without the second bullet, the visible inner text of the button would be helloworld, not matching the accessible name of hello world due to spacing…
I guess we need to add an example to show that.

Done in b2df021

This raises another question: what should we do with this?
<a aria-label="Download specification" href="#">Downloadxspecification</a>
According to the current definition, because of the clause "contains only [whitespace][]", the visible inner text of the <a> element is "Downloadspecification". Visually it looks like "Download specification". So I wonder if we could remove the clause "contains only [whitespace][]". What do you think?

Good point 🤔 But if the span was invisible due to absolute positioning out of viewport, it shrould be removed:

<a aria-label="Download specification" href="#">Downloadxspecification</a>

I guess the true condition is whether it creates a CSS box that lies somewhere between the ones of the rest of the text taking part in the computation (and isn't fully contained in them), or something like that 🙈
Or maybe we just make the special case for visibility: hidden and assume that these is already a corner case and that it won't create too many true problems (We've been using that definition in Alfa for two years and I don't remember seeing a problem caused by it, so it may be safe to assume that it is a good enough approximation).

This has given me a lot to think about. I'll try to bring it up in our next one-on-one meeting.

…://github.com/Siteimprove/sanshikan/blob/main/terms/visible-inner-text.md) - changing glossary links' prefixes from "./" to "#". I don't know if the former was working or not. but the latter is the common practice, it seems.

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

…placing it with a new idea: the algorithm 'return value' eg. 'returns "is contained"'. - rewording rule expectation. I think that 'For the target element' is better than 'For each target element' because for this rule, the computation of the expecation for each applicable target element is done in isolation from the other applicable targets on the page. It's simpler if the "for loop" over all applicable targets is done by the tool, not the rule.

…s algorithm is for.

Changes done

giacomo-petri · 2026-03-25T09:00:03Z

+Sub-algorithm to tokenize a string:
+
+1. Do Unicode [case folding][] on the string then convert it to [normalization form KD][].
+1. For each character that either a) represents non-text content, or b) isn't a letter or a digit: replace that character with a space character.


I understand that there is (or should be) a separate issue addressing non-latin languages, but IMO the current wording is overly strict. Japanese for example is not composed of letters. As a result, a string like "これは何ですか", per this bullet, gets replaced with seven whitespace characters, which is clearly incorrect and leads to invalid results. Given that the current/existing rule handles simple Japanese scenarios but the new one does not, IMO we can't proceed in this direction. We need a better definition of "letter or digit" that also accounts for ideographic writing systems; otherwise, this change would be a step backward.

Fair point for sure, but I'm a little stumped as to how to fix this. Do you have any ideas?

Wait a minute. I think that Japanese works out fine because they are "letters" according to Unicode. For example, see https://www.compart.com/en/unicode/U+3059 - it says "Category: Other Letter (Lo)". That is covered by my algorithm and won't be replaced by a space. I just pushed a commit which changes some small things, but does not change this case.

giacomo-petri · 2026-03-25T09:07:04Z

+1. For each character that either a) represents non-text content, or b) isn't a letter or a digit: replace that character with a space character.
+    - For a) Judgment of "non-text" probably can't be fully automated.  For example: "X" for "close" probably can be automated, but presumably there are more cases than this.
+    - For b) Use the Unicode classes Letter, Mark, and "Number, Decimal Digit [Nd]". (This will exclude hyphens, punctuation, emoji, and more.)
+1. Remove parentheses (also known as round brackets) and all characters that are between an opening and closing parenthesis.


We need to exclude anything that is a mathematical, regular, logical, or similar type of expression.
For example, in a multiple-answer quiz asking "Which of the following is correct?":

if ((a || b) && c)

if (a || b && c)

…

Here the parentheses make a difference so treating them as having the same accessible name would be invalid

It's another fine puzzle. How could we exclude such things? Change this:
Remove parentheses (also known as round brackets) and all characters that are between an opening and closing parenthesis.
to this?
Remove parentheses (also known as round brackets) and all characters that are between an opening and closing parenthesis, unless the parentheses are part of a mathematical, regular, logical, or similar type of expression.

patrickhlauke · 2026-03-26T22:31:44Z

At this stage, I don't have any concerns with the algorithm ... though we will probably need to revisit this if we widen the discussion (this was mentioned recently, but I can't find the email/issue for it) to add additional considerations such as making digits and their actual written out words (e.g. "1" and "one") be ok as synonyms (though this can possibly get hairy when having to decide if "123" is ok as BOTH "one two three" and/or "one hundred and twenty three" or even "one hundred twenty three")

- changing unicode wording. class -> category. - excluding "Mark". I don't know how "mark" got in there, and I think it should not have been in there.

Jym77

Please get #2403 merged in first to clean up the autogenerated changelogs (no need to have a "label in name algorithm" entry in the changelog of the "keyboard trap" rule).
Many small polishes, some larger ones.
Note that it is possible to get specific "examples for definition" pages, e.g. Example of Visible which can be a way to alleviate the many examples inside the rule that mostly illustrate the definition (while actually giving more examples of corner cases of the definition). OTOH, these examples for definitions are not included in the tests in any way, so implementers can take inspiration from them but there is no "validation of implementation" See also #2087.

I do like the way it goes 😀

Jym77 · 2026-04-14T13:44:28Z

+
+This rule assumes that the visible label doesn't use CSS to add whitespace where none exists in the DOM.
+
+This rule - specifically, the [label in name algorithm][] that this rule relies on - assumes that the algorithm's treatment of parentheses is appropriate in the given human language. "Parentheses" are also known as "round brackets". The algorithm's treatment of parentheses is to remove them and all characters within them. This assumption can be reworded as: content within parentheses can be ignored. This assumption is almost always true in English. It is known to be often false in other languages, such as German (where parentheses indicate dual states) and Arabic (where parentheses are often used as quotation marks). Violations of this assumption will, in real-world scenarios, more often result in a false negative for this rule rather than a false positive.


Issue: I am a bit uncomfortable in stating an assumption and immediately saying that it is often not met 😓
I think the bottom line is OK as it is indeed, "only" false negatives. But I think it should be rephrased and maybe moved to Background (like the "image of text" discussion).
Something like "In languages where parenthesis are used for non-incidental [or whatever the correct grammatical term] content, this rule may pass while 2.5.3 fails because a parenthesis is present on one side and its content matter. Examples of such languages include Arabic and German [putting the languages in alphabetical order]" (with a bit more meat to that text, but essentially what is in the current one).

I'm not sure I completely agree. I am very comfortable stating an assumption and immediately saying that it is often not met ... if that's true and helpful. I have spent enough hours trying to decipher specs - WCAG, ACT, you name it - wishing they would be more straightforward and not try to hide their warts. I think that WCAG has a serious problem in this area. ACT doesn't AFAICS, but I am loathe to move the needle even the tiniest amount in that direction. Your thoughts?

I'm certainly not advocating to remove it totally, but moving it to background like the "image of text" note. That note could as well be phrased as "this rule assumes that the page has not image of text".
I'd rather keep assumptions for rare cases.

Not blocking for me however.

I see this as an argument to move the "image of text" note to the "Assumptions" section, not to move the parentheses note to the "Background" section. :)

I had a conversation with someone you know at CSUN. He also saw assumption violations as rare things. I guess I don't. I just looked at my database and found 127 assumption violations for alfa's target size rules. Customers dispute those due to the "equivalent" exception of the SC == assumption of the alfa rule. We've had the target size rules for exactly two years. 127/(52*2) = 1.2 assumption violations per week. Whether that meets the definition of "rare" depends on one's perspective. It's small compared to other things. But still happens regularly (= 1.2 times per week).

At any rate, if it's not a blocker for you, I'll leave it as is - and thank you for the discussion. If someone else weighs in, I'll take it from there.

Jym77 · 2026-04-15T11:33:22Z

+    - For b) Use the Unicode general categories "L" (Letter) and "N" (Number).  (This will exclude hyphens, punctuation, emoji, and more.)
+1. Remove parentheses (also known as round brackets) and all characters that are between an opening and closing parenthesis.
+    - Don't do this for square brackets, nor braces.
+1. Split the string into a list of strings, one string per word, according to the word segmentation rules for the inherited programmatic language.


Suggestion: We should have a link for "inherited programmatic language" (of the element), which I realise is tricky because the existing definition goes the other way around.

Oh dear. Would switching to most common element language help?

🤔 I guess so, it depends whether we want to act on the lang attribute or the actual language…

OTOH, it looks like HTML definition of language is already what we need 😄

Right on - I just did it in commit 3586285

Jym77 · 2026-04-15T11:33:52Z

+[element]: https://dom.spec.whatwg.org/#element
+[normalization form KD]: https://www.unicode.org/glossary/#normalization_form_kd
+[visible inner text]: #visible-inner-text 'Definition of Visible inner text'
+[whitespace][]: #whitespace 'Definition of whitespace'


Suggested change

[whitespace][]: #whitespace 'Definition of whitespace'

[whitespace]: #whitespace 'Definition of whitespace'

Jym77 · 2026-04-15T11:37:59Z

+    - In English and most other European languages, a greedy [whitespace][] regular expression will accomplish this.  In languages such as Thai, Chinese, and Japanese, it won't.
+    - A consequence of using the ACT definition of [whitespace][] here is that all kinds of whitespace are covered.  That includes the Unicode code point U+00A0 - the "No-Break Space" - which can be represented by the HTML named character reference `&nbsp;`.
+
+Then do the check: is the tokenized 'label' a sublist of the tokenized 'name'?


Suggested change

Then do the check: is the tokenized 'label' a sublist of the tokenized 'name'?

Then do the check: is the tokenized `label` a sublist of the tokenized `name`?

Jym77 · 2026-04-15T11:43:37Z

+
+Then do the check: is the tokenized 'label' a sublist of the tokenized 'name'?
+- This 'sublist' check has these properties:
+    - Each string comparison (between a list element in the tokenized label and a list element in the tokenized name) is a simple string equality check.


Note: "Contiguous subsequence" or "subarray" seem to be the commonly used terms, but I do not find a reference that would be authoritative enough to be pointed here :-/

Maybe this comparison can be rephrased as "check whether the tokenised label list can be obtained by removing any number of tokens from the start and/or end of the tokenised name list"?

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

…ext-clause-2.

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

Also removing whitespace between the divs. Doing this because that whitespace was introduced accidentally in commit 5617755 (which was a merge).

dan-tripp-siteimprove and others added 6 commits April 4, 2023 12:25

invalid-form-field-value-36b590: updating failed example 2.

aeafb90

Merge branch 'develop' into develop

5a07973

Merge branch 'act-rules:develop' into develop

a75c7f8

Rule visible-label-in-accessible-name-2ee8b8: introducing a new "labe…

623d26e

…l in name algorithm". It's intended mostly to handle whitespace and punctuation.

Merge branch 'act-rules:develop' into develop

f920a47

Merge remote-tracking branch 'origin/develop' into rule-2ee8b8-may-2023

ee3e993

dan-tripp-siteimprove added Rule Update Use this label for an existing rule that is being updated reviewers wanted labels Jun 22, 2023

dan-tripp-siteimprove requested review from giacomo-petri and kengdoj June 22, 2023 00:53

dan-tripp-siteimprove self-assigned this Jun 22, 2023

dan-tripp-siteimprove changed the title ~~Rule 2ee8b8 may 2023~~ Rule 2ee8b8 ("Visible label is part of accessible name"): introducing a new "label in name algorithm". Jun 22, 2023

dan-tripp-siteimprove marked this pull request as draft July 20, 2023 21:19

dan-tripp-siteimprove and others added 2 commits August 17, 2023 12:14

Merge branch 'act-rules:develop' into develop

75a9878

Adding examples to rule presentational-children-no-focusable-content-…

81caf8a

…307n5z

Jym77 mentioned this pull request Sep 28, 2023

Update visible-label-in-accessible-name-2ee8b8.md #2101

Merged

7 tasks

dan-tripp-siteimprove added 2 commits October 27, 2023 12:49

Merge remote-tracking branch 'upstream/develop' into develop

2928be6

Merge branch 'develop' of https://github.com/dan-tripp-siteimprove/ac…

5cd8b2c

…t-rules.github.io into develop

Jym77 previously requested changes Nov 9, 2023

View reviewed changes

dan-tripp-siteimprove and others added 8 commits November 9, 2023 11:42

removing Passed Example 15 because it's a duplicate.

092c849

editing example: WAVE -> WCAG

473bcb8

Update pages/glossary/visible-inner-text.md

5c7fc1e

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

Update pages/glossary/visible-inner-text.md

3d3b657

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

adding mention of innerText

8ed61b8

adding preamble to label-in-name-algorithm.md which mentions what thi…

46294dd

…s algorithm is for.

WilcoFiers moved this from Backlog to In progress in ACT Projects Mar 19, 2026

WilcoFiers assigned kengdoj and HelenBurge Mar 19, 2026

HelenBurge approved these changes Mar 20, 2026

View reviewed changes

shunguoy approved these changes Mar 24, 2026

View reviewed changes

giacomo-petri reviewed Mar 25, 2026

View reviewed changes

algorithm:

60e5734

- changing unicode wording. class -> category. - excluding "Mark". I don't know how "mark" got in there, and I think it should not have been in there.

WilcoFiers moved this from In progress to In review in ACT Projects Apr 2, 2026

dan-tripp-siteimprove added the Review Call 1 week Call for review for small changes label Apr 13, 2026

Jym77 mentioned this pull request Apr 14, 2026

Run prettier #2403

Merged

8 tasks

Jym77 requested changes Apr 15, 2026

View reviewed changes

dan-tripp-siteimprove and others added 17 commits April 15, 2026 21:57

Update _rules/visible-label-in-accessible-name-2ee8b8.md

0b25658

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

Update _rules/visible-label-in-accessible-name-2ee8b8.md

07e2c27

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

Update _rules/visible-label-in-accessible-name-2ee8b8.md

99a88a6

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

Update _rules/visible-label-in-accessible-name-2ee8b8.md

b781366

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

Update pages/glossary/label-in-name-algorithm.md

774547e

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

minor tweaks

a839498

for language, now linking to whatwg definition.

3586285

Update _rules/visible-label-in-accessible-name-2ee8b8.md

84f2e2d

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

passed example 8: rewording.

c01ccfa

Passed Example 11: adding "fragment link" to visible-inner-text:for-t…

fd8029c

…ext-clause-2.

fixing previous commit

b50d890

fixing previous commit

6816e7b

tweaking previous commit

dd9d7f1

another tweak

e0b890a

another tweak

b9460bf

Update _rules/visible-label-in-accessible-name-2ee8b8.md

29e576b

Co-authored-by: Jean-Yves Moyen <jym@siteimprove.com>

Passed Example 9: changing from p to div as per Jym's review.

5aa55e6

Also removing whitespace between the divs. Doing this because that whitespace was introduced accidentally in commit 5617755 (which was a merge).


		This rule assumes that the visible label doesn't use CSS to add whitespace where none exists in the DOM.

		This rule - specifically, the [label in name algorithm][] that this rule relies on - assumes that the algorithm's treatment of parentheses is appropriate in the given human language. "Parentheses" are also known as "round brackets". The algorithm's treatment of parentheses is to remove them and all characters within them. This assumption can be reworded as: content within parentheses can be ignored. This assumption is almost always true in English. It is known to be often false in other languages, such as German (where parentheses indicate dual states) and Arabic (where parentheses are often used as quotation marks). Violations of this assumption will, in real-world scenarios, more often result in a false negative for this rule rather than a false positive.

	[whitespace][]: #whitespace 'Definition of whitespace'
	[whitespace]: #whitespace 'Definition of whitespace'

	Then do the check: is the tokenized 'label' a sublist of the tokenized 'name'?
	Then do the check: is the tokenized `label` a sublist of the tokenized `name`?

Conversation

dan-tripp-siteimprove commented Jun 22, 2023 • edited by Jym77 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Etiquette

When creating PR:

After creating PR:

When merging a PR:

How to Review And Approve

Uh oh!

WilcoFiers commented Jul 20, 2023

Uh oh!

dan-tripp-siteimprove commented Jul 20, 2023

Uh oh!

Jym77 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

patrickhlauke commented Mar 26, 2026

Uh oh!

Jym77 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

dan-tripp-siteimprove commented Jun 22, 2023 •

edited by Jym77

Loading