tgallina-hub/liquid-glass-web

Liquid Glass Web

Un sistema de diseño web que adapta el modelo de material Liquid Glass a los navegadores. El contenido se asienta sobre una capa opaca, y una capa funcional fina y translúcida de navegación y controles flota sobre ella. Es una adaptación independiente de la guía pública de Apple "Adopting Liquid Glass". No incluye fuentes, símbolos ni recursos de Apple.

Qué contiene esta skill

Ruta	Uso
assets/tokens.json	Fuente de verdad: colores (temas light, dark, contrast), tipografía, espaciado, radio, tamaño, material, sombra.
assets/tokens.css	Propiedades personalizadas CSS compiladas y clases tipográficas. Regenerar con scripts/build_tokens_css.py después de cambiar tokens.
assets/liquid-glass.css	Estilos de componentes (clases lg-*). Independiente de frameworks.
assets/liquid-glass.react.js	Bundle opcional para React 18 que expone window.LG (script clásico; necesita window.React y window.ReactDOM).
assets/liquid-glass.d.ts	Props de componentes, como documentación.
assets/example.html	Una pantalla completa en HTML plano. Copia su estructura.
references/brand-book.md	Principios, voz, color, material, tipografía, maquetación, movimiento, iconografía, accesibilidad. Léelo antes de diseñar.
references/html-api.md	Marcado para cada componente sin React.
references/components/<Name>.md	Guías por componente: qué aporta el consumidor, qué hacer y qué no hacer.
scripts/contrast_check.py	Verificación WCAG de cada par de tokens en cada tema, incluyendo el peor caso de glass. Sale con código 1 si falla.
scripts/build_tokens_css.py	Compila tokens.json en tokens.css.

Flujo de trabajo

A. Construir o rediseñar una interfaz

1. Lee references/brand-book.md y luego los archivos de componente que necesites de references/components/.
2. Copia assets/tokens.css y assets/liquid-glass.css al proyecto y cárgalos en ese orden. En proyectos React, el bundle o un puerto del marcado de references/html-api.md funcionan. En otros frameworks, adapta el marcado.
3. Coloca dos capas:
   • Contenido: opaco, sobre canvas y surface. Todo lo que se lee va aquí.
   • Glass: solo navegación y controles, flotando sobre el contenido con scroll (barra de herramientas, barra de pestañas, grupos, menús, hojas medianas).
4. Usa los tokens por nombre (var(--accent)). Nunca codifiques un color, radio o espaciado que cubra un token.
5. Ejecuta la lista de verificación antes de entregar.

B. Cambio de marca (nuevo acento o neutros)

1. Cambia los valores solo en assets/tokens.json. Mantén los nombres de los tokens, porque el CSS depende de ellos.
2. Cada acento modificado necesita sus acompañantes en cada tema: accent, on-accent, accent-text, accent-glass, focus-ring. Si el acento del tema oscuro es claro, on-accent debe ser oscuro.
3. Ejecuta python3 scripts/contrast_check.py assets/tokens.json. Ajusta los valores hasta que imprima RESULT: PASS. No debilites los umbrales.
4. Ejecuta python3 scripts/build_tokens_css.py assets/tokens.json > assets/tokens.css.
5. Mantén los tokens de glass (glass-fill, glass-edge, glass-lift, glass-blur) a menos que se pida lo contrario. La capa de glass se mantiene sin color.

Reglas no negociables

• Glass solo en la capa funcional. Nunca en filas de listas, tarjetas de contenido o secciones de página, y nunca glass sobre glass.
• El texto sobre glass normal usa solo ink, ink-glass-muted, accent-glass o critical-glass. Nunca uses ink-secondary, accent-text o critical sobre glass: fallan sobre contenido oscuro o brillante.
• Glass claro (lg-glass--clear) solo sobre fotos, vídeos o mapas, con lg-dim debajo. Solo se colocan sobre él símbolos y etiquetas negritas de 19px o más.
• Un botón prominent por vista. Cada control es una cápsula (radius-full). Los radios anidados son concéntricos: interior = exterior − sangría.
• Las áreas táctiles miden al menos target-min (44px). Cada control solo de icono tiene un aria-label.
• Un estado siempre combina un glifo y una palabra; el color nunca transmite significado por sí solo.
• Respeta prefers-reduced-transparency, prefers-contrast y prefers-reduced-motion. El CSS los maneja; no los anules.
• No uses los símbolos SF de Apple, las fuentes de Apple ni sus logotipos. La pila tipográfica usa la fuente del sistema del dispositivo; el conjunto de iconos del bundle de React es un marcador de posición original.

Lista de verificación antes de entregar

• Sin fondo personalizado detrás de las barras; el contenido se desplaza debajo de ellas, con el efecto de borde lg-edge donde las barras se superponen al contenido.
• La cantidad de glass es pequeña (barras, grupos, menús, hoja). Nada más es glass.
• Pantallas verificadas en data-theme="light", "dark" y "contrast".
• Si se cambiaron tokens: contrast_check.py imprime PASS y tokens.css se ha regenerado.
• Teclado: todos los controles son accesibles y muestran el contorno focus-ring.
• Textos: mayúscula inicial en acciones, Capital Inicial solo en encabezados de sección de listas, verbo primero, sin emojis.