internetarchive / internetarchive/openlibrary

Standardize Subject Tags UX using BEM CSS

Open
#11,728 3 comments 1 reaction 1 assignee Claimed by @evelynpham04 View on GitHub
Affects: UI Lead: @lokesh Needs: Design Feedback Needs: Designs Priority: 3 Team: Front-end Theme: Book Tags Theme: CSS Theme: Design Type: Design Proposal
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

Tag links vs. label tags: current vs. canonical BEM styling

UI goal: pill-shaped easy-to-read tags for subjects, people, and places

## 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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.