Ambient CSS: Physics-Based Lighting System for Tactile UI

Authorkikkupico

Last UpdateSeptember 4, 2026

LicenseMIT

Features

Shared light direction and intensity across related elements.
Flat, concave, convex, and horizontal concave surfaces.
Chamfer, fillet, and groove edge treatments.
Four elevation levels and three material thickness levels.
Matte, shiny, glass, brushed, spun, and blasted finishes.
Inherited material color and shade controls.
Directional light helper classes for corners and axes.
Glow, emissive color, radius, and press-effect utilities.
Optional React components based on the CSS primitives.

Use Cases

Digital audio workstations and synthesizer interfaces.
Hardware monitoring dashboards.
Interactive product configurators.
Tactile interface controls.

How To Use It

Installation

Install the CSS package with npm:

npm install @ambientcss/css

Import the stylesheet:

@import "@ambientcss/css/ambient.css";

You can also load the core stylesheet from a CDN.

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@ambientcss/[email protected]/dist/ambient.css"
/>

Basic Usage

Apply a light helper to a parent and build each surface from the ambient class plus surface, edge, elevation, and shape classes.

amb-light-tl sets a top-left light direction for descendants. The button uses a flat surface, chamfered edge, low elevation, and 4px radius.

<div class="amb-light-tl">
  <button
    class="ambient amb-surface amb-chamfer amb-elevation-1 amb-rounded"
  >
    Power
  </button>
</div>

Configure The Lighting Environment

Set light variables on :root or any container that should define its own lighting environment.

.control-panel {
  --amb-light-x: -0.8;
  --amb-light-y: -1;
  --amb-key-light-intensity: 0.9;
  --amb-fill-light-intensity: 0.68;
  --amb-light-hue: 215;
  --amb-light-saturation: 12%;
}

Core lighting variables:

--amb-light-x: Horizontal light direction from -1 to 1.
--amb-light-y: Vertical light direction from -1 to 1.
--amb-key-light-intensity: Primary light intensity from 0 to 1.
--amb-fill-light-intensity: Fill light intensity from 0 to 1.
--amb-light-hue: Light hue from 0 to 360.
--amb-light-saturation: Light saturation.

Directional helper classes are available when fixed positions are enough:

amb-light-tl
amb-light-tr
amb-light-bl
amb-light-br
amb-light-top
amb-light-bottom
amb-light-left
amb-light-right

Surfaces, Edges, And Depth

Surface classes control face shading:

amb-surface
amb-surface-concave
amb-surface-concave-h
amb-surface-convex

Edge classes control the inner highlight and shadow around the element:

amb-chamfer
amb-chamfer-2
amb-fillet
amb-fillet-2
amb-groove

Elevation controls drop-shadow depth:

amb-elevation-0
amb-elevation-1
amb-elevation-2
amb-elevation-3

Material thickness is configured independently:

amb-thickness-0
amb-thickness-1
amb-thickness-2

A panel can contain raised and recessed elements under the same light:

<div class="amb-light-tl control-panel">
  <section
    class="ambient amb-surface amb-chamfer-2 amb-elevation-2 amb-rounded-lg"
  >
    <button
      class="ambient amb-surface-convex amb-fillet amb-elevation-1 amb-rounded-md"
    >
      Start
    </button>
    <div
      class="ambient amb-surface-concave amb-groove amb-rounded-md"
    >
      Status
    </div>
  </section>
</div>

Material Color And Finishes

Set --amb-albedo to define the surface material color. Use --amb-shade for lighter or darker regions that should retain the inherited color.

.mixer-panel {
  --amb-albedo: #354a55;
}
.mixer-panel .control-well {
  --amb-shade: 0.38;
}

Available material classes:

amb-mat-matte
amb-mat-shiny
amb-mat-glass
amb-mat-brushed
amb-mat-brushed-round
amb-mat-blasted

amb-mat-brushed-round uses a circular grain pattern and works well on round dial faces. Brushed and blasted material relief can be adjusted with --amb-grain-amount.

.dial-face {
  --amb-grain-amount: 0.5;
}

Radius, Glow, And Emissive Colors

Radius utilities:

amb-rounded
amb-rounded-md
amb-rounded-lg
amb-rounded-xl
amb-rounded-full

Ambient CSS also defines emissive color helpers:

amb-emit-red
amb-emit-green
amb-emit-amber
amb-emit-cyan
amb-emit-blue
amb-emit-white

The emissive classes set --amb-emit-color. Apply that value to the element when it should use the selected fill color.

<span
  class="ambient amb-rounded-full amb-glow amb-emit-green status-light"
></span>

.status-light {
  display: inline-block;
  width: 12px;
  height: 12px;
  background-color: var(--amb-emit-color);
}

React Components

The component package contains ready-made controls and lower-level mechanisms for custom control skins. Mechanisms manage input, state, and ARIA behavior. Custom parts control the rendered appearance.

Install the component package together with the CSS package:

npm install @ambientcss/components @ambientcss/css

Import both stylesheets and the controls required by the application:

import {
  AmbientButton,
  AmbientKnob,
  AmbientPanel,
  AmbientProvider
} from "@ambientcss/components";
import "@ambientcss/css/ambient.css";
import "@ambientcss/components/styles.css";
function Mixer() {
  return (
    <AmbientProvider
      theme={{
        lightX: -1,
        lightY: -1,
        keyLight: 0.9,
        fillLight: 0.72
      }}
    >
      <AmbientPanel>
        <AmbientButton>Play</AmbientButton>
        <AmbientKnob label="Gain" defaultValue={50} />
      </AmbientPanel>
    </AmbientProvider>
  );
}