Ambient CSS

https://kikkupico.github.io/ambientcss/
Admin
Ambient CSS is a small design system that provides lighting primitives and utility classes for UI...
Tokens:9,998
Snippets:130
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run documentation locally

Source: https://kikkupico.github.io/ambientcss/guide/contributing

Starts the development server for the documentation site.

```bash
pnpm docs:dev  
```

--------------------------------

### Run the demo application

Source: https://kikkupico.github.io/ambientcss/guide/demo

Starts the development server for the demo application from the monorepo root.

```bash
pnpm --filter demo dev
```

--------------------------------

### Install dependencies

Source: https://kikkupico.github.io/ambientcss/guide/contributing

Run this command to install all workspace dependencies.

```bash
pnpm install  
```

--------------------------------

### Install Ambient CSS packages

Source: https://kikkupico.github.io/ambientcss/ambient-components/install

Use pnpm to install the core components and CSS primitives.

```bash
pnpm add @ambientcss/components @ambientcss/css
```

--------------------------------

### Install Ambient CSS package

Source: https://kikkupico.github.io/ambientcss/ambient-css/install

Use pnpm to add the package to your project dependencies.

```bash
pnpm add @ambientcss/css
```

--------------------------------

### Basic React Component Setup with Ambient CSS

Source: https://kikkupico.github.io/ambientcss/examples/react-basic

Demonstrates the implementation of a React component using Ambient CSS controls like AmbientPanel, AmbientButton, AmbientSwitch, and AmbientKnob wrapped in an AmbientProvider.

```tsx
import React, { useState } from "react";
import {
AmbientProvider,
AmbientPanel,
AmbientButton,
AmbientKnob,
AmbientSwitch,
} from "@ambientcss/components";
  

export default function App() {
const [gain, setGain] = useState(50);
const [armed, setArmed] = useState(false);
  

return (
<div style={{ background: "#e8edf2", minHeight: "100vh", display: "flex", alignItems: "center", justifyContent: "center" }}>
<AmbientProvider theme={{ lightHue: 220, lightSaturation: 14, lumeHue: 190, keyLight: 0.9, fillLight: 0.72 }}>
<AmbientPanel style={{ display: "flex", flexDirection: "column", gap: 16, padding: 24, alignItems: "center" }}>
<AmbientButton>Play</AmbientButton>
<AmbientSwitch label="Arm" checked={armed} onCheckedChange={setArmed} led="#ef4444" />
<AmbientKnob label="Gain" value={gain} onChange={setGain} />
</AmbientPanel>
</AmbientProvider>
</div>
);
}
```

--------------------------------

### React App with Ambient CSS and Tailwind

Source: https://kikkupico.github.io/ambientcss/examples/react-tailwind

A complete React component example using Ambient CSS controls within a Tailwind-styled layout.

```tsx
import React, { useState } from "react";
import {
AmbientProvider,
AmbientPanel,
AmbientButton,
AmbientKnob,
AmbientSwitch,
} from "@ambientcss/components";
  

export default function App() {
const [gain, setGain] = useState(50);
const [armed, setArmed] = useState(false);
  

return (
<div className="bg-slate-300 min-h-screen flex items-center justify-center">
<AmbientProvider theme={{ lightHue: 220, lightSaturation: 14, lumeHue: 190, keyLight: 0.9, fillLight: 0.72 }}>
<AmbientPanel className="flex flex-col gap-4 p-6 items-center">
<AmbientButton>Play</AmbientButton>
<AmbientSwitch label="Arm" checked={armed} onCheckedChange={setArmed} led="#ef4444" />
<AmbientKnob label="Gain" value={gain} onChange={setGain} />
</AmbientPanel>
</AmbientProvider>
</div>
);
}
```

--------------------------------

### Build the demo application

Source: https://kikkupico.github.io/ambientcss/guide/demo

Compiles the demo application for production from the monorepo root.

```bash
pnpm --filter demo build
```

--------------------------------

### Initialize Ambient Components

Source: https://kikkupico.github.io/ambientcss/ambient-components/usage

Import necessary styles and components, then wrap the application in an AmbientProvider to apply theme settings.

```javascript
import "@ambientcss/css/ambient.css";  
import "@ambientcss/components/styles.css";  
  
import {  
  AmbientButton,  
  AmbientFader,  
  AmbientKnob,  
  AmbientPanel,  
  AmbientProvider,  
  AmbientSlider,  
  AmbientSwitch  
} from "@ambientcss/components";  
  
export function Example() {  
  return (  
    <AmbientProvider  
      theme={{  
        lightX: -1,  
        lightY: -1,  
        keyLight: 0.9,  
        fillLight: 0.72,  
        lightHue: 220,  
        lightSaturation: 14,  
        highlightColor: "#7dd3fc",  
        lumeHue: 190  
      }}  
    >  
      <AmbientPanel>  
        <AmbientButton>Play</AmbientButton>  
        <AmbientSwitch label="Bypass" defaultChecked />  
        <AmbientKnob value={40} onChange={(next) => console.log("knob", next)} />  
        <AmbientSlider value={28} onChange={(next) => console.log("slider", next)} />  
        <AmbientFader value={72} onChange={(next) => console.log("fader", next)} />  
      </AmbientPanel>  
    </AmbientProvider>  
  );  
}  
```

--------------------------------

### Build documentation

Source: https://kikkupico.github.io/ambientcss/guide/contributing

Generates the static build for the documentation site.

```bash
pnpm docs:build  
```

--------------------------------

### Apply Minimal Markup

Source: https://kikkupico.github.io/ambientcss/ambient-css/usage

Use standard utility classes to create a basic ambient surface panel.

```html
<div class="ambient amb-surface amb-chamfer amb-elevation-2 amb-rounded-lg">  
  Ambient panel surface  
</div>  

```

--------------------------------

### Implement Quick Variants

Source: https://kikkupico.github.io/ambientcss/ambient-css/usage

Demonstrates raised and inset surface variations using different class combinations.

```html
<!-- raised -->  
<div class="ambient amb-surface-convex amb-chamfer amb-elevation-2 amb-rounded-md"></div>  
  
<!-- inset -->  
<div class="ambient amb-surface-concave amb-fillet amb-elevation-1 amb-rounded-md"></div>  

```

--------------------------------

### Build all workspaces

Source: https://kikkupico.github.io/ambientcss/guide/contributing

Builds all packages and applications within the monorepo.

```bash
pnpm build  
```

--------------------------------

### Implement a theme switcher shell

Source: https://kikkupico.github.io/ambientcss/ambient-components/examples

Demonstrates dynamic theme switching using the AmbientProvider component to update light properties based on state.

```typescript
import { useState } from "react";  
import { AmbientProvider, AmbientPanel, AmbientSwitch } from "@ambientcss/components";  
  
export function ThemeToggleShell() {  
  const [warm, setWarm] = useState(false);  
  
  return (  
    <AmbientProvider  
      theme={  
        warm  
          ? { lightHue: 28, lightSaturation: 18, lumeHue: 36, keyLight: 0.9, fillLight: 0.7 }  
          : { lightHue: 220, lightSaturation: 14, lumeHue: 190, keyLight: 0.9, fillLight: 0.72 }  
      }  
    >  
      <AmbientPanel>  
        <AmbientSwitch label="Warm Mode" checked={warm} onCheckedChange={setWarm} />  
      </AmbientPanel>  
    </AmbientProvider>  
  );  
}  
```

--------------------------------

### Run release gate

Source: https://kikkupico.github.io/ambientcss/guide/contributing

Executes the full release verification process.

```bash
pnpm release:check  
```

--------------------------------

### Configure Key-to-Fill Light Ratios

Source: https://kikkupico.github.io/ambientcss/guide/concept

Adjust the key and fill light intensity values to control scene contrast.

```text
key = 0.85, fill = 0.80  →  soft, diffuse  
key = 0.90, fill = 0.72  →  balanced  
key = 0.95, fill = 0.50  →  high contrast  
```

--------------------------------

### Publish with Changesets locally

Source: https://kikkupico.github.io/ambientcss/guide/contributing

Manually triggers the publish process using Changesets.

```bash
pnpm release:changeset:publish  
```

--------------------------------

### Import Ambient CSS

Source: https://kikkupico.github.io/ambientcss/ambient-css/usage

Include the base CSS file to enable Ambient styles in your project.

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

```

--------------------------------

### Add a changeset

Source: https://kikkupico.github.io/ambientcss/guide/contributing

Initiates the process to create a new changeset for versioning.

```bash
pnpm changeset  
```

--------------------------------

### Apply material variants to components

Source: https://kikkupico.github.io/ambientcss/ambient-components/examples

Shows how to use the material prop to switch between matte, shiny, and glass finishes for panels and buttons.

```typescript
import { AmbientPanel, AmbientButton } from "@ambientcss/components";  
  
export function MaterialsDemo() {  
  return (  
    <div style={{ display: "flex", gap: 16 }}>  
      {/* Default Matte finish */}  
      <AmbientPanel material="matte">  
        <AmbientButton material="matte">Matte Button</AmbientButton>  
      </AmbientPanel>  
  
      {/* Shiny finish with light-driven highlights */}  
      <AmbientPanel material="shiny">  
        <AmbientButton material="shiny">Shiny Button</AmbientButton>  
      </AmbientPanel>  
  
      {/* Modern Frosted Glass effect */}  
      <AmbientPanel material="glass">  
        <AmbientButton material="glass">Glass Button</AmbientButton>  
      </AmbientPanel>  
    </div>  
  );  
}  
```

--------------------------------

### Load and Configure AmbientCSS

Source: https://kikkupico.github.io/ambientcss/examples/css-basic

A complete HTML document showing the inclusion of the AmbientCSS stylesheet and the definition of lighting variables within a wrapper class.

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>AmbientCSS – Basic</title>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ambientcss/css/dist/ambient.css" />
<style>
body {
background: #e8edf2;
display: flex;
align-items: center;
justify-content: center;
min-height: 100vh;
margin: 0;
font-family: sans-serif;
}
.wrapper {
--amb-light-x: -1; --amb-light-y: -1;
--amb-key-light-intensity: 0.9; --amb-fill-light-intensity: 0.72;
--amb-light-hue: 220; --amb-light-saturation: 14%;
--amb-highlight-color: #7dd3fc; --amb-lume-hue: 190;
}
.panel { padding: 24px; display: flex; gap: 16px; align-items: center; }
button {
padding: 10px 20px;
font-size: 0.9rem;
font-weight: 600;
color: #1e293b;
border: 0;
cursor: pointer;
background: transparent;
}
</style>
</head>
<body>
Play Stop Record
Open Sandbox
```

--------------------------------

### Include the stylesheet

Source: https://kikkupico.github.io/ambientcss/ambient-css/install

Import the stylesheet using either CSS or JavaScript/TypeScript syntax.

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

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

--------------------------------

### Apply elevation levels

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

Demonstrates different shadow depths using elevation classes.

```html
<div class="ambient amb-surface amb-chamfer amb-elevation-1">Elevation 1</div>  
<div class="ambient amb-surface amb-chamfer amb-elevation-2">Elevation 2</div>  
<div class="ambient amb-surface amb-chamfer amb-elevation-3">Elevation 3</div>  
```

--------------------------------

### Configure Bright Baseline Settings

Source: https://kikkupico.github.io/ambientcss/ambient-css/usage

Override CSS variables in the root scope to adjust light intensity, position, and color properties.

```css
:root {  
  --amb-light-x: -1;  
  --amb-light-y: -1;  
  --amb-key-light-intensity: 0.9;  
  --amb-fill-light-intensity: 0.72;  
  --amb-light-hue: 220;  
  --amb-light-saturation: 14%;  
  --amb-highlight-color: #7dd3fc;  
  --amb-lume-hue: 190;  
}  

```

--------------------------------

### Apply Bright Reference Preset

Source: https://kikkupico.github.io/ambientcss/ambient-css/global-settings

A configuration preset for a bright scene, setting light direction, intensity, and color variables.

```css
:root {  
  --amb-light-x: -1;  
  --amb-light-y: -1;  
  --amb-key-light-intensity: 0.9;  
  --amb-fill-light-intensity: 0.72;  
  --amb-light-hue: 220;  
  --amb-light-saturation: 14%;  
  --amb-highlight-color: #7dd3fc;  
  --amb-lume-hue: 190;  
}  
```

--------------------------------

### Apply matte material

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

The default non-reflective finish for skeuomorphic surfaces.

```html
<div class="ambient amb-surface amb-mat-matte amb-elevation-1">Matte Surface</div>  
```

--------------------------------

### Configure Ambient CSS in React

Source: https://kikkupico.github.io/ambientcss/guide/getting-started

Import the required CSS files and wrap your application with the AmbientProvider to apply theme settings.

```javascript
import "@ambientcss/css/ambient.css";
import "@ambientcss/components/styles.css";

import { AmbientButton, AmbientKnob, AmbientProvider } from "@ambientcss/components";

export function Example() {
  return (
    <AmbientProvider
      theme={{
        lightX: -1,
        lightY: -1,
        keyLight: 0.9,
        fillLight: 0.72,
        lightHue: 220,
        lightSaturation: 14,
        highlightColor: "#7dd3fc",
        lumeHue: 190
      }}
    >
      <AmbientButton>Play</AmbientButton>
      <AmbientKnob value={40} onChange={(next) => console.log(next)} />
    </AmbientProvider>
  );
}
```

--------------------------------

### Typecheck workspaces

Source: https://kikkupico.github.io/ambientcss/guide/contributing

Runs type checking for all publishable and workspace applications.

```bash
pnpm typecheck  
```

--------------------------------

### Apply glass material

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

Creates a frosted glass effect with translucency and background blur.

```html
<div class="ambient amb-surface amb-mat-glass amb-elevation-3">Glass Surface</div>  
```

--------------------------------

### Basic AmbientButton usage

Source: https://kikkupico.github.io/ambientcss/ambient-components/button

Renders a standard button with ambient styling.

```jsx
<AmbientButton>Play</AmbientButton>  
```

--------------------------------

### Integrate AmbientCSS with PureCSS

Source: https://kikkupico.github.io/ambientcss/examples/css-purecss

A complete HTML template showing the required order of CSS imports and the application of AmbientCSS classes to PureCSS grid elements.

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>AmbientCSS + PureCSS</title>
<link rel="stylesheet" href="https://unpkg.com/purecss@3/build/pure-min.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ambientcss/css/dist/ambient.css" />
<style>
body { background: #e8edf2; padding: 40px; font-family: sans-serif; }
.wrapper {
--amb-light-x: -1; --amb-light-y: -1;
--amb-key-light-intensity: 0.9; --amb-fill-light-intensity: 0.72;
--amb-light-hue: 220; --amb-light-saturation: 14%;
--amb-highlight-color: #7dd3fc; --amb-lume-hue: 190;
}
.panel { padding: 24px; display: flex; gap: 12px; flex-wrap: wrap; align-items: center; }
.amb-btn { padding: 10px 20px; font-size: 0.9rem; color: #1e293b; border: 0; cursor: pointer; background: transparent; }
</style>
</head>
<body>
<div class="wrapper">
<div class="pure-g">
<div class="pure-u-1 pure-u-md-1-2">
<div class="ambient amb-surface amb-chamfer amb-elevation-2 amb-rounded-lg panel">
<button class="pure-button ambient amb-surface-convex amb-chamfer amb-elevation-1 amb-rounded-md amb-btn">Play</button>
<button class="pure-button ambient amb-surface-convex amb-chamfer amb-elevation-1 amb-rounded-md amb-btn">Stop</button>
</div>
</div>
</div>
</div>
</body>
</html>
```

--------------------------------

### Implementing AmbientProvider in a React App

Source: https://kikkupico.github.io/ambientcss/ambient-components/provider

Wraps application content with the AmbientProvider to apply custom theme configurations.

```typescript
import { AmbientProvider } from "@ambientcss/components";  
  
export function AppTheme({ children }: { children: React.ReactNode }) {  
  return (  
    <AmbientProvider  
      theme={{  
        lightX: -1,  
        lightY: -1,  
        keyLight: 0.9,  
        fillLight: 0.72,  
        lightHue: 220,  
        lightSaturation: 14,  
        highlightColor: "#7dd3fc",  
        lumeHue: 190  
      }}  
    >  
      {children}  
    </AmbientProvider>  
  );  
}  
```

--------------------------------

### AmbientCSS and Tailwind Integration

Source: https://kikkupico.github.io/ambientcss/examples/css-tailwind

A complete HTML document demonstrating the coexistence of AmbientCSS and Tailwind CSS utility classes.

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>AmbientCSS + Tailwind</title>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ambientcss/css/dist/ambient.css" />
<script src="https://cdn.tailwindcss.com"></script>
</head>
<body class="bg-slate-300 flex items-center justify-center min-h-screen">
<div style="--amb-light-x:-1; --amb-light-y:-1; --amb-key-light-intensity:0.9; --amb-fill-light-intensity:0.72; --amb-light-hue:220; --amb-light-saturation:14%; --amb-highlight-color:#7dd3fc; --amb-lume-hue:190;">
<div class="ambient amb-surface amb-chamfer amb-elevation-2 amb-rounded-lg flex gap-4 items-center p-6">
<button class="ambient amb-surface-convex amb-chamfer amb-elevation-1 amb-rounded-md px-5 py-2.5 text-sm font-semibold text-slate-800">
Play
</button>
<button class="ambient amb-surface-concave amb-fillet amb-elevation-1 amb-rounded-md px-5 py-2.5 text-sm font-semibold text-slate-800">
Record
</button>
</div>
</div>
</body>
</html>
```

--------------------------------

### Apply bounce animation

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

Adds a simple press animation for active or focus states.

```html
<button class="ambient amb-surface-convex amb-chamfer amb-elevation-1 amb-bounce">Press Me</button>  
```

--------------------------------

### Apply Warm Bright Preset

Source: https://kikkupico.github.io/ambientcss/ambient-css/global-settings

A configuration preset for a warm, bright scene, adjusting light direction and intensity for a specific aesthetic.

```css
:root {  
  --amb-light-x: -1;  
  --amb-light-y: -0.8;  
  --amb-key-light-intensity: 0.9;  
  --amb-fill-light-intensity: 0.7;  
  --amb-light-hue: 28;  
  --amb-light-saturation: 18%;  
  --amb-highlight-color: #fbbf24;  
  --amb-lume-hue: 36;  
}  
```

--------------------------------

### Create a channel strip with transport controls

Source: https://kikkupico.github.io/ambientcss/ambient-components/examples

Uses state management to control playback, arming, gain, and level settings within an AmbientPanel.

```typescript
import { useState } from "react";  
import {  
  AmbientButton,  
  AmbientFader,  
  AmbientKnob,  
  AmbientPanel,  
  AmbientSwitch  
} from "@ambientcss/components";  
  
export function ChannelStrip() {  
  const [level, setLevel] = useState(68);  
  const [gain, setGain] = useState(40);  
  const [armed, setArmed] = useState(false);  
  
  return (  
    <AmbientPanel  
      style={{  
        display: "grid",  
        gap: 16,  
        justifyItems: "center",  
        width: 220  
      }}  
    >  
      <AmbientButton>Play</AmbientButton>  
      <AmbientSwitch label="Arm" checked={armed} onCheckedChange={setArmed} led="#ef4444" />  
      <AmbientKnob label="Gain" value={gain} onChange={setGain} />  
      <AmbientFader label="Level" value={level} onChange={setLevel} />  
    </AmbientPanel>  
  );  
}  
```

--------------------------------

### Implement a Gain Control with AmbientKnob

Source: https://kikkupico.github.io/ambientcss/ambient-components/knob

Uses React state to manage the knob's value and updates it via the onChange callback.

```typescript
import { useState } from "react";  
  
function GainKnob() {  
  const [gain, setGain] = useState(45);  
  
  return (  
    <AmbientKnob  
      label="Gain"  
      value={gain}  
      min={0}  
      max={100}  
      step={1}  
      onChange={setGain}  
    />  
  );  
}  
```

--------------------------------

### Apply pending changesets

Source: https://kikkupico.github.io/ambientcss/guide/contributing

Updates versions and changelogs based on pending changesets.

```bash
pnpm version-packages  
```

--------------------------------

### Define a flat surface

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

Use the default flat surface class for standard panels and cards.

```html
<div class="ambient amb-surface amb-elevation-1">Flat Surface</div>  
```

--------------------------------

### AmbientProvider Component

Source: https://kikkupico.github.io/ambientcss/ambient-components/provider

The AmbientProvider component wraps your application to provide global theme overrides. It accepts a theme object, className, style, and children.

```APIDOC
## AmbientProvider

### Description
Applies theme values by writing Ambient CSS variables to `document.documentElement`.

### Props
- **theme** (AmbientTheme) - Optional - Global light/theme overrides.
- **className** (string) - Optional - Wrapper class.
- **style** (CSSProperties) - Optional - Wrapper inline style.
- **children** (ReactNode) - Required - Wrapped app content.

### AmbientTheme Fields
- **lightX** (number)
- **lightY** (number)
- **keyLight** (number)
- **fillLight** (number)
- **lightHue** (number)
- **lightSaturation** (number)
- **highlightColor** (string)
- **lumeHue** (number)

### Usage Example
```tsx
import { AmbientProvider } from "@ambientcss/components";

export function AppTheme({ children }: { children: React.ReactNode }) {
  return (
    <AmbientProvider
      theme={{
        lightX: -1,
        lightY: -1,
        keyLight: 0.9,
        fillLight: 0.72,
        lightHue: 220,
        lightSaturation: 14,
        highlightColor: "#7dd3fc",
        lumeHue: 190
      }}
    >
      {children}
    </AmbientProvider>
  );
}
```
```

--------------------------------

### Apply shiny material

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

Adds a light-reflective gradient for polished plastic or metal finishes.

```html
<div class="ambient amb-surface amb-mat-shiny amb-elevation-2">Shiny Surface</div>  
```

--------------------------------

### Apply filleted edge

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

Creates a soft, rounded transition.

```html
<div class="ambient amb-surface amb-fillet amb-elevation-2">Filleted Edge</div>  
```

--------------------------------

### Apply glow effect

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

Makes an element emit light based on its background color.

```html
<div class="ambient amb-surface-convex amb-rounded-full amb-glow" style="background-color: #ef4444;"></div>  
```

--------------------------------

### Import React Component Styles

Source: https://kikkupico.github.io/ambientcss/ambient-css/usage

Required additional import when using Ambient CSS with React components.

```javascript
import "@ambientcss/components/styles.css";  

```

--------------------------------

### Implement a horizontal and vertical control pair

Source: https://kikkupico.github.io/ambientcss/ambient-components/slider-fader

Demonstrates using AmbientSlider and AmbientFader together with React state to manage pan and level values.

```tsx
import { useState } from "react";  
  
function MixerPair() {  
  const [pan, setPan] = useState(50);  
  const [level, setLevel] = useState(72);  
  
  return (  
    <>  
      <AmbientSlider label="Pan" value={pan} min={0} max={100} step={1} onChange={setPan} />  
      <AmbientFader label="Level" value={level} min={0} max={100} step={1} onChange={setLevel} />  
    </>  
  );  
}  
```

--------------------------------

### Define Surface Grammar Structure

Source: https://kikkupico.github.io/ambientcss/guide/concept

Overview of the CSS classes used to define element structure, surface type, edge treatment, and elevation.

```text
┌─────────────┬──────────────────────────────────┐  
│ Structure   │ ambient                          │  
│ Surface     │ amb-surface / -concave / -convex  │  
│ Edge        │ amb-chamfer / amb-fillet          │  
│ Depth       │ amb-elevation-0 … amb-elevation-3 │  
└─────────────┴──────────────────────────────────┘  
```

--------------------------------

### Apply chamfered edge

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

Creates a hard, angled transition for an industrial look.

```html
<div class="ambient amb-surface amb-chamfer amb-elevation-2">Chamfered Edge</div>  
```

--------------------------------

### AmbientSlider and AmbientFader Props

Source: https://kikkupico.github.io/ambientcss/ambient-components/slider-fader

The following properties are supported by both AmbientSlider and AmbientFader components.

```APIDOC
## Component Properties

### value (number)
- Required
- The current value of the component.

### min (number)
- Optional (Default: 0)
- The minimum allowed value.

### max (number)
- Optional (Default: 100)
- The maximum allowed value.

### step (number)
- Optional (Default: 1)
- The increment step for value changes.

### label (string)
- Optional
- A descriptive label for the component.

### onChange ((nextValue: number) => void)
- Optional
- Callback function triggered when the value changes.
```

--------------------------------

### Integrate AmbientCSS with React-Bootstrap

Source: https://kikkupico.github.io/ambientcss/examples/react-bootstrap

Uses AmbientProvider to wrap AmbientCSS components inside a Bootstrap grid layout.

```tsx
import React, { useState } from "react";
import { Container, Row, Col, Stack } from "react-bootstrap";
import {
AmbientProvider,
AmbientPanel,
AmbientButton,
AmbientKnob,
AmbientSwitch,
} from "@ambientcss/components";
  

export default function App() {
const [gain, setGain] = useState(50);
const [armed, setArmed] = useState(false);
  

return (
<div style={{ background: "#e8edf2", minHeight: "100vh" }}>
<Container className="py-5">
<Row className="justify-content-center">
<Col xs="auto">
<AmbientProvider theme={{ lightHue: 220, lightSaturation: 14, lumeHue: 190, keyLight: 0.9, fillLight: 0.72 }}>
<AmbientPanel style={{ padding: 24 }}>
<Stack gap={3} className="align-items-center">
<AmbientButton>Play</AmbientButton>
<AmbientSwitch label="Arm" checked={armed} onCheckedChange={setArmed} led="#ef4444" />
<AmbientKnob label="Gain" value={gain} onChange={setGain} />
</Stack>
</AmbientPanel>
</AmbientProvider>
</Col>
</Row>
</Container>
</div>
);
}
```

--------------------------------

### AmbientPanel Component Usage

Source: https://kikkupico.github.io/ambientcss/ambient-components/panel

The AmbientPanel component is used as a wrapper for content, applying specific ambient styling classes automatically. It accepts all standard HTMLDivElement attributes.

```APIDOC
## AmbientPanel Component

### Description
AmbientPanel is a convenience wrapper over the standard HTML `div` element that applies default ambient panel classes for consistent styling.

### Props
- **HTMLAttributes<HTMLDivElement>** - Inherits all standard attributes available to a div element.

### Default Class Stack
`ambient amb-surface amb-chamfer amb-elevation-2 ambx-panel`

### Example
```tsx
import { AmbientPanel, AmbientButton } from "@ambientcss/components";

export function RackPanel() {
  return (
    <AmbientPanel className="my-panel-layout">
      <AmbientButton>Armed</AmbientButton>
    </AmbientPanel>
  );
}
```
```

--------------------------------

### AmbientSwitch with Custom LED Color

Source: https://kikkupico.github.io/ambientcss/ambient-components/switch

Pass a color string to the led prop to override the default green indicator color.

```jsx
<AmbientSwitch label="Record" led="#ef4444" defaultChecked />
```

--------------------------------

### Uncontrolled AmbientSwitch

Source: https://kikkupico.github.io/ambientcss/ambient-components/switch

Use the defaultChecked prop to manage the initial state of the switch without external state management.

```jsx
<AmbientSwitch label="Power" defaultChecked />
```

--------------------------------

### AmbientKnob Component API

Source: https://kikkupico.github.io/ambientcss/ambient-components/knob

The AmbientKnob component is a React-based control that maps vertical drag gestures to a numeric value. It supports configuration for range, precision, and event handling.

```APIDOC
## AmbientKnob Component

### Description
A vertical-drag control that maps pointer movement to a numeric value. Dragging up increases the value, while dragging down decreases it.

### Props
- **value** (number) - Required - The current numeric value of the knob.
- **min** (number) - Optional - The minimum allowed value. Default: 0.
- **max** (number) - Optional - The maximum allowed value. Default: 100.
- **step** (number) - Optional - The increment/decrement step size. Default: 1.
- **label** (string) - Optional - A label for the knob.
- **onChange** ((nextValue: number) => void) - Optional - Callback function triggered when the value changes.

### Usage Example
```jsx
import { useState } from "react";

function GainKnob() {
  const [gain, setGain] = useState(45);

  return (
    <AmbientKnob
      label="Gain"
      value={gain}
      min={0}
      max={100}
      step={1}
      onChange={setGain}
    />
  );
}
```
```

--------------------------------

### Change the Emissive Hue

Source: https://kikkupico.github.io/ambientcss/ambient-css/global-settings

Override the default emissive hue by setting the --amb-lume-hue variable on the :root element.

```css
:root {  
  --amb-lume-hue: 190; /* cyan accent */  
}  
```

--------------------------------

### Define a convex surface

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

Apply for raised elements like buttons, knobs, or faders.

```html
<div class="ambient amb-surface-convex amb-elevation-1">Convex Surface</div>  
```

--------------------------------

### AmbientSwitch Component API

Source: https://kikkupico.github.io/ambientcss/ambient-components/switch

The AmbientSwitch component is a UI element used for toggling states. It supports various props for configuration, including state management, sizing, and visual customization.

```APIDOC
## AmbientSwitch Component

### Description
A circular switch button with an optional LED indicator. It supports both controlled and uncontrolled state management.

### Props
- **checked** (boolean) - Optional - Controlled state of the switch.
- **defaultChecked** (boolean) - Optional - Uncontrolled initial state (default: false).
- **onCheckedChange** ((checked: boolean) => void) - Optional - Callback function triggered when the switch is toggled.
- **size** ("sm" | "md" | "lg") - Optional - Defines the size variant of the switch (default: "md").
- **label** (string) - Optional - An optional visible label for the switch.
- **led** (boolean | string) - Optional - Enables an LED indicator. Use `true` for the default green color or a string for a custom CSS color value.

### Usage Examples

#### Uncontrolled
<AmbientSwitch label="Power" defaultChecked />

#### Controlled
const [enabled, setEnabled] = useState(false);
<AmbientSwitch checked={enabled} onCheckedChange={setEnabled} label="Bypass" />

#### Custom LED color
<AmbientSwitch label="Record" led="#ef4444" defaultChecked />
```

--------------------------------

### Implement AmbientPanel in React

Source: https://kikkupico.github.io/ambientcss/ambient-components/panel

Use AmbientPanel to wrap child components like AmbientButton within a styled container.

```tsx
import { AmbientPanel, AmbientButton } from "@ambientcss/components";  
  
export function RackPanel() {  
  return (  
    <AmbientPanel className="my-panel-layout">  
      <AmbientButton>Armed</AmbientButton>  
    </AmbientPanel>  
  );  
}  
```

--------------------------------

### AmbientButton with custom click handler

Source: https://kikkupico.github.io/ambientcss/ambient-components/button

Attaches a custom onClick event handler to the button component.

```jsx
<AmbientButton onClick={() => console.log("trigger")}>Trigger</AmbientButton>  
```

--------------------------------

### Controlled AmbientSwitch

Source: https://kikkupico.github.io/ambientcss/ambient-components/switch

Use the checked and onCheckedChange props to manage the switch state via React state hooks.

```jsx
const [enabled, setEnabled] = useState(false);  
  
<AmbientSwitch checked={enabled} onCheckedChange={setEnabled} label="Bypass" />
```

--------------------------------

### Define a concave surface

Source: https://kikkupico.github.io/ambientcss/ambient-css/classes

Apply for inset areas like screens, meters, or depressed buttons.

```html
<div class="ambient amb-surface-concave amb-elevation-1">Concave Surface</div>  
```

--------------------------------

### Disabled AmbientButton usage

Source: https://kikkupico.github.io/ambientcss/ambient-components/button

Renders a button in a disabled state using the standard HTML disabled attribute.

```jsx
<AmbientButton disabled>Bypass</AmbientButton>  
```
Tokens:
Raw