AO3-7131 Text used by screen readers to announce help links is unclear

[richard-hajek]

Pull Request Checklist

• Have you read "How to write the perfect pull request"?
• Have you read the contributing guidelines?
• Have you added tests for any changed functionality?
• Have you added the Jira issue number
  as the first thing in your pull request title (e.g. AO3-1234 Fix thing)
• Do you have fewer than 5 pull requests already open? If not, please wait
  until they are reviewed and merged before creating new pull requests.

Issue

https://otwarchive.atlassian.net/browse/AO3-7131

Purpose

This PR addresses AO3-7131, bad accessibility of help modals.

I have some concerns:

• This PR does the "bare minimum" fix as described in the AO3-7131
• BUT a better solution would require a major undertaking of restructuring the help modals
• AND there's a fresh comment in the source code, from Dec 2025, indicating that the entire function will be replaced anyway for help pages, so a bare minimum fix might work

# TODO: AO3-7208 Make help modals dynamic and translatable and use link_to_help_modal instead of this method 

Testing Instructions

Described in AO3-7131, I tested using KDE built in screen reader and Firefox.

Credit

Richard Hajek, he/him, assigned in Jira

[slavalamp]

According to the ticket, the links should only have the aria-label attribute, not both title and aria-label. The title attribute is not very accessible, since it can't be seen on mobile devices and screen reader behavior is inconsistent with it

The new method link_to_help_modal already exists, it's right after link_to_help in the same file, so the attribute should be replaced there too.

(from the ticket)

It will take a while to come up with a good naming system for the links, but we can make the underlying changes and add new link text in one location as a test/proof of concept.

The Tag Search page, referenced in “Steps to reproduce”/”What happens,” has one help link for the “Tag name” field that can be used for this purpose. We can change the link name from “Tag search text help” to “Tag name search help.”

Now that the "locale preferences" help modal is prepared for localization and using the new method, it might be a good idea to do it with that one instead, with a new link name like "Locale preferences help"

Also, you should fix style issues that Rubocop finds - use double quotes and add the space where it's missing after a colon in this case. There's a bit of info on Rubocop in the wiki (Reviewdog and RuboCop, Previewing Reviewdog comments) and you can look up info on specific guidelines using their names if you need examples - e.g. Style/StringLiterals

[richard-hajek]

Thanks for the review! I'll get on it

[richard-hajek]

I think I did everything as you requested.

Did the force push because I rebased recent changes from master.

I have some concerns:

• The file ao3modal.js, which implements the modal feature, is still working a lot with the "title" property. I don't think it touches anything that I changed but I don't fully understand it
• I renamed the locale_help_title to locale_help_label, since well, it is not a title anymore, but the renaming might have been above my paygrade. I checked and noone else is using it though

[richard-hajek]

Please hold on on further review, the think the rebase went wrong, I can't even start it right now.

Could not find aws-sdk-s3-1.208.0, connection_pool-2.5.5, shoulda-matchers-7.0.1, minitest-5.27.0, aws-sdk-core-3.240.0, aws-sdk-kms-1.118.0, aws-sigv4-1.12.1, aws-eventstream-1.4.0, aws-partitions-1.1196.0 in locally installed gems

I think it may be related to #5513 ? I can't even start a fresh master now

[slavalamp]

Seems like your development environment isn't up to date. Are you using Docker? There's a guide for updating it in the wiki

[richard-hajek]

Oh yep! I'm trying to rebuild the images now and it looks promising

[slavalamp]

changed the dynamic modal instead

Both need to be changed - most help modals still use link_to_help. Ideally link_to_help and link_to_help_modal would behave the same

Also I don't think renaming the _title to _label is needed, technically it's still a title, it's just not in the title attribute anymore

[richard-hajek]

I apologize for the persistent misunderstandings, does this look good? This ended up much smaller patch than I expected

[richard-hajek]

By checking my other PR, I found out that the tests failings isnt normal, I'll fix it tomorrow

[slavalamp]

Ah, the tests are failing because the title attribute got removed, sorry for not noticing that earlier...

I've looked more into accessibility for buttons like these to see if there are better solutions and it seems it's usually recommended to use invisible text rather than aria-label, but that would also require a lot of changes to the buttons' structure and styles.

An simpler option would be just modifying the tests to work for buttons that are only aria-labeled and I see that there is actually an option for that (Capybara.enable_aria_label = true), but I'm not sure what a good way to use it would be.

@sarken what do you think?

---

Regardless of these test failures, the ao3modal.js file also needs to be updated - right now it gets the modals' bottom titles from the title attribute so they're missing (it's referenced once on line 200)

[sarken]

I think I'd be inclined to define a new step for the help links in particular instead of updating our configuration to use Capybara.enable_aria_label = true. (We might want to at some point, but it's probably better to look into it as a separate issue in case we get a fun cascade of test failures to sort out.) It looks like it would be possible to use that in the step definition, but if not, Xpath might also work.

[richard-hajek]

Alright, how about now? Only concern of my right now is that

show($(this).attr('href'), $(this).attr('title') ? $(this).attr('title') : $(this).attr('aria-label'));

may redundantly check for both title and aria-label but I wanted to keep backwards compatibility with title, as I'm sure there are other parts of the site that still use title

[slavalamp]

I wanted to keep backwards compatibility with title, as I'm sure there are other parts of the site that still use title

There are a couple other modals that do, yeah, so that part is good

[slavalamp]

I think it'd be nicer to call this step "I open help modal", it probably wouldn't ever need the "within selector" part, and as sarken said, you can use the capybara option in the step definition, so it could look like this

When /^(?:|I )open help modal "([^"]*)"$/ do |link|
  Capybara.enable_aria_label = true
  step %{I follow "#{link}"}
end

and it doesn't really belong in web_steps.rb, you can make a new file help_steps.rb for this