internetarchive / internetarchive/openlibrary
Standardize Subject Tags UX using BEM CSS
- Dominant language
- Python
- Stars
- 6.7k
- Forks
- 2k
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 138
Description
## 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](https://github.com/internetarchive/openlibrary/wiki/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](https://github.com/internetarchive/openlibrary/wiki/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](https://github.com/internetarchive/openlibrary/wiki/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`
Contributor guide
Assessment
This issue has not been assessed yet.