Ajit-ApTech/premium-glass-android

Vidrio Premium para Android

Objetivo: una interfaz que se sienta tranquila, espacial y costosa. El vidrio es un material para los controles que flotan sobre el contenido. No es un estilo para esparcir por todas partes. Prueba de éxito: la gente dice "esto se siente limpio y en capas", nunca "alguien le puso desenfoque a todo".

Esta habilidad controla material, jerarquía, profundidad, movimiento y accesibilidad. La propia marca del proyecto controla la identidad y el texto. Los valores de marca predeterminados están en assets/tokens.json (Retain palette) y pueden reemplazarse.

0. Seguridad y alcance

• Trabaja solo dentro del proyecto que el usuario seleccionó. No leas secretos, claves ni variables de entorno. No hagas solicitudes de red ni instales paquetes; si se necesita una biblioteca, nómbrala y deja que el usuario decida.
• No sobrescribas archivos existentes sin que te lo pidan; propón primero (sección 2).
• Usa solo contenido de ejemplo ficticio.
• Nunca uses fuentes de Apple (San Francisco), SF Symbols, logotipos de Apple o cromo de iOS. Usa Inter e iconos Material Symbols/Lucide.
• Los hechos marcados como (VERIFY) pueden desactualizarse (API, versiones). Dile al usuario que los confirme.

1. Las cinco reglas estrictas

1. El contenido nunca es vidrio. Las tarjetas, filas de listas, formularios, fondos de página y medios permanecen opacos o con superficie suave.
2. Vidrio solo en la capa flotante: píldora de navegación inferior, barra superior sobre contenido desplazable, botón de acción flotante, láminas inferiores y menús, campo de búsqueda, toasts/snackbars, pequeños chips flotantes.
3. Nunca vidrio sobre vidrio. Dentro de una superficie de vidrio, separa los elementos con rellenos, divisores u opacidad.
4. La legibilidad supera la estética. El texto del cuerpo necesita 4.5:1 (texto grande e iconos 3:1) sobre el fondo del peor caso. Ejecuta scripts/contrast_check.py.
5. Cada superficie de vidrio tiene un respaldo sólido (Android antiguo, reducir transparencia, alto contraste, ahorro de batería, desenfoque deshabilitado por el dispositivo).

Pregunta de puerta antes de aplicar vidrio a cualquier elemento: "¿Qué rol funcional comunica este material?" Respuestas válidas: flota sobre contenido desplazable; es temporal o contextual; debe permanecer accesible mientras el contenido se mueve debajo. Sin respuesta = sin vidrio.

2. Flujo de trabajo

1. Inspecciona: plataforma, min/target SDK, tema/tokens existentes, estructura de navegación, necesidades de accesibilidad, objetivos de rendimiento. Enumera preguntas abiertas en lugar de adivinar.
2. Mapa de capas (antes de cualquier código): tabla de elementos -> capa (contenido / estructura / flotante) -> ¿vidrio sí/no? -> nivel -> razón. Preséntalo con el plan.
3. Tokens: comienza desde assets/tokens.json; ajusta los colores de marca; vuelve a ejecutar la verificación de contraste para cada nivel en ambos modos.
4. Construye con las plantillas en assets/GlassTheme.kt y la guía en references/compose-implementation.md.
5. Verifica con references/review-checklist.md y scripts/audit_compose.py. Reporta evidencia (valores de contraste, cantidad de capas de vidrio por pantalla, capturas de respaldo). No afirmes que una verificación pasó sin evidencia.

3. Niveles de material (valores iniciales, dp)

Nivel	Uso	Desenfoque	Relleno (oscuro)	Relleno (claro)
ninguno	contenido, tarjetas, listas, fondos	-	-	-
delgado	controles solo icono o etiqueta grande	16	tinta @ 0.55	blanco @ 0.55
regular	píldora de navegación, barra superior, búsqueda, FAB, toasts	24	tinta @ 0.66	blanco @ 0.70
grueso	láminas, menús, diálogos, superposiciones con mucho texto	32	tinta @ 0.78	blanco @ 0.82
cortina	atenuar detrás de láminas modales	0-8	negro @ 0.20-0.45	negro @ 0.20-0.45
Detalles y números de contraste verificados: references/tokens.md. Los rellenos se tiñen con el color de tinta de la superficie, no blanco puro, para que el texto en modo oscuro sobreviva a fondos brillantes.

4. Verificación de realidad en Android (lee antes de prometer algo)

• Modifier.blur() / RenderEffect desenfocan el contenido propio del elemento, no lo que está detrás. El desenfoque de fondo real necesita una biblioteca (Haze tiene licencia Apache-2.0 y es compatible con Compose en Android) o desenfoque de ventana para diálogos. Los nombres de API de bibliotecas cambian entre versiones: lee el README de la versión instalada (VERIFY).
• Los efectos de desenfoque necesitan Android 12 (API 31) o superior (VERIFY). Por debajo de eso, usa la superficie de respaldo sólida.
• Las láminas inferiores modales y los diálogos viven en una ventana separada, por lo que el desenfoque de fondo en composición puede no ver el contenido detrás de ellos. Usa desenfoque de fondo de ventana donde sea compatible y verifica WindowManager.isCrossWindowBlurEnabled (VERIFY); de lo contrario, usa una lámina casi opaca y gruesa con una cortina.
• El desenfoque sobre un degradado plano es invisible; el vidrio necesita estructura detrás (contenido, imágenes o un brillo suave deliberado). De lo contrario, cuesta rendimiento para nada.
• Presupuesto: como máximo 2-3 capas de desenfoque simultáneas por pantalla (1-2 en teléfonos de gama baja). Nunca desenfoques elementos de lista o pantallas completas. No animes el radio de desenfoque en superficies grandes; anima alfa o transformación.
• Prueba en un teléfono de gama baja (3-4 GB de RAM) en una compilación similar a la de producción.

5. Modos de accesibilidad (implementa todos)

• Transparencia reducida (configuración interna de la app + señales del sistema "eliminar animaciones"/alto contraste): intercambia vidrio por tokens de superficie sólida con un borde visible de 1 dp.
• Fuente grande (200%) y TalkBack: sin información solo en color; etiquetas en controles solo icono; orden de enfoque sensato.
• Movimiento reducido: reemplaza movimiento con fundidos; mantén la retroalimentación de estado.
• Objetivos táctiles de al menos 48 dp. Los gestos (deslizar) siempre tienen una alternativa de botón o customActions.

6. Componentes

Especificaciones para píldora de navegación, barra superior, FAB, láminas, campo de búsqueda, chips, tarjetas, filas deslizables, pila de triaje, entrada de chat, chips de valor enmascarado: references/components.md. Usa un radio por rol (chip 999, control 16, tarjeta 24, píldora de navegación 28, lámina 32); radio anidado = radio exterior - relleno.

7. Movimiento

Resortes 250-350 ms, fundidos cortos 150 ms, sin rebote excesivo. Tic háptico en el umbral de deslizamiento. Estado presionado: escala 0.97 más un resaltado suave. Respeta el movimiento reducido.

8. Modo de prompts de imagen (pantallas de referencia)

Cuando se te pidan prompts de maquetas, sigue references/image-prompts.md: una pantalla por prompt, bloque de estilo autocontenido, texto exacto en pantalla, vidrio solo en la capa flotante, "las tarjetas son opacas", barra de estado de Android, sin elementos de Apple. Seis prompts de pantalla trabajados están en la referencia. Recuerda al usuario que los generadores distorsionan texto pequeño y devanagari; usa las salidas como referencias de diseño y ambiente, luego reconstruye en Figma/Compose.

9. Modo de revisión

Cuando se te pida revisar un diseño o código: clasifica cada elemento por capa, cuenta las capas de vidrio por pantalla, ejecuta el script de auditoría (python scripts/audit_compose.py <src>), ejecuta el script de contraste, luego enumera los hallazgos por gravedad con la corrección de references/review-checklist.md.

10. Expectativas de salida

Para cualquier tarea, indica: qué es vidrio y por qué; qué nivel; evidencia de contraste; respaldos; cualquier cosa aproximada o no verificada. Mantén los cambios acotados: no rediseñes UX no relacionado; enumera los problemas no relacionados por separado.

Referencias y archivos

• references/principles.md - Principios derivados de Apple y fuentes
• references/tokens.md - Tablas de tokens y resultados de contraste verificados
• references/compose-implementation.md - Arquitectura de Compose, fragmentos de código, respaldos, rendimiento
• references/components.md - Especificaciones de componentes y estados
• references/image-prompts.md - Plantilla de prompt y flujo de trabajo
• references/review-checklist.md - Puertas de calidad y antipatrones
• scripts/contrast_check.py, scripts/audit_compose.py - Verificadores locales (sin red)
• assets/tokens.json, assets/GlassTheme.kt (opcional: añadir el conjunto de 45 prompts de pantalla Retain como assets/retain-screen-prompts.md)