---
title: "Surface"
description: "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."
url: "https://opsinjs.pensievelabs.org/docs/components/surface"
source: "https://opsinjs.pensievelabs.org/docs/components/surface.md"
section: "Components"
status: "shipped"
kind: "component"
category: "surfaces"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["material", "blur", "translucency", "glass", "vibrancy", "elevation", "layer"]
governedBy: ["two-colour-axes"]
usedIn: ["daily-logging", "result-disclosure", "onboarding-and-first-run"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="surface"
  status="shipped"
  questions="[
  &#x22;Nothing measures the tint composited at its published floor, so every figure here is a rung's opaque fallback and `minScrimOpacity` is asserted rather than derived.&#x22;,
  &#x22;Whether `prefers-contrast: more` belongs in this component at all, since the edge widens and keeps its published alpha against an unmeasured non-text floor.&#x22;,
  &#x22;Nobody has opened the site under a real Windows contrast theme, and the scrim's dimming does not survive there because the palette replaces the tint with Canvas.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="surface" unbuilt="false" importPath="@/components/ui/surface" />

```tsx
import { Surface } from "@/components/ui/surface"
```

```tsx
<Surface rung="sheet">Everything the surface holds</Surface>
```

## Examples [#examples]

<ComponentPreview name="surface" />

### Chrome that content scrolls beneath [#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.

<ComponentPreview name="surface-over-scrolling-content" kind="example" align="start" />

### The degraded path, without changing a setting [#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.

<ComponentPreview name="surface-opaque-fallback" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Building a layered component at a defined rung: a custom panel, a floating bar or a persistent header.&#x22;,
  &#x22;Any surface that overlays scrolling content and must stay readable whatever passes beneath it.&#x22;,
  &#x22;Expressing depth through material rather than shadow, which is how this system shows layering.&#x22;,
]"
  avoid="[
  { case: &#x22;You need a bounded group of related content with padding and a border, on the page rather than over it.&#x22;, instead: &#x22;card&#x22; },
  { case: &#x22;You are building a bottom sheet with detents and drag.&#x22;, instead: &#x22;sheet&#x22; },
  { case: &#x22;You are building a modal that traps focus.&#x22;, instead: &#x22;dialog&#x22; },
  { case: &#x22;You are reaching for a fourth composited translucent layer on one screen, which stutters on mid-range Android.&#x22;, instead: &#x22;card&#x22; },
  { case: &#x22;A number a person must read is going on `sheet` or `overlay`. A health value never sits on a translucent rung above `raised`.&#x22;, instead: &#x22;card&#x22; },
]"
/>

## Accessibility [#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](../foundations/accessibility.mdx) 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](../foundations/accessibility.mdx) 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](../health/two-colour-axes.mdx) rule and its repair are stated on the API, and no element the component itself renders mixes them.

<KeyboardTable
  name="surface"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Passes through the surface&#x22;,
    notes: &#x22;Surface is presentational, with no role, no focus and no tab stop.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Passes through the surface&#x22;,
    notes: &#x22;Same in reverse. A Surface never joins the focus order, at any rung.&#x22;,
  },
]"
/>

<ContrastReport component="surface" />

## Props interface [#props-interface]

<PropsTable name="SurfaceProps" />

`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](../health/two-colour-axes.mdx)
rule applies in full.
