Standardize Subject Tags UX using BEM CSS

[mekarpeles]

Description, Patron Story

Currently, subject, person, place, and time tags on Open Library are rendered as plain links which are difficult to scan, are visually inconsistent, and do not serve as clear canonical tags/labels. This makes it harder for readers to visually parse important metadata at a glance and introduces visual inconsistency with other UI components. We'd like to:

• Render these consistently as "tag/label" elements, not just clickable text links.
• Apply a canonical BEM CSS class (per our frontend guide) so these visual tags are uniform and easy to style/modify in the future.
• Ensure the style is accessible, readable, and works well in lists and multi-line layouts (see attached images for example "before/after").
• Apply this approach sitewide—targeting books, people, authors, places, and subjects—wherever tags appear.

Why is this design change necessary?

• Consistency and readability for our subject/entity tags
• Improved scannability and navigation
• Reduces the "link salad" effect; helps patrons better distinguish between metadata and body content
• Enables future extension (e.g., colored/taxonomically meaningful tags, accessibility improvments, dark mode, mobile)

Who is it for?

• Patrons and contributors, especially those browsing or editing works, authors, and collections
• Front-end team and contributors maintaining Open Library's UX

Constraints/Considerations

• BEM CSS (class like .ol-tag, .ol-tag--subject)
• Must follow Open Library's frontend guide
• Should ensure ARIA/accessibility is not regressed
• Consistency across templates: some tags generated via macros (SubjectTags.html), others inline in templates

Relevant Designs

Implementation/Reference Research

Below is a technical overview for initial scoping and onboarding (include for future contributors):

Key files affecting subject/person/place tag UI

• openlibrary/macros/SubjectTags.html: Macro for most book page subject/person/place tags
• openlibrary/macros/RelatedSubjects.html: Related sidebar tags
• openlibrary/templates/subjects.html, openlibrary/templates/search/subjects.html: Main subject+search result layouts
• openlibrary/templates/type/author/view.html: Author page tags

CSS locations

• static/css/components/tagging-menu.less: Tag/label core styles for tags
• static/css/legacy.less, static/css/page-subject.less: Current link/list styling, needs harmonization

Guidance for new contributors

• See frontend guide for BEM usage and conventions

Feedback Questions

• Are these tag styles clear (accessibility) and readable everywhere they appear?
• Accessibility: Any color/contrast issues or other a11y concerns?
• Any opportunity to DRY or centralize logic for which templates/macros output subject/person/place/times tags?
• Are there outstanding use cases missed?

Stakeholders

@mekarpeles, @cdrini, @jimchamp, @RayBB, @hayoonc, @beccat123, @rebecca-shoptaw, @sbwhitt

---

References:

• Frontend Guide: https://github.com/internetarchive/openlibrary/wiki/frontend-Guide
• Tag styling: static/css/components/tagging-menu.less
• Macros: openlibrary/macros/SubjectTags.html, openlibrary/macros/RelatedSubjects.html

[evelynpham04]

Hi @mekarpeles, I understand the scope of this issue and have started working on it. I’d like to work on this issue. Could you please assign it to me?

[RayBB]

@evelynpham04 this issue is already assigned to lokesh so he's taking the lead here.
@lokesh if you think there's a sub issue ready for contributors please let us know