Ajit-ApTech/premium-liquid-glass

Premium Liquid Glass

Ziel: Eine Oberfläche, die sich ruhig, räumlich und hochwertig anfühlt. Glas ist ein Material für die Steuerelemente, die über dem Inhalt schweben. Es ist kein Stil, der überall eingesetzt wird. Erfolgstest: Nutzer sagen „fühlt sich sauber und geschichtet an“, niemals „da hat jemand alles mit Unschärfe überzogen“.

Diese Fähigkeit steuert Material, Hierarchie, Tiefe, Bewegung und Barrierefreiheit auf Android (Compose), iOS (SwiftUI), Flutter und Web (CSS/Tailwind). Die eigene Marke des Projekts bestimmt Identität, Palette und Texte. Standard-Marken-Tokens sind in assets/tokens.json.

0. Sicherheit und Umfang

• Arbeite nur innerhalb des vom Benutzer ausgewählten Projekts. Lese keine Secrets, Schlüssel oder Umgebungsvariablen. Führe keine Netzwerkanfragen durch und installiere keine Pakete; wenn eine Bibliothek benötigt wird, nenne sie und überlasse dem Benutzer die Entscheidung.
• Schlage Änderungen vor, bevor bestehender Anwendungscode geändert wird.
• Verwende nur fiktive Beispielinhalte.
• Verwende niemals Apple-Schriftarten (San Francisco) oder SF Symbole auf Nicht-Apple-Plattformen. Verwende Inter, Roboto oder plattformgerechte Schriftarten mit Symbolen im Material Symbols/Lucide-Stil. Auf iOS (SwiftUI) sind native SF Symbole und Systemschriftarten Standard.
• Fakten, die mit (VERIFY) gekennzeichnet sind, können mit API-Versionen veralten; überprüfe sie immer gegen die Projektabhängigkeiten.

1. Die fünf harten Regeln

1. Inhalt ist nie aus Glas. Karten, Listenzeilen, Formulare, Seitenhintergründe und Medien bleiben deckend oder mit weicher Oberfläche.
2. Glas nur auf der schwebenden Ebene: Navigations-Pille, obere Leiste über scrollendem Inhalt, schwebender Aktionsbutton, untere Sheets und Menüs, Suchfeld, Toasts/Snackbars und kleine schwebende Chips.
3. Niemals Glas auf Glas. Innerhalb einer Glasoberfläche trenne Elemente durch solide Füllungen, subtile Trennlinien oder Deckkraftunterschiede.
4. Lesbarkeit ist wichtiger als Optik. Fließtext benötigt 4,5:1-Kontrast (große Texte und Symbole 3:1) über dem schlimmsten Hintergrund. Führe scripts/contrast_check.py aus.
5. Jede Glasfläche hat eine solide Fallback-Option (ältere Betriebssystemversionen, Barrierefreiheit-Einstellung „Transparenz reduzieren“, Energiesparmodus, geringe GPU-Leistung oder Browser ohne backdrop-filter).

Prüf-Frage vor dem Anwenden von Glas auf ein Element: „Welche funktionale Rolle kommuniziert dieses Material?“ Gültige Antworten: Es schwebt über scrollendem Inhalt; es ist temporär oder kontextbezogen; es muss erreichbar bleiben, während sich der Inhalt darunter bewegt. Keine Antwort = kein Glas.

2. Universeller Arbeitsablauf

1. Inspizieren: Zielplattform (Android Compose, iOS SwiftUI, Flutter, Web), Betriebssystemversionsgrenzen, vorhandene Theme-Tokens, Navigationsstruktur, Barrierefreiheitsanforderungen und Leistungsziele.
2. Ebenen-Karte (vor jedem Code): Tabelle der Elemente -> Ebene (Inhalt / Struktur / schwebend) -> Glas ja/nein -> Stufe -> Grund. Präsentiere sie mit dem Plan.
3. Tokens: Beginne mit assets/tokens.json; passe Markenfarben an; führe python scripts/contrast_check.py --tokens assets/tokens.json für jede Stufe in beiden Modi erneut aus.
4. Bauen mit Plattform-Vorlagen:
   • 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. Überprüfen: Prüfen mit references/review-checklist.md und scripts/audit_compose.py (Android). Nachweise melden (Kontrastverhältnisse, Anzahl Glas-Schichten pro Bildschirm, Fallback-Darstellung).

3. Materialstufen (Startwerte)

Stufe	Verwendung	Unschärfe	Füllung (dunkel)	Füllung (hell)
none	Inhalt, Karten, Listen, Hintergründe	-	Deckende Oberfläche	Deckende Oberfläche
thin	Nur-Symbol oder große Beschriftungen, Chips	16 dp/px	Tinte @ 0.55	Weiß @ 0.55
regular	Navigations-Pille, obere Leiste, Suchfeld, FAB, Toasts	24 dp/px	Tinte @ 0.66	Weiß @ 0.70
thick	Sheets, Menüs, Dialoge, textlastige Overlays	32 dp/px	Tinte @ 0.78	Weiß @ 0.82
scrim	Abdunkelung hinter modalen Sheets	0-8 dp/px	Schwarz @ 0.20-0.45	Schwarz @ 0.20-0.45

Details und bestätigte Kontrastzahlen: references/tokens.md. Füllungen sind mit der Oberflächentintenfarbe getönt, nicht mit reinem Weiß, damit Texte im dunklen Modus auf hellen Hintergründen überleben.

4. Plattform-Realitätsprüfungen

Android (Jetpack Compose)

• Modifier.blur() / RenderEffect verwischt den eigenen Inhalt des Elements, nicht das dahinter Liegende. Echte Hintergrundunschärfe erfordert eine Bibliothek (Haze ist Apache-2.0 und unterstützt Compose) oder Fensterunschärfe für Dialoge (API 31+).
• Unschärfeeffekte benötigen Android 12 (API 31) oder höher (VERIFY). Unter API 31 wird immer die solide Fallback-Oberfläche gerendert.
• Budget: Maximal 2-3 gleichzeitige unscharfe Ebenen pro Bildschirm. Nie Listenelemente unscharf machen.
• Vollständige Details: references/compose-implementation.md.

iOS (SwiftUI)

• Verwende native SwiftUI-Materialien: .ultraThinMaterial (dünne Stufe), .thinMaterial / .regularMaterial (normale Stufe) und .thickMaterial (dicke Stufe).
• Unterstütze iOS-kontinuierliche Ecken mit RoundedRectangle(cornerRadius: ..., style: .continuous).
• Verwende .presentationBackground(.thinMaterial) für Bottom Sheets (iOS 16.4+).
• Vollständige Details: references/swiftui-implementation.md.

Flutter

• Verwende BackdropFilter mit ImageFilter.blur(sigmaX: tier.blur, sigmaY: tier.blur), eingeschlossen in ClipRRect.
• Immer in RepaintBoundary einschließen, um ein Neuzeichnen der Hintergrundunschärfe in jedem Frame zu verhindern.
• Verwende BackdropFilter niemals innerhalb von ListView.builder- oder GridView.builder-Elementen.
• Vollständige Details: references/flutter-implementation.md.

Web (CSS / Tailwind CSS)

• Füge immer sowohl -webkit-backdrop-filter: blur(...) als auch backdrop-filter: blur(...) für browserübergreifende Unterstützung hinzu (Safari benötigt -webkit-).
• Gib immer eine @supports not (backdrop-filter: blur(1px))-Fallback für ältere Browser an.
• Implementiere immer eine @media (prefers-reduced-transparency: reduce)-Fallback zu soliden Hintergründen.
• Vollständige Details: references/web-implementation.md.

5. Barrierefreiheitsmodi (alle implementieren)

• Transparenz reduzieren: Überprüfe System-Barrierefreiheitsflags (prefers-reduced-transparency im Web, accessibilityReduceTransparency in SwiftUI, accessibleNavigation in Flutter oder In-App-Umschalter auf Android). Ersetze Glas durch solide Oberflächentoken mit einem sichtbaren 1-dp/px-Rand.
• Große Schrift (200%) und Bildschirmlesegeräte: Keine Information, die nur durch Farbe vermittelt wird; Beschriftungen auf Nur-Symbol-Steuerelementen; logischer Fokus-Reihenfolge.
• Reduzierte Bewegung: Ersetze Federbewegung durch schnelle Überblendungen (150 ms); bewahre Status-Feedback.
• Berührungsziele: Mindestens 48x48 dp / 44x44 pt. Gesten (Wischen) bieten immer eine Schaltfläche oder ein barrierefreies Menü als Alternative.

6. Komponenten & Geometrie

Spezifikationen für Navigationspille, obere Leiste, FAB, Sheets, Suchfeld, Chips, Karten und Triage-Stapel: references/components.md. Verwende konsistente Eckradien:

• Kleine Chips: 999 (volle Pille)
• Kleine Steuerelemente / Buttons: 16 dp/pt
• Inhaltskarten (deckend): 24 dp/pt
• Schwebende Navigationspille: 28 dp/pt
• Modale Sheets: 32 dp/pt
• Radius verschachtelter Elemente = äußerer Radius - Innenabstand.

7. Bewegung & Haptik

Federanimationen (250-350 ms Dauer), kurze Überblendungen (150 ms), minimales oder kein Überschwingen. Subtil haptischer Tick bei Schwellwertauslösern (Wisch-Commit, Pillenauswahl). Gedrückter Zustand: Skalierung 0.97 plus weiche Hervorhebung. Beachte die Einstellungen für reduzierte Bewegung des Systems.

8. Bild-Prompt-Modus (Referenzbildschirme)

Beim Generieren von UI-Mock-up-Prompts befolge references/image-prompts.md: ein Bildschirm pro Prompt, eigener Stilblock, exakter Text auf dem Bildschirm, Glas nur auf der schwebenden Ebene, „Karten sind deckend“, plattformkorrekte Statusleiste. Verwende die Ausgaben als Layout- und Stimmungsreferenzen, implementiere sie dann mit Designtokens im Code.

9. Überprüfungsmodus

Wenn du gebeten wirst, ein Design oder eine Codebasis zu überprüfen:

1. Klassifiziere jedes UI-Element in seine Ebene (Inhalt vs. schwebend).
2. Zähle die Glas-Schichten pro Bildschirm (erzwinge das Maximum von 2-3).
3. Scanne nach Anti-Patterns (Glas auf Karten, Glas in Glas verschachtelt, fehlende Fallbacks).
4. Führe Kontrastprüfung durch (python scripts/contrast_check.py --tokens assets/tokens.json).
5. Für Android-Projekte führe python scripts/audit_compose.py <src> aus.
6. Liste die Ergebnisse nach Schweregrad mit korrigierenden Hinweisen aus references/review-checklist.md auf.

10. Referenzen und Dateien

• references/principles.md - Kern-Raumprinzipien & Apple-Design-Inspiration
• references/tokens.md - Token-Tabellen, Farbwerte und geprüfte Kontrastzahlen
• references/compose-implementation.md - Android Compose Architektur & Code-Ausschnitte
• references/swiftui-implementation.md - iOS SwiftUI Architektur & Code-Ausschnitte
• references/flutter-implementation.md - Flutter Architektur & Code-Ausschnitte
• references/web-implementation.md - Web CSS & Tailwind CSS Architektur & Code-Ausschnitte
• references/components.md - Komponenten-Geometrie, Layouts und Zustände
• references/image-prompts.md - Prompt-Vorlagen für KI-Mock-up-Generierung
• references/review-checklist.md - Qualitätskontrollen und Anti-Patterns
• scripts/contrast_check.py - WCAG-Kontrastprüfskript
• scripts/audit_compose.py - Compose-Statik-Scanner-Skript
• assets/tokens.json - Vollständiges Designtoken-Schema
• assets/GlassTheme.kt - Jetpack Compose Vorlage
• assets/GlassView.swift - SwiftUI Vorlage
• assets/glass_theme.dart - Flutter Vorlage
• assets/glass.css & assets/tailwind-glass.config.js - Web CSS & Tailwind Vorlagen