Improve accessibility for the visually impaired

[neosonic2]

I am a completely blind individual using the VoiceOver screen reading program on macOS to navigate around the Internet, including working inside Freescout.

While the Web app is pretty accessible out of the box, there are many areas of the interface that could use some improvement in terms of how they are read by and made interactible with screen readers.

What plans do the Freescout team have for improving the accessibility of this app for those who use screen readers and other assistive technologies?

I am a Web developer experienced in PHP and the Laravel framework (versions 7 and 8 though, not version 5) as well as Web accessibility standards like ARIA. I would be happy to help contribute to this effort, especially since I already know, based on my usage of Freescout as a blind individual, what elements should be made more accessible and how their accessibility can be improved, without sacrificing their functionality or visual appearance. If you would like me to assist in this endeavor please let me know how I can get started.

Thank you!

[freescout-helpdesk]

You can create a simple custom module (Improved Accessibility, for example) and we will add it to https://github.com/freescout-helpdesk/freescout/wiki/Community-Modules. When activated the module will adjust the CSS of the FreeScout. You can create a GitHub repo for the module, so that other can also contribute.

Here is the info on developing modules: https://github.com/freescout-helpdesk/freescout/wiki/Modules-Development

[neosonic2]

Thanks for your reply. However, the accessibility changes/improvements that are needed would require modifying the HTML of the core Freescout application, i.e. to add or improve ARIA roles and other attributes. Could this be done by creating a custom module as you suggest? I'm not going to be changing anything visually so I probably wouldn't be editing any CSS; I would mostly just be making HTML changes.

[freescout-helpdesk]

Yes. Just use Actions and Filters.

[neosonic2]

After some further investigation, it looks like a lot of the accessibility changes I need to make can be done to the HTML within the resources/views folder. For example, there are unlabeled buttons that change the conversation type from e-mail to phone and are located in resources/views/conversations/create.blade.php that could be edited. Once these changes are made, can I create a pull request here to merge my accessibility enhancements into the core project?

[freescout-helpdesk]

Yes.

[fulldecent]

@neosonic2 Could you please provide one example of a thing we can change. Let's start with that and then make a process to fix more

[neosonic2]

Certainly. One thing that, as of right now, is completely inaccessible in the Freescout user interface are the buttons for sending a reply, adding a note, and performing related actions while viewing a specific conversation. The buttons nearby, i.e. for setting the status of a conversation and assigning it to a different user, and even the dropdown menu that allows a conversation to be forwarded and etc., are accessible, but the aforementioned actions are not. Something else that could be made more accessible are certain buttons throughout the application that do not have ARIA labels on them that identifies them to screen reader users even when the button is just an icon (and thus contains no text). Examples of these are found in the HTML editor used when writing conversations, or in the buttons to switch a new conversation from an e-mail to a note, or even in the assignment, status, and other buttons mentioned previously when viewing a specific conversation.

…

On Jun 22, 2021, at 12:39 PM, William Entriken ***@***.***> wrote: @neosonic2 <https://github.com/neosonic2> Could you please provide one example of a thing we can change. Let's start with that and then make a process to fix more — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDDRGC24Q6WN6PM3XYLTUC4DTANCNFSM42WBJFHQ>.

[fulldecent]

@neosonic2 Awesome, thank you.

And are you able to run a copy of FreeScout using a specific git branch in order to evaluate if a PR fixes the problem?

[neosonic2]

Yes. I have a local development environment on my Mac that can be used to run specific branches of software as required. I also have experience in developing for accessibility, in making Websites and Web applications accessible, etc. As a visually impaired individual, accessibility was something I learned about from the start when learning to develop for the Web, so I am willing to assist in getting these issues fixed, and in testing potential fixes, wherever necessary. I am also willing to provide any additional information as required, and test using multiple screen reading programs on multiple operating systems (I currently have macOS and Windows available).

…

On Jun 22, 2021, at 5:48 PM, William Entriken ***@***.***> wrote: @neosonic2 <https://github.com/neosonic2> Awesome, thank you. And are you able to run a copy of FreeScout using a specific git branch in order to evaluate if a PR fixes the problem? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDBLG4B2LRTJINU6IATTUEALNANCNFSM42WBJFHQ>.

[fulldecent]

Here is a shot to fix just the action buttons.

#1285

The drop down is not as straightforward.

Does this fix the reply/note/delete buttons for you?

[neosonic2]

Thanks for putting this together. I haven’t had a chance to look at it yet but will do so later today and let you know if the buttons are fixed. Just wanted to acknowledge I saw your reply. Also off hand without looking at the code for the dropdown, adding the “aria-label” attribute to the dropdown element (the clickable element that opens the menu) should be enough to make those accessible, as the only issue with them is that they are simply missing labels.

…

On Jun 24, 2021, at 12:29 AM, William Entriken ***@***.***> wrote: Here is a shot to fix just the action buttons. #1285 <#1285> The drop down is not as straightforward. Does this fix the reply/note/delete buttons for you? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDD6ESKD5R4IPGCADN3TUKYA3ANCNFSM42WBJFHQ>.

[fulldecent]

Currently they do have a title, which I think DOES get picked up. So I just added the role. But only testing can be sure...

[neosonic2]

Just had a second to grab the pull request and test locally. Adding role=“button” to the three conversation action buttons did the trick - they are now completely accessible. It may be helpful to wrap them inside a “Conversation actions” region (i.e. an invisible div with a role of region and an aria-label attribute of “Conversation actions”) so that when navigating by landmarked regions on the page, the actions can easily be found. However, this isn’t as high priority really unless we also want to wrap other key parts of their page in their own landmarks for easier discovery by screen readers.

…

On Jun 24, 2021, at 2:16 PM, William Entriken ***@***.***> wrote: Currently they do have a title, which I think DOES get picked up. So I just added the role. But only testing can be sure... — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDDD7FBNXUYGZDUSE43TUNZBVANCNFSM42WBJFHQ>.

[fulldecent]

Nice!

Okay, I learned one part here. If you can help identify all other roles that need to be updated just like me know and I can help hunt them down. Let's do that as one pull request. Maybe that's enough to address this issue and should be the biggest help.

And then as you said, let's do regions separately. Since this may require new text, and localizations, and input from design. We can make new issues for other accessibility issues if needed.

[neosonic2]

Sure. I know you were originally going to work on the dropdown menus near the conversation action buttons, but you said those might be more difficult. Looking at the code, it seems these dropdown already have the button role on their parent span element (that is clicked to open the menu), but are missing an aria-label attribute. The containing element of the span seems to have a title attribute but this doesn’t work with accessibility as usually aria-labels are preferred.

…

On Jun 25, 2021, at 10:43 AM, William Entriken ***@***.***> wrote: Nice! Okay, I learned one part here. If you can help identify all other roles that need to be updated just like me know and I can help hunt them down. Let's do that as one pull request. Maybe that's enough to address this issue and should be the biggest help. And then as you said, let's do regions separately. Since this may require new text, and localizations, and input from design. We can make new issues for other accessibility issues if needed. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDAZNUK5IAFKSJVNCJLTUSIZJANCNFSM42WBJFHQ>.

[fulldecent]

Cool. Added more button roles at role="button". I think this should fix it.

In general, I have been using aria-label only when the reader text differs from the literal text in HTML (e.g. for icons and other visual explanation of intent).

[neosonic2]

That’s a good strategy, however some screen readers do not report e.g. things like title labels on elements and will only report aria-labels. For example, I am using VoiceOver on macOS. All of the dropdown next to the conversation action buttons, i.e. the one for assigning the conversation to someone else, are unlabeled. Adding aria-label attributes to these elements would provide context to screen reading programs that may already be available in other forms to sighted users.

…

On Jun 25, 2021, at 9:27 PM, William Entriken ***@***.***> wrote: Cool. Added more button roles at role="button". I think this should fix it. In general, I have been using aria-label only when the reader text differs from the literal text in HTML (e.g. for icons and other visual explanation of intent). — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDHRWK5EY5KCVQ5AIMDTUUUHFANCNFSM42WBJFHQ>.

[fulldecent]

Got it, cool. OK, so I have added aria-label everywhere that we have a role="button" and a title but do not have the essential text inside that element.

[neosonic2]

I just pulled down the latest changes to the pull request but when I load the app in my browser it doesn’t look like anything has changed…Can you give me an example of a button you specifically modified so I can see if for some reason I just still don’t have the latest changes or something? I suspect something just may not have synced on my end perhaps.

…

On Jun 25, 2021, at 9:51 PM, William Entriken ***@***.***> wrote: Got it, cool. OK, so I have added aria-label everywhere that we have a role="button" and a title but do not have the essential text inside that element. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDF7XIHMWAOSFP34JE3TUUXBDANCNFSM42WBJFHQ>.

[fulldecent]

Yes, one example is the Reply button. As of yesterday, my branch only added a role="button" but today it also includes the aria-label.

[neosonic2]

The Reply button is part of the three conversation action buttons right? That was one of the buttons that was initially completely inaccessible when we started all of this but then after your first batch of changes yesterday I noticed it was working for me. I think at first all you did was just add a button role but honestly I don’t remember and I’ve already pulled down the latest code so I can’t go back. Did you add aria-labels to the other controls outside of the action buttons?

…

On Jun 25, 2021, at 10:06 PM, William Entriken ***@***.***> wrote: Yes, one example is the Reply button. As of yesterday, my branch only added a role="button" but today it also includes the aria-label. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDFRNHU6VB3ECNZSMODTUUY2LANCNFSM42WBJFHQ>.

[fulldecent]

Yes. Let me give you a full accounting of the changes here:

• Reply — added aria-label
• Note — added aria-label
• Delete — added aria-label
• Delete forever — added aria-label
• Run workflow — added aria-label
• Follow
• Unfollow
• Print
• Merge
• Delete
• Delete forever
• Account (application page) — added aria-label
• Search (application page) — added aria-label

[neosonic2]

I can see the Reply, Add Note, and Delete buttons but I could yesterday as well after you Madde initial changes. Those buttons were not visible to VoiceOver at all, and no they show up as regular buttons on the page. The dropdown menus next to those though (i.e. for assigning the conversation or setting its status), while they appear, are not actually labeled so I always have to click on one to open its options in order to see what it does (or just remember which button does what based on where they are located).

…

On Jun 25, 2021, at 10:11 PM, William Entriken ***@***.***> wrote: Yes. Let me give you a full accounting of the changes here: Reply Note Delete Delete forever Run workflow — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDGK3JIPSOZSFZ4I5DLTUUZNVANCNFSM42WBJFHQ>.

[fulldecent]

I took a stab at labeling the dropdowns.

[neosonic2]

Oh OK awesome, now I see the “Status” dropdown is labeled now. If that’s the only one you did (since the other ones don’t have labels) then I think what you did works perfectly so you can duplicate it on the others if you’d like. I’d help contribute here but I don’t know how to add code to the pull request you are working on (I am not extremely familiar with Git and only know the basics).

…

On Jun 25, 2021, at 10:49 PM, William Entriken ***@***.***> wrote: I took a stab at labeling the dropdowns. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDEGKAEVXTHTGMGNWRTTUU54BANCNFSM42WBJFHQ>.

[neosonic2]

On a related note while we are talking about labeling things, I am looking at an individual conversation and I see there is an unlabeled link between the last folder in the list of folders and the “New Conversation” link. Even though it’s a link, I am guessing it should probably be re-classified as a menu button as it appears to drop down a menu when clicked, that has options like Edit Mailbox, Connection Settings, Permissions, etc. Also I just saw your labeling of the “Account” and “Search” menus in the application’s layout blade, they are perfect now, thank you.

…

On Jun 25, 2021, at 10:49 PM, William Entriken ***@***.***> wrote: I took a stab at labeling the dropdowns. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDEGKAEVXTHTGMGNWRTTUU54BANCNFSM42WBJFHQ>.

[fulldecent]

Cool. Thank you for showing me how to set these up.

Hopefully somebody else can help with menus and reclassification.

At this moment PR #1285 might be good to merge as an incremental improvement.

[neosonic2]

Can you try to add the button role to the unlabeled link I’m talking about, and maybe an aria-label as well so that the link/button becomes labeled? Honestly that’s all that needs to be done to make that item accessible. If not though that’s OK, you’ve already done a lot thus far as you said and this PR looks great and will provide some much-needed accessibility enhancements to the application.

…

On Jun 26, 2021, at 2:09 AM, William Entriken ***@***.***> wrote: Cool. Thank you for showing me how to set these up. Hopefully somebody else can help with menus and reclassification. At this moment PR #1285 <#1285> might be good to merge as an incremental improvement. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDHEXNMZC7X4YRHVA33TUVVJVANCNFSM42WBJFHQ>.

[freescout-helpdesk]

Where in the source code is the modal dialog code located? This will save me from having to hunt around for it as I haven’t messed with this part of Freescout yet.

https://github.com/freescout-helpdesk/freescout/blob/dist/public/js/main.js#L389

[philippkraft]

Just changing lines 2115 and 2119 did the trick, as my blind collegue confirmed. I will add a PR later or tomorrow afternoon (Europe time).

[neosonic2]

What did you change about those two lines of code?

…

On Dec 8, 2021, at 6:46 AM, Philipp Kraft ***@***.***> wrote: Just changing lines 2115 and 2119 did the trick, as my blind collegue confirmed. I will add a PR later or tomorrow afternoon (Europe time). — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDDGJIDVAAY572JBWQ3UP5AP7ANCNFSM42WBJFHQ>. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[philippkraft]

See PR #1577, however I need to create a new one targetting the master branch.

[neosonic2]

The link to the PR you included actually links to an issue about sending e-mail (1557). Did you mean to link to something else?

…

On Dec 8, 2021, at 9:56 AM, Philipp Kraft ***@***.***> wrote: See PR #1557 <#1557>, however I need to create a new one targetting the master branch. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDG4R6PWTAKSHR6DOFDUP5WZFANCNFSM42WBJFHQ>. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[philippkraft]

It is #1577. Sorry for the typo.

[neosonic2]

I want to test your changes with VoiceOver on macOS and NVDA on Windows (via my virtual machine) before your pull request is merged into master. When you get that created can you link to it so I can grab it and test your work with these other screen readers? I know you tested already with JAWS for Windows and that’s awesome, I just want to make sure we have complete screen reader coverage across supported platforms.

…

On Dec 8, 2021, at 2:06 PM, Philipp Kraft ***@***.***> wrote: It is #1577 <#1577>. Sorry for the typo. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDFDUJP5ENOHX3WYDSDUP6UCTANCNFSM42WBJFHQ>. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[philippkraft]

Now I have created #1578 targeting master. @neosonic2, let me no how it is working, so I can mark the PR for review.

[neosonic2]

OK. I will add my notes after testing to the PR rather than to this discussion so that the PR can be modified as necessary. I should be able to get to this later this evening (Eastern time). Hopefully everything will just work right out of the box as it now does for you with JAWS.

…

On Dec 8, 2021, at 2:46 PM, Philipp Kraft ***@***.***> wrote: Now I have created #1578 <#1578> targeting master. @neosonic2 <https://github.com/neosonic2>, let me no how it is working, so I can mark the PR for review. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDA3AY6IZC2GVXE7LP3UP6YZ3ANCNFSM42WBJFHQ>. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[philippkraft]

@xogium, if you are still interested in this issue, it would be great if you can check PR #1578 with orca on linux.

[philippkraft]

Our blind colleague is using FreeScout now operationally and handled over 300 tickets. She has only problems at 2 places left:

1. The style buttons of the summernote editor are not correctly labelled. This is solved in summernote 0.8.10, FreeScout uses 0.8.9. Version 0.8.12 improves on issue Paste and Copy of formatted text can cause strange behaviour #1672

2. Input boxes, where each keystroke submits a search (kind of combobox), eg. the "To" field while forwarding, do not read the listed options. I guess this one is tough or not resolvable, as even google struggles with this in her screen reader in the google.com landing page.

[neosonic2]

That’s great that your blind colleague has been using Freescout successfully in her support environment. I appreciate the work everyone has done and continues to do to make this product more accessible. I too have experienced both of the concerns you raise, though have been able to successfully work around the second one (regarding some input boxes). Using VoiceOver on macOS, when I select to start a new ticket and have to enter text into the “To” field, for example, I will perform the keystroke that simulates a mouse click. This usually puts VoiceOver inside the actual input field so I can start typing the name or e-mail address of the person I am looking for. Arrowing over to the right gives me a table of results of the search, and if I click on the item in that table it will populate the original field for me automatically. However, I’m not sure how this approach could be translated for use in other screen readers, or if it would even work for them. It is also not the easiest process to describe and could perhaps be improved. What screen reader and operating system is your colleague using? I have built accessible input fields for Web apps in the past that perform automatic searches as you type, using some jQuery and JavaScript code I integrated into my applications. This enabled me to use regular input fields of type “text” that any screen reader can understand, but also present a dropdown list of search results that can be navigated easily by screen reader users with the arrow keys, the Enter key, and the Escape key. I haven’t looked into exactly how these inputs are handled in Freescout though.

…

On Feb 10, 2022, at 6:30 AM, Philipp Kraft ***@***.***> wrote: Our blind colleague is using FreeScout now operationally and handled over 300 tickets. She has only problems at 2 places left: The style buttons of the summernote editor are not correctly labelled. This is solved in summernote 0.8.10, FreeScout uses 0.8.9. Version 0.8.12 improves on issue #1672 <#1672> Input boxes, where each keystroke submits a search (kind of combobox), eg. the "To" field while forwarding, do not read the listed options. I guess this one is tough or not resolvable, as even google struggles with this in her screen reader in the google.com landing page. — Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDEIHTD5RGBTILD6NYLU2OOWLANCNFSM42WBJFHQ>. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you were mentioned.

[freescout-helpdesk]

2. Input boxes, where each keystroke submits a search (kind of combobox), eg. the "To" field while forwarding, do not read the listed options. I guess this one is tough or not resolvable, as even google struggles with this in her screen reader in the google.com landing page.

Will it help if aria-label will be added to each listed option?

[freescout-helpdesk]

Implemented in master:

• Add aria-labels to summernote buttons 9884a76
• Add aria-labels to select2 options a9d4343

[philippkraft]

Sorry, I had no time to test this with my colleague earlier. The summernote buttons do definitely work for here now.

[fulldecent]

Recommending to close issue. We have made good progress here!

Can reopen when we identify a set of new things to fix or some automated tool can fully review the entire product.

[neosonic2]

Agreed.

…

On Oct 12, 2022, at 11:17 AM, William Entriken ***@***.***> wrote: Recommending to close issue. We have made good progress here! Can reopen when we identify a set of new things to fix or some automated tool can fully review the entire product. — Reply to this email directly, view it on GitHub <#1150 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDHPKNPI5FJXYGWJ3H3WC3JBXANCNFSM42WBJFHQ>. You are receiving this because you were mentioned.

[philippkraft]

Even if I am late to the party, I like to thank you for the fast adaptation of our issues - my blind and non-tech colleague is working all day with freescout now and it just works! Wish her other tools would adopt as fast as freescout. If someone else is creating issues concerning accessibility for blind people, do not hesitate to ping me for testing it with her.

[freescout-helpdesk]

#3829 (comment)

[freescout-help]

FYI: #4412