Surface | Shift CSS

Overview

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

Import

/* Full framework (includes all components) */
@import "@shift-css/core";

/* Or import just the surface component */
@import "@shift-css/core/components/surface";

Note: When importing individual components, you also need @shift-css/core/reset and @shift-css/core/tokens for the base styles and design tokens.

Elevation Variants

Elevation hierarchy

Sunken

s-surface="sunken"

Flat

s-surface="flat"

Raised

s-surface="raised"

Floating

s-surface="floating"

<div class="demo-grid">
<div s-surface="sunken" style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2);">Sunken</strong>
  <p style="margin: 0; font-size: var(--s-text-sm);"><code>s-surface="sunken"</code></p>
</div>
<div s-surface="flat" style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2);">Flat</strong>
  <p style="margin: 0; font-size: var(--s-text-sm);"><code>s-surface="flat"</code></p>
</div>
<div s-surface="raised" style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2);">Raised</strong>
  <p style="margin: 0; font-size: var(--s-text-sm);"><code>s-surface="raised"</code></p>
</div>
<div s-surface="floating" style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2);">Floating</strong>
  <p style="margin: 0; font-size: var(--s-text-sm);"><code>s-surface="floating"</code></p>
</div>
</div>

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>

Modifiers

Surface modifiers

Bordered

s-bordered

Interactive

s-interactive - hover me!

<div class="demo-grid">
<div s-surface="flat" s-bordered style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2);">Bordered</strong>
  <p style="margin: 0; font-size: var(--s-text-sm);"><code>s-bordered</code></p>
</div>
<div s-surface="raised" s-interactive style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2);">Interactive</strong>
  <p style="margin: 0; font-size: var(--s-text-sm);"><code>s-interactive</code> - hover me!</p>
</div>
</div>

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

Brand color surfaces

Primary

s-surface="primary"

Secondary

s-surface="secondary"

Accent

s-surface="accent"

<div class="demo-grid">
<div s-surface="primary" style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2); color: #fff;">Primary</strong>
  <p style="margin: 0; font-size: var(--s-text-sm); color: #fff;"><code style="color: #fff; background: transparent;">s-surface="primary"</code></p>
</div>
<div s-surface="secondary" style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2); color: #fff;">Secondary</strong>
  <p style="margin: 0; font-size: var(--s-text-sm); color: #fff;"><code style="color: #fff; background: transparent;">s-surface="secondary"</code></p>
</div>
<div s-surface="accent" style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2); color: #fff;">Accent</strong>
  <p style="margin: 0; font-size: var(--s-text-sm); color: #fff;"><code style="color: #fff; background: transparent;">s-surface="accent"</code></p>
</div>
</div>

State Surfaces

For alerts and notifications:

State surfaces for feedback

Success

For success messages

Warning

For warning messages

Danger

For error messages

<div class="demo-grid">
<div s-surface="success" style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2);">Success</strong>
  <p style="margin: 0; font-size: var(--s-text-sm);">For success messages</p>
</div>
<div s-surface="warning" style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2);">Warning</strong>
  <p style="margin: 0; font-size: var(--s-text-sm);">For warning messages</p>
</div>
<div s-surface="danger" style="padding: var(--s-space-4);">
  <strong style="display: block; margin: 0 0 var(--s-space-2);">Danger</strong>
  <p style="margin: 0; font-size: var(--s-text-sm);">For error messages</p>
</div>
</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