Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
surface · base base · style base-lyraOpen under the product theme

Chrome 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.

Theme
Density
Text
Status
Accent theme
Accent
surface-over-scrolling-content · base base · style base-lyraOpen under the product theme
surface-over-scrolling-content.tsx
"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.

Theme
Density
Text
Status
Accent theme
Accent
surface-opaque-fallback · base base · style base-lyraOpen under the product theme
surface-opaque-fallback.tsx
import { 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 card instead.
  • You are building a bottom sheet with detents and drag.Use sheet instead.
  • You are building a modal that traps focus.Use dialog instead.
  • You are reaching for a fourth composited translucent layer on one screen, which stutters on mid-range Android.Use card instead.
  • A number a person must read is going on `sheet` or `overlay`. A health value never sits on a translucent rung above `raised`.Use card instead.

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: more the edge widens from a hairline to an emphasis width but keeps its published --opsin-material-*-border colour, and several rungs publish a low alpha, so whether it clears 3:1 for SC 1.4.11 is unmeasured. A solid colour would give canvas and scrim an edge they are specified not to have, so the fix sits in tokens/material.json.
  • className is 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.
KeyActionNotes
TabPasses through the surfaceSurface is presentational, with no role, no focus and no tab stop.
Shift+TabPasses through the surfaceSame in reverse. A Surface never joins the focus order, at any rung.
Contrast: 52 measured token pairs, 16 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor
body text on the canvas materiallight104.717.96:1Pass
body text on the canvas materialdark-100.518.00:1Pass
body text on the inset materiallight98.116.32:1Pass
body text on the inset materialdark-100.117.18:1Pass
body text on the card materiallight104.717.96:1Pass
body text on the card materialdark-99.616.32:1Pass
body text on the raised materiallight104.717.96:1Pass
body text on the raised materialdark-97.513.77:1Pass
body text on the sheet material over the darkest backdroplight99.916.76:1Pass
body text on the sheet material over the darkest backdropdark-99.716.47:1Pass
body text on the sheet material over the lightest backdroplight104.717.96:1Pass
body text on the sheet material over the lightest backdropdark-80.86.07:1Pass
body text on the overlay material over the darkest backdroplight85.913.48:1Pass
body text on the overlay material over the darkest backdropdark-99.916.77:1Pass
body text on the overlay material over the lightest backdroplight104.717.96:1Pass
body text on the overlay material over the lightest backdropdark-54.22.69:1Below 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.