Accessibility issues with Tabbed and Tab extensions

[myasonik]

Description

The rendered tabs are missing a few things needed to create an accessible experience.

Spec example implementation can be found in the APG

The needed changes:

• Focus state for tabs

• The DOM needs to be considerably rewritten

  The basic structure should be:

  <div role="tab">
  <div role="tablist">
    <button type="button" role="tab" id="tab-1" aria-selected={true|false} aria-controls="tabpanel-1" tabindex="0">
      Tab 1
    </button>
    <button type="button" role="tab" id="tab-2" aria-selected={true|false} aria-controls="tabpanel-2" tabindex="-1">
      Tab 1
    </button>
  </div>
  <div role="tabpanel" id="tabpanel-1" tabindex="0" aria-labelledby="tab-1">{content}</div>
  <div role="tabpanel" id="tabpanel-2" tabindex="0" aria-labelledby="tab-2">{content}</div>
  </div>

Not needed per spec but best practice for unknown tab content:

• Add tabindex="0" to tabpanels

Minimal Reproduction

1. Render tabs (any example on Tabbed or Tab)
2. Try to navigate with any screen reader (tabs are not identified as tabs and are difficult to navigate)

Version(s) & System Info

• Operating System: MacOS
• Python Version:
• Package Version: 10.8.1

[facelessuser]

The current layout was created with the help from the author of Material for MkDoc's. They currently rely heavily on the current approach. I would like to loop in them for any discussions on the possibility of restructuring the tab container.

@squidfunk, any thoughts on this?

[squidfunk]

I understand the concerns, and improving accessibility is always a priority for us. However note that this implementation is one of the very few tab implementations that does not rely on JavaScript – it works without JavaScript. This is also one of the goals in Material for MkDocs. We gravitated towards this solution in https://github.com/facelessuser/pymdown-extensions/issues/1415.

If we can improve accessibility, we're happy to accept PRs, but it's unlikely that we change the implementation completely. For instance, adding the role attributes could be something done here, in this project, and it is not expected to have any impact on the rendering. If we can dynamically add aria-* attributes when tabs are used and JavaScript is available, we're happy to do so. Again, PR appreciated.

[facelessuser]

I'm kind of on the same page here. I'm open to accessibility changes that could be made here, but I would like to avoid a complete restructure.

My main interest was to get insight on possible directions. Do aria attributes need to be dynamic? Is there anything about the way we currently do things that impedes accessibility goals, and if so, which ones?

The statements was made "The DOM needs to be considerably rewritten", but I'm not sure there was clear reasoning specifying exactly why this is. What specific functionality is impossible to implement in our current approach?

I agree that functional tabs with pure CSS is an asset. With that said, I would at least like to understand the any negatives if they can be articulated clearly.

[myasonik]

Sorry about the quality of this video (and the audio especially!) but I had to compress it quite a bit to get it under GH's size limit. Hopefully this illustrates some of the issues.

https://github.com/facelessuser/pymdown-extensions/assets/4188087/56819c7b-fbe4-4bff-a681-5a3b2ab11a31

[facelessuser]

Videos are great, and I'll check it as soon as I can, but can you summarize the main points why the current structure can not be adapted and requires an overhaul? Ideally, we could adapt the current layout to improve accessibility.

[myasonik]

The current structure is something along the lines of:

<input type="radio">
<label><a>Tab name</a></label>
<div>Tab content</div>

To work with assistive tech, it needs to have a structure similar to what I mention at the top of the ticket.

The current structure:

• doesn't have any of the correct semantics
• without JS, can't correctly set selected state
• the hidden inputs are position at the top of the page confusing screen readers
• has nested interactive controls (label > a) which causes issues for screen readers and keyboard focus

If more resources on accessible implementations would be helpful, let me know! Happy to provide links to more robust implementation guides.

[myasonik]

If an accessible implementation of tabs is not feasible, 3 things can be improved to mitigate some problems:

1. Add a focus state to the <input> (to highlight the associated <label>) – this will probably still require moving the <input> elements to directly precede their associated <label> rather than all being at the start
2. Remove the nested <a>

3. Use better hidden styles for the <input>

   • To be honest, I'm not sure if this will fix the issue with screen reader cursor placement which is demoed in the video but I think it will...
   • position: absolute; transform: scale(0); is one simple option but this implementation is more battle tested

This still doesn't expose any correct tab semantics and may still be confusing but it should at least reduce bugs across assistive tech.

[facelessuser]

Is this true for the alternate style that is available? Are you aware of the alternate style vs the default?

Granted, we not currently apply roles to worker yet, but I want to make sure we are not just looking at the default or the alternate approach style.

[facelessuser]

I enabled a screen reader and played with this a bit. I at least have a better feel for what doesn't work, and even when adding roles and such, I see that the screen reader does seem to expect things to be configured a certain way. You can kind of get aspects of it to work without following things exactly, but it seems you can't get everything to work. I will play with this more.

[myasonik]

Is this true for the alternate style that is available? Are you aware of the alternate style vs the default?

Hadn't seen it before but just checked it out and it seems to be largely the same.

I enabled a screen reader and played with this a bit... I will play with this more.

That's awesome - thanks for jumping into the deep end!