# 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.

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 у реальному часі)"]
```

| Renderizador | Capacidades Ópticas | Carga na GPU | Suporte de Navegadores | Melhor Caso de Uso |
| :--- | :--- | :--- | :--- | :--- |
| **CSS (Auto)** | Tonalização, desfoque, bordas, sombras | Mínima | 99.8% (Todas as plataformas modernas) | Botões, campos de formulário, cards, navegação, listas |
| **SDF / SVG** | Refração da luz ao longo do contorno da forma (IOR) | Moderada | Todos os navegadores com suporte a filtros SVG | Modais, docks flutuantes, tabs |
| **WebGL2** | Dispersão cromática realista, lentes | Alta | Requer suporte a WebGL2 | Players 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)"]
```

> [!WARNING]
> 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:

| Categoria | Componentes na Biblioteca |
| :--- | :--- |
| **Elementos de Ação e Controles** | `Button`, `IconButton`, `ToggleButton`, `SegmentedControl`, `Switch`, `Slider`, `Stepper` |
| **Navegação e Containers** | `Toolbar`, `Dock`, `Tabs`, `Breadcrumbs`, `Pagination`, `Menu`, `MenuItem` |
| **Overlays e Popups** | `Dialog`, `Drawer`, `Popover`, `Tooltip`, `Toast`, `Alert`, `Banner` |
| **Formulários e Entrada de Dados** | `TextField`, `Textarea`, `NumberField`, `SearchField`, `Select`, `Checkbox`, `RadioGroup`, `FileDropzone` |
| **Exibição de Informação** | `Card`, `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 / Erro | Causa Raiz | Solução de Engenharia |
| :--- | :--- | :--- |
| Efeito de vidro ausente (fundo branco/cinza) | Arquivo de estilos `styles.css` não importado | Adicione `import "open-glass-ui/styles.css";` na raiz do projeto |
| Texto ilegível sobre fotos claras | Material `clear` excessivamente transparente usado | Alterne a prop para `material="regular"` ou `material="frosted"` para criar um fundo fosco |
| Lag no scroll em dispositivos móveis | Muitas superfícies aninhadas com renderer `sdf-svg` | Mantenha `renderer="auto"` (CSS) para elementos de interface em massa |
| Erro `WebGL context lost` | Limite de contextos canvas ativos excedido | Limite 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.