aria-required-children "unallowed" message not actionable

[dbjorge]

Product

axe-core

Product Version

4.6.1

Latest Version

• I have tested the issue with the latest version of the product

Issue Description

The message for the unallowed type of aria-required-children failure introduced in axe-core 4.5 via #3597 is a little confusing for folks that aren't already familiar with ARIA ownership rules because the message doesn't summarize why the given children would be disallowed. We think this would be improved by updating the message to be more clear that the reason the children are disallowed is that they have roles which are disallowed, and what those roles are.

We understand that not including the roles in the message was an intentional choice to avoid the complexity of cases with children that don't have roles, but we'd like to request revisiting that choice - we think the amount of complexity this would add to the message calculation would be a worthwhile tradeoff to avoid user confusion.

Expectation

The message should contain enough information for a user unfamiliar with the rule to understand why it's being triggered in a given specific case. For example:

Element with role "menu" cannot have children with roles img,link

or:

Element with role "list" cannot have children visible to screen readers with no role

Actual

The message currently reads:

Element has children which are not allowed (see related nodes)

...without explaining what causes the children to be not allowed.

How to Reproduce

Codepen containing examples of each of the 6 cases suggested below, along with an embedded working example of the suggested output below

Additional context

Suggested new message templates to replace the rule's current "unknown" template:

"unallowedRoleSingular": "Element with role \"${data.role}\" cannot have child with role ${data.unallowedRoles}",
"unallowedRolePlural": "Element with role \"${data.role}\" cannot have children with roles ${data.unallowedRoles}",
"unallowedNoRoleSingular": "Element with role \"${data.role}\" cannot have child visible to screen readers with no role",
"unallowedNoRolePlural": "Element with role \"${data.role}\" cannot have children visible to screen readers with no role",
"unallowedMixedRoleSingular": "Element with role \"${data.role}\" cannot have children visible to screen readers with no role or with role ${data.unallowedRoles}",
"unallowedMixedRolePlural": "Element with role \"${data.role}\" cannot have children visible to screen readers with no role or with roles ${data.unallowedRoles}"

...and suggested aria-required-children-evaluate.js snippet (to replace current L87-89) to populate the necessary data/messageKey:

    const unallowedRoles = unallowed.map(({ role }) => role).filter(role => role !== null);
    const unallowedNullRoleCount = unallowed.length - unallowedRoles.length;
    
    let messageKey;
    if(unallowedRoles.length === 0) {
      if (unallowedNullRoleCount === 1) {
        messageKey = 'unallowedNoRoleSingular';
      } else {
        messageKey = 'unallowedNoRolePlural';
      }
    } else if (unallowedRoles.length === 1) {
      if (unallowedNullRoleCount === 0) {
        messageKey = 'unallowedRoleSingular';
      } else {
        messageKey = 'unallowedMixedRoleSingular';
      }
    } else { // unallowedRoles.length > 1
      if (unallowedNullRoleCount === 0) {
        messageKey = 'unallowedRolePlural';
      } else {
        messageKey = 'unallowedMixedRolePlural';
      }
    }

    this.data({
      messageKey,
      role,
      unallowedRoles,
    });

No-role terminology

The terminology "visible to screen readers" was the closest analogue I found in existing messages (aria-errormessage, aria-labelledby, button-has-visible-text, has-visible-text) for the case that would trigger an unknown failure for a no-role child here ("has a global aria property OR is focusable"). I think this is easier to understand than the current text, but it might be even more actionable to be more specific and literally tell the user that the issue is that there's a child "with global ARIA property {data.propertyName}" or "which is focusable".

I chose not to include that in this suggestion since it exploded the number of messages even further; I think if we wanted to go down that route, it might be better to separate this logical check out of aria-required-children into a separate rule which creates a separate failure per bad parent-child relationship (maybe `aria-allowed-child' or something).

[straker]

Thanks for the suggestion. Rather than multiple messages, we could do what we do for definition-list when there are elements or roles that are not allowed as children. The only-dlitems check uses a single message and uses the invalid-children-evaluate method. The method generates a simple list of selectors that are invalid which covers both invalid elements and roles. That way we aren't pointing them to related nodes and instead list exactly what's wrong.

So taking the following HTML, it produces the following violation:

<dl>
  <li>hello</li>
  <li>baz</li>
  <div role="button">bar</div>
</dl>

Fix all of the following:
  dl element has direct children that are not allowed: li, [role=button]

[dbjorge]

@straker Yes, I think something along those lines would work. I think it would be good for the message to include some clarification of why the children are not allowed though (because they have an unallowed ARIA role). Maybe something like this, where data.parentSelector is derived similarly to invalid-children-evaluate's values?

${data.parentSelector} element has children with ARIA roles that are not allowed: ${data.values}

Or possibly with this extra clause, depending if #3850 is accepted:

${data.parentSelector} element has children visible to screen readers with ARIA roles that are not allowed: ${data.values}

[dbjorge]

We've started receiving feedback about this message being confusing from our users, so we're likely to include a local patch implementing the message update here as part of our update to axe-core 4.6 in Accessibility Insights. We'd like to have that patch use wording similar to what axe-core 4.7 is likely to end up with if possible.

@straker, do either of the specific proposals from my previous comment look good to you? Or do you have a different specific wording you'd prefer to use instead?

[straker]

The parentSelector is already available from the node itself and the target property, so I don't think it's needed in the message. The problem with calling out that ARIA roles are not allowed is that unless you know that an li element has an implicit listitem role, seeing the message element has children with ARIA roles that are not allowed: li would be confusing as well since the li does not have a role attribute.

Do we need to say exactly why the child is not allowed?

[dbjorge]

I included parentSelector because, since the rule only applies to parents with explicit roles, in practice it will be of the form role=specific_aria_role, which I think would be clear about identifying the specific part of the parent selector that is related to the problem at hand. I think something like element with role ${data.parentRole} would also be equally fine. If the message needs to be shortened for brevity, I think dropping the parent role would be better than dropping child roles.

The feedback we're receiving from users is that they're confused about what they need to change to resolve the issue. I think it it would help to say exactly why the child is not allowed. I agree with you that saying li would probably still be confusing because of the implicit role. Specific points of feedback we're seeing are:

• "I don't know which children are unallowed" (from users that don't understand that they need to look inside the individual check to find the "related nodes" the current message references)
• "I don't know why the child would be unallowed" (from users that can identify the problematic children but either don't understand that ARIA roles are the issue or don't understand how to map children to their implicit roles)
• "I don't know how to identify what roles would be allowed" (from users that understand that the ARIA roles are the issue but don't understand that they need to look up the ARIA spec for the parent role and look at the "required owned" characteristic)

I think something like this would be ideal from the standpoint of "including enough information to be self-actionable for all of the above cases", but I appreciate that it's a bit verbose compared to most other rules:

Children of element with ARIA role ${data.parentRole} must have an ARIA role in ${data.allowedChildRoles}, but found children: ${data.unallowedChildren}

...where ${data.unallowedChildren} elements are of form role=listitem for children with explicit roles, li (implicit role listitem) for children with implicit roles, and div (no role) for children with no implicit or explicit role.

Does that sound reasonable? Can you think of a good way to include comparable information that's less verbose? Probably would be better to come up with an option that doesn't require translating individual elements of a data property, that's probably rough.

[dbjorge]

I wonder if it would be better to split out this specific check into a different check/rule that produces violations per-parent-child-pair instead of per-parent to help make it less verbose and easier to template the translatable parts of the message. Maybe something like aria-unallowed-child with message templates of forms:

• Child with role: Element has ARIA role ${data.explicitRole}, but its parent's role (${data.parentRole}) requires that children visible to screen readers have one of the following roles: ${data.allowedChildRoles}
• Child with no role: Element has no ARIA role, but its parent's role (${data.parentRole}) requires that children visible to screen readers have one of the following roles: ${data.allowedChildRoles}

[straker]

I think the approach we should take is that the message should be informative enough that if you know what the problem is you can fix it based on the message, but if you don't understand the why then you'll need to refer to the help page to get that information.

With that in mind, I think we should just list out the selectors that are invalid and then update the the rule help page with more information if it doesn't have enough to help with those specific points of feedback.

[padmavemulapati]

Validated with the latest axe-core develop branch code base,
for aria-required-children unallowed fix message, the message is changed from passing related nodes to data.values so that on which value, chidren not allowing can be identified and can be fixed easily when it fails.

for ex: for the below code snippet:

<dl>
  <li>hello</li>
  <li>baz</li>
  <div role="button">bar</div>
</dl>

definition-list fails and communicating the fix message as
dl element has direct children that are not allowed: li, [role=button]
Earlier it was
List element has direct children that are not allowed inside <dt> or <dd> elements

Now:

Older: