Foundations

Scrollbar

Browser-default scrollbars are drawn by the OS and do not follow the theme — a light-gray scrollbar on a dark or pure-black surface reads as a rendering bug. Zetta defines three tokens per theme and one cross-browser recipe, so every scrollable region matches the surface it scrolls. New in v1.5; this is guardrail 17.

The tokens

Two independent mechanisms: WebKit uses the ::-webkit-scrollbar pseudo-elements, Firefox uses the standard scrollbar-color / scrollbar-width properties. Ship both.

scrollbar-track #f1f5f9 · #1e2530 · #000000

The groove. Sits flush with the surface it scrolls — never bordered.

scrollbar-thumb #cbd1d8 · #3a4150 · #808080

The draggable indicator, and the only high-contrast part.

scrollbar-thumb-hover #aeb4bd · #4b5563 · #ffffff

The thumb while the pointer is over the scrollbar.

Live example

A scrollable region using the recipe below. Switch the theme to see the scrollbar follow it.

Scroll this region. The track sits quietly on the surface; the thumb is the affordance and carries the contrast. In the Accessibility theme the thumb rests at mid-gray and lifts to white on hover.

Apply this to any component with an internal overflow region: the sidebar nav list, the table body and its horizontal scroll, dropdown and select menus, the command palette list, drawers and modals with scrolling bodies, code blocks, and long popovers.

Keep the track flush with its surface, never add a border to the track, and never restyle per component with ad-hoc colours — always resolve the three tokens.

The thumb is 10px and uses the full radius, matching the system's rounded language.

The recipe

/* WebKit / Blink (Chrome, Edge, Safari) */
.scroll-region::-webkit-scrollbar { width: 10px; height: 10px; }
.scroll-region::-webkit-scrollbar-track {
  background: var(--color-scrollbar-track);
}
.scroll-region::-webkit-scrollbar-thumb {
  background: var(--color-scrollbar-thumb);
  border-radius: var(--radius-full);
}
.scroll-region::-webkit-scrollbar-thumb:hover {
  background: var(--color-scrollbar-thumb-hover);
}

/* Firefox */
.scroll-region {
  scrollbar-color: var(--color-scrollbar-thumb) var(--color-scrollbar-track);
  scrollbar-width: thin;
}

The rules

17Scrollable containers use the three scrollbar-* tokens at 10px, thumb at rounded.full. Ship the WebKit pseudo-elements and the Firefox properties.
Never scrollbar-width: none, and never hide the scrollbar on a scrollable region — the thumb is a necessary affordance and a cue for keyboard and assistive-technology users.
Style overflow regions, not the whole document chrome, unless the app owns the full viewport.

All three values per theme are on the Color tokens page.