@vibe-labs/design-surfaces

Surface, opacity, overlay, and backdrop tokens and utilities for the Vibe Design System — semantic background and foreground tokens built on top of the neutral color scale.

Installation

@import "@vibe-labs/design-surfaces";

Tokens

CSS custom properties defined in @layer vibe.tokens:

Opacity

--opacity-0 … --opacity-100 — steps: 0, 5, 10, 20, 25, 50, 75, 80, 90, 95, 100

Backdrop Blur

Token	Value
--blur-sm	4px
--blur-md	8px
--blur-lg	16px
--blur-xl	24px

Overlays

Token	Default	Description
--overlay-scrim	rgba(0,0,0,0.4)	Standard scrim
--overlay-heavy	rgba(0,0,0,0.6)	Heavy overlay
--overlay-tint	rgba(255,255,255,0.08)	Light tint

Semantic Backgrounds

Token	Default
--surface-background	--color-neutral-950
--surface-base	--color-neutral-900
--surface-elevated	--color-neutral-850
--surface-subtle	--color-neutral-850
--surface-overlay	--color-neutral-800
--surface-modal	--color-neutral-750

Semantic Foregrounds

Token	Default
--surface-fg-primary	--text-primary
--surface-fg-secondary	--text-secondary
--surface-fg-inverse	--text-inverse
--surface-fg-muted	--text-muted
--surface-fg-disabled	--text-disabled

Utilities / Generated Classes

All classes generated into @layer vibe.utilities.

Opacity

.opacity-{n} — 0, 5, 10, 20, 25, 50, 75, 80, 90, 95, 100

Backdrop Blur

.backdrop-blur-none · .backdrop-blur-sm · .backdrop-blur-md · .backdrop-blur-lg · .backdrop-blur-xl

Overlays

.overlay-scrim · .overlay-heavy · .overlay-tint

Semantic Backgrounds

.bg-background · .bg-base · .bg-elevated · .bg-subtle · .bg-overlay · .bg-modal

Semantic Foregrounds

.fg-primary · .fg-secondary · .fg-inverse · .fg-muted · .fg-disabled

Background Blend Modes

.bg-blend-normal · .bg-blend-multiply · .bg-blend-screen · .bg-blend-overlay · .bg-blend-darken · .bg-blend-lighten

Dist Structure

File	Description
index.css	Barrel — imports both files below
surfaces.css	Token definitions
surfaces.g.css	Generated utility classes

Dependencies

Requires --color-neutral-* tokens from @vibe-labs/design-colors and --text-* tokens from @vibe-labs/design-typography.

Build

npm run build

---

Usage Guide

Provides semantic background, foreground, opacity, overlay, and backdrop blur utilities for consistent surface treatment in the Vibe Design System.

Import

@import "@vibe-labs/design-surfaces";

Common Patterns

1. Layered surface hierarchy

Use semantic background classes to create depth without specifying raw color values:

<div class="bg-background">              <!-- outermost page -->
  <aside class="bg-base">               <!-- sidebar -->
    <div class="bg-elevated p-4">       <!-- elevated panel -->
      Content
    </div>
  </aside>
  <dialog class="bg-modal p-6">         <!-- modal dialog -->
    Dialog
  </dialog>
</div>

2. Scrim behind modal

<div class="overlay-scrim fixed inset-0 z-overlay"></div>
<dialog class="bg-modal relative z-modal p-8 rounded-xl">
  Modal content
</dialog>

3. Frosted glass navigation (via backdrop blur)

<nav class="backdrop-blur-md bg-base opacity-90 sticky top-0 z-sticky">
  Navigation content
</nav>

4. Dimming a disabled section

<section class="opacity-50 pointer-events-none">
  <form>...</form>
</section>

5. Foreground color tokens for text layering

<article class="bg-base fg-primary">
  <h1>Primary text on base surface</h1>
  <p class="fg-secondary">Secondary / supporting text</p>
  <small class="fg-muted">Metadata or timestamps</small>
  <button class="fg-disabled" disabled>Disabled action</button>
</article>

6. Light tint overlay on a hero image

<div class="relative">
  <img src="hero.jpg" alt="" class="w-full h-screen object-cover" />
  <div class="overlay-tint absolute inset-0"></div>
  <h1 class="absolute inset-0 flex items-center justify-center">Headline</h1>
</div>

Token Reference

Token	Default	Use
--surface-background	neutral-950	Page root
--surface-base	neutral-900	Primary surfaces
--surface-elevated	neutral-850	Cards, panels
--surface-overlay	neutral-800	Dropdowns, popovers
--surface-modal	neutral-750	Modal dialogs
--overlay-scrim	rgba(0,0,0,0.4)	Modal backdrop
--blur-md	8px	Standard backdrop blur