Skip to main content
Todos os guias
Conteúdo do guia

Conteúdo do guia

Tempo de leitura: 12 min
#automation#openglass#liquid#glass#react
Iniciante12 min

OpenGlass UI: Guia completo da biblioteca Liquid Glass para React

Arquitetura e implementação do OpenGlass UI: 40 componentes nativos, renderizadores CSS, SVG SDF e WebGL2, configuração de tokens, SSR no Next.js e WCAG 2.2.

Publicado:
PARA AGENTE DE IAChatGPTClaude

OpenGlass UI é uma biblioteca moderna de componentes React e web, criada para implementar a estética "Liquid Glass" (Vidro Líquido) em interfaces digitais. Diferente das implementações primitivas em CSS com um simples backdrop-filter: blur(), o OpenGlass UI combina modelos físicos reais de refração da luz, suporte a Signed Distance Fields (SDF), aceleração de hardware via WebGL2 e acessibilidade nativa conforme o padrão WCAG 2.2.

Este guia abrange a arquitetura da biblioteca, os princípios do renderizador em três níveis, a integração prática no Next.js App Router, o sistema de design tokens e as regras de otimização de performance.

1. A Conceito Liquid Glass e as Capacidades do OpenGlass UI

1.1. Filosofia do Vidro Líquido: Combinando DOM Nativo e Efeitos Ópticos

O glassmorfismo clássico é frequentemente criticado pela alta carga na CPU e pela má legibilidade do texto. O OpenGlass UI resolve esse problema através de uma separação rigorosa de camadas:

  • Estrutura Semântica: Todos os 40 componentes da biblioteca são construídos exclusivamente sobre tags HTML nativas (<button>, <input>, <dialog>), preservando a navegação por teclado e o suporte a leitores de tela.
  • Materiais Ópticos: A camada de material visual se adapta ao fundo subjacente utilizando contraste adaptativo, tonalização, biséis (bevel) e reflexos.
  • Hierarquia de Degradation Graciosa (Graceful Degradation): Se o dispositivo não suportar cálculos de hardware ou se o usuário tiver ativado o modo de transparência reduzida no sistema, a biblioteca alterna silenciosamente para materiais CSS opacos sem distorcer o layout.

1.2. Matriz Comparativa dos Três Renderizadores: CSS, Refração SVG e WebGL2

O OpenGlass UI oferece três pipelines gráficos complementares, dependendo da complexidade da superfície:

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 у реальному часі)"]
RenderizadorCapacidades ÓpticasCarga na GPUSuporte de NavegadoresMelhor Caso de Uso
CSS (Auto)Tonalização, desfoque, bordas, sombrasMínima99.8% (Todas as plataformas modernas)Botões, campos de formulário, cards, navegação, listas
SDF / SVGRefração da luz ao longo do contorno da forma (IOR)ModeradaTodos os navegadores com suporte a filtros SVGModais, docks flutuantes, tabs
WebGL2Dispersão cromática realista, lentesAltaRequer suporte a WebGL2Players de mídia, lentes interativas sobre 3D/vídeo

2. Arquitetura de Pacotes e Instalação

2.1. Estrutura Modular: Fachada open-glass-ui e Pacotes Internos

A fachada pública open-glass-ui unifica quatro pacotes internos de workspace, delineando claramente as responsabilidades dos componentes:

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)"]
Aviso

Importar componentes diretamente dos pacotes internos (por exemplo, @open-glass-ui/core ou @open-glass-ui/recipes) é estritamente proibido. Utilize apenas os subcaminhos públicos da fachada:

  • open-glass-ui — Componentes React principais, providers e hooks.
  • open-glass-ui/webgl — Subsistema de superfícies de hardware WebGL2.
  • open-glass-ui/core — Utilitários puros de matemática de tema, cálculo de contraste e cor para Server Components.

2.2. Instalação de Dependências e Configuração Base de Estilos

Instale a biblioteca usando seu gerenciador de pacotes preferido:

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

Inclua os estilos globais no ponto de entrada da sua aplicação (por exemplo, em src/app/layout.tsx ou 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. Configuração do Sistema de Temas: Paletas, Contraste e Tokens CSS

3.1. Gerenciamento de Temas: Presets, Modos de Appearance e Raio de Borda

O tema no OpenGlass UI baseia-se em três dimensões interconectadas:

  1. Appearance: Aceita os valores light, dark ou system. Com o valor system, o servidor entrega um defaultAppearance seguro, enquanto no cliente a media query prefers-color-scheme assume o controle.
  2. Paleta de Cores (Presets): Estão disponíveis esquemas prontos e calibrados (neutral, cobalt, teal, violet, coral, amber) ou valores personalizados através dos parâmetros accent, secondary, tertiary.
  3. Raio de Borda (Radius): Opções sharp (mínimo), balanced (padrão, 12–16px) e soft (orgânico, 24–28px).

3.2. Matriz de Tokens Semânticos --ogui-* e Verificação de Contraste (WCAG)

Todos os componentes são estilizados através de variáveis CSS estáveis:

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;

💡 Regra de Verificação de Contraste: Use a função exportada contrastRatio(colorA, colorB) de open-glass-ui/core. O contraste do texto deve ser de pelo menos 4.5:1 para texto normal e 3:1 para cabeçalhos grandes, conforme o padrão WCAG 2.2 AA.

4. Catálogo de Componentes: Visão Geral dos 40 Recipes no DOM Nativo

4.1. Categorias de Componentes Prontos: Controles, Overlays, Navegação e Formulários

O pacote contém 40 componentes prontos com marcação nativa:

CategoriaComponentes na Biblioteca
Elementos de Ação e ControlesButton, IconButton, ToggleButton, SegmentedControl, Switch, Slider, Stepper
Navegação e ContainersToolbar, Dock, Tabs, Breadcrumbs, Pagination, Menu, MenuItem
Overlays e PopupsDialog, Drawer, Popover, Tooltip, Toast, Alert, Banner
Formulários e Entrada de DadosTextField, Textarea, NumberField, SearchField, Select, Checkbox, RadioGroup, FileDropzone
Exibição de InformaçãoCard, Stat, Badge, Avatar, AvatarGroup, Accordion, Progress, Meter, Spinner, Skeleton, MediaControls

4.2. Padrões de Acessibilidade (a11y): Rótulos ARIA, Gestão de Foco e Estados

Ao usar os componentes do OpenGlass UI, siga rigorosamente as regras de acessibilidade:

  • aria-label Obrigatório para Ícones: IconButton e SegmentedControl exigem uma descrição textual explícita para leitores de tela.
  • Retorno de Foco em Diálogos: Em Dialog e Drawer, o foco retorna automaticamente ao elemento que disparou a abertura quando o componente é fechado.
  • Codificação Dupla de Estados: Não indique estados de seleção, erro ou bloqueio apenas através de transparência ou cor. Sempre acompanhe essas mudanças com alterações de ícone ou badges textuais.

5. Trabalhando com Renderizadores: Do CSS Básico ao WebGL2 Opcional

5.1. Refração Declarativa SVG/SDF para Formas Geométricas Fechadas

Para cards flutuantes ou painéis de controle, você pode habilitar a refração real da luz usando Signed Distance Fields (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. Lentes Ópticas de Hardware em WebGL2 sobre Vídeo e Canvas

Se houver reprodução de vídeo, gráficos interativos ou cenas 3D na página, o módulo open-glass-ui/webgl permite aplicar uma lente de hardware com índice de refração físico (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. Integração no Next.js App Router e Server-Side Rendering (SSR)

6.1. Hidratação sem Conflitos: Isolamento de Fronteiras Client-Side e Utilitários Core

O OpenGlass UI foi projetado considerando o rendering server-side moderno. O servidor nunca tenta acessar window, document ou o contexto WebGL.

Crie o provider raiz em um 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> ); }

Importe funções puras para cálculo de cores ou esquemas de tema nos Server Components a partir de 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. Evitando Mismatches de Markup e Lidando com prefers-color-scheme

Para prevenir avisos de Hydration Mismatch:

  • Não use operadores ternários dependentes de window.innerWidth no primeiro render.
  • Use a prop defaultAppearance="dark" para estabilizar o HTML inicial entre servidor e cliente.

7. Performance e Otimização do Pipeline Gráfico

7.1. Reduzindo a Carga na GPU: Limitando DPR e Uso Seletivo de Vidro

A sobreposição massiva de camadas com desfoque de fundo pode sobrecarregar até mesmo GPUs dedicadas. Siga estas recomendações:

  • Limite o Device Pixel Ratio: Defina sempre maxDevicePixelRatio={2} nas configurações de superfícies WebGL. Renderizar em telas Retina com DPR 3+ consome quatro vezes mais memória de vídeo sem diferença perceptível na qualidade.
  • Aplicação Pontual do Material: Aplique o efeito de vidro apenas nas camadas superiores de navegação (Header, Dock, Modal). Listas de conteúdo comuns devem ter fundos CSS clássicos, opacos ou semitransparentes.
  • Atualização de Posição do Cursor: Para efeitos interativos de tracking do mouse, altere variáveis CSS ou transform via ref, evitando chamar setState a cada pixel de movimento.

7.2. Cache de Mapas de Distância (SDF) e Otimização de Resize

A geração de mapas SDF para filtros SVG é uma operação intensiva em recursos. O hook useSdfFilter cacheia automaticamente os mapas baseados no hash dos parâmetros geométricos. Durante o redimensionamento da janela do navegador, a biblioteca alternará automaticamente para baixa qualidade de renderização, restaurando a nitidez máxima somente após a parada do resize.

8. Matriz de Problemas Comuns e FAQ

8.1. Diagnóstico de Falhas de Renderização, Queda de Contraste e Vazamentos de Memória

Sintoma / ErroCausa RaizSolução de Engenharia
Efeito de vidro ausente (fundo branco/cinza)Arquivo de estilos styles.css não importadoAdicione import "open-glass-ui/styles.css"; na raiz do projeto
Texto ilegível sobre fotos clarasMaterial clear excessivamente transparente usadoAlterne a prop para material="regular" ou material="frosted" para criar um fundo fosco
Lag no scroll em dispositivos móveisMuitas superfícies aninhadas com renderer sdf-svgMantenha renderer="auto" (CSS) para elementos de interface em massa
Erro WebGL context lostLimite de contextos canvas ativos excedidoLimite o número de lentes ativas a 6 por fonte WebGLGlassSurface

8.2. Respostas às Perguntas Frequentes dos Desenvolvedores sobre o OpenGlass UI

❓ A biblioteca é compatível com Tailwind CSS?
Sim. O OpenGlass UI não bloqueia utilitários do Tailwind. Você pode combinar classes como className="flex items-center gap-4 p-6" com as props material e interactive com segurança.

❓ A biblioteca está pronta para produção?
Atualmente, a biblioteca possui status pre-release. Sua arquitetura e API pública já estão estabilizadas, porém, antes de atualizar versões minoritárias, recomenda-se revisar cuidadosamente o Changelog.

❓ Como a interface se comporta se o usuário tiver Alto Contraste Forçado ativado no Windows?
A biblioteca detecta automaticamente o modo de alto contraste e ajusta os materiais para garantir conformidade com as diretrizes de acessibilidade do sistema operacional.

Este guia é totalmente gratuito. Se ele te poupou uma noite, você pode apoiar o crescimento do projeto.
Apoiar o autor