Skip to main content
Alle Guides
Inhaltsverzeichnis

Inhaltsverzeichnis

Lesezeit: 12 Min.
#automation#openglass#liquid#glass#react
Einsteiger12 Min.

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.

Veröffentlicht:
FÜR KI-AGENTChatGPTClaude

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 у реальному часі)"]
RendererOptische FähigkeitenGPU-LastBrowserunterstützungOptimales Einsatzgebiet
CSS (Auto)Tönung, Blur, Ränder, SchattenMinimal99,8 % (Alle modernen Plattformen)Buttons, Formularfelder, Karten, Navigation, Listen
SDF / SVGLichtbrechung entlang der Kontur (IOR)MittelAlle Browser mit SVG-Filter-SupportModals, schwebende Dock-Panels, Tabs
WebGL2Realistische chromatische Dispersion, LinsenHochErfordert WebGL2-SupportMedia 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)"]
Warnung

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:

KategorieKomponenten in der Bibliothek
Aktions-Elemente & ControlsButton, IconButton, ToggleButton, SegmentedControl, Switch, Slider, Stepper
Navigation & ContainerToolbar, Dock, Tabs, Breadcrumbs, Pagination, Menu, MenuItem
Overlays & PopupsDialog, Drawer, Popover, Tooltip, Toast, Alert, Banner
Forms & DateneingabeTextField, Textarea, NumberField, SearchField, Select, Checkbox, RadioGroup, FileDropzone
InformationsdarstellungCard, 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 / FehlerUrsacheIngenieurslösung
Glaseffekt fehlt (weißer/grauer Hintergrund)Style-Datei styles.css nicht eingebundenFügen Sie import "open-glass-ui/styles.css"; im Projektroot hinzu
Text unlesbar auf hellen FotosZu transparentes Material clear verwendetWechseln Sie das Prop auf material="regular" oder material="frosted", um einen matten Untergrund zu erzeugen
Scroll-Lag auf MobilgerätenViele verschachtelte Oberflächen mit Renderer sdf-svgBelassen Sie renderer="auto" (CSS) für Massen-UI-Elemente
Fehler WebGL context lostLimit aktiver Canvas-Kontexte überschrittenBegrenzen 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.

Dieser Leitfaden ist komplett kostenlos. Wenn er Ihnen einen Abend erspart hat, können Sie das Wachstum des Projekts unterstützen.
Autor unterstützen