kikkupico/ambientcss

A physics-based lighting system for CSS. Define a light source, and every shadow, highlight, and surface gradient follows from it — no more hand-tuned shadow-sm / shadow-md / shadow-lg.

Summary

Ambient CSS is a CSS framework that derives shadows, highlights, and surface gradients from a single physics-based light source instead of hand-tuned shadow scales. The visual output is calibrated against Blender raytraces, and the project ships as two npm packages: @ambientcss/css (zero-dependency pure CSS) and @ambientcss/components (React component library). It is MIT-licensed and built in TypeScript.

What it is useful for

Ambient CSS is designed for UIs that need visually consistent lighting across many elements — for example, a dashboard where every card, button, and panel reads as sharing the same light direction. Instead of choosing shadow-sm or shadow-lg on each element, you set a light vector on a parent (e.g. .amb-light-tl, or custom properties like --amb-light-x / --amb-light-y) and descendants inherit the scene. Each surface combines five box-shadow layers — drop shadow, fillet highlight, fillet shadow, chamfer highlight, chamfer shadow — driven by that shared light. The framework also exposes surface shapes (flat, concave, convex), edge treatments (chamfer, fillet, groove), and materials (matte, shiny, glass, brushed, brushed-round, blasted) that all read from the same light environment. The React package adds preset controls like AmbientButton, AmbientKnob, AmbientPanel, and AmbientRotary, which publish CSS custom properties (--ambx-percent, --ambx-angle, --ambx-size) so that a part can be styled with plain CSS. The motivation the README gives is that traditional shadow scales are decorative: a card with shadow-lg next to a button with shadow-sm on the same page does not imply a shared physical scene, because the two blur values are unrelated.

How engineers can use it

For plain HTML or any framework:

npm install @ambientcss/css

Then link node_modules/@ambientcss/css/dist/ambient.css and wrap content in a light container:

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

For React:

npm install @ambientcss/components @ambientcss/css

import { AmbientProvider, AmbientButton, AmbientKnob, AmbientPanel } from "@ambientcss/components";
import "@ambientcss/css/ambient.css";
import "@ambientcss/components/styles.css";

<AmbientProvider theme={{ lightX: -1, lightY: -1, keyLight: 0.9, fillLight: 0.7 }}>
  <AmbientPanel>
    <AmbientButton>Press</AmbientButton>
    <AmbientKnob label="Gain" defaultValue={50} />
  </AmbientPanel>
</AmbientProvider>

For local development, the README documents cloning the repo, then pnpm install, pnpm build, pnpm typecheck, pnpm --filter demo dev, and pnpm docs:dev. Ready-to-run starters under examples/ cover Tailwind, Bootstrap, pure CSS, and React variants. Albedo can be customized on any element with --amb-albedo and a --amb-shade multiplier, and grain-heavy materials like amb-mat-brushed are scaled with --amb-grain-amount.