Surface

Overview

The s-surface attribute provides background surfaces with different elevation levels for creating visual hierarchy.

Basic Usage

<div s-surface="flat">Default flat surface</div>

Elevation Variants

Sunken

Recessed appearance, ideal for input areas or inset content:

<div s-surface="sunken">Sunken surface - appears recessed</div>

Flat

Default level surface:

<div s-surface="flat">Flat surface - no elevation</div>

Raised

Subtle elevation, good for cards and containers:

<div s-surface="raised">Raised surface - subtle lift</div>

Floating

Higher elevation for overlays, modals, and dropdowns:

<div s-surface="floating">Floating surface - highest elevation</div>

Comparison

<div
  style="display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--s-space-4);"
>
  <div s-surface="sunken" style="padding: var(--s-space-4);">
    <strong>Sunken</strong>
    <p>Use for input areas, wells</p>
  </div>
  <div s-surface="flat" style="padding: var(--s-space-4);">
    <strong>Flat</strong>
    <p>Use for base content</p>
  </div>
  <div s-surface="raised" style="padding: var(--s-space-4);">
    <strong>Raised</strong>
    <p>Use for cards, sections</p>
  </div>
  <div s-surface="floating" style="padding: var(--s-space-4);">
    <strong>Floating</strong>
    <p>Use for modals, dropdowns</p>
  </div>
</div>

Modifiers

Bordered

Add a border to any surface:

<div s-surface="flat" s-bordered>Flat surface with border</div>

Interactive

Make a surface hoverable with lift effect:

<div s-surface="raised" s-interactive>Hover me!</div>

Color Variants

Brand Colors

<div s-surface="primary">Primary surface</div>
<div s-surface="secondary">Secondary surface</div>
<div s-surface="accent">Accent surface</div>

State Surfaces

For alerts and notifications:

<div s-surface="success">Success message</div>
<div s-surface="warning">Warning message</div>
<div s-surface="danger">Error message</div>

How It Works

Surfaces use semantic tokens that automatically adapt to light/dark mode:

:where([s-surface]) {
  --_surface-bg: var(--s-surface-base);
  background-color: var(--_surface-bg);
  border-radius: var(--s-radius-lg);

  /* Auto-contrast text color */
  @supports (color: oklch(from red l c h)) {
    color: oklch(
      from var(--_surface-bg) clamp(0.15, calc((0.6 - l) * 1000 + 0.15), 0.95) 0
        0
    );
  }
}

[s-surface="sunken"] {
  --_surface-bg: var(--s-surface-sunken);
  box-shadow: var(--s-shadow-inner);
}

[s-surface="raised"] {
  --_surface-bg: var(--s-surface-raised);
  box-shadow: var(--s-shadow-md);
}

[s-surface="floating"] {
  --_surface-bg: var(--s-surface-raised);
  box-shadow: var(--s-shadow-xl);
}

Dark Mode

Surfaces automatically adapt to dark mode via light-dark():

:root {
  --s-surface-base: light-dark(var(--s-neutral-50), var(--s-neutral-900));
  --s-surface-raised: light-dark(var(--s-neutral-0), var(--s-neutral-800));
  --s-surface-sunken: light-dark(var(--s-neutral-100), var(--s-neutral-950));
}

CSS Custom Properties

Property	Description
--_surface-bg	Background color (private)
--s-surface-base	Default surface background
--s-surface-raised	Elevated surface background
--s-surface-sunken	Recessed surface background

All Attributes

Attribute	Purpose	Values
s-surface	Surface variant	flat, sunken, raised, floating, primary, secondary, accent, success, warning, danger
s-bordered	Add border	Boolean
s-interactive	Hover lift effect	Boolean

Use Cases

• Sunken: Input fields, code blocks, inset sections
• Flat: Main content areas, page backgrounds
• Raised: Cards, panels, grouped content
• Floating: Modals, popovers, dropdown menus, tooltips
• Primary/Secondary/Accent: Brand-colored sections
• Success/Warning/Danger: Alert banners, notifications