Foundations

Greys.

Low numbers are backgrounds and borders, high numbers are text. All of them lean slightly yellow rather than pure grey — that warmth is what makes the page read as paper instead of as a white screen.

Ink for anything see-through — hover shading, drop shadows.

Looks too brown to use as a solid fill, deliberately: transparency washes most of the color out, and --neutral-900 faded comes back the cold grey we're avoiding.

Page canvas.

Warmer than any grey above, which spread across a whole page read a little cold. Only --color-background should use it.

Blue — the one accent: links, primary buttons, focus rings.

Leans slightly purple rather than sky, so it doesn't go cold next to the warm greys.

Red, green, amber — error, success, warning.

50 is a message background, 200 its border, 400 the bright alarm step for tiny attention dots, 500 a solid object (filled icon, destructive button), and 600/700 the text; only those last two are dark enough to read on white.

Brick red rather than fire-engine, so errors read serious, not alarming — 400 is the one deliberate exception, because an 8px dot has to shout.

Olive rather than mint, so success states sit with the warm greys.

Amber — warning states, plus the gold on star ratings.

Pink — data-chart bars only.

400 clears 3:1 on white as a non-text shape 600 is the selected bar, a clear step darker.

Bars in the /stats daily charts.

Text

The dark fill that --color-text-inverse sits on — tooltips, dark chips.

Decorative tier: 2.5:1 on white, under WCAG 1.4.11's 3:1.

Inert chrome only — a chevron beside a label, a placeholder glyph. An icon that carries meaning on its own needs --color-text-muted or darker.

Surfaces

A step lighter than -header: recessed panels and image wells should read as a shade off the surface around them, not as a filled block.

Links

Environment badge & favicon — match the static/images/openlibrary-{development,testing}-*.png favicons.

Primary action

Edge of a raised primary control: a half-step below the fill, as --color-control-border is for the neutral one, so the shape reads without an outline.

Destructive action fill (delete, remove). Pair with --color-on-primary.

Disabled

Hover for flat rows — menu items, list rows, popover items.

See-through, so it darkens whatever surface the row sits on rather than forcing one grey.

Resting fill for raised neutral controls — the secondary button and its static twins. The first step off white on the warm ramp, so a control reads as a distinct surface on a white card without going grey; --color-control-hover is the next step down the same ramp.

Edge of a raised neutral control.

A half-step: --color-border-subtle reads too faint now that the fill is no longer white, and --color-border-muted (the hover edge below) reads as an outline rather than an edge. The ramp is evenly spaced here, so this is one role wanting a half-step rather than a missing rung, and it's a mix like the selected-state tokens above.

Hover for raised controls.

One step down the ramp from --color-control-bg which is what makes the hover register now that the resting fill is already off white. Opaque — see --color-control-selected-surface.

Inset track that a selected pill floats in — ol-segmented-control.

One step below --color-control-bg: enough for the pill to sit proud of it, while staying lighter than --color-border-subtle so the pill keeps a visible outline against the track.

Drag handle on a sheet or tray — see-through ink, like --color-hover-overlay.

Loading skeletons (components/skeleton.css); see-through, so they work on any surface.

Selected look for neutral controls.

Shared by ol-button[selected] and ol-toggle[variant="button"][checked] so the two can't drift apart.

Solid versions of the tints above.

Always hand --control-surface one of these — alpha leaks into the top highlight and turns it into a dark line.

Borders & outline roles

Edge of an image, e.g. a book cover: see-through ink, so a pale cover gets a line and a dark one keeps its own.

Messages and notices. Info borrows the blue ramp rather than its own hue.

Counterparts for status *shapes* — switches, bars, dots.

The -fg ramps are tuned for AA text and read muddy as a block of color. The neutral one is the same shape switched off: dark enough that a white knob still reads on it.

Data lines — sparklines and small charts, one hue per series in this order. The 500 steps: dark enough that a 2px line reads on white, not so dark they turn to ink.

Bars in data charts (reading-log stats). Counts sit past the bar end in text ink.

Bars in the publishing-history chart on subject and publisher pages.

Default bar colour for the daily stats charts on /stats.

Font families

Schibsted Grotesk and Literata are self-hosted webfonts (static/css/fonts/) that only render on pages whose bundle imports them; everywhere else the stacks fall through to the system fonts they always used. Schibsted covers Latin and Latin Extended only, so Greek, Cyrillic and the rest fall through to the system sans, with Noto Sans behind that.

Font sizes

The size ramp, in the display / headline / title / label / body vocabulary. Elements and roles pick a step from here.

Font weights

Four steps, matching the 400–700 range the variable webfonts cover. Off-scale values in legacy rules (650, 300) snap to the nearest step when migrated. Fall back to a primitive only where no role fits.

Line heights

Unitless, so leading scales with the font size. Smaller for impact (big headings) and scanning (dense UI text); larger for reading.

Heading

Section headings, h1–h3. Medium weight in body ink; the size ramp carries the hierarchy per element, so the role has no size token.

Subheading

h4–h6. These sit at body sizes, so semibold is what separates them from copy; don't lighten them to match the heading role.

Overline

The small all-caps heading over a group: popover section headings ("Sort by"), search-modal result groups ("Top results"), design-page nav groups. Sits on --font-size-label-medium at a medium weight, and tracks slightly tight so the caps read as one word rather than a row of letters.

Families by role

Which stack each kind of text uses. These fold into full role blocks above as the roles gain a second property.

Line heights by role

Which leading each kind of text uses. These fold into full role blocks above as the roles gain a second property.

prettier-ignore

Inline: horizontal gaps between sibling elements

┌───┐ ↔ ┌───┐ ↔ ┌───┐
│ A │   │ B │   │ C │
└───┘   └───┘   └───┘

Use for: row gaps, icon-to-label, toolbar items, pagination buttons, breadcrumb separators

One gap between an icon and the label it sits beside, so a button, a menu row and a split button all read as the same control family.

Stack: vertical gaps between sibling elements

┌─────────┐
│    A    │
└─────────┘
     ↕
┌─────────┐
│    B    │
└─────────┘

Use for: column gaps, heading-to-body, form fields, stacked lists, book detail sections

Inset: padding inside a container

┌─────────────────┐
│ ↑               │
│ ← [ content ] → │
│ ↓               │
└─────────────────┘

Use for: padding on cards, dialogs, buttons, tags, read-more panels, search result items

Pairs with --border-card and --border-radius-card, so cards side by side share one padding.

Layout: page-level spacing

│←gutter→┌──────────┐←gutter→│
│        │ section  │        │
│        └──────────┘        │
│             ↕ section-gap  │
│        ┌──────────┐        │
│        │ section  │        │
│        └──────────┘        │

Use for: page edge margins, gaps between top-level page sections (e.g. header → carousel → lists)

Border-Radius Primitives

Rarely used directly in components - use semantic tokens instead

Border-Radius Semantic Tokens

Reference these throughout the app for consistent border-radius styling.

The step carries the meaning, so a card and a dialog don't end up the same shape:

lg  12px  floating   — it sits above the page: dialog, popover, toast, tray
md   8px  in-page    — it sits in the page: card, banner, button, input, row
sm   4px  object     — it is a small thing in its own right: badge, tag

A bigger box reads squarer at the same radius, which is why one step covers both a 32px button and an 800px card without either looking wrong.

Book covers, author portraits, illustrations.

A printed object has a near-square corner — a cover rounded like a control reads as an app tile rather than a book — and covers are the most-repeated shape on the site.

Rows inside an overlay.

Derived, not chosen: a row inset --menu-row-inset (4px) from a 12px panel is concentric at 12 - 4 = 8px. Change one and the other has to move, or the two corners stop sharing a centre.

Not --border-radius-pill: a chip that wraps to two lines under a 9999px radius reads as a lozenge with a dent, so this is a fixed step that holds up at either height.

Border Primitives

Rarely used directly in components - use semantic tokens instead

Border Widths

Complete border styles.

Every hairline is --color-border-subtle, so cards tables, and inputs share one warm line.

Focus Ring — accessible focus indicator

Surface a raised control sits on.

Components override it alongside their own background-color so the specular highlight tones to that fill, not white.

Specular edge strength on a saturated fill (primary, danger, a selected chip). White reads much louder on a dark fill than on the neutral one's 35%, so this is tuned to land as quietly as the neutral edge does.

Raised-control drop shadow — the surface-independent half of the lift.

The matching inset highlight is deliberately not in this token: a :root custom property resolves its var()s against :root, so --control-surface would bake to white and element-level overrides could never reach it. Components apply it inline instead, as inset 0 1px 0 color-mix(in srgb, var(--white) 35%, var(--control-surface)). Alpha is on the --ink-overlay hue, and stays literal — var() can't carry it.

Floating-control drop shadow — a control that sits over content (a save button on cover art) rather than on the page. Pair with the same inline specular highlight as above; see ol-button[elevation="floating"].

Overlay surface — the floating panel behind popovers, menus, dialogs, and toasts. The hairline border draws the edge that a soft shadow alone loses against a white page; because the border carries the definition, the shadow can stay light and read as depth rather than as a smudge. Shares the divider tone, so an overlay's edge and the rules inside it are the same value.

The scrim behind a modal overlay — the dialog's ::backdrop, the drawer's scrim, the popover's mobile tray, which should all read as the same gesture. The blur is what pushes the page back; the dim is what makes it inert. Blur follows modality, never a breakpoint; a non-modal overlay gets neither. See docs/frontend/design.md#blur-follows-modality-not-viewport-width.

Design approach to Control Heights

• One source of truth for the outer height of single-line, line-height-locked controls (buttons, segmented controls, inputs, selects).
• Controls set height (not vertical padding) to one of these tokens with box-sizing: border-box, so same-size controls line up exactly regardless of their font-size, border-width, or content height. See /developers/design ("Control alignment") for the side-by-side check.

Do NOT use these for controls whose content can wrap to multiple lines (chips/tags, textareas) — those should grow with their content. Use min-height there instead, or a different scale (e.g. --line-height-chip).

Menu rows are a different shape: rows inside a panel — a popover, a drawer — sized to be comfortably tappable rather than to line up beside a button. Applied as min-height, never height, so a described row can grow past it; keep the row's own vertical padding under it.

The row is inset from the panel by --menu-row-inset and rounded so its hover fill reads as a pill, then gives that inset back as --menu-row-padding-inline to hold the label column 16px from the panel. Light-DOM panels that can't margin the row put the inset on their own side padding instead.

Press feedback scale

Controls squeeze on :active. The percentage is tiered by width so the edge always travels about 1.5px: 3% on a 32px icon button is sub-pixel, 3% on a 500px search bar is a lurch. Pick by width, not importance — compact for square icon controls, default for text, wide for stretched ones. Only self-contained controls scale; menu rows and surfaces never do.

Z-Index Primitives

Raw stacking values. Components use the semantic tokens below, never these (Stylelint enforces it). Gaps in numbering are deliberate; do not fill them.

prettier-ignore

Local Layers

Ordinals for layering inside a component whose root sets isolation: isolate. Meaningless without it. Use --z-index-behind for negative layers.

prettier-ignore

Primitives

Semantic easing

Durations