Epic: UI Modernization — consistency, mobile, accessibility #13240

Summary

Make Open Library look and feel maintained, trustworthy, and usable everywhere — one design language across the site, accessible and mobile-solid, measured through Core Vitals.

Two things follow from that, and they run through every workstream below: content gets the screen, chrome gets out of the way. Headers, toolbars, filter rows, and droppers should take as few vertical pixels as they can and recede visually — consistent heights, one hover treatment, quiet colors — so the eye lands on books, not on the frame around them. Today chrome takes 62% of the viewport on mobile search results (#13482), and each surface invents its own control heights and hover states.

Inconsistent typography and dated UI signals "unmaintained." A patron who lands on a page with four heading styles, three button treatments, and a layout that breaks at 375px doesn't file a bug — they leave, and they don't trust us with their reading data. This work is the substrate every other H2 patron-facing initiative ships on: Prompts (#12858), the Genre Explorer (#13158), and carousel/browsing work (#9828, #10512) all need a component vocabulary and an accessibility baseline to build against. Doing it once here is cheaper than each of those inventing its own buttons, dialogs, and focus handling.

This epic supersedes #11555 (two-tiered design tokens) and absorbs its remaining checklist — see Foundation below.

Success criteria

• Core Vitals (CLS/LCP/INP) tracked and non-regressing on the four highest-traffic templates: home, search, book, subject
• No new raw hex colors, magic-number font sizes, or ad-hoc z-index values merged (enforced by stylelint, not by review vigilance)
• Zero critical/serious axe violations on those same four templates
• Every ol-* component has a docs page and a stated mobile + keyboard contract

In flight

Open PRs already doing this work:

• Add unified icon system #12955 — Unified icon system: <ol-icon>, $:macros.icon() macro, build-time sprite (Foundation → components + docs). Replaces the PNG/one-off-SVG icon patchwork with 42 glyphs on one 24×24 grid, served as a single hashed sprite (1.9 KB gzipped); adopted across 49 call sites, with a searchable gallery at /developers/design/icons and 50 legacy image files deleted. Still in draft.
• Rebuild ol-carousel on native scroll snapping #13220 — Rebuild ol-carousel on native scroll snapping (Mobile pass, + a11y). Replaces hand-rolled gesture/spring physics with platform scroll snapping: OS-native momentum and overscroll, mouse wheel works, off-page items no longer inert so they're reachable by tab, find-in-page, and screen readers. Net −132 lines in OlCarousel.js, plus a new unit-test suite. Supersedes ol-carousel touch gestures and swipe physic refinements #13101. Currently conflicts with master — the docs page it patches moved to templates/design/components/carousel.html.jinja.
• Unify the site's colors on one warm palette and remove the old color names #13338 — Unify the site's colors on one warm palette and remove the old color names (Foundation → tokens). The tail of Color tokens: warm neutral ramps, semantic layer, deprecated aliases #13102, in two halves: bring the accent colors, card/table lines, shadows, chips, and chart hues into the same warm family as the greys, then move the remaining ~370 call sites onto purpose-based names and delete the 16 legacy aliases that no longer have users. Absorbs the former Finish the deprecated color-alias migration #13284, which was closed and folded in so both halves ship as one reviewable change to the same files.
• Type scale (rem) + serif heading hierarchy + living token spec #13104 / feat: add font-size and font-weight design tokens #12772 — Two competing takes on font-size and font-weight tokens. These need reconciling before either lands; the type scale is the largest remaining token gap.
• Unify header nav #13508 — Unify the header nav into matching ghost buttons with sprite icons (Foundation → surfaces). One --header-control-height for the search field, Browse, My Books, and the account button; one ghost-button hover treatment across all three nav controls; every header glyph moved onto the Lucide sprite (including the archive.org avatar photo, dropping a third-party image request per logged-in page load). Nets 16px of vertical chrome back to content on every page (the row height itself is bound by the 47px logo, not the controls).
• feat(a11y): wire @axe-core/playwright into the e2e suite #13251 — Wire @axe-core/playwright into the e2e suite (A11y, implements A11y Phase 2: Playwright + axe-core integration for page-level WCAG testing #13007).
• feat(vitals): Core Vitals Retention Score, with an on-demand trigger #13213 — Core Vitals Retention Score with an on-demand trigger (Measurement), building on the read-only Matomo client in feat(core): read-only Matomo client + offline mock (groundwork for #11956) #13252.
• Add OlDrawer component for hamburger menu #12326 — ol-drawer for the hamburger menu (Foundation → components). Rebuilt on native <dialog>.showModal(), so the drawer gets the top layer, background inerting and Escape from the platform — the stacking-context problem solved without a z-index. Also surfaces Sign Up in the header below 480px, where the auth links were hidden entirely.

Recently landed: #13228 (search results toolbar onto web components, adding <ol-menu-popover> and the Details/Grid segmented control), #13238 (ol-pagination size variants), #13102 (color tokens), #13247 (z-index tokens), #13006 (jest-axe CI gate).

---

Workstream 1 — Foundation

Design tokens, the ol-* web component family, and living docs. This is the part everything else depends on.

Tokens (absorbed from #11555)

Two-tier structure — primitives (a small curated set of raw values) → semantic tokens (design intent, e.g. --radius-card, --color-surface-raised). Semantic tokens are what templates and components reference, so a category-wide change is a one-line edit. Tokens live in static/css/tokens/, aggregated by static/css/tokens.css.

Create tokens for…

• colors — Color tokens: warm neutral ramps, semantic layer, deprecated aliases #13102
• font families — refactor: Define semantic font family LESS vars #11540
• font sizes and weights — Type scale (rem) + serif heading hierarchy + living token spec #13104 / feat: add font-size and font-weight design tokens #12772 (reconcile)
• line heights — refactor: Define Line Height LESS vars #11619
• border radius — refactor: Define semantic border radius LESS vars #11557
• spacing — refactor: Define primitive and semantic spacing variables #12116
• borders — refactor: Define primitive and semantic border LESS variables #11602
• z-index — Systematize z-index usage across the site #12363
• breakpoints
• control heights
• icon sizes — in Add unified icon system #12955

Apply tokens across existing CSS…

• font families — refactor: Utilize semantic font family LESS vars #11556
• line heights — refactor: Utilize semantic line-height LESS vars  #11669
• border radius — refactor: Utilize new border radius LESS vars #11596
• spacing
• z-index — refactor: replace raw z-index values with semantic tokens #13247 (zero raw z-index: values remain in static/css or in the Lit components; stylelint now enforces it)
• colors — all but 4 raw hex values are gone from static/css; what's left is the deprecated aliases (in flight as Unify the site's colors on one warm palette and remove the old color names #13338) and 42 raw hexes inside Lit shadow DOM (see components, below)
• font sizes and weights — 280 literal font-size values vs. 194 tokenized
• borders — 199 literal border widths vs. 41 tokenized

Remaining foundation work:

• Self-hosted web fonts (variable, latin subset) — Literata + Schibsted Grotesk. Needs a fresh PR; Web fonts: self-hosted Literata + Inter (variable, latin subset) #13103 (Literata + Inter) was closed unmerged before the typeface decision settled.
• Foundation surfaces: canvas, header chrome, semantic buttons/forms — Foundation surfaces: paper canvas, flat header chrome, semantic buttons/forms #13105 (closed, needs re-landing on current tokens)
• Make font size consistent throughout the site — Make font size consistent throughout the site #8692
• Standardize subject tags UX using BEM — Standardize Subject Tags UX using BEM CSS #11728

ol-* web components

20 Lit components exist today in openlibrary/components/lit/ — ol-button, ol-dialog, ol-popover, ol-select-popover, ol-options-popover, ol-menu-popover, ol-segmented-control, ol-toggle, ol-chip/ol-chip-group, ol-toast/ol-toast-region, ol-banner, ol-tooltip, ol-carousel, ol-pagination, ol-scorecard, ol-read-more, ol-markdown-editor, and others. The family is real; what's missing is consistency guarantees across it.

• Shadow-boundary contract documented and honored across all components — focus/tabbing, CSS custom-property surface, form association, ARIA. Several components already implement pieces of this (form-associated mixin, non-modal popover); it isn't yet uniform or written down.
• Lint the Lit css template literals. lint:css globs only static/**/*.css and openlibrary/**/*.css, so styles authored inside .js are unlinted — which is why 42 raw hexes survive in shadow DOM. Until this exists, "no new raw hex" is unenforceable there. Drafted in Stylelint coverage for Lit + Vue; retire raw hex from web components #13110 (closed).
• Every component consumes semantic tokens only — no raw hex inside shadow DOM
• Add font-size to stylelint's declaration-strict-value list once a type scale lands — currently the only success criterion with no enforcement path
• Retire slick, the last jQuery widget duplicating an ol-* component (js/carousel/Carousel.js, static/css/lib/slick*.css) — blocked on Rebuild ol-carousel on native scroll snapping #13220
• Migrate any other legacy jQuery widgets that duplicate an existing ol-* component

Living docs

The design system docs live at /developers/design, assembled by openlibrary/plugins/openlibrary/design.py from 19 component pages under openlibrary/templates/design/components/, with tokens parsed straight out of the token CSS.

• A docs page for every shipped component (only ol-icon's page is outstanding, in Add unified icon system #12955)
• Token reference page — primitives and semantics, browsable
• Each page states the mobile behavior and keyboard contract, not only the prop table — today 4 of 19 pages mention keyboard behavior and 2 mention mobile

---

Workstream 2 — A11y audit

A systematic WCAG 2.1 AA sweep, building on fixes already shipped rather than starting cold. Recently landed: search-modal dialog naming + arrow-key result nav + live region (52da434), ReadButton dropdown summary name (#13116), generic-dropper arrow button label (#13029), OlSelectPopover role=group (#13037), iframe titles (#13012), decorative star ratings hidden (#13028), several contrast fixes (#13030, #13027), and the interactive-element audits for the book page (#4906) and Want To Read (#4911).

• Systematic page-by-page WCAG 2.1 AA audit — start with home, search, book, subject, My Books
• Automated a11y CI gate using jest-axe — Add automated a11y CI gate using jest-axe (WCAG 2.1 AA) #13005, shipped in feat(a11y): add jest-axe CI gate for Lit component ARIA patterns #13006
• Playwright + axe-core for page-level testing — A11y Phase 2: Playwright + axe-core integration for page-level WCAG testing #13007, in flight as feat(a11y): wire @axe-core/playwright into the e2e suite #13251
• Contrast sweep against the new color tokens — Background and foreground colors do not have a sufficient contrast ratio. #9633
• Accessible names for ARIA input fields — ARIA input fields do not have accessible names #9631; discernible link names — Links do not have a discernible name #9630
• Visible, consistent keyboard focus indicator — Providing more clear visual indicator for keyboard navigation #7857
• Skip links to bypass navigation blocks — Add Skip Links to Bypass Blocks of Navigation #5012
• Book page accessibility score — Improve Accessibility Score of Book Pages #9618
• Explicit lang on non-English passages — Passages of Text Must Have Their Language Explicitly Declared #5015

The CI gate matters more than any individual fix: without it, this list regenerates itself every 18 months. jest-axe covers component ARIA patterns; #13251 extends that to whole pages.

---

Workstream 3 — Mobile pass

Touch behavior, keyboard handling, and layout at small sizes. Extends the shipped search-modal mobile work (full-height modal, equal-height filter row, text-entry auto-zoom rules) and carousel touch gestures (#13101).

• Small-screen layout audit across primary templates — no horizontal overflow, no clipped controls
• Mobile search results density — chrome takes 62% of the viewport, 0 fully readable results above the fold — Mobile search results: 0 readable results above the fold — page chrome takes 62% of the viewport #13482
• Touch target sizing meets 44×44 minimum on interactive controls
• All text-entry controls sized to prevent iOS auto-zoom (rule documented in docs/ai/design.md; needs enforcement)
• Virtual keyboard handling — inputs stay visible when the keyboard opens; dialogs don't fight it
• Touch/pointer parity for components that assume hover (tooltip, popover, dropper)
• Excessive top spacing / alignment on mobile My Books — Excessive top spacing and inconsistent left alignment on mobile view (My Books page) #12095
• Reserve cover image space to prevent CLS in list-view results — Reserve cover image space to prevent CLS in list view search results #12825

---

Measurement

Core Vitals are the outside check on whether this is working, since "looks maintained" isn't measurable on its own:

• CLS — reserved image space, no late-loading font swaps
• LCP — self-hosted subset fonts, no render-blocking token cascade
• INP — component interaction cost, especially carousels and poppers

Nothing measures these today — there's no vitals instrumentation in the repo yet. #13252 (read-only Matomo client) and #13213 (Core Vitals Retention Score) are the proposed reporting path. This ties into item 2 (Metrics/Core Vitals) of #13194.

---

Related

• Epic: Subject page redesign — a guided "genre dashboard" #13135 — Epic: Subject page redesign (consumed this foundation; now closed)
• Author Page UX Improvements #12129 — Author Page UX Improvements
• feat(community): Weekly Prompt homepage widget — staff-curated book discovery #12858 — Weekly Prompt homepage widget
• Genre Explorer: genre/subgenre bookshelf browsing backed by Tag hierarchy #13158 — Genre Explorer
• 2026 H2 Planning: Engineering Initiatives Recap #13194 — 2026 H2 Planning: Engineering Initiatives Recap

Stakeholders

@lokesh @cdrini @mekarpeles @jimchamp @RayBB

---

Instructions for Contributors

• Before creating a new branch or pushing up changes to a PR, please first run these commands to ensure your repository is up to date, as the pre-commit bot may add commits to your PRs upstream.