# OpenGlass UI: Complete Guide to the Liquid Glass React Library

> Architecture and integration guide for OpenGlass UI: 40 native components, CSS, SVG SDF, and WebGL2 renderers, token systems, Next.js SSR, and WCAG 2.2.

OpenGlass UI is a modern React and web component library designed to deliver physical Liquid Glass aesthetics across digital interfaces. Moving far beyond trivial CSS implementations relying solely on `backdrop-filter: blur()`, OpenGlass UI pairs physically based refraction models, Signed Distance Fields (SDF), hardware-accelerated WebGL2 lenses, and native WCAG 2.2 accessibility compliance.

This guide provides an exhaustive engineering breakdown of the library: from three-tier rendering pipelines and Next.js App Router integration to token-driven theming and GPU performance optimization.

---

## 1. Liquid Glass Concept and Core Capabilities of OpenGlass UI

### 1.1. The Philosophy of Liquid Glass: Bridging Native DOM and Optics

Traditional glassmorphic implementations are frequently criticized for poor legibility and excessive CPU overhead. OpenGlass UI resolves these limitations through architectural decoupling:
- **Semantic Foundation:** All 40 included components render onto native HTML elements (`<button>`, `<input>`, `<dialog>`), preserving browser keyboard navigation and assistive technology trees.
- **Optical Materials:** The visual surface dynamically adapts to its background layer using tinting, beveling, specular highlights, and edge refraction.
- **Graceful Fallbacks:** When running on low-powered mobile devices or under operating system accessibility settings like reduced transparency, the system automatically degrades to high-contrast opaque CSS surfaces.

### 1.2. Comparative Matrix of the Three Renderers: CSS, SVG Refraction, and WebGL2

OpenGlass UI incorporates three dedicated rendering pipelines tailored for different UI surfaces:

```mermaid
flowchart TD
    A["GlassSurface Render Request"] --> B{"Source Type & Boundary Geometry"}
    B -->|"Arbitrary DOM / Controls / Text"| C["1. CSS Renderer (Default: performant blur, border, shadow)"]
    B -->|"Closed Geometric Bounds (Rounded Rect, Capsule)"| D["2. SVG / SDF Renderer (True light refraction via Displacement Map)"]
    B -->|"Dynamic Media (Video, Canvas, Images)"| E["3. WebGL2 Renderer (Hardware chromatic dispersion & IOR lenses)"]
```

| Renderer Pipeline | Optical Capabilities | GPU Overhead | Browser Support | Recommended Use Case |
| :--- | :--- | :--- | :--- | :--- |
| **CSS (Auto)** | Tint, blur, border highlights, shadows | Minimal | 99.8% (All modern browsers) | Buttons, form inputs, cards, navigation, lists |
| **SDF / SVG** | Contour light bending (Index of Refraction) | Moderate | All browsers supporting SVG filters | Modals, floating dock bars, segmented tabs |
| **WebGL2** | Realistic chromatic dispersion, lenses | High | Requires WebGL2 support | Media players, interactive glass over 3D/video |

---

## 2. Package Architecture and Dependency Installation

### 2.1. Modular Design: The open-glass-ui Facade and Internal Workspaces

The public npm package `open-glass-ui` consolidates four internal modular workspaces:

```mermaid
flowchart LR
    A["open-glass-ui (Public npm Facade)"] --> B["@open-glass-ui/core (Geometry, SDF math, tokens without React)"]
    A --> C["@open-glass-ui/renderers (CSS materials, WebGL2 shaders, SVG helpers)"]
    A --> D["@open-glass-ui/react (State providers, hooks, SSR hydration lifecycle)"]
    A --> E["@open-glass-ui/recipes (40 ready UI recipes on native DOM)"]
```

> [!WARNING]
> Direct imports from internal workspaces (such as `@open-glass-ui/core` or `@open-glass-ui/recipes`) are private implementation boundaries. Always import via the public facade:
> - `open-glass-ui` — primary React components, providers, and hooks.
> - `open-glass-ui/webgl` — hardware WebGL2 surface subsystem.
> - `open-glass-ui/core` — pure math utilities for theme calculations, contrast ratios, and colors in server components.

### 2.2. Package Installation and Global Style Ingestion

Install OpenGlass UI using your preferred package manager:

```bash
npm install open-glass-ui
# or
pnpm add open-glass-ui
```

Import global stylesheet tokens at your application entry point (e.g. `src/app/layout.tsx` or `src/main.tsx`):

```typescript
// Required import for base CSS materials:
import "open-glass-ui/styles.css";
import { Button, Glass, GlassSystemProvider } from "open-glass-ui";

export function RootApplication() {
  return (
    <GlassSystemProvider
      renderer="auto"
      quality="auto"
      motion="system"
      theme={{
        appearance: "system",
        defaultAppearance: "dark",
        theme: { preset: "neutral", contrast: "high", radius: "balanced" },
      }}
    >
      <main className="min-h-screen bg-slate-950 p-8">
        <Glass material="regular" interactive>
          <Button variant="primary">Get Started</Button>
        </Glass>
      </main>
    </GlassSystemProvider>
  );
}
```

---

## 3. Theme System Configuration: Palettes, Contrast, and CSS Tokens

### 3.1. Theme Orchestration: Presets, Appearance Modes, and Corner Radii

The OpenGlass UI theming engine is structured across three axes:
1. **Appearance Mode:** Accepts `light`, `dark`, or `system`. When set to `system`, the server renders a deterministic `defaultAppearance`, synchronizing with `prefers-color-scheme` post-hydration.
2. **Palette Presets:** Choose from built-in validated palettes (`neutral`, `cobalt`, `teal`, `violet`, `coral`, `amber`) or override with custom hex values via `accent`, `secondary`, and `tertiary`.
3. **Corner Radius:** Select between `sharp`, `balanced` (standard 12–16px), or `soft` (organic 24–28px).

### 3.2. Semantic Token Matrix (--ogui-*) and WCAG Contrast Verification

All component surfaces map to stable CSS variables:

```css
/* Base surfaces and borders */
--ogui-color-background: #090d16;
--ogui-color-surface: rgba(15, 23, 42, 0.65);
--ogui-color-border: rgba(255, 255, 255, 0.12);
--ogui-color-text: #f8fafc;
--ogui-color-muted: #94a3b8;

/* Accent states and focus indicators */
--ogui-color-accent: #38bdf8;
--ogui-color-accent-ink: #031525;
--ogui-color-focus: #0284c7;

/* Radii and optical material parameters */
--ogui-radius-control: 8px;
--ogui-radius-surface: 16px;
--ogui-material-blur: 16px;
--ogui-material-bevel: 1px;
```

> 💡 **Contrast Verification Rule:** Use the exported `contrastRatio(colorA, colorB)` utility from `open-glass-ui/core`. Contrast must measure at least 4.5:1 for body copy and 3:1 for large headings to fulfill WCAG 2.2 AA.

---

## 4. Component Catalog: Comprehensive Review of 40 Native Recipes

### 4.1. Component Taxonomy: Controls, Overlays, Navigation, and Forms

The package ships with 40 production-ready recipes built on native DOM elements:

| Functional Category | Included UI Components |
| :--- | :--- |
| **Action Controls** | `Button`, `IconButton`, `ToggleButton`, `SegmentedControl`, `Switch`, `Slider`, `Stepper` |
| **Navigation & Layout** | `Toolbar`, `Dock`, `Tabs`, `Breadcrumbs`, `Pagination`, `Menu`, `MenuItem` |
| **Overlays & Dialogs** | `Dialog`, `Drawer`, `Popover`, `Tooltip`, `Toast`, `Alert`, `Banner` |
| **Form Inputs** | `TextField`, `Textarea`, `NumberField`, `SearchField`, `Select`, `Checkbox`, `RadioGroup`, `FileDropzone` |
| **Data Presentation** | `Card`, `Stat`, `Badge`, `Avatar`, `AvatarGroup`, `Accordion`, `Progress`, `Meter`, `Spinner`, `Skeleton`, `MediaControls` |

### 4.2. Accessibility Standards (a11y): ARIA Bindings, Focus Rings, and State Logic

Adhere to core accessibility invariants when integrating OpenGlass UI recipes:
- **Mandatory Icon Labels:** `IconButton` and `SegmentedControl` strictly require explicit `aria-label` strings for screen readers.
- **Deterministic Focus Restoration:** `Dialog` and `Drawer` primitives automatically retain and restore keyboard focus to the triggering element upon dismissal.
- **Multi-Modal State Signaling:** Never communicate selected, disabled, or error states solely via transparency or color. Always provide textual or icon-based status indicators.

---

## 5. Working with Renderers: From Universal CSS to Hardware WebGL2

### 5.1. Declarative SVG/SDF Refraction for Closed Geometric Geometries

For floating control panels or standalone cards, enable physical light refraction using Signed Distance Fields:

```typescript
import React from "react";
import { Glass, SdfFilterDefinition, useSdfFilter } from "open-glass-ui";

const panelGeometry = {
  kind: "rounded-rect",
  width: 360,
  height: 200,
  cornerRadius: 24,
} as const;

export function RefractedControlPanel({ children }: { children: React.ReactNode }) {
  const filter = useSdfFilter({
    id: "main-panel-filter",
    width: 360,
    height: 200,
    geometry: panelGeometry,
    quality: "medium",
  });

  return (
    <div className="relative inline-block">
      <SdfFilterDefinition filter={filter} />
      <Glass 
        renderer="sdf-svg" 
        filterId={filter.filterId} 
        geometry={panelGeometry}
        material="regular"
      >
        <div className="p-6 text-slate-100">
          {children}
        </div>
      </Glass>
    </div>
  );
}
```

### 5.2. Hardware Optical Lenses in WebGL2 Over Live Video and Canvas

When rendering over live video, canvas streams, or 3D viewports, `open-glass-ui/webgl` layers hardware lenses with Index of Refraction (IOR) physics:

```typescript
"use client";

import React, { useRef } from "react";
import { GlassProvider } from "open-glass-ui";
import { WebGLGlassSurface } from "open-glass-ui/webgl";

const opticalMaterial = {
  thickness: 0.62,
  ior: 1.48,           // Glass refraction index
  dispersion: 0.015,   // Edge chromatic dispersion
  edgeStrength: 0.5,
  bevel: 0.7,
  frost: 0.2,
};

export function InteractiveVideoLens() {
  const videoRef = useRef<HTMLVideoElement>(null);

  return (
    <GlassProvider>
      <div className="relative overflow-hidden rounded-2xl">
        <video 
          ref={videoRef} 
          src="/ambient-flow.mp4" 
          autoPlay 
          loop 
          muted 
          playsInline 
          className="w-full h-auto block"
        />
        <WebGLGlassSurface
          sourceRef={videoRef}
          continuous
          maxDevicePixelRatio={2}
          lenses={[
            {
              x: 180,
              y: 120,
              width: 240,
              height: 120,
              radius: 0.4,
              material: opticalMaterial,
            },
          ]}
        />
      </div>
    </GlassProvider>
  );
}
```

---

## 6. Next.js App Router Integration and Server-Side Rendering (SSR)

### 6.1. Clean Hydration: Isolating Client Boundaries and Server-Safe Core Utilities

OpenGlass UI is built for Next.js App Router conventions. Server rendering never references `window`, `document`, or WebGL contexts.

Encapsulate client-side state in a dedicated provider component:

```typescript
// src/components/providers/GlassRootProvider.tsx
"use client";

import React from "react";
import "open-glass-ui/styles.css";
import { GlassSystemProvider } from "open-glass-ui";

export function GlassRootProvider({ children }: { children: React.ReactNode }) {
  return (
    <GlassSystemProvider
      renderer="auto"
      quality="auto"
      theme={{
        appearance: "system",
        defaultAppearance: "dark",
      }}
    >
      {children}
    </GlassSystemProvider>
  );
}
```

Import pure utility functions for color calculations into Server Components directly from `open-glass-ui/core`:

```typescript
// src/app/page.tsx (Server Component)
import { createGlassTheme } from "open-glass-ui/core";
import { GlassRootProvider } from "@/components/providers/GlassRootProvider";

export default function Page() {
  const staticTheme = createGlassTheme({ preset: "neutral", contrast: "high" });

  return (
    <GlassRootProvider>
      <h1 className="text-2xl font-bold">SSR Initialized Successfully</h1>
    </GlassRootProvider>
  );
}
```

### 6.2. Preventing Layout Flicks and Dynamic prefers-color-scheme Synchronization

To eliminate hydration mismatches:
- Avoid branching initial JSX output on viewport dimensions (`window.innerWidth`).
- Declare `defaultAppearance="dark"` to ensure deterministic server and client initial markup.

---

## 7. Performance Engineering and Graphics Pipeline Optimization

### 7.1. Minimizing GPU Overhead: DPR Clamping and Selective Glass Adoption

Extensive backdrop filtering can tax consumer GPUs. Follow these production rules:
- **Clamp Device Pixel Ratio:** Always constrain `maxDevicePixelRatio={2}` on WebGL surfaces. Rendering on Retina displays at DPR 3+ quadruples pixel shading cost with zero perceptible quality gain.
- **Selective Layering:** Restrict glass materials to top-level navigation (Headers, Docks, Modals). Routine list items should employ opaque or semi-transparent flat CSS backgrounds.
- **Pointer-Rate Updates:** For interactive mouse-tracking effects, mutate CSS variables or `transform` matrices via element refs rather than triggering React re-renders on every animation frame.

### 7.2. Signed Distance Field (SDF) Caching and Resize Throttling

Generating SDF displacement maps is compute-intensive. The `useSdfFilter` hook automatically caches maps keyed to geometric parameters. During viewport resizing, the library automatically drops render quality, restoring full fidelity only after resize events settle.

---

## 8. Troubleshooting Matrix and Frequently Asked Questions (FAQ)

### 8.1. Diagnosing Rendering Artifacts, Contrast Failures, and Memory Leaks

| Symptom / Error | Root Cause | Engineering Solution |
| :--- | :--- | :--- |
| Glass effect absent (flat white/gray) | Missing global stylesheet import | Add `import "open-glass-ui/styles.css";` to root layout |
| Text illegible over bright photography | High transparency in `material="clear"` | Switch to `material="regular"` or `material="frosted"` for increased backing opacity |
| Frame drops during page scroll | Too many active `sdf-svg` filter nodes | Revert bulk elements to `renderer="auto"` (CSS) |
| `WebGL context lost` runtime warning | Exceeded maximum concurrent canvas contexts | Limit active lenses to 6 per single `WebGLGlassSurface` |

### 8.2. Frequently Asked Questions by Frontend Engineers Adopting OpenGlass UI

> ❓ **Is OpenGlass UI compatible with Tailwind CSS?**  
> Yes. OpenGlass UI does not conflict with Tailwind classes. You can safely compose utility classes (`className="flex items-center gap-4 p-6"`) alongside `material` and `interactive` props.

> ❓ **Is OpenGlass UI ready for enterprise production?**  
> The package is currently in pre-release. Its architecture and public API are stabilized, but reviewing release changelogs before upgrading minor versions is strongly recommended.

> ❓ **How does the library handle Windows High Contrast Mode?**  
> OpenGlass UI detects `forced-colors: active` media queries automatically, stripping all translucency effects and applying solid high-contrast borders and standard system colors.