Ajit-ApTech/premium-liquid-glass

Vidro Líquido Premium

Objetivo: uma interface que pareça calma, espacial e cara. Vidro é um material para os controles que flutuam sobre o conteúdo. Não é um estilo para ser espalhado em todo lugar. Teste de sucesso: os usuários dizem "isso parece limpo e em camadas", nunca "alguém adicionou desfoque em tudo".

Esta skill controla material, hierarquia, profundidade, movimento e acessibilidade em Android (Compose), iOS (SwiftUI), Flutter e Web (CSS / Tailwind). A marca do próprio projeto controla identidade, paleta e cópia. Os tokens de marca padrão estão em assets/tokens.json.

0. Segurança e escopo

• Trabalhe apenas dentro do projeto selecionado pelo usuário. Não leia segredos, chaves ou variáveis de ambiente. Não faça requisições de rede nem instale pacotes; se uma biblioteca for necessária, nomeie-a e deixe o usuário decidir.
• Proponha alterações antes de modificar o código da aplicação existente.
• Use apenas conteúdo de exemplo fictício.
• Nunca use fontes da Apple (San Francisco) ou SF Symbols em plataformas que não sejam da Apple. Use Inter, Roboto ou fontes apropriadas à plataforma com ícones Material Symbols/Lucide-style. No iOS (SwiftUI), as fontes nativas SF Symbols e do sistema são padrão.
• Fatos marcados como (VERIFY) podem ficar desatualizados com as versões das APIs; sempre confirme com as dependências do projeto.

1. As cinco regras rígidas

1. O conteúdo nunca é vidro. Cartões, linhas de lista, formulários, fundos de página e mídia permanecem opacos ou com superfície suave.
2. Vidro apenas na camada flutuante: pílula de navegação inferior, barra superior sobre conteúdo rolável, botão de ação flutuante, folhas inferiores e menus, campo de busca, toasts/snackbars e pequenos chips flutuantes.
3. Nunca vidro sobre vidro. Dentro de uma superfície de vidro, separe itens com preenchimentos sólidos, divisores sutis ou diferenças de opacidade.
4. Legibilidade supera a aparência. O texto do corpo precisa de contraste 4.5:1 (texto grande e ícones 3:1) sobre o pior cenário de fundo. Execute scripts/contrast_check.py.
5. Toda superfície de vidro tem um fallback sólido (versões mais antigas do SO, configuração de acessibilidade Reduzir Transparência, economia de bateria, baixa capacidade de GPU ou navegadores sem suporte a backdrop-filter).

Pergunta essencial antes de aplicar vidro a qualquer elemento: "Qual papel funcional este material comunica?" Respostas válidas: ele flutua sobre conteúdo rolável; é temporário ou contextual; deve permanecer acessível enquanto o conteúdo se move abaixo dele. Sem resposta = sem vidro.

2. Fluxo de trabalho universal

1. Inspecione: Plataforma alvo (Android Compose, iOS SwiftUI, Flutter, Web), limites de versão do SO, tokens de tema existentes, estrutura de navegação, requisitos de acessibilidade e metas de desempenho.
2. Mapa de camadas (antes de qualquer código): Tabela de elementos -> camada (conteúdo / estrutura / flutuante) -> vidro sim/não -> nível -> motivo. Apresente com o plano.
3. Tokens: Comece a partir de assets/tokens.json; ajuste as cores da marca; re-execute python scripts/contrast_check.py --tokens assets/tokens.json para cada nível em ambos os modos.
4. Construa com modelos de plataforma:
   • Android: assets/GlassTheme.kt & references/compose-implementation.md
   • iOS (SwiftUI): assets/GlassView.swift & references/swiftui-implementation.md
   • Flutter: assets/glass_theme.dart & references/flutter-implementation.md
   • Web (CSS/Tailwind): assets/glass.css, assets/tailwind-glass.config.js & references/web-implementation.md
5. Verifique: Confira com references/review-checklist.md e scripts/audit_compose.py (Android). Relate evidências (taxas de contraste, contagem de camadas de vidro por tela, renderização de fallback).

3. Níveis de material (valores iniciais)

Nível	Uso	Desfoque	Preenchimento (escuro)	Preenchimento (claro)
nenhum	conteúdo, cartões, listas, fundos	-	Superfície opaca	Superfície opaca
fino	controles apenas de ícone ou rótulo grande, chips	16 dp/px	tinta @ 0.55	branco @ 0.55
regular	pílula de navegação, barra superior, campo de busca, FAB, toasts	24 dp/px	tinta @ 0.66	branco @ 0.70
grosso	folhas, menus, diálogos, sobreposições com muito texto	32 dp/px	tinta @ 0.78	branco @ 0.82
scrim	escurecimento atrás de folhas modais	0-8 dp/px	preto @ 0.20-0.45	preto @ 0.20-0.45

Detalhes e números de contraste verificados: references/tokens.md. Os preenchimentos são matizados com a cor da tinta da superfície, não com branco puro, para que o texto do modo escuro sobreviva a fundos claros.

4. Verificações de realidade da plataforma

Android (Jetpack Compose)

• Modifier.blur() / RenderEffect desfoca o conteúdo do próprio elemento, não o que está atrás dele. O desfoque de fundo real precisa de uma biblioteca (Haze é Apache-2.0 e suporta Compose) ou desfoque de janela para diálogos (API 31+).
• Efeitos de desfoque precisam do Android 12 (API 31) ou superior (VERIFY). Abaixo da API 31, sempre renderize a superfície de fallback sólida.
• Orçamento: No máximo 2-3 camadas desfocadas simultâneas por tela. Nunca desfoque itens de lista.
• Detalhes completos: references/compose-implementation.md.

iOS (SwiftUI)

• Use materiais nativos do SwiftUI: .ultraThinMaterial (nível fino), .thinMaterial / .regularMaterial (nível regular) e .thickMaterial (nível grosso).
• Suporte aos cantos contínuos do iOS com RoundedRectangle(cornerRadius: ..., style: .continuous).
• Use .presentationBackground(.thinMaterial) para folhas inferiores (iOS 16.4+).
• Detalhes completos: references/swiftui-implementation.md.

Flutter

• Use BackdropFilter com ImageFilter.blur(sigmaX: tier.blur, sigmaY: tier.blur) envolto em ClipRRect.
• Sempre envolva em RepaintBoundary para evitar a repintura do desfoque de fundo a cada quadro.
• Nunca use BackdropFilter dentro de itens de ListView.builder ou GridView.builder.
• Detalhes completos: references/flutter-implementation.md.

Web (CSS / Tailwind CSS)

• Sempre inclua tanto -webkit-backdrop-filter: blur(...) quanto backdrop-filter: blur(...) para suporte entre navegadores (Safari requer -webkit-).
• Sempre especifique um fallback @supports not (backdrop-filter: blur(1px)) para navegadores antigos.
• Sempre implemente o fallback @media (prefers-reduced-transparency: reduce) para fundos sólidos.
• Detalhes completos: references/web-implementation.md.

5. Modos de acessibilidade (implementar todos)

• Reduzir transparência: Verifique as flags de acessibilidade do sistema (prefers-reduced-transparency na Web, accessibilityReduceTransparency no SwiftUI, accessibleNavigation no Flutter ou alternância no aplicativo no Android). Substitua vidro por tokens de superfície sólida com uma borda visível de 1 dp/px.
• Fonte grande (200%) e leitores de tela: Nenhuma informação transmitida apenas por cor; rótulos em controles apenas de ícone; ordem lógica de foco.
• Movimento reduzido: Substitua movimento de mola por fades rápidos (150 ms); preserve o feedback de estado.
• Alvos de toque: Mínimo 48x48 dp / 44x44 pt. Gestos (deslizar) sempre fornecem um botão ou menu acessível alternativo.

6. Componentes e geometria

Especificações para pílula de navegação, barra superior, FAB, folhas, campo de busca, chips, cartões e pilhas de triagem: references/components.md. Use raios de canto consistentes:

• Chips pequenos: 999 (pílula completa)
• Controles / botões pequenos: 16 dp/pt
• Cartões de conteúdo (opacos): 24 dp/pt
• Pílula de navegação flutuante: 28 dp/pt
• Folhas modais: 32 dp/pt
• Raio do elemento aninhado = raio externo - preenchimento.

7. Movimento e háptica

Animações de mola (duração 250-350 ms), fades curtos (150 ms), overshoot de salto mínimo ou zero. Toque háptico sutil em acionadores de limite (confirmação de deslize, seleção de pílula). Estado pressionado: escala 0.97 mais um destaque suave. Respeite as configurações de movimento reduzido do sistema.

8. Modo de prompt de imagem (telas de referência)

Ao gerar prompts de UI mock-up, siga references/image-prompts.md: uma tela por prompt, bloco de estilo autocontido, texto exato na tela, vidro apenas na camada flutuante, "cartões são opacos", barra de status precisa para a plataforma. Use as saídas como referências de layout e clima, depois implemente em código com tokens de design.

9. Modo de revisão

Ao ser solicitado a revisar um design ou código base:

1. Classifique cada elemento de UI em sua camada (conteúdo vs. flutuante).
2. Conte as camadas de vidro por tela (imponha o orçamento máximo de 2-3).
3. Verifique antipadrões (vidro em cartões, vidro aninhado em vidro, fallbacks ausentes).
4. Execute a verificação de contraste (python scripts/contrast_check.py --tokens assets/tokens.json).
5. Para projetos Android, execute python scripts/audit_compose.py <src>.
6. Liste as descobertas por gravidade com orientação corretiva de references/review-checklist.md.

10. Referências e arquivos

• references/principles.md - Princípios espaciais centrais e inspiração de design da Apple
• references/tokens.md - Tabelas de tokens, valores de cor e números de contraste verificados
• references/compose-implementation.md - Arquitetura Android Compose e trechos de código
• references/swiftui-implementation.md - Arquitetura iOS SwiftUI e trechos de código
• references/flutter-implementation.md - Arquitetura Flutter e trechos de código
• references/web-implementation.md - Arquitetura Web CSS & Tailwind CSS e trechos de código
• references/components.md - Geometria, layouts e estados de componentes
• references/image-prompts.md - Modelos de prompt para geração de mock-ups com IA
• references/review-checklist.md - Portões de qualidade e antipadrões
• scripts/contrast_check.py - Script de verificação de contraste WCAG
• scripts/audit_compose.py - Script de scanner estático Compose
• assets/tokens.json - Esquema completo de tokens de design
• assets/GlassTheme.kt - Modelo Jetpack Compose
• assets/GlassView.swift - Modelo SwiftUI
• assets/glass_theme.dart - Modelo Flutter
• assets/glass.css & assets/tailwind-glass.config.js - Modelos Web CSS & Tailwind