Screenreaders unable to read Gitea's various dropdowns #7057

Closed dpy013 closed 3 years ago

Gitea version (or commit ref): 1.8.1

Git version: 2.21.0

Operating system: windows10-1903

Database (use [x]):

[ ] PostgreSQL

[x] MySQL

[ ] MSSQL

[x] SQLite

Can you reproduce the bug at https://try.gitea.io:

[ ] Yes (provide example URL)

[ ] No

[x] Not relevant

Log gist: not needed

Description

Gitea, as with gogs which it was forked from, has many accessibility issues with screen readers including:

The dropdown menus are clickables, so many screen readers do not know what to do with them as they do not use the mouse cursor.

The license selection/.gitignore selection (and most other menus of that type) are inaccessible, as they all use mouse oriented actions.

Possibly others I haven't seen yet.

Unfortunately, this is caused by the toolkit you use, which does not seem interested in making their toolkit accessible. It can be worked around with aria markup, or by changing toolkits (the first of which is easier to begin with but requires more maintenance over time, the second of which is of course much harder, but once you get it done it's done pretty much forever).

See the original issue on gogs for more info: gogs/gogs#3340

Looking forward to seeing if anything can be done about this. -dingpengyu. tests screen reader: NVDA thank

You need to do UI testing using screen readers manually during development. The same way you test UI with your eyes.

On Sun, Jul 18, 2021 at 02:36:22PM -0700, techknowlogick wrote:

FWIW Gitea has some modest funds we could hopefully put towards this, and I believe the same applies for Codeberg. I know Codeberg has discussed this, as well as have discussed searching for a firm that could do a study of Gitea, and also some remediation.

This of course is not a onetime fix, and then no one needs to be concerned with it every again, but rather an ongoing effort that is needed. So UI testing via CI, documentation for developers/maintainers of best practices when building Gitea, and even more than I could list at the moment.

-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/go-gitea/gitea/issues/7057#issuecomment-882119742

You need to do UI testing using screen readers manually during development. The same way you test UI with your eyes.

There are accessibility check add-ons afaik and Firefox has a built-in tool which could also help catching easy issues

You need to do UI testing using screen readers manually during development. The same way you test UI with your eyes.

I completely agree, as mentioned the list I gave was not exhaustive. Manual testing would also certainly be included.

I'm sure many people here (me included) would be willing to do testing, even if the developers were unable to test themselves. In fact, it is the approach used in many companies. Develop and user tests. I'm not familiar with Go nor the inner workings of Gitea, but I can definitely test.

On 7/19/21, techknowlogick @.***> wrote:

You need to do UI testing using screen readers manually during development. The same way you test UI with your eyes.

I completely agree, as mentioned the list I gave was not exhaustive. Manual testing would also certainly be included.

-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/go-gitea/gitea/issues/7057#issuecomment-882255798

As it stands, the merge of #15951 and #15193 currently break the very minimal screen reader support. Please do not upgrade to https://github.com/go-gitea/gitea/tree/v1.15.0-rc1 (or above) if you use screen reading software.

Knowing that Gitea is used and relied on by keyboard/screen reader users, yet still merging accessibility-breaking changes is a very unwise move, especially because, to my knowledge, there is nothing else that provides the same (or even a similar) feature set as Gitea. I understand that backward compatibility requires a lot of effort to maintain, but without it, you are essentially ignoring users (by choice) who have to rely on screen reading software, which is not by choice, by the way. Please strongly reconsider this, especially @silverwind and @techknowlogick. We don't just lose some #a11y, we lose most of what's been there. In fact, there have been no other accessibility improvements made other than these two, as far as I know.

Many modern UI toolkits have ARIA-enabled controls these days, or due to their design, they require very minimal ARIA/javascript to make their controls keyboard/screen reader accessible.

I still believe that since there is no interest whatsoever in accessibility upstream, dropping Fomantic and switching to something like Bootstrap, React, etc, is the way forward in ensuring that Gitea can be accessed equally. Until this is done, however, blind/visually impaired users are currently left in the dark (no pun intended).

I am currently trying to look into the issue and I'm trying to find out what exactly is broken. I'm currently testing with Orca as the first step.

So far I've found that dropdown does not work. I suspect it must be completely re-done:

it automatically expands when you focus on it and it is not announced at all
it's impossible to select dropdown items with keyboard. Tabbing switches to the useless inner button of the dropdown instead (as a note to developers: even if you don't test with screen reader you can still try to use keyboard to see if things work)

Hovewer I do not see the problem with #15951 ? It uses details/summary elements which are pretty well supported by screen readers I believe.

Dropdowns did work, now they're broken again.

Details/summary elements are not accordions.

@charlag, thank you very much for looking into this.

Hovewer I do not see the problem with #15951 ?

You are right. I was under the impression that this would be a Fomantic custom control, but this is browser-native, which works fine.

Details/summary elements are not accordions. From an #a11y point of view, they work, but technically they are not meant to be used as accordions, you are right. This is more of a best practices issue, however, similarly to how buttons should not be used to link pages, especially if they are not styled to look like buttons.

@Flameborn I think there's a disparity between how it was supposed to be used and how it is used in practice. What I am interested in right now is making it work and dropdowns are completely broken so I propose to focus on that.

@Flameborn I think there's a disparity between how it was supposed to be used and how it is used in practice. What I am interested in right now is making it work and dropdowns are completely broken so I propose to focus on that.

You are right, best practices in this case are less important (especially if they are still accessible natively) than something that is completely unusable. Since dropdowns are used everywhere, even on the installation page, having that fixed is probably the most important thing for v1.15. Other, less important things can be focused on later down the line.

I think there are two options:

Using native <select>/<option>. It looks decent when collapsed but doesn't look as good when expanding it etc. This is obviously the easiest option.
Override dropdown like it was suggested here https://github.com/fomantic/Fomantic-UI/issues/1332#issuecomment-588079479 and how it was used before #15193. This is a bigger investment and that's what @Jookia already did once and is properly better equipped to do than me.

I know, I know, "the whole UI must be rewritten", unfortunately this doesn't help right now and something must be done right now.

I could try to hack together option 2 again. It basically needs:

Click handler for opening the dropdown and selecting the first item
Click handler for dropdown items
Blur handler for closing the dropdown when focus is lost
Animations for both

I want to get some feedback from maintainers before I will proceed with either.

For how <select> can work go to https://github.com/settings/profile and check language/email dropdown there.

As discussed in https://github.com/fomantic/Fomantic-UI/issues/1332#issuecomment-882465723, here is some draft of ui native dropdown to a select tag i tried some time ago. Don't know, if this helps the project at all.

https://jsfiddle.net/lubber/cupwk8sh/75/

Native <select> works in some cases but looks ugly and Gitea has some dropdowns that have HTML content which requires a different solution.

Personally, I like using tippy.js which builds on popper.js for its flawless positioning of overlay content. I think anything based on popper.js would be fine. Fomantic certainly has issues with positioning dropdown contents in some cases.

Looking at their demo, the dropdowns seem to show up as a collapsed/expanded button, as well as focusable buttons as dropdown items to a screen reader.

While this does not have a native feel, e.g. items can't be focused with the arrow keys once the dropdown is expanded, items have a defined tabIndex. If this ends up being used, it's still a huge improvement over the Fomantic dropdowns.

Or we could just not use fomantic-ui dropdown JavaScript but replace it with own built Vue component (just with correctly added aria attributes etc) something like I did with branch selection somewhere if I remember correctly. But still using fomantic css and html elements as needed

For reference: https://github.com/go-gitea/gitea/blob/ec357833bcfc90860331f956a811ecbf45df47aa/web_src/js/index.js#L3495

Yes I think we should do a custom dropdown initialization. I quite like how Github has done it using <details> and <summary> elements because that works even with JavaScript disabled, so it can be probably be done completely in HTML with no JS/Vue involved. For proper menu positioning, JS might be unavoidable thought.

It should probably also distinguish between select-style dropdowns and more complex ones like the review dropdown.

I've built dropdowns in other projects before but I have no experience with either Vue or jQuery for that matter. Anyone wants to step in and make one? From what I understand is that @silverwind implies that PR might get included and not just lay around. @Codeberg-org would really like to solve this and they might even sponsor this work so would be nice if there's a competent champion for this.

Oh and btw tippy looks like a library for tooltips, not for dropdowns.

Oh and btw tippy looks like a library for tooltips, not for dropdowns.

It's labeled as "Tooltip, popover, dropdown, and menu library" so I think it's still suitable, and sufficiently lightweight at that.

Yeah except it doesn't create anything focusable afaik

It does, see my previous comment above. In a dropdown, items are actual buttons. It’s not perfect, but it works much better than what we currently have in RC1.

On 2021. Jul 27., at 18:12, Ivan Kupalov @.***> wrote:

Yeah except it doesn't create anything focusable afaik

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/go-gitea/gitea/issues/7057#issuecomment-887645237, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHLD4AZZVPRIDPP7VRNJOTTZ3LINANCNFSM4HPYFNCQ.

Does the Gitea team consider the broken accessibility as release critical for 1.15? Like, does it matter if the software is not usable for some users at all? If so, you might want to add an issue to the milestone to make sure some fix makes it in! Shall I open a new one to explicitly track the accessibility regressions in 1.15 and keep this as a general discussion?

I don't really know how to best move on. Paying someone for a quick fix is surely possible, but it will be hard to motivate someone if there is no guarantee that the fixes aren't broken again, as it happened to the last ones, and when there is no overall strategy on how to take care of accessibility in the future. I perfectly understand that some people are not willing to help in this situation, and even money won't help here.

If we don't manage to move forward here, what about having a brief meeting and discussing some next steps, or using some chat group (e.g. Matrix) to discuss the matter? We also have some testers around who might be interested to join the discussion and help in identifying the issues and confirming the fixes.

BTW, I like the details/summary approach without requiring JavaScript for some basic functionality, this sounds good, tippy doesn't work without JS. But I don't really want to force something on UI people, I don't have much knowledge of Web UI.

The vendored dropdown that contained Jookia's fixes was removed in #15193 due to it becoming incompatible with fomantic and then breaking everything. The decision was made to abandon it - an action I had prevented twice before but this time I was unable to spend time updating it and had been unable to understand what it was doing.

This was a course of action I was disappointed in but I hoped that it might actually spur someone to actually propose a more stable solution or even just re-port jookia's changes to the latest fomantic for Gitea and repropose them.

This has not happened and instead we have had another 30 comments not really getting anywhere.

So can we please take a more constructive course?

I'll take a look at Jookia's patch again and try to reapply them to fomantic's dropdown.
However, clearly fomantic's dropdowns aren't going to work. Jookia's fix although comprehensive is fundamentally not a maintainable solution for us without further help from Jookia.
I have been unable to find a concise explanation of what would work or had one proposed. No explanation of why what is currently present doesn't work or steps to fix the problem.

Can anyone point to an actual example of a dropdown that will work? Or propose incremental changes to improve Gitea's accessibility?

The vendored dropdown that contained Jookia's fixes was removed in #15193 due to it becoming incompatible with fomantic and then breaking everything. The decision was made to abandon it - an action I had prevented twice before but this time I was unable to spend time updating it and had been unable to understand what it was doing.

This was a course of action I was disappointed in but I hoped that it might actually spur someone to actually propose a more stable solution or even just re-port jookia's changes to the latest fomantic for Gitea and repropose them.

This has not happened and instead we have had another 30 comments not really getting anywhere.

So can we please take a more constructive course?
* I'll take a look at Jookia's patch again and try to reapply them to fomantic's dropdown.

* However, clearly fomantic's dropdowns aren't going to work. Jookia's fix although comprehensive is fundamentally not a maintainable solution for us without further help from Jookia.

* I have been unable to find a concise explanation of what would work or had one proposed. No explanation of why what is currently present doesn't work or steps to fix the problem.
Can anyone point to an actual example of a dropdown that will work? Or propose incremental changes to improve Gitea's accessibility?

Dropdown cannot be opened using keyboard, you cannot close of using keyboard, you cannot select items using keyboard. That is the problem. Once it's done it roll work with screen readers.

We have acessible dropdowns at mail.tutanota.com (try "change color theme" under more) if you need an example. It's done on top of mithril but there's nothing really special about it.

Dropdown cannot be opened using keyboard, you cannot close of using keyboard, you cannot select items using keyboard. That is the problem. Once it's done it roll work with screen readers.

This is not true, by testing try.gitea.io keyboard navigation works and I can open/close dropdowns, and even navigate to/select links in the list, however VoiceOver doesn't recognize that the dropdown is open and won't read out things.

This screenshot is from keyboard navigation, it shows that I've opened the dropdown, and am able to hover over (and can open the link), however you'll note that the voiceover select sticks with the user icon at the top of the dropdown.

Screenshot showing voiceover keeps on the user icon in dropdown while keyboard is able to select an item in the list

I've copied Jookia's changes to a branch of fomantic, however @zeripath is looking at how to get it working with jQuery. We (the Gitea project), are happy to pay a nominal amount to 1. Jookia for existing work done, 2. Person who gets an acceptable PR merged to fomantic, and 3. the fomantic maintainers to assist with getting our dropdown's working with screenreaders.

Shortterm we would be happy accept a PR that fixes issues into the 1.15 release, as it is considered bugs and we backport bugs. Longterm a study on accessibility needs to be done and remedial work based on the outcome of that report (as well as likely a change in UI framework).

Dropdown cannot be opened using keyboard, you cannot close of using keyboard, you cannot select items using keyboard. That is the problem. Once it's done it roll work with screen readers.

This is not true, by testing try.gitea.io keyboard navigation works and I can open/close dropdowns, and even navigate to/select links in the list, however VoiceOver doesn't recognize that the dropdown is open and won't read out things.

This screenshot is from keyboard navigation, it shows that I've opened the dropdown, and am able to hover over (and can open the link), however you'll note that the voiceover select sticks with the user icon at the top of the dropdown.

I've copied Jookia's changes to a branch of fomantic, however @zeripath is looking at how to get it working with jQuery. We (the Gitea project), are happy to pay a nominal amount to 1. Jookia for existing work done, 2. Person who gets an acceptable PR merged to fomantic, and 3. the fomantic maintainers to assist with getting our dropdown's working with screenreaders.

Shortterm we would be happy accept a PR that fixes issues into the 1.15 release, as it is considered bugs and we backport bugs. Longterm a study on accessibility needs to be done and remedial work based on the outcome of that report (as well as likely a change in UI framework).

I'm sorry that I missed that, thanks for actually checking.

If opening the dropdown works I think it should be enough to just focus the first element after that and return focus back once dropdown is closed.

The actual process for properly fixing things is this:

Find a broken widget
Decide what the widget actually is in the ARIA spec
Give it corrected ARIA markup in HTML
Provide hooks for Fomantic's JS

All UI developers going forward will have to understand ARIA to write Gitea UI code.

Why is this?

Semantic-UI and Fomantic-UI are too low level to add ARIA accessibility natively. They do not provide widgets, they provide components that Gitea uses to make its own ad-hoc widgets. Gitea is the one making widgets, so it needs to implement the accessibility code itself. Maybe down the line you could take this experience and turn it in to a Fomantic widget library or something.

The best solution is to probably start rewriting individual templates to use Bootstrap or something that provides clearly defined widgets.

Edit: The existing Fomantic code I wrote just takes a guess at what widget is which, and actually uses invalid ARIA roles.

@Jookia I'm more than happy to add ARIA codes to our templates. I'd be more than happy to learn what ARIA requires too.

But ...

The documentation for this stuff is absolutely terrible and is full of contradictions. It's all rather specific to each specific case.

As I wrote 1.5 years ago:

We need to learn the patterns that make things accessible.

I genuinely want this to improve but have no time to learn how to do it. You clearly have the skills to do this so please don't disappear. We need your help.

The way we will learn this is through examples of working practices.

If you are available I'd like to go through that dropdown patch in detail on a different - hopefully more productive - thread which I'll link soon. I think a lot of it could be done using fomantic hooks and template changes and I could do with understanding why you've made certain changes.

@Jookia I'm more than happy to add ARIA codes to our templates. I'd be more than happy to learn what ARIA requires too.

But ...

The documentation for this stuff is absolutely terrible and is full of contradictions. It's all rather specific to each specific case.

This is what I've worked with: https://www.w3.org/TR/wai-aria-practices-1.2/ As well as googling what roles specifically are. The dropdown I made uses the 'menu or menu bar' section when it should be using a 'listbox'.

As I wrote 1.5 years ago:

We need to learn the patterns that make things accessible. I genuinely want this to improve but have no time to learn how to do it. You clearly have the skills to do this so please don't disappear. We need your help.

The way we will learn this is through examples of working practices.

wai-aria-practices is full of examples complete with Javascript: https://www.w3.org/TR/wai-aria-practices-1.2/examples/listbox/listbox-collapsible.html

If you are available I'd like to go through that dropdown patch in detail on a different - hopefully more productive - thread which I'll link soon. I think a lot of it could be done using fomantic hooks and template changes and I could do with understanding why you've made certain changes.

Sure, I'll try.

I initially wrote a very, very long reply here about what Gitea should do next, but really what Gitea needs to do is a very basic accessibility audit. Things like icons or images without alt text, bad contrast, what which widgets are in ARIA terms, how things actually sound or work. This isn't that big a task, it just requires a list of every page template, and writing down notes in an issue, then drawing conclusions about the problem areas and how to move forward from there.

This would move things from 'Gitea has an accessibility problem' to 'Gitea has certain problems'. Then you can start moving to classify the problems and work on ways to systemically fix them.

@Jookia We (myself & the project) agree. I was going to reply with the following to my email from earlier, but might as well put it here instead. We have been researching accessibility vendors to complete an audit like you have mentioned above, and just today have reached out to see if we can hire one. From that report, like you said, we will have explicit issues to resolve, but we can also create best practices for going forward.

Thank you for creating that original PR before, but also your advocacy to make Gitea better software for everyone.

I originally wrote a long message before my last comment but deleted it since it wasn't really that important, but I might as well paste it here anyway:

There's mainly three things I think the project needs to get widgets fixed:

The first is a widget factory page. This would contain reference HTML for each type of widget Gitea uses, and other HTML stuff like forms. This would allow much easier testing of accessibility features- at least for code on this page. This applies not just to ARIA but things like WCAG accessibility, etc. Just things whose accessibility is affected by code like HTML/CSS/JS. Fixing accessibility bugs would then become for the most part focused on this page as a test platform, assuming it contains each type/permutation of the widgets.

The second is to refactor ALL HTML to use reference HTML. There's a variety of ways to do this, the preferred way would be using some form of templates that get compiled in to the reference HTML. I think this is how server-side React tends to do things. The other way I can think of would be having a linter that will warn when templates don't match reference HTML, or at least how we decide things should be. A linter might actually be better for building habits and allowing more flexible systems, but it really depends on what people can actually build. It would also warn about missing alt tags on images and things like that.

The third is CI. AFAIK there's no CI solutions for testing accessibility things since a lot of it is human based. But I think there's two things you'd want to implement: The first is a WebDriver that crawls pages and lints widgets for ARIA properties to make sure they're actual reference/working widgets, to some extent. The second is a Orca test for the widgets page, which would basically mean implementing something like https://github.com/GNOME/orca/blob/master/test/keystrokes/firefox/line_nav_hidden_float.py

In the end, the best tools are the ones that people will use, so it's really up to the Gitea developers to give input on what would build in to their workflow and how to handle a refactor. Starting with just dropdowns would be a decent exercise for this. The main busywork comes from fixing up the HTML to use specific widgets.

The actual game plan for this involves creating widgets that are mappable to ARIA widgets, and code that adds ARIA support code for them. Ideally this would build on top of Fomantic's components as some kind of glue to make widgets, so instead of a 'dropdown' component used in various places, you'd have high level widgets like 'listbox'. How this gets written and made varies depending on whether you want this to end up as part of Fomantic and maintain that, or just as some template code in Gitea. Maybe it could go in another package altogether? I don't know.

The process would probably go like this:

Go through all the Gitea pages and identify what types of widgets you have and what they do
Figure out a mapping between those and some high-level widgets you'd make that support ARIA
Identify and replace Fomantic widgets with ARIA-aware widgets incrementally

As a summary of what's generally working:

Modal dialogs let you tab through background elements still

Modal dialogs don't speak

I started implementing accessibility features to Fomantic-UI. Modal is currently covered by https://github.com/fomantic/Fomantic-UI/pull/2036

Thanks everyone for participation in this thread. I'm going to close this specific issue thread now, not because I believe everything to be solved but rather once we have an audit completed we can create individual issues for remediation.

We are still seeking out someone to complete an audit (they would of course be compensated for their time) and have reached out to some professionals already, however if anyone has any leads on where we could get an audit please let us know.

Can you keep it open until the audit is completed?

On Sun, Aug 08, 2021 at 11:42:19AM -0700, techknowlogick wrote:

Thanks everyone for participation in this thread. I'm going to close this specific issue thread now, not because I believe everything to be solved but rather once we have an audit completed we can create individual issues for remediation.

We are still seeking out someone to complete an audit (they would of course be compensated for their time) and have reached out to some professionals already, however if anyone has any leads on where we could get an audit please let us know.

-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/go-gitea/gitea/issues/7057#issuecomment-894838206

What's the point of closing the bug if it's not fixed and there's no immediate issues to point to?

Is there an issue for an accessibility audit?

I agree to close this rather long (and sometimes a little heated) thread and create a new one. I would have done this before closing, also to publicly call for this and collect some necessary resources (link someone to existing issues and comments that might be useful), but don't want to heat this up again.

Who finds the time to open it first wins my appreciation :-)

Shouldn't you make the thread before closing it? Seems like an easy way to forget about this issue.

Been AFK for a bit, opened issue here: https://github.com/go-gitea/gitea/issues/16660

Do not worry about this issue being forgotten, as my/others inboxes certainly aren't lacking in emails with regards to accessibility.

Please re-open this until there's a timeline for #16660 and place change the title back to 'Gitea accessibility problem' since the discussion was much wider

go-gitea / gitea

Screenreaders unable to read Gitea's various dropdowns #7057

Description