Skip to content

Add descriptive alt text to Hyrax thumbnail render paths and overrides#1201

Merged
haitzlm merged 7 commits intodevelopfrom
update-hyrax-index-file-for-alt-text-on-thumbnails
Apr 10, 2026
Merged

Add descriptive alt text to Hyrax thumbnail render paths and overrides#1201
haitzlm merged 7 commits intodevelopfrom
update-hyrax-index-file-for-alt-text-on-thumbnails

Conversation

@Janell-Huyck
Copy link
Copy Markdown
Contributor

@Janell-Huyck Janell-Huyck commented Apr 9, 2026

Summary

This PR improves thumbnail accessibility by ensuring thumbnail images have meaningful alt text across Hyrax/Blacklight render paths, including fallback and featured collection thumbnails.

Why

Some thumbnail images were rendered with weak/missing descriptions (or marked as presentational), which reduced the usefulness of those images for screen reader users.

What Changed

  • Added a shared alt-text helper in ApplicationHelper:
    • thumbnail_alt_text_for(record)
    • Builds alt text from record type + label when available.
    • Falls back safely when data is incomplete.
    • Treats null-like labels (for example "null") as missing to avoid output like Collection thumbnail: null.
  • Ensured default Blacklight thumbnail rendering gets alt text when none is explicitly provided via CatalogHelper#render_thumbnail_tag.
  • Added/overrode Hyrax/Blacklight thumbnail partials to pass descriptive alt text where thumbnails are rendered with image_tag.
  • Updated featured collections homepage rendering to use helper-generated alt text and removed presentational treatment.
  • Updated featured collection feature spec to assert helper-derived alt text (resilient to text wording changes).

Accessibility Impact

  • Thumbnail images now expose meaningful alt text in key UI surfaces.
  • Prevents null placeholder labels from leaking into assistive text.
  • Removes presentational treatment where thumbnails carry content meaning.

Risk / Notes

  • This PR includes local Hyrax/Blacklight view overrides; future gem upgrades should re-validate override compatibility.
  • No DB/schema changes.
  • No API contract changes.

Rollback

Revert this PR to restore prior thumbnail alt text behavior.


Affects thumbnails on the index pages only:
Screenshot 2026-04-10 at 11 22 49 AM
Screenshot 2026-04-10 at 11 23 09 AM

Uses the alt text "Collection Thumbnail: {name of collection}" or "Work Thumbnail: {name of work}" on index pages only.
Screenshot 2026-04-10 at 11 27 25 AM

Does include index page of works inside a collection:
Screenshot 2026-04-10 at 11 53 44 AM

Does not affect images inside individual collections:
Screenshot 2026-04-10 at 11 23 35 AM

Treat null-like labels as missing to avoid rendering "thumbnail: null", and add helper/view/feature specs to verify thumbnail alt text stays present and resilient across key render paths.

Made-with: Cursor
@Janell-Huyck Janell-Huyck changed the title WIP Add descriptive alt text to Hyrax thumbnail render paths and overrides Add descriptive alt text to Hyrax thumbnail render paths and overrides Apr 10, 2026
Copy link
Copy Markdown
Contributor

@haitzlm haitzlm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks like an excellent update, replacing missing or unhelpful alt text with meaningful, which increases compatibility with new accessibility guidelines

@haitzlm haitzlm merged commit ede5cda into develop Apr 10, 2026
4 checks passed
@Janell-Huyck Janell-Huyck deleted the update-hyrax-index-file-for-alt-text-on-thumbnails branch April 10, 2026 18:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants