# OpenGlass UI: Vollständiger Leitfaden zur Liquid-Glass-Bibliothek für React

> Architektur und Implementierung von OpenGlass UI: 40 native Komponenten, CSS-, SVG-SDF- und WebGL2-Renderer, Token-Konfiguration, SSR in Next.js sowie WCAG 2.2.

OpenGlass UI ist eine moderne React- und Web-Komponentenbibliothek, die entwickelt wurde, um die Ästhetik des „Liquid Glass“ (flüssiges Glas) in digitalen Interfaces zu realisieren. Im Gegensatz zu primitiven CSS-Implementierungen mit einfachem `backdrop-filter: blur()` kombiniert OpenGlass UI echte physikalische Modelle der Lichtbrechung (Refraktion), Unterstützung für Signed Distance Fields (SDF), hardwarebeschleunigtes Rendering via WebGL2 sowie native Barrierefreiheit gemäß dem WCAG 2.2-Standard.

Dieses Handbuch deckt die Architektur der Bibliothek, die Prinzipien des dreistufigen Renderings, die praktische Integration in Next.js App Router, das Design-Token-System sowie Regeln zur Performance-Optimierung ab.

---

## 1. Das Konzept von Liquid Glass und die Fähigkeiten von OpenGlass UI

### 1.1. Die Philosophie des flüssigen Glases: Kombination aus nativem DOM und optischen Effekten

Klassischer Glassmorphismus wird oft aufgrund hoher Prozessorlast und schlechter Textlesbarkeit kritisiert. OpenGlass UI löst dieses Problem durch eine strikte Trennung der Schichten:
- **Semantisches Gerüst:** Alle 40 Komponenten der Bibliothek basieren ausschließlich auf nativen HTML-Tags (`<button>`, `<input>`, `<dialog>`), wodurch Tastaturnavigation und Screenreader-Unterstützung erhalten bleiben.
- **Optische Materialien:** Die visuelle Materialschicht passt sich an den Hintergrund mittels adaptivem Kontrast, Tönung, Facetten (Bevels) und Reflexionen an.
- **Hierarchie des Fallbacks (Graceful Degradation):** Wenn ein Gerät keine Hardware-Berechnungen unterstützt oder der Nutzer im Systemmodus reduzierte Transparenz aktiviert hat, wechselt die Bibliothek nahtlos zu undurchsichtigen CSS-Materialien, ohne das Markup zu verzerren.

### 1.2. Vergleichsmatrix der drei Renderer: CSS, SVG-Refraktion und WebGL2

OpenGlass UI bietet drei komplementäre Grafik-Pipelines, abhängig von der Komplexität der Oberfläche:

```mermaid
flowchart TD
    A["GlassSurface запит на рендеринг"] --> B{"Тип джерела та цільова форма"}
    B -->|"Довільний DOM / Контроли / Текст"| C["1. CSS Renderer (За замовчуванням: швидкий blur, border, shadow)"]
    B -->|"Замкнена геометрія DOM (Прямокутник, капсула)"| D["2. SVG / SDF Renderer (Справжнє заломлення світла через Displacement Map)"]
    B -->|"Динамічне медіа (Відео, Canvas, Зображення)"| E["3. WebGL2 Renderer (Апаратні лінзи з дисперсією IOR у реальному часі)"]
```

| Renderer | Optische Fähigkeiten | GPU-Last | Browserunterstützung | Optimales Einsatzgebiet |
| :--- | :--- | :--- | :--- | :--- |
| **CSS (Auto)** | Tönung, Blur, Ränder, Schatten | Minimal | 99,8 % (Alle modernen Plattformen) | Buttons, Formularfelder, Karten, Navigation, Listen |
| **SDF / SVG** | Lichtbrechung entlang der Kontur (IOR) | Mittel | Alle Browser mit SVG-Filter-Support | Modals, schwebende Dock-Panels, Tabs |
| **WebGL2** | Realistische chromatische Dispersion, Linsen | Hoch | Erfordert WebGL2-Support | Media Player, interaktive Linsen über 3D/Video |

---

## 2. Paketarchitektur und Installation

### 2.1. Modulare Struktur: Fassade open-glass-ui und interne Pakete

Die öffentliche Fassade `open-glass-ui` bündelt vier interne Workspace-Pakete und trennt klar die Zuständigkeiten der Komponenten:

```mermaid
flowchart LR
    A["open-glass-ui (Публічний npm-фасад)"] --> B["@open-glass-ui/core (Геометрія, математика SDF, токени без React)"]
    A --> C["@open-glass-ui/renderers (CSS-матеріали, шейдери WebGL2, SVG-хелпери)"]
    A --> D["@open-glass-ui/react (Провайдери стану, хуки, життєвий цикл SSR)"]
    A --> E["@open-glass-ui/recipes (40 готових UI-компонентів на нативному DOM)"]
```

> [!WARNING]
> Der direkte Import von Komponenten aus internen Paketen (z. B. `@open-glass-ui/core` oder `@open-glass-ui/recipes`) ist streng untersagt. Verwenden Sie nur die öffentlichen Subpfade der Fassade:
> - `open-glass-ui` — Haupt-React-Komponenten, Provider und Hooks.
> - `open-glass-ui/webgl` — Subsystem für hardwarebeschleunigte WebGL2-Oberflächen.
> - `open-glass-ui/core` — Reine Utilities für Themenmathematik, Kontrastberechnung und Farbverwaltung für Server Components.

### 2.2. Abhängigkeiten installieren und Basis-Stil-Konfiguration

Installieren Sie die Bibliothek über Ihren bevorzugten Paketmanager:

```bash
npm install open-glass-ui
# або
pnpm add open-glass-ui
```

Binden Sie die globalen Styles am Einstiegspunkt Ihrer Anwendung ein (z. B. in `src/app/layout.tsx` oder `src/main.tsx`):

```typescript
// Обов'язковий імпорт базових CSS-матеріалів:
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">Розпочати роботу</Button>
        </Glass>
      </main>
    </GlassSystemProvider>
  );
}
```

---

## 3. Einrichtung des Themensystems: Paletten, Kontraste und CSS-Tokens

### 3.1. Themensteuerung: Presets, Appearance-Modi und Radius-Einstellungen

Das Thema in OpenGlass UI basiert auf drei miteinander verbundenen Dimensionen:
1. **Appearance (Erscheinungsbild):** Akzeptiert die Werte `light`, `dark` oder `system`. Bei `system` liefert der Server einen sicheren `defaultAppearance`, während auf Client-Seite die Media Query `prefers-color-scheme` ausgewertet wird.
2. **Farbpalette (Presets):** Verfügbar sind geprüfte vorgefertigte Schemata (`neutral`, `cobalt`, `teal`, `violet`, `coral`, `amber`) oder eigene Werte über die Parameter `accent`, `secondary`, `tertiary`.
3. **Radius (Abgerundete Ecken):** Optionen sind `sharp` (minimal), `balanced` (standard, 12–16 px) und `soft` (organisch, 24–28 px).

### 3.2. Matrix semantischer Tokens --ogui-* und Kontrastprüfung (WCAG)

Alle Komponenten werden über stabile CSS-Variablen gestylt:

```css
/* Базові поверхні та межі */
--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;

/* Акцентні стани та фокус */
--ogui-color-accent: #38bdf8;
--ogui-color-accent-ink: #031525;
--ogui-color-focus: #0284c7;

/* Радіуси та оптичні властивості матеріалу */
--ogui-radius-control: 8px;
--ogui-radius-surface: 16px;
--ogui-material-blur: 16px;
--ogui-material-bevel: 1px;
```

> 💡 **Regel zur Kontrastprüfung:** Verwenden Sie die exportierte Funktion `contrastRatio(colorA, colorB)` aus `open-glass-ui/core`. Der Textkontrast muss gemäß WCAG 2.2 AA mindestens 4,5:1 für normalen Text und 3:1 für große Überschriften betragen.

---

## 4. Komponenten-Katalog: Überblick über 40 Rezepte auf nativem DOM

### 4.1. Kategorien fertiger Komponenten: Controls, Overlays, Navigation und Forms

Das Paket enthält 40 sofort einsatzbereite Komponenten mit nativem Markup:

| Kategorie | Komponenten in der Bibliothek |
| :--- | :--- |
| **Aktions-Elemente & Controls** | `Button`, `IconButton`, `ToggleButton`, `SegmentedControl`, `Switch`, `Slider`, `Stepper` |
| **Navigation & Container** | `Toolbar`, `Dock`, `Tabs`, `Breadcrumbs`, `Pagination`, `Menu`, `MenuItem` |
| **Overlays & Popups** | `Dialog`, `Drawer`, `Popover`, `Tooltip`, `Toast`, `Alert`, `Banner` |
| **Forms & Dateneingabe** | `TextField`, `Textarea`, `NumberField`, `SearchField`, `Select`, `Checkbox`, `RadioGroup`, `FileDropzone` |
| **Informationsdarstellung** | `Card`, `Stat`, `Badge`, `Avatar`, `AvatarGroup`, `Accordion`, `Progress`, `Meter`, `Spinner`, `Skeleton`, `MediaControls` |

### 4.2. Standards für Barrierefreiheit (a11y): ARIA-Labels, Fokusmanagement und Zustände

Bei der Verwendung von OpenGlass UI-Komponenten müssen folgende Barrierefreiheitsregeln eingehalten werden:
- **Pflicht-`aria-label` für Icons:** `IconButton` und `SegmentedControl` erfordern eine explizite textliche Beschreibung für Screenreader.
- **Fokus-Rückgabe in Dialogen:** In `Dialog` und `Drawer` kehrt der Fokus beim Schließen automatisch zum aufrufenden Element zurück.
- **Doppelte Kodierung von Zuständen:** Markieren Sie Auswahl-, Fehler- oder Blockierzustände nicht allein durch Transparenz oder Farbe. Ergänzen Sie diese immer durch eine Icon-Änderung oder ein Text-Badge.

---

## 5. Arbeit mit Renderern: Vom basischen CSS bis zum optionalen WebGL2

### 5.1. Deklarative SVG/SDF-Refraktion für geschlossene geometrische Figuren

Für schwebende Karten oder Bedienpanels kann echte Lichtbrechung über Signed Distance Fields (SDF) aktiviert werden:

```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. Hardwarebeschleunigte optische Linsen in WebGL2 über Video und Canvas

Wenn auf der Seite Videos, interaktive Grafiken oder 3D-Szenen wiedergegeben werden, ermöglicht das Modul `open-glass-ui/webgl` das Overlay einer hardwarebeschleunigten Linse mit physikalischem Brechungsindex (IOR):

```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,           // Показник заломлення (коефіцієнт скла)
  dispersion: 0.015,   // Хроматична дисперсія по краях
  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. Integration in Next.js App Router und Server Side Rendering (SSR)

### 6.1. Hydration ohne Konflikte: Isolation von Client-Grenzen und Core-Utilities

OpenGlass UI ist für modernes Server Side Rendering konzipiert. Der Server versucht niemals, auf `window`, `document` oder den WebGL-Kontext zuzugreifen.

Erstellen Sie den Root-Provider in einem Client 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>
  );
}
```

Importieren Sie reine Funktionen zur Berechnung von Farben oder Themeschemas in Server Components aus `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">Серверний рендеринг готовий</h1>
    </GlassRootProvider>
  );
}
```

### 6.2. Vermeidung von Markup-Divergenzen und Umgang mit prefers-color-scheme

Um Hydration Mismatch-Warnungen zu vermeiden:
- Verwenden Sie keine ternären Operatoren, die von `window.innerWidth` abhängen, im initialen Render.
- Nutzen Sie das Prop `defaultAppearance="dark"`, um das initiale HTML zwischen Server und Client zu stabilisieren.

---

## 7. Performance und Optimierung der Grafik-Pipeline

### 7.1. Reduktion der GPU-Last: DPR-Limits und selektiver Glaseinsatz

Massives Stapeln von Ebenen mit Hintergrund-Blur kann selbst diskrete Grafikkarten überlasten. Befolgen Sie diese Empfehlungen:
- **Device Pixel Ratio begrenzen:** Setzen Sie in den Einstellungen für WebGL-Oberflächen immer `maxDevicePixelRatio={2}`. Rendering auf Retina-Displays mit DPR 3+ verbraucht viermal so viel VRAM ohne wahrnehmbaren Qualitätsunterschied.
- **Punktuelle Materialanwendung:** Wenden Sie Glas nur auf oberste Navigationsschichten an (Header, Dock, Modal). Normale Content-Listen sollten einen klassischen undurchsichtigen oder halbtransparenten CSS-Hintergrund haben.
- **Cursor-Positions-Updates:** Für interaktive Mouse-Tracking-Effekte ändern Sie CSS-Variablen oder `transform` über `ref`, um `setState`-Aufrufe pro Bewegungspixel zu vermeiden.

### 7.2. Caching von Distanzkarten (SDF) und Resize-Optimierung

Die Generierung von SDF-Karten für SVG-Filter ist ressourcenintensiv. Der Hook `useSdfFilter` cached Karten automatisch anhand eines Hashes der geometrischen Parameter. Bei Änderungen der Browserfenstergröße schaltet die Bibliothek automatisch auf niedrige Rendering-Qualität um und stellt die maximale Schärfe erst nach Beendigung des Resizes wieder her.

---

## 8. Matrix typischer Probleme und häufig gestellte Fragen (FAQ)

### 8.1. Diagnose von Rendering-Fehlern, Kontrastverlust und Memory Leaks

| Symptom / Fehler | Ursache | Ingenieurslösung |
| :--- | :--- | :--- |
| Glaseffekt fehlt (weißer/grauer Hintergrund) | Style-Datei `styles.css` nicht eingebunden | Fügen Sie `import "open-glass-ui/styles.css";` im Projektroot hinzu |
| Text unlesbar auf hellen Fotos | Zu transparentes Material `clear` verwendet | Wechseln Sie das Prop auf `material="regular"` oder `material="frosted"`, um einen matten Untergrund zu erzeugen |
| Scroll-Lag auf Mobilgeräten | Viele verschachtelte Oberflächen mit Renderer `sdf-svg` | Belassen Sie `renderer="auto"` (CSS) für Massen-UI-Elemente |
| Fehler `WebGL context lost` | Limit aktiver Canvas-Kontexte überschritten | Begrenzen Sie die Anzahl aktiver Linsen auf 6 pro Quelle `WebGLGlassSurface` |

### 8.2. Antworten auf häufige Entwicklerfragen zu OpenGlass UI

> ❓ **Ist die Bibliothek kompatibel mit Tailwind CSS?**  
> Ja. OpenGlass UI blockiert Tailwind-Utilities nicht. Sie können Klassen wie `className="flex items-center gap-4 p-6"` sicher mit den Props `material` und `interactive` kombinieren.

> ❓ **Ist die Bibliothek produktionsreif?**  
> Derzeit befindet sich die Bibliothek im Pre-Release-Status. Ihre Architektur und Public API sind bereits stabilisiert, jedoch wird vor Minor-Version-Updates empfohlen, das Changelog sorgfältig zu prüfen.

> ❓ **Wie verhält sich die UI, wenn der Nutzer Windows High Contrast Mode erzwungen hat?**  
> Die Bibliothek erkennt die Media Query `forced-colors: active` automatisch und deaktiviert alle halbtransparenten Effekte, indem sie hochkontrastreiche solide Rahmen und Standard-Systemfarben rendert.