Components
Surface
The primitive behind every panel, sheet and card. It decides how solid or translucent a layer looks, and guarantees whatever sits on it stays readable.
Usage
pnpm dlx shadcn@latest add @opsinjs/surface
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Surface } from "@/components/ui/surface"<Surface rung="sheet">Everything the surface holds</Surface>Examples
surface · base base · style base-lyraOpen under the product themeChrome that content scrolls beneath
rung="overlay" on a panel that opens already scrolled, so a dark row sits under
the pinned header and the scrim holds the heading legible over it.
surface-over-scrolling-content · base base · style base-lyraOpen under the product theme"use client"
import { useEffect, useRef } from "react"
import { Surface } from "@/components/ui/surface"
/* Deliberately contentless rows. This example is about a material, and a
screenshot of an opsinjs example must never be mistakable for somebody's
own readings. There is therefore no number, no unit and no date anywhere in
it. */
const ROWS = [
"First example row",
"Second example row",
"Third example row",
"Fourth example row",
"Fifth example row",
"Sixth example row",
"Seventh example row",
"Eighth example row",
"Ninth example row",
"Tenth example row",
]
const HEADING_ID = "surface-over-scrolling-content-heading"
/* The row the panel opens with sitting under the header. Its index is odd, so
it is a dark row, and it is near the top so the reader can still scroll both
up and down from the resting frame. The offset is measured from where the row
sits relative to the scroll container rather than computed from a padding sum,
so it stays correct whatever the type size the preview is set to. */
const RESTING_ROW_INDEX = 1
export default function SurfaceOverScrollingContent() {
const scrollRef = useRef<HTMLDivElement>(null)
const restingRowRef = useRef<HTMLLIElement>(null)
useEffect(() => {
const scroller = scrollRef.current
const row = restingRowRef.current
if (!scroller || !row) return
/* Open with the dark row behind the header. The header height and a row
height are the same padding and the same-size text, so aligning the row's
top to the scroll origin lands the row squarely under the pinned header,
and the heading is read over a dark backdrop in the resting frame. The
row's top is measured against the scroll container's own top and not read
from `offsetTop`. Nothing in this tree is positioned, so `offsetTop` would
resolve against the document body and return a figure far past this
container's scroll range; the browser would then clamp it to the maximum,
every row would land on that same clamped frame, and the chosen row would
stop mattering. A rect difference stays relative to the container whatever
is positioned around it. */
scroller.scrollTop =
row.getBoundingClientRect().top -
scroller.getBoundingClientRect().top +
scroller.scrollTop
}, [])
return (
<div
ref={scrollRef}
/* `group` rather than `region`: this is a scrollable box inside a
preview, not a landmark of the page that embeds it. It takes its name
from the sticky heading, so a screen-reader user arriving on the tab
stop hears what they have landed in rather than "scrollable". */
role="group"
tabIndex={0}
aria-labelledby={HEADING_ID}
className="h-80 w-full max-w-sm overflow-y-auto rounded-opsin-lg border border-border bg-background"
>
{/* A direct child of the scroll container, so `top-0` sticks to it rather
than to the page. `z-10` puts it above the rows; it does not create a
backdrop root, so the blur still reaches the content passing under. */}
<Surface rung="overlay" className="sticky top-0 z-10">
<div className="px-opsin-4 py-opsin-3">
<h2 id={HEADING_ID} className="m-0 text-opsin-headline">
Example section
</h2>
</div>
</Surface>
{/* `role="list"` because `list-none` removes the list role in WebKit, and
Safari 16.4 is this system's tested floor. Without it a reader loses
the count and the "n of 10" position that tells them where they are in
a scroller they have been asked to scroll. */}
<ul role="list" className="m-0 flex list-none flex-col p-0">
{ROWS.map((row, index) => (
<li
key={row}
ref={index === RESTING_ROW_INDEX ? restingRowRef : undefined}
className={
index % 2 === 0
? "border-b border-border px-opsin-4 py-opsin-3 text-opsin-body"
: "border-b border-border bg-foreground px-opsin-4 py-opsin-3 text-opsin-body text-background"
}
>
{row}
</li>
))}
</ul>
</div>
)
}The degraded path, without changing a setting
opaque renders the same fallback that reduced transparency, prefers-contrast: more and a missing backdrop-filter reach. The border, shadow and geometry
stay, because they carry the layering once translucency goes.
surface-opaque-fallback · base base · style base-lyraOpen under the product themeimport { Surface } from "@/components/ui/surface"
/* Surface roles only. A backdrop is decoration, and the category and status
axes both mean something specific about a person's data; neither is
available as wallpaper. */
const BACKDROP_TILES = [
"bg-foreground",
"bg-primary",
"bg-background",
"bg-background",
"bg-muted",
"bg-foreground",
"bg-background",
"bg-muted",
"bg-foreground",
"bg-foreground",
"bg-primary",
"bg-background",
]
export default function SurfaceOpaqueFallback() {
return (
<div className="relative w-full max-w-lg overflow-hidden rounded-opsin-lg">
<div
aria-hidden="true"
className="absolute inset-0 grid grid-cols-6 grid-rows-2"
>
{BACKDROP_TILES.map((tone, index) => (
<div key={`${tone}-${index}`} className={tone} />
))}
</div>
{/* Concentric radius, matching the component's own demo: the wrapper is
rounded-opsin-lg (21px) with p-opsin-4 (16px) between it and each
panel, so a panel's radius is 21 minus 16, which is 5px, floored to the
published floor radius-xs (4px). tokens/shape.json rules[2] is the
rule. The job line is text-opsin-body and not text-opsin-footnote: the
page's Don't names small caption text on a heavily blurred surface, and
footnote's published use is provenance rather than prose a reader
reads. */}
<div className="relative grid gap-opsin-3 p-opsin-4 sm:grid-cols-2">
<Surface rung="sheet" className="rounded-opsin-xs">
<div className="p-opsin-3">
<p className="m-0 text-opsin-headline">Sheet rung</p>
<p className="m-0 text-opsin-body">
Translucent, with the page blurred behind it.
</p>
</div>
</Surface>
<Surface rung="sheet" opaque className="rounded-opsin-xs">
<div className="p-opsin-3">
<p className="m-0 text-opsin-headline">Same rung, opaque</p>
<p className="m-0 text-opsin-body">
What reduced transparency, increased contrast and a missing
backdrop-filter all produce.
</p>
</div>
</Surface>
</div>
</div>
)
}When to use it
Use it when
- Building a layered component at a defined rung: a custom panel, a floating bar or a persistent header.
- Any surface that overlays scrolling content and must stay readable whatever passes beneath it.
- Expressing depth through material rather than shadow, which is how this system shows layering.
Do not use it when
- You need a bounded group of related content with padding and a border, on the page rather than over it.Use
cardinstead. - You are building a bottom sheet with detents and drag.Use
sheetinstead. - You are building a modal that traps focus.Use
dialoginstead. - You are reaching for a fourth composited translucent layer on one screen, which stutters on mid-range Android.Use
cardinstead. - A number a person must read is going on `sheet` or `overlay`. A health value never sits on a translucent rung above `raised`.Use
cardinstead.
Accessibility
The audit found zero axe violations, no target-size or focus-visible finding and
no horizontal scroll at 320px, and changed nothing. The surface is
presentational, with no role, name or tab stop, and its three decorative layers
are empty and aria-hidden. The Backdrop renders only where the Scrim is
unconditional, so no text sits over an unscrimmed blur. Reduced
transparency, prefers-contrast: more, forced-colors: active and a missing
backdrop-filter each reach a defined
opaque fallback that keeps the border,
shadow and geometry. The boundary is an outline, so forced-colors preserves it
where a shadow would be dropped.
Residual items. Both belong to the token owner, not to this file.
- Under
prefers-contrast: morethe edge widens from a hairline to an emphasis width but keeps its published--opsin-material-*-bordercolour, and several rungs publish a low alpha, so whether it clears 3:1 for SC 1.4.11 is unmeasured. A solid colour would givecanvasandscriman edge they are specified not to have, so the fix sits intokens/material.json. classNameis merged unrestricted, so a caller can put a category tint and a status tint on one Surface, which the component cannot detect at render time. The two colour axes rule and its repair are stated on the API, and no element the component itself renders mixes them.
| Key | Action | Notes |
|---|---|---|
| Tab | Passes through the surface | Surface is presentational, with no role, no focus and no tab stop. |
| Shift+Tab | Passes through the surface | Same in reverse. A Surface never joins the focus order, at any rung. |
Contrast: 52 measured token pairs, 16 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
| body text on the canvas material | light | 104.7 | 17.96:1 | Pass |
| body text on the canvas material | dark | -100.5 | 18.00:1 | Pass |
| body text on the inset material | light | 98.1 | 16.32:1 | Pass |
| body text on the inset material | dark | -100.1 | 17.18:1 | Pass |
| body text on the card material | light | 104.7 | 17.96:1 | Pass |
| body text on the card material | dark | -99.6 | 16.32:1 | Pass |
| body text on the raised material | light | 104.7 | 17.96:1 | Pass |
| body text on the raised material | dark | -97.5 | 13.77:1 | Pass |
| body text on the sheet material over the darkest backdrop | light | 99.9 | 16.76:1 | Pass |
| body text on the sheet material over the darkest backdrop | dark | -99.7 | 16.47:1 | Pass |
| body text on the sheet material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the sheet material over the lightest backdrop | dark | -80.8 | 6.07:1 | Pass |
| body text on the overlay material over the darkest backdrop | light | 85.9 | 13.48:1 | Pass |
| body text on the overlay material over the darkest backdrop | dark | -99.9 | 16.77:1 | Pass |
| body text on the overlay material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the overlay material over the lightest backdrop | dark | -54.2 | 2.69:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from SurfaceProps in registry/bases/base/surface.tsx.
rung is required, because no default depth is safe to guess. There is no
blur, opacity, tint, radius or as prop, and no contentWeight, because
no large-text scrim floor has been measured. A rung outside the six is refused.
Development warns and the children still render, with no material. className
is merged unrestricted, so the two colour axes
rule applies in full.