Skip to main content
Wszystkie poradniki
Spis treści poradnika

Spis treści poradnika

Czas czytania: 12 min
#automation#openglass#liquid#glass#react
Początkujący12 min

OpenGlass UI: Kompletny przewodnik po bibliotece Liquid Glass dla React

Architektura i implementacja OpenGlass UI: 40 natywnych komponentów, renderery CSS, SVG SDF oraz WebGL2, konfiguracja tokenów, SSR w Next.js i zgodność z WCAG 2.2.

Opublikowano:
DLA AGENTA AIChatGPTClaude

OpenGlass UI to nowoczesna biblioteka komponentów React i webowych, stworzona w celu implementacji estetyki „płynnego szkła” (Liquid Glass) w interfejsach cyfrowych. W odróżnieniu od prymitywnych implementacji CSS opartych na prostym backdrop-filter: blur(), OpenGlass UI łączy prawdziwe fizyczne modele refrakcji światła, obsługę pól odległości znakowanej (SDF, Signed Distance Fields), akcelerację sprzętową przez WebGL2 oraz natywną dostępność zgodną ze standardem WCAG 2.2.

Niniejszy przewodnik obejmuje architekturę biblioteki, zasady trójpoziomowego renderingu, praktyczną integrację z Next.js App Router, system tokenów designu oraz reguły optymalizacji wydajności.

1. Koncepcja Liquid Glass i możliwości OpenGlass UI

1.1. Filozofia płynnego szkła: połączenie natywnego DOM i efektów optycznych

Klasyczny glassmorphism jest często krytykowany za wysokie obciążenie procesora i słabą czytelność tekstu. OpenGlass UI rozwiązuje ten problem dzięki ścisłemu rozdzieleniu warstw:

  • Szkielet semantyczny: Wszystkie 40 komponentów biblioteki zostało zbudowanych wyłącznie na natywnych tagach HTML (<button>, <input>, <dialog>), co zapewnia zachowanie nawigacji klawiaturowej oraz wsparcie dla czytników ekranu.
  • Materiały optyczne: Warstwa materiału wizualnego dostosowuje się do tła przy użyciu adaptacyjnego kontrastu, tonowania, fazek (bevel) i odbić.
  • Hierarchia degradacji (Graceful Degradation): Jeśli urządzenie nie obsługuje obliczeń sprzętowych lub użytkownik włączył tryb zmniejszonej przejrzystości w systemie, biblioteka niezauważalnie przełącza się na nieprzezroczyste materiały CSS bez deformacji markupu.

1.2. Macierz porównawcza trzech rendererów: CSS, refrakcja SVG i WebGL2

OpenGlass UI oferuje trzy uzupełniające się potoki graficzne w zależności od złożoności powierzchni:

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 у реальному часі)"]
RendererMożliwości optyczneObciążenie GPUObsługa przez przeglądarkiOptymalny zakres zastosowań
CSS (Auto)Tonowanie, rozmycie, obramowania, cienieMinimalne99.8% (Wszystkie współczesne platformy)Przyciski, pola formularzy, karty, nawigacja, listy
SDF / SVGRefrakcja światła wzdłuż konturu figury (IOR)UmiarkowaneWszystkie przeglądarki z obsługą filtrów SVGOkna modalne, pływające panele Dock, zakładki
WebGL2Realistyczna dyspersja chromatyczna, soczewkiWysokieWymagana obsługa WebGL2Odtwarzacze mediów, interaktywne soczewki nad 3D/wideo

2. Architektura pakietów i instalacja

2.1. Struktura modułowa: fasada open-glass-ui i wewnętrzne pakiety

Publiczna fasada open-glass-ui łączy cztery wewnętrzne pakiety workspace, wyraźnie rozdzielając obowiązki komponentów:

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)"]
Ostrzeżenie

Bezpośrednie importowanie komponentów z pakietów wewnętrznych (np. @open-glass-ui/core lub @open-glass-ui/recipes) jest surowo zabronione. Korzystaj wyłącznie z publicznych podścieżek fasady:

  • open-glass-ui — główne komponenty React, providery i hooki.
  • open-glass-ui/webgl — podsystem akcelerowanych sprzętowo powierzchni WebGL2.
  • open-glass-ui/core — czyste utility matematyki motywu, kalkulacji kontrastu i kolorów dla komponentów serwerowych.

2.2. Instalacja zależności i podstawowa konfiguracja stylów

Zainstaluj bibliotekę za pomocą wybranego menedżera pakietów:

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

Podłącz globalne style w punkcie wejścia aplikacji (np. w src/app/layout.tsx lub 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. Konfiguracja systemu motywów: palety, kontrast i tokeny CSS

3.1. Zarządzanie motywami: presety, tryby appearance i promienie zaokrąglenia

Motyw w OpenGlass UI opiera się na trzech powiązanych wymiarach:

  1. Wygląd (Appearance): Przyjmuje wartości light, dark lub system. Dla wartości system serwer zwraca bezpieczny defaultAppearance, a po stronie klienta przechwytywane jest zapytanie media prefers-color-scheme.
  2. Paleta kolorów (Presets): Dostępne są gotowe, dopracowane schematy (neutral, cobalt, teal, violet, coral, amber) lub własne wartości poprzez parametry accent, secondary, tertiary.
  3. Promień zaokrąglenia (Radius): Warianty sharp (minimalny), balanced (standardowy, 12–16px) oraz soft (organiczny, 24–28px).

3.2. Macierz semantycznych tokenów --ogui-* i weryfikacja kontrastu (WCAG)

Wszystkie komponenty są stylizowane poprzez stabilne zmienne CSS:

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;

💡 Reguła weryfikacji kontrastu: Używaj eksportowanej funkcji contrastRatio(colorA, colorB) z open-glass-ui/core. Kontrast tekstu musi wynosić co najmniej 4.5:1 dla zwykłego tekstu oraz 3:1 dla dużych nagłówków zgodnie ze standardem WCAG 2.2 AA.

4. Katalog komponentów: przegląd 40 przepisów na natywnym DOM

4.1. Kategorie gotowych komponentów: kontrolki, nakładki, nawigacja i formularze

Pakiet zawiera 40 gotowych komponentów z natywnym markupiem:

KategoriaKomponenty w składzie biblioteki
Elementy akcji i kontrolkiButton, IconButton, ToggleButton, SegmentedControl, Switch, Slider, Stepper
Nawigacja i konteneryToolbar, Dock, Tabs, Breadcrumbs, Pagination, Menu, MenuItem
Nakładki i okna wyskakująceDialog, Drawer, Popover, Tooltip, Toast, Alert, Banner
Formularze i wprowadzanie danychTextField, Textarea, NumberField, SearchField, Select, Checkbox, RadioGroup, FileDropzone
Prezentacja informacjiCard, Stat, Badge, Avatar, AvatarGroup, Accordion, Progress, Meter, Spinner, Skeleton, MediaControls

4.2. Standardy dostępności (a11y): etykiety ARIA, zarządzanie fokusem i stanami

Przy korzystaniu z komponentów OpenGlass UI należy bezwzględnie przestrzegać zasad dostępności:

  • Obowiązkowy aria-label dla ikon: IconButton oraz SegmentedControl wymagają jawnego opis tekstowego dla czytników ekranu.
  • Zwrot fokusu w dialogach: W Dialog i Drawer fokus przy zamknięciu automatycznie wraca do elementu wywołującego.
  • Podwójne kodowanie stanów: Nie oznaczaj stanu wyboru, błędu ani blokady wyłącznie przez przezroczystość lub kolor. Zawsze towarzyszy temu zmiana ikony lub tekstowa plakietka (badge).

5. Praca z rendererami: od bazowego CSS do opcjonalnego WebGL2

5.1. Deklaratywna refrakcja SVG/SDF dla zamkniętych figur geometrycznych

Dla pływających kart lub paneli sterowania można włączyć prawdziwą refrakcję światła przy użyciu pól odległości znakowanej (SDF):

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. Sprzętowe soczewki optyczne w WebGL2 nad wideo i canvas

Jeśli na stronie odtwarzane jest wideo, grafika interaktywna lub scena 3D, moduł open-glass-ui/webgl pozwala nałożyć sprzętową soczewkę z fizycznym wskaźnikiem refrakcji (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. Integracja z Next.js App Router i renderingiem po stronie serwera (SSR)

6.1. Hydratacja bez konfliktów: izolacja granic klienckich i utility core

OpenGlass UI została zaprojektowana z myślą o współczesnym renderingu po stronie serwera. Serwer nigdy nie próbuje odwoływać się do window, document ani kontekstu WebGL.

Utwórz provider korzeniowy w komponencie klienckim:

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> ); }

Czyste funkcje do obliczania kolorów lub schematów motywów importuj w Server Components z 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. Unikanie rozbieżności markupu i praca z prefers-color-scheme

Aby zapobiec ostrzeżeniom o niedopasowaniu hydratacji (Hydration Mismatch):

  • Nie używaj operatorów ternarnych zależnych od window.innerWidth podczas pierwszego renderu.
  • Używaj propa defaultAppearance="dark" w celu stabilizacji początkowego HTML między serwerem a klientem.

7. Wydajność i optymalizacja potoku graficznego

7.1. Redukcja obciążenia GPU: ograniczenie DPR i selektywne stosowanie szkła

Masowe nakładanie warstw z rozmyciem tła może przeciążyć nawet dedykowaną kartę graficzną. Przestrzegaj następujących rekomendacji:

  • Ogranicz Device Pixel Ratio: Zawsze ustawiaj maxDevicePixelRatio={2} w konfiguracjach powierzchni WebGL. Rendering na ekranach Retina z DPR 3+ zużywa czterokrotnie więcej pamięci wideo bez zauważalnej różnicy w jakości.
  • Punktowe nakładanie materiału: Stosuj szkło tylko dla górnych warstw nawigacji (Header, Dock, Modal). Zwykłe listy treści powinny mieć klasyczne nieprzezroczyste lub półprzezroczyste tło CSS.
  • Aktualizacja pozycji kursora: Dla interaktywnych efektów śledzenia myszy zmieniaj zmienne CSS lub transform przez ref, unikając wywoływania setState dla każdego piksela ruchu.

7.2. Cacheowanie map odległości (SDF) i optymalizacja zmiany rozmiaru (Resize)

Generowanie map SDF dla filtrów SVG jest operacją zasobożerną. Hook useSdfFilter automatycznie cacheuje mapy według hasha parametrów geometrycznych. Przy zmianie rozmiaru okna przeglądarki biblioteka automatycznie przełącza się na niską jakość renderingu, przywracając maksymalną ostrość dopiero po zakończeniu resize’u.

8. Macierz typowych problemów i najczęściej zadawane pytania (FAQ)

8.1. Diagnostyka awarii renderingu, spadku kontrastu i wycieków pamięci

Objaw / BłądPrzyczyna źródłowaRozwiązanie inżynierskie
Efekt szkła nieobecny (białe/szare tło)Nie podłączono pliku stylów styles.cssDodaj import "open-glass-ui/styles.css"; w katalogu głównym projektu
Tekst staje się nieczytelny na jasnych zdjęciachUżyto zbyt przezroczystego materiału clearPrzełącz prop na material="regular" lub material="frosted", aby utworzyć matowe podłoże
Spadek płynności scrollowania na urządzeniach mobilnychDuża liczba zagnieżdżonych powierzchni z rendererem sdf-svgPozostaw renderer="auto" (CSS) dla masowych elementów interfejsu
Błąd WebGL context lostPrzekroczono limit aktywnych kontekstów canvasOgranicz liczbę aktywnych soczewek do 6 na jedno źródło WebGLGlassSurface

8.2. Odpowiedzi na częste pytania deweloperów dotyczące OpenGlass UI

❓ Czy biblioteka jest kompatybilna z Tailwind CSS?
Tak. OpenGlass UI nie blokuje utilitów Tailwind. Możesz bezpiecznie łączyć klasy typu className="flex items-center gap-4 p-6" z propsami material i interactive.

❓ Czy biblioteka jest gotowa do użycia w środowisku produkcyjnym?
Obecnie biblioteka ma status pre-release. Jej architektura i publiczne API są już ustabilizowane, jednak przed aktualizacją wersji minor zaleca się uważne przeglądanie dziennika zmian (Changelog).

❓ Jak zachowuje się interfejs, jeśli użytkownik ma włączony wymuszony wysoki kontrast w Windows?
Biblioteka wykrywa preferencje systemowe i odpowiednio modyfikuje materiały, zapewniając pełną czytelność i zgodność z normami dostępności, nawet w trybach wysokiego kontrastu.

Ten poradnik jest całkowicie darmowy. Jeśli oszczędził Ci wieczór, możesz wesprzeć rozwój projektu.
Wesprzyj autora