Surface

Playground

Overview

Surface solves a common contrast problem: a button that looks correct on the page background can become unreadable on a brand-colored hero, a dark section, or an inverted card. Rather than detecting the painted background at runtime (unreliable and SSR-unsafe), Tessina UI uses an explicit, inheritable tone — the same approach taken by Material 3, Radix, and Adobe Spectrum.

Wrap a colored region in <Surface> and every nested Button, IconButton, Fab, SplitButton, ToggleButton, and ButtonGroup inherits tone="on-color". A per-component tone prop always overrides the inherited value.

Installation

pnpm add @tessinaui/ui

Usage

import { Surface } from "@tessinaui/ui";
import { Button } from "@tessinaui/ui";

{/* Recommended — `background` paints a paired bg + on-* ink and auto-enables on-color */}
<Surface background="primary" className="rounded-xl p-6">
  <Button>Get started</Button>          {/* solid inverse chip */}
  <Button variant="secondary">Docs</Button>
  <Button variant="ghost">Learn more</Button>
</Surface>

{/* Per-button override — opt one button back out */}
<Surface background="primary">
  <Button>Inherited on-color</Button>
  <Button tone="default">Forced default</Button>
</Surface>

{/* Raw mode — bring your own background + a readable ink color */}
<Surface tone="on-color" className="bg-[#3b0764] p-6 text-white">
  <Button variant="outline">Outline</Button>
</Surface>

Showcase

How on-color styling works

Under tone="on-color", each variant renders a contrast-safe treatment derived from the surface ink (currentColor):

Quiet variants rest transparent so their label contrast equals the surface's own on-*/surface ratio — they never render below what the palette can support. Interaction tints use color-mix(in srgb, currentColor X%, transparent), so they adapt to any surface color.

API Reference

Props

Hooks & helpers

Notes

• Recommended path: use the background sugar — it pairs the background with its matching on-* ink so the inherited currentColor is guaranteed legible in both light and dark themes.
• Raw mode: when you supply your own background via className, also set a readable text color (e.g. text-white) so the quiet variants' currentColor-derived fills and labels read correctly.
• No auto-detection: Surface does not inspect the painted background; it propagates an explicit, deterministic, build-time-verifiable tone (audited against WCAG AA).