Design System — Komponentenspezifikation

Kanonische, plattformunabhängige Spezifikation aller Komponenten — wächst über die Iterationen hinweg (nichts wird gelöscht, nur ergänzt). Verbindlich für die plattformübergreifende Implementierung (Android · iOS · Web). Der jeweilige Pro-Iteration-Lieferumfang steht in iteration-1.html (Home + Burger-Menü) und iteration-2.html (Lesepläne-Komponenten). Die Referenz-Implementierung für Android befindet sich in packages/android.

Zielgruppe

Engineers (plattformübergreifend), Designer zur Verifikation des Kontrakts, QA, agentische Implementierungs-Tools.

Status

v1 — übergabebereit · 16 Komponenten · 21 Abschnitte · 250 Token-Pfade katalogisiert.

Begleitdokumente

index.html (Engineering-Referenz, generierte Tabellen) · handover.json (maschinenlesbare Zusammenfassung)

Konventionen

dp / sp · ms · cubic-bezier · DTCG-Token-Pfade.

Aufbau dieses Dokuments

Jede Komponente unten ist nach einem einheitlichen Kontrakt dokumentiert:

Überblick — was die Komponente ist und warum sie im Erlebnis existiert.
Visuelle Spezifikation — Dimensionen, Aufbau (Layer-Stack), Tokens, die ihr Erscheinungsbild bestimmen.
Zustände — jeder visuelle Zustand mit Auslöser und Austrittsbedingung.
Verhalten — Zustandsautomat, Lebenszyklus, Seiteneffekte, Datenabhängigkeiten.
Bewegung — Dauern, Easings, Choreografie. Immer in Millisekunden + cubic-bezier angegeben.
Interaktion & UX — Eingabebehandlung (Drücken, Ziehen, Wischen, Tastatur, Fokus), Gesten, Scrollen.
Barrierefreiheit — semantische Rolle, Labels, Fokusreihenfolge, Mindest-Trefferflächen, Verhalten bei reduzierter Bewegung.
Verwendete Tokens — jeder DTCG-Token-Pfad, den die Komponente liest, nach Ebene.
Implementierungsreferenz — Android-spezifische Hinweise; iOS und Web ergänzen hier eigene Hinweise, sobald sie eingeführt werden.

Konventionen:

Größen werden in dichteunabhängigen Pixeln angegeben (dp = Android / iOS-Punkt @1x / CSS px / Flutter logical pixel — sie sind für das Layout austauschbar).
Schriftgrößen werden in skalierbaren Pixeln angegeben (sp auf Android, äquivalent zu Dynamic Type auf iOS, rem im Web). Beide Plattformen müssen die Schriftgrößen-Einstellung des Nutzers respektieren.
Farben und Deckkraftwerte sind Tokens, niemals Hex-Literale. Token-Pfade folgen der vierstufigen Hierarchie primitives → semantic → component → views.
Icons stammen ausnahmslos aus dem Material Symbols Rounded-Set und werden per Symbolname referenziert (z. B. [play_arrow], [auto_awesome]), nie als Unicode-Glyph oder Emoji. Android: androidx.compose.material.icons.Icons.Rounded.* über MaterialSymbols.kt; andere Plattformen bilden auf visuell äquivalente Rounded-Icons ab (iOS importiert keine Material-Ikonografie — siehe Plattform-Hinweise). Implementierungslücke (Produktion): die Produktions-App verwendet Material Symbols, aber nicht durchgängig die Rounded-Variante — Implementierungen müssen auf Rounded vereinheitlichen.
Zeit wird in Millisekunden angegeben. Easings werden benannt oder als cubic-bezier(x1, y1, x2, y2) angegeben.
"Container" bezeichnet eine generische Layout-Box (Android Box / iOS UIView / Web div). "Stack" bezeichnet ein vertikales oder horizontales Layout (Column/Row / VStack/HStack / flex).

Token-System

Tokens werden in tokens/{primitive,semantic,component,view}/*.json im W3C-DTCG-Format definiert. Die einzige Quelle der Wahrheit ist die Design-Tokens-API unter /api/v1/tokens; die Plattformen laden den konsolidierten Payload zur Laufzeit und legen ihn über ihre gebündelten Standardwerte.

Ebene	Zweck	Beispiel
Primitive	Rohwerte: Farben, Abstände, Schriftstärken, Deckkraft-Stufen.	`primitives.opacity.scale80` = `0.8`
Semantic	Theme-bewusste Bedeutung: dunkler/heller Text, Rahmen, Oberflächen.	`semantic.dark.text.primary` = `#FFFFFF`
Component	Komposition pro Komponente.	`component.heroVideo.tabletTitleFontSize` = `26`
View	Komposition pro Bildschirm (bindet Primitives + Semantic an Oberflächen eines spezifischen Bildschirms).	`views.home.modalScrim.alpha` = `0.8`

Die Implementierung muss Tokens aus der API lesen; jeder für den Nutzer sichtbare Wert, der kein Token ist, gilt als Bug.

Token-Pfad-Konvention. In diesem Dokument folgen Pfade innerhalb von <code>-Tags der API-Benennungskonvention. Von den 250 genannten eindeutigen Pfaden werden 157 (63%) heute vollständig über die API aufgelöst; 70 (28%) existieren als Kotlin-Modell-Defaults und warten auf API-Promotion; 23 (9%) sind reine Spezifikations-Vorschläge, die während der plattformübergreifenden Implementierung formalisiert werden. Siehe Abschnitt Token-Referenz am Ende für die vollständige Statustabelle — vor der Implementierung lesen.

Plattform-Hinweise

Android. Referenz-Implementierung. Verfügbar in packages/android. Verwendet Jetpack Compose mit Material 3. Die Referenz ist verbindlich für das Verhalten — wenn diese Spezifikation und die Android-Quelle abweichen, gilt die Spezifikation, aber die Android-Quelle ist die nächstgelegene existierende Antwort.

iOS. Implementierung ausstehend. Ziel: SwiftUI. Material-3-äquivalente Semantik über die SwiftUI-Material-Bibliothek oder ein dünnes Shim adoptieren; keine Material-spezifische Ikonografie importieren.

Web. Implementierung ausstehend. Ziel: React + ein token-getriebenes CSS-Variablen-System. Das HTML-Referenzdokument index.html zeigt eine Möglichkeit, component-tokens.css zu konsumieren.

Glossar

In diesem Dokument verwendete Begriffe — plattformunabhängig definiert.

Begriff	Bedeutung
`dp`	Dichteunabhängiges Pixel. Ein `dp` = ein logisches Pixel auf einem "Baseline"-Bildschirm mit 160 dpi. Äquivalent zu: Android `dp`, iOS-Punkt @ 1×, CSS `px`, Flutter logical pixel.
`sp`	Skalierbares Pixel. Wie `dp`, skaliert aber mit der vom Nutzer bevorzugten Schriftgröße. Für jede Schriftgröße verwenden. iOS Dynamic Type und CSS `rem` erfüllen dieselbe Rolle.
Container	Eine generische Layout-Box, die weitere Elemente enthält. Entspricht Android `Box`, iOS `UIView` / SwiftUI `VStack`-Wrapper, Web `div`.
Stack	Eine lineare Anordnung von Kindelementen, entweder vertikal oder horizontal. Entspricht Compose `Column`/`Row`, SwiftUI `VStack`/`HStack`, CSS `flex-direction: column`/`row`.
Press-Feedback	Die transiente visuelle Bestätigung, wenn ein Nutzer ein interaktives Element antippt. Android = Ripple, iOS = Highlight/Scale, Web = Active-State.
Scrim	Eine halbtransparente Überlagerung hinter einer modalen Oberfläche, die den darunterliegenden Inhalt abdunkelt und visuell trennt. Immer antippbar zum Schließen.
Slot	Ein benannter Bereich innerhalb einer Eltern-Komponente, in den ein Kind eingefügt wird. Das Eltern-Element gibt Geometrie und Styling des Slots vor; das Kind füllt ihn. Äquivalent zu Compose-Composable-Content-Lambdas, SwiftUI `@ViewBuilder`-Parametern, Web-Slots / React-Children.
Chrome	Wiederverwendbare visuelle Umrandung um Inhalt (Rahmen, Eckenradius, Schatten, Badge-Slot) — die Komponente dekoriert, ohne den Inhalt vorzugeben.
Settle	Der Endzustand nach einem Wisch- oder Fling-Gesten, wenn der scrollbare Bereich an einer stabilen Seitenposition zur Ruhe kommt.
Trefferfläche	Der transparente antippbare Bereich um ein visuelles Icon oder einen Button. Muss gemäß Barrierefreiheits-Baseline ≥ 48dp × 48dp sein, unabhängig von der sichtbaren Größe.
BP / Breakpoint	Viewport-Größenschwelle, die den Layout-Modus umschaltet. Iteration 1 hat zwei aktive: mobile (kürzeste Seite < 600dp) und tablet (≥ 600dp). Siehe Breakpoints.
DTCG	W3C Design Tokens Community Group-Format. Die JSON-Struktur, in der Tokens unter `tokens/{primitive,semantic,component,view}/*.json` verfasst werden. Spezifikation: tr.designtokens.org/format.
Token	Ein benannter Designwert (Farbe, Dimension, Deckkraft, Dauer, …), der in DTCG verfasst, von der Design-Tokens-API ausgeliefert und zur Laufzeit von der Plattform konsumiert wird. Die vier Ebenen (Primitive · Semantic · Component · View) komponieren in Richtung spezifischerer Bedeutungen.
Vorab-Palette	Laufzeitanalyse eines Bildes, um eine dominante "Basis"-Farbe und eine "Akzent"-Farbe abzuleiten, die zum Einfärben der Hero-Gradients und des umgebenden Bildschirmhintergrunds verwendet werden. Die Android-Referenz verwendet den `palette=json`-Endpoint von Imgix oder als Fallback die `androidx.palette`-Bibliothek.
Skeleton	Ein Platzhalter-Visual, das angezeigt wird, während der echte Inhalt lädt. Gleiche Form wie die finale Karte / Reihe, gefüllt mit einer kontrastarmen Farbe, die dezent pulsieren darf.
Composition Payload	Server-getriebenes JSON, das die Struktur eines Bildschirms beschreibt: welche Abschnitte vorhanden sind, deren Reihenfolge und welcher Inhalt jeden füllt. Der Home-Bildschirm liest dies, um zu bestimmen, welche RowSections in welcher Reihenfolge gerendert werden.

Theming — Kontrakt für hellen & dunklen Modus

Die App unterstützt zwei Farbschemata. Jede Komponente muss in beiden korrekt funktionieren. Die meisten Oberflächen wechseln automatisch über semantische Tokens — Designer und Implementierer sollten KEIN modus-spezifisches CSS direkt im Komponenten-Code schreiben.

Wie die Modi verdrahtet sind

System-Ebene: Der aktive Modus wird durch die System-Theme-Präferenz des Nutzers bestimmt (Android System-Theme / iOS UITraitCollection / Web prefers-color-scheme).
Semantic-Ebene: Der Großteil der Token-Auflösung liegt in semantic.{dark,light}.* — jede sichtbare Farbe stammt von dort. Komponenten lesen semantic.{mode}.text.primary, background.canvas usw., und die Laufzeit wählt den korrekten Sub-Tree basierend auf dem aktiven Modus.
Component-/View-Ebene: Manche Komponenten haben strukturelle Unterschiede zwischen den Modi (nicht nur Farbwechsel) — z.B. erscheint der Schlagschatten der Hero-Karte nur im dunklen Modus. Diese strukturellen Regeln sind im jeweiligen Komponenten-Abschnitt unten explizit dokumentiert.

Strukturelle Unterschiede (Zusammenfassung pro Komponente)

Komponente	Heller Modus	Dunkler Modus
TopBar	Statusleiste = dunkle Icons auf hell. Hintergrund der Leiste blendet zu `semantic.light.background.surface` (Pfirsich).	Statusleiste = helle Icons auf dunkel. Hintergrund der Leiste blendet zu `semantic.dark.background.canvas` (Tiefseegrün).
HeroCarousel	Kein Schlagschatten am Hero-Kartenkörper. Rahmenfarbe aus Light-Mode-Semantic.	Schlagschatten bei `heroCarousel.elevation = 16dp`. Rahmenfarbe aus Dark-Mode-Semantic.
HeroVideoCard	Unterer Gradient = 7 Stufen (hellere Rampe). Light-Mode-Textfarben.	Unterer Gradient = 8 Stufen (dichtere Rampe für Textlesbarkeit auf Foto). Dark-Mode-Textfarben.
ButtonGroupSection	Primärer Button = vollflächige Oberfläche, KI-Variante verwendet Light-Mode-Akzent-Gradient.	Gleiche Komponente, Dark-Mode-Akzent-Gradient.
RowSection	Titeltext aus `semantic.light.text.primary`.	Titeltext aus `semantic.dark.text.primary`.
CardPoster	Rahmen- + Schattenwerte aus Light-Mode-Tokens. Skeleton-Füllung verwendet helle bgColor.	Dasselbe mit Dark-Mode-Tokens.
MenuDrawer	Panel-Hintergrund `semantic.light.background.canvas × α 0.85` (Mobile) bzw. `× α 0.92` (Tablet-Panel) + Backdrop-Blur (24dp, Android 12+). Zeilen-Hintergrund `Color.Transparent` — Zeilen erben vom Panel.	Panel `semantic.dark.background.canvas × α 0.85 / 0.92` + Backdrop-Blur. Zeilen-Hintergrund `Color.Transparent`. Press-Feedback ist die einzige zeilenspezifische visuelle Antwort.
Home-Bildschirm	Canvas = `semantic.light.background.surface` (Pfirsich). Gradient mischt Hero-Farbe über Pfirsich.	Canvas = `semantic.dark.background.canvas` (Tiefseegrün). Gradient mischt Hero-Farbe über Tiefseegrün.

Jede Zeile gegen den Abschnitt der jeweiligen Komponente unten verifizieren — jeder strukturelle Unterschied wird auch im Audit-Notizen-Block der Komponente erwähnt.

Was (noch) NICHT im Umfang ist

Disziplin beim Umfang ist wichtig. Bisher ausgeliefert: Iteration 1 — Home-Bildschirm + Burger-Menü (iteration-1.html); Iteration 2 — die Lesepläne-Komponenten (HeroGenericCard, HeroPosterCard, CardLandscape, CardAvatar + voller ButtonGroupSection-Umfang; iteration-2.html) sowie der Design-Sync vom 2026-06-10 (festes Scrim-Band der Hero-Karten, Seitenhintergrund vereinheitlicht auf bg.canvas mit nahtloser Gradient-Konvergenz, API-Felder appearance.backgroundColor*, Badge-Textfarbe per Luminanz, Split-Karten-Verankerung).

Inzwischen geliefert und daher aus der Liste entfernt: CardOverlay und CardSplit (eigene Komponenten-Abschnitte seit Iteration 3) · Pull-to-Refresh (CollectionScreen rendert PullToRefreshBox) · der Lesepläne-Tab als Komponenten-Showcase.

Die folgenden Bildschirme und Features bleiben auch nach Iteration 2 explizit außerhalb des Umfangs und sollen jetzt nicht gebaut oder spezifiziert werden, selbst wenn die Android-Quelle Hinweise darauf enthält. Eine künftige Iteration wird jeden Punkt adressieren.

Andere Bildschirme als Home + Burger-Menü: Bibellese-Ansicht, Live-TV, TV-Programm, Konto, Suchergebnisse, Detailansichten (Serie / Video / Playlist), Vollbild-Videoplayer. Die Bottom-Nav-Ziele für diese Tabs verweisen irgendwohin, aber die Zielbildschirme sind nicht im Umfang. (Der Lesepläne-Tab beherbergt derzeit den Iteration-2-Komponenten-Showcase — das eigentliche Lesepläne-Produkt bleibt außerhalb des Umfangs.)
Authentifizierungs-Flows: Der "Anmelden"-Button im Drawer ist sichtbar, aber für den Implementierer eine No-Op-Verdrahtung — die tatsächlichen Anmeldebildschirme sind eine separate Spezifikation.
Bildschirmübergreifende Routen-Transitions: Wenn der Nutzer eine Karte → Detail antippt, die Plattform-Standardanimation verwenden. Eine dedizierte Motion-Spezifikation folgt später (Shared-Axis / Fade / Push, je nach Plattform-Konvention).
Internationalisierung über Deutsch hinaus. UI-Text ist in v1 ausschließlich deutsch; künftige Spezifikationen führen strings.json-Keys für den Rest ein.
Theming über Hell / Dunkel hinaus. Kein Akzentfarben-Picker, keine benutzerdefinierten Themes, keine nutzerspezifische Palette. Das System unterstützt sie auf Token-API-Ebene (modus-bewusst), aber die UI legt sie nicht offen.
Offline-/Cache-Inhalte. Karten rendern Skeleton- und Fehlerzustände, aber es gibt keinen lokalen Storage-Fallback und kein "Für später gespeichert"-Feature in dieser Phase.
Analytics, Crash-Reporting, Telemetrie. Der Implementierer sollte das Standard-SDK der Plattform verdrahten, aber es sind keine spezifischen Events spezifiziert.
Live-Updates über EPG-Polling hinaus. HeroLiveStreamSlide pollt EPG; keine andere Komponente empfängt Push-Updates.
Benutzerdefiniertes Fokus-Management im Web über den Plattform-Standardring + die Modal-Falle für MenuDrawer hinaus. Die aktuellen Iterationen erfordern keine Tastenkürzel.

Changelog

Änderungen an Spezifikation, Token-API und Referenz-Implementierung — adressiert u. a. den BT-3900 Token-Drift-Report (04.06.2026). Einträge, die das Rendering von Iteration-1-Komponenten (Home) verändern, sind mit [Iteration 1] markiert.

2026-07-01

Globale Icon-Regel ergänzt (Konventionen, Aufbau dieses Dokuments): Alle Icons stammen aus dem Material Symbols Rounded-Set, per Symbolname referenziert (nie als Glyph/Emoji); Android Icons.Rounded.* über MaterialSymbols.kt. Implementierungslücke (Produktion): die Produktions-App nutzt Material Symbols, aber nicht durchgängig die Rounded-Variante — auf Rounded vereinheitlichen.
HeroVideoCard: veraltete „REGRESSION"-Notizen korrigiert (#hero-video). Die Zeilenlimits sind orientierungsabhängig und im aktuellen Code umgesetzt (rememberHeroVideoDynamics, konsumiert im Mobile- und Tablet-Pfad); die früheren Hinweise „statisch … — wiederherstellen" trafen nicht mehr zu und wurden entfernt. Werte Titel/Beschreibung: Mobile 2/3 · Tablet Portrait 2/3 (crowded 2/2) · Tablet Landscape 3/5.

2026-06-11

[Iteration 1] API: heroVideo.titleFontSize — Platzhalter behoben (Report-Punkt 1). Die API liefert jetzt die echte absteigende Skala 28/24/22/20/18sp (Schwellen <20/<30/<40/<50/≥50 Zeichen, Zeilenhöhe = Größe+2) statt flat 28. Der Token ist runtime-gemergt (⚙️ API) — Clients können den gebündelten Fallback weiter nutzen, beide Quellen stimmen jetzt überein.
Doku: Geist-Token mobileEyebrowFontSize entfernt (Report-Punkt 2). Die Eyebrow-Größe kommt — wie im Code — aus heroVideo.tabletDescFontSize (14sp, bewusst auch auf Mobile). Kein neuer API-Token nötig.
Doku an API angeglichen (Report-Punkt 3): paddingDefault-Tabelle jetzt 16dp (mobil) / 20dp (tablet) statt pauschal 24dp · surfaceRaised-Replica + Beschriftung auf #252F35 korrigiert (vorher „Neutral700 #1A2733", ein Hex außerhalb jeder Palette).
[Iteration 1] Proto: globales Text-Letterspacing entfernt (Report-Punkt 4). Die Material3-Typography der Referenz-App setzte (M3-Default) letterSpacing = 0.5sp auf bodyLarge/labelSmall — nicht durch die Spec gedeckt. Jetzt 0sp; der frühere ~8px-Versatz gegenüber der BTV-App entfällt.
⚠️ cardSplit.titleFontSize/Weight — API-Korrektur 14→16 (betrifft Report-Zeile „RowSection-Poster-Fallback"): Der API-Wert 14/SemiBold war selbst Drift — die Referenz-Implementierung (Kotlin-Truth) rendert 16sp/SemiBold/1.2; API + Doku wurden am 10.06. darauf korrigiert (Drift-Gate verifiziert). Bitte den BTV-Fix „16/Medium → 14/SemiBold" auf 16/SemiBold nachziehen — zur Laufzeit liefert die API den Wert bereits.
[Iteration 1] Badges + Fortschrittsbalken auf allen Kartenvarianten: CardPoster und CardLandscape rendern jetzt das Status-/Kategorie-Badge (tagVariant/tag/contentType, oben links) nativ; CardTop10 reicht Badge + Progress an die innere Karte durch (manuelles Overlay entfernt).
Tablet-Hero: Scrim-Breite modusabhängig — tabletGradientWidthFraction hell 0.6 / dunkel 0.5 (per-Mode in API + gemergt; vorher nur gebündelt). Begründung: dunkler Text auf hellem Scrim verliert nahe der Ausblendung schneller an Lesbarkeit.

2026-06-10

[Iteration 1] Hero-Scrim: festes Band statt proportionalem Gradient (HeroVideoCard + HeroGenericCard, mobil). Volle Deckkraft am Anker contentTopPadding(140) + scrimFadeShift(52) = 192dp (Baseline der ersten Headline-Zeile), Rampe scrimFadeHeight(240dp) nach oben, darunter Vollton — unabhängig von der Texthöhe. Neue ⚙️-API-Token scrimFadeShift/scrimFadeHeight; Stop-Kurven (band-relativ) in heroVideo.gradient.stops dokumentiert. Vorher skalierten die Stop-Anteile mit der Boxhöhe — bei viel Text saßen Eyebrow/Titel auf halbtransparentem Verlauf.
[Iteration 1] Seitenhintergrund vereinheitlicht auf bg.canvas (beide Modi; hell #F8F9FA, dunkel #080D16): Basis, TopBar-Fade-Ziel und Gradient-Konvergenzpunkt sind identisch; der Seiten-Gradient konvergiert exakt (6. Stop = Canvas, vorher 24 % Rest-Tint = sichtbare Naht). Per-Page-Override via appearance.backgroundColorDark/Light (neu in der Page-API); appearance.gradientColor* hat jetzt Vorrang vor der extrahierten Hero-Farbe.
[Iteration 1] Badge-Textfarbe per Luminanz (BtvBadge): weiß auf dunklen/transluzenten, #1A1A1A auf hellen Hintergründen (Schwelle 0.179). Neuer Token badge.textColorOnLight.
[Iteration 1] Buttons brechen nie um (maxLines = 1 + Ellipsis, alle ProtoBibleButton-Varianten); auf Tablet-Heroes darf der CTA über die Inhaltsspalte hinaus bis zur Kartenbreite wachsen.
Tablet-Portrait-Zeilenlimits reduziert: heroVideo.maxLines Portrait 3/4 → 2/3 (crowded 2/2); heroFeatured erhält eigene Portrait-Limits (2/3). ⚙️ API.
Split-Karte: Titel oben ohne Eyebrow — Info-Bereich behält die feste Höhe, Eyebrow+Titel oben verankert, Footer unten; ohne Eyebrow rückt der Titel nach oben statt eine Leerzeile zu reservieren.
Karten-Token an Kotlin-Truth angeglichen (Drift seit 092): imageOnly/overlay.cornerRadius 16→12 · overlay.titleLineHeight 1.07→1.2143 · split.titleFontSize 14→16 · split.titleLineHeight 1.07→1.2. Drift-Gate (d2-card) aktualisiert und grün.
Pull-to-Refresh auf Collection-Screens ausgeliefert (PullToRefreshBox) — aus „Nicht im Umfang" entfernt.
Token-Pipeline-Hinweis (Report-Punkt 5, teilweise): diverse 🔧-Kotlin-Pfade wurden in die ⚙️ API überführt (Scrim-Maße, Hero-Zeilenlimits inkl. heroVideo.maxLines.* + heroFeatured.tabletPortrait*, badge.textColorOnLight, Tablet-Layout-Fraktionen). Noch offen u. a.: Kern-Button-Farben, Hero-Schriftfamilien, MenuDrawer-Werte, broadcast.live/focusRing — Migrations-Backlog für Iteration 3.

Jeder Eintrag ist im Repo nachvollziehbar (Branch iteration-2, Commits vom 10.–11.06.2026); Token-Werte gegen die Live-API prüfbar (/api/v1/tokens). Figma (Datei JSmrFLCfLv8vTVAZVgEwVl, Seiten i2 ·) wurde synchron aktualisiert inkl. Spec-Karten je Komponente.

Implementierungs-Schnellstart

Eine komprimierte Checkliste für einen Entwickler (oder Agenten), der auf einer Nicht-Android-Plattform kalt startet. Jeder Schritt verweist auf den ausführlichen Abschnitt.

Token-API-Client verdrahten. Beim App-Start /api/v1/tokens abrufen. Antwort cachen und beim App-Foreground erneut laden. Die vier Ebenen auf Plattformtypen abbilden (z.B. Swift-Structs / TypeScript-Interfaces). Fallback auf gebündelte Defaults, falls das Netzwerk nicht erreichbar ist — siehe Android-resolveMediathekTokens für das Merge-Muster.
Zuerst die übergreifenden Kontrakte implementieren. Bewegungssprache (Dauernskala + 6 Easings), Barrierefreiheits-Baseline (48dp-Trefferflächen, Fokusringe, reduzierte Bewegung), Breakpoints (mobile / tablet auf Root-Ebene berechnet, per Kontext propagiert).
Dann Leaf-Komponenten bottom-up bauen. Mit den kleinsten beginnen: CardPoster. Sein visueller Kontrakt ist in sich geschlossen, der einzige Seiteneffekt ist der Tap-to-Detail-Callback. (Andere Kartenvarianten wie CardLandscape / CardTop10 sind im Android-Quellcode für andere Views vorhanden, aber außerhalb des Iteration-1-Home-Umfangs.)
Dann die Abschnitts-Container. RowSection (rendert eine horizontal scrollende Reihe von Karten) · ButtonGroupSection. RowSection steuert die Karten-Varianten-Dispatch aus Serverdaten.
Dann der Hero-Stack. HeroCardShell-Chrome-Wrapper · die vier Slide-Varianten · HeroCarousel-Außenhülle (verwaltet Auto-Advance, Wischen, Farbauflösung aus der Composition-API) · PageIndicator.
Dann die bildschirmebene Oberflächen. TopBar · BottomNavigation · Home-Bildschirm-Orchestrator, der alles komponiert.
Schließlich das Overlay. MenuDrawer — das einzige Modal im Umfang von Iteration 1. Fokus-Falle und reduzierte Bewegung korrekt umsetzen.
Validieren. Den Barrierefreiheits-Audit der Plattform ausführen (axe im Web, Accessibility Inspector auf iOS, Espresso Accessibility auf Android). Eigene Renderings gegen die in jedem Komponenten-Abschnitt eingebetteten Android-Referenzscreenshots vergleichen.

Agenten- / autonomes Tooling. Eine maschinenlesbare Zusammenfassung dieses Kontrakts wird unter handover.json veröffentlicht — Komponenten, Klassifikation, Bewegungsskala, Breakpoints, Barrierefreiheits-Baseline, Token-Abdeckung, Governance-Gates. Damit lassen sich automatisierte Implementierungen oder Compliance-Prüfungen bootstrappen. Abschnitts-Anker zur Nachvollziehbarkeit zitieren (z.B. handover.html#hero-carousel).

Komponentenmatrix

Komponenten über die bisherigen Iterationen hinweg. Die Spalte Iter. nennt, in welcher Iteration die Komponente in den Lieferumfang kam: 1 = Home + Burger-Menü (iteration-1.html), 2 = Lesepläne-Komponenten (iteration-2.html). Die Spezifikation ist kanonisch und wächst — die Matrix ergänzt sich pro Iteration.

Komponente	Klasse	Iter.	BP-bewusst	Animiert	Abschnitt
Home-Bildschirm	Composite (Orchestrator)	1	✓	Scroll, Hintergrund-Transition	→
TopBar	Sticky	1	✓	Scroll-Fade	→
HeroCarousel	Composite · wischbar (inkl. Shell + Indicator)	1	✓	Auto-Advance · Drag	→
HeroVideoCard	Hero-Karte · Video	1	✓	Bild-Fade	→
HeroPosterCard	Hero-Karte · image-only (2-Asset)	2	✓	Bild-Fade	→
HeroGenericCard	Hero-Karte · custom URL	2	✓	Bild-Fade · Press	→
ButtonGroupSection	Section (Single-AI · Multi · Overflow)	1 · 2	✓	Press-Feedback	→
RowSection	Section · horizontales Scrollen	1	✓	horizontales Scrollen	→
CardPoster	Row-Item · 9:16	1	—	Bild-Fade · Press	→
CardLandscape	Row-Item · 16:9 image-only (S/M/L)	2	—	Bild-Fade · Press	→
CardAvatar	Row-Item · Kreis + Label	2	—	Press	→
MenuDrawer	Modal · Overlay	1	✓	Slide · Scrim-Fade	→

12 Komponenten + 1 Home-Orchestrator über Iteration 1 + 2. Jeder numerische Wert in diesem Dokument stammt aus der tatsächlichen Android-Implementierung — File:Line-Zitate erscheinen neben jedem Token, sodass jeder Wert in Sekunden gegen packages/android verifizierbar ist.

Maschinenlesbare Zusammenfassung. Ein strukturierter JSON-Snapshot dieser Matrix plus Bewegungsskala, Breakpoints, Barrierefreiheits-Baseline und Token-Abdeckungszahlen wird neben dem Dokument unter handover.json veröffentlicht — nützlich für automatisiertes Tooling, agenten-getriebene Implementierung und CI-Checks, die den Spezifikations-Kontrakt programmatisch konsumieren müssen.

Home-Bildschirm — Layout & Verhalten

Umfang Iteration 1 Composite

Der Home-Bildschirm ("Mediathek") ist die primäre Oberfläche zur Inhaltsentdeckung der App. Er besteht aus einem vertikalen Scroll von eigenständigen Inhaltsblöcken: einer fixierten Top-Leiste, einem wischbaren Hero-Karussell, einem CTA-Streifen "Die Bibel erkunden" über die volle Breite und einem unbestimmten Stapel horizontal scrollender Inhaltszeilen, die von der Page-Composition-API geladen werden.

Oberfläche

Vollbild.

Hintergrund

semantic.{mode}.background.canvas

Scroll

Vertikal, einspaltig, volle Breite.

Design

Übernimmt Hell oder Dunkel gemäß Nutzerpräferenz. Hero-Blöcke überschreiben lokal basierend auf Slide-Inhalt.

Layout-Struktur

Der Home-Bildschirm ("Mediathek") ist ein vertikaler Scroll eigenständiger Inhaltsblöcke, orchestriert von CollectionScreen (dem server-getriebenen Home-Composer). Er hat drei Verantwortlichkeiten, die die im Umfang befindlichen Komponenten nicht selbst übernehmen: (1) Abschnittskomposition + Abstände, (2) die Sticky-Top-Leiste mit scroll-getriebenem Hintergrund-Fade, und (3) die Hintergrund-Transition — ein Vollbild-Gradient, der die Farbe des aktiven Hero-Slides aufnimmt und sie über die gesamte Canvas blutet.

Mobil — vertikale Komposition Alle Abschnittsabstände aus views.home.layout.* Tokens

Callout-Legende

Canvas — Basis-HintergrundVollbild-Hintergrund = pageBackgroundColor: semantic.{mode}.background.canvas in beiden Modi (hell #F8F9FA / dunkel #080D16). Die Page-API kann pro Seite per appearance.backgroundColorLight/Dark übersteuern. Der Gradient-Bleed (Punkt 2) zeichnet darüber.CollectionScreen.kt:98–104, 152–155
Hintergrund-Gradient-Bleed (die "Hintergrund-Transition")Vertikaler Gradient mit 6 Stufen, gezeichnet von GradientBackground von y=0 bis zur Bildschirmhöhe via ColorTransformations.pageGradientStops. Obere Farbe = Mischung der gradientSourceColor über canvas bei α 0.8. Stop-Anteile: 0.0 → obere Farbe · headerStopFraction → obere Farbe · 0.3 → α 0.68 · 0.5 → α 0.48 · 0.75 → α 0.24 · 1.0 → canvas exakt (α 0) — der Gradient konvergiert nahtlos in den Seitenhintergrund (identisch zur color-engine computeGradientStops). Dies ist es, was dem Home seine hero-getriebene Stimmung verleiht.CollectionScreen.kt:315–343 (GradientBackground) · ColorTransformations.kt:35 (pageGradientStops)
HeroCarousel-BlockOberster Inhaltsblock. Sein onBackgroundColorChange-Callback aktualisiert den heroBackgroundColorArgb-State auf dem Home. Die Gradient-Quellfarbe wird per resolvePageGradientSource aufgelöst: API-appearance.gradientColorLight/Dark gewinnt, extrahierte Hero-Farbe ist Fallback, sonst Canvas.CollectionScreen.kt:107–110, 133–140, 345–351
AbschnittsabstandVertikaler Abstand zwischen allen Abschnitten · views.home.layout.sectionGapMobile = 24dp · sectionGapTablet = 32dp · getrieben von verticalArrangement = Arrangement.spacedBy(section.verticalSpacing) in der LazyColumnCollectionRenderer.kt:54 · views/home.json (Spec 083)
ButtonGroupSectionCTA-Streifen über volle Breite. Siehe ButtonGroupSection.
RowSection × N — server-getriebenAnzahl der Reihen + ihre Kartentypen kommen aus der Composition-API. Iteration 1 rendert nur POSTER_PORTRAIT-Reihen. Siehe RowSection.

Hintergrund-Transition — formaler Kontrakt

Der Hintergrund des Home "folgt" dem aktiven Hero-Slide. Dies ist die wichtigste visuelle Signatur des Designs; sie verbindet Hero → Home-Canvas zu einer kohärenten Oberfläche. Der Implementierer muss diesen Kontrakt exakt reproduzieren.

Phase	Was passiert	Quelle
Initiales Laden	Home wird gerendert. Wenn der erste Hero-Slide eine `gradientColor`-Hex-Angabe in seinem Composition-Payload trägt, wird einmal eine initiale Farbe emittiert — der Hintergrund-Gradient übernimmt diese Farbe. Andernfalls bleibt die Canvas-Farbe als Basis.	HeroCarousel.kt:176–199
Slide settled	HeroCarousel emittiert `onBackgroundColorChange(currentPageBgColor)` über seinen Callback. Home speichert ihn als `heroBackgroundColorArgb`-State. Die nächste Recomposition berechnet `gradientSourceColor` = `heroBackgroundColor` neu. `GradientBackground` zeichnet mit der neuen oberen Farbe neu.	CollectionScreen.kt:100–103, 132–139, 263–266
Nutzer zieht Karussell	HeroCarousel emittiert kontinuierlich während des Ziehens — die Farbe wird interpoliert `lerp(fromBgColor, toBgColor, dragProgress)`. Der Hintergrund-Gradient des Home aktualisiert sich in Echtzeit und morpht zwischen den Stimmungen der zwei Slides.	HeroCarousel.kt:137–159
Seitenwechsel (Auto-Advance)	Wie bei "Slide settled" — der Emit erfolgt auf der neuen `currentRealPage`, nachdem die Auto-Advance-Animation abgeschlossen ist.	HeroCarousel.kt:165–174
Nutzer scrollt nach unten	Der TopBar-Hintergrund blendet ein (Alpha 0 → 1 über 300 px Scroll). Die Headline-Opazität bleibt bei 1. Der Gradient-Bleed (unter der TopBar) bleibt sichtbar, bis der Nutzer darüber hinausscrollt — es gibt keinen separaten scroll-getriebenen Fade auf dem Gradient selbst.	CollectionScreen.kt:141–152
Theme-Wechsel (Dunkel ↔ Hell)	Sowohl `baseDarkColor` als auch `canvasBg` werden neu berechnet (heller Modus verwendet `background.surface`, dunkler verwendet `background.canvas`). Der Gradient wird neu gemischt.	CollectionScreen.kt:95–97, 327

Hintergrund-Gradient — 6 Stufen, vollständig spezifiziert

Stop-Anteil	Farbe	Hinweise
`0.0`	`blendOver(gradientColor, canvas, α 0.8)`	Oberer Bildschirmrand — stärkster Hero-Farbeinfluss.
`headerStopFraction`	`blendOver(gradientColor, canvas, α 0.8)`	Gleiche Farbe wie 0.0 — hält den oberen Farbton flach unter der TopBar. `headerStopFraction = stickyHeaderHeight / screenHeight`.
`0.3`	`blendOver(gradientColor, canvas, α 0.68)` = `0.8 × 0.85`	Beginnt zur Canvas auszublenden.
`0.5`	`blendOver(gradientColor, canvas, α 0.48)` = `0.8 × 0.6`	Mitte des Bildschirms — halb gemischt.
`0.75`	`blendOver(gradientColor, canvas, α 0.24)` = `0.8 × 0.3`	Letzter getönter Stop.
`1.0`	`canvas` (exakt, α 0)	Unten — konvergiert exakt in den Seitenhintergrund, keine Naht.

ColorTransformations.kt:35 (pageGradientStops) · blendOver(source, destination, sourceAlpha) in ColorTransformations · blendAlpha = 0.8f macht den oberen Bereich "dominant hero, aber nicht reines Hero" · Stop-Kurve identisch zur color-engine (lib/palette.js computeGradientStops), die die per-Item-Paletten der Page-API erzeugt.

Verhalten

Abschnittskomposition

Der Server liefert eine collection.sections-Liste. CollectionRenderer rendert sie in Reihenfolge mit LazyColumn und verticalArrangement = Arrangement.spacedBy(section.verticalSpacing). Jeder Abschnitt ist eines von: HeroCarouselSection, ButtonGroupSection, RowSection (POSTER_PORTRAIT im Umfang von Iteration 1). Außerhalb des Umfangs liegende Abschnittstypen (FEATURED, TOP10, AVATAR) sind aktuell im Quellcode vorhanden, werden aber im Iteration-1-Home nicht gerendert.

Produktiver Home-Payload (Iteration 1, live)

Live-Beispiel aus https://page-api.beta.bibeltv.de/v1/page/home (Stand Mai 2026) — die Iteration-1-Produktions-Payload trägt genau diese 5 Komponenten in dieser Reihenfolge:

slider_hero mit 2 card_hero_media-Slides (→ HeroCarousel mit HeroVideoCard)
group_button mit 1 Button "Die Bibel erkunden" (→ ButtonGroupSection im Single-Item-AI-CTA-Modus)
slider mit 3 card_poster_small-Karten (→ RowSection mit CardPoster)
slider mit 3 card_poster_medium-Karten
slider mit 3 card_poster_small-Karten

Was das für Iteration 1 bedeutet: die Agentur muss nur die zwei Karten-Typen card_hero_media und card_poster_* ausliefern, plus die Single-Item-AI-CTA-Variante der ButtonGroupSection. Andere Karten-Typen (verse, featured, livestream, landscape, top10, avatar) existieren im Composition-Modell und im Android-Renderer, werden aber von dieser Payload nicht angefordert und sind explizit verschoben. Der Multi-Item-/Overflow-Branch der ButtonGroupSection muss trotzdem implementiert werden — er ist der dokumentierte Vertrag und kann in einer zukünftigen Payload-Variante aktiviert werden ohne Code-Änderung.

Sticky Header

Die TopBar wird in einer separaten Box bei zIndex(10f) gerendert, NICHT innerhalb der LazyColumn. Das bedeutet, sie bleibt am oberen Rand geklebt, auch wenn der Inhalt darunter scrollt. Ihr Hintergrund ist der scroll-getriebene Fade (siehe TopBar).

Statusleiste

Die System-Statusleiste wird per window.statusBarColor = TRANSPARENT auf transparent gezwungen; isAppearanceLightStatusBars spiegelt das aktuelle Design, sodass die System-Icons lesbar bleiben. Padding für die Höhe der Statusleiste wird innerhalb der TopBar-Komponente hinzugefügt (nicht als Window-Inset auf der Bildschirm-Wurzel), sodass der Gradient-Bleed dahinter durchgreift.

Pull to Refresh

Iteration 1: ja, Pull-to-Refresh ist über PullToRefreshBox verdrahtet. Löst onRefresh aus, das den Composition-Payload erneut lädt. Spinner-Farbe folgt dem Design.CollectionScreen.kt:160–164

Dimensionen

Eigenschaft	Mobil	Tablet	Token
Horizontales Seitenpadding	16dp	32dp	`views.home.layout.contentPaddingHorizontal{Mobile,Tablet}`
Oberes Inhalts-Padding	8dp	16dp	`views.home.layout.contentPaddingTop{Mobile,Tablet}`
Abschnittsabstand (zwischen Abschnitten)	24dp	32dp	`views.home.layout.sectionGap{Mobile,Tablet}`
Unteres Inhalts-Padding	24dp	32dp	`views.home.layout.contentPaddingBottom{Mobile,Tablet}`
Karten-Abstand innerhalb Reihe	16dp	16dp	`views.home.layout.rowCardSpacing{Mobile,Tablet}`
Höhe des Sticky-Headers	statusBar + 56dp	statusBar + 56dp	`collectionView.headerHeightDp` + System-Inset
Hintergrund-Gradient — Blend-Alpha	0.8	0.8	`collectionView.gradientBlendAlpha`

Barrierefreiheit

Der Home ist eine vertikale Scroll-Region — Hilfstechnologien kündigen jeden Abschnitt nacheinander an.
Der Hintergrund-Gradient ist rein dekorativ — er trägt keine semantische Bedeutung.
Pull-to-Refresh kündigt "Aktualisieren" beim Auslösen und "Aktualisiert" bei Erfolg an.
Die Statusleiste verwendet das passende Erscheinungsbild (helle Icons im dunklen Design, dunkle Icons im hellen Design) für die Lesbarkeit.

Audit-Notizen

Keine Regressionen erkannt. Alle Abschnittsabstände werden über views.home.layout.*-Tokens gelesen (Spec 083). Der Hintergrund-Gradient verwendet das tokenisierte collectionView.gradientBlendAlpha = 0.8f. Die 5 Stop-Anteile des Gradients (0.0, headerStopFraction, 0.3, 0.5, 1.0) und die kumulativen Alpha-Multiplikatoren (×0.85, ×0.6, ×0.3) sind Laufzeit-Layoutkonstanten — sie sind zurecht nicht tokenisiert, da sie die Kurvenform definieren, nicht einen Designwert.

Ein Hinweis für Implementierer: Die Hintergrund-Gradient-Logik liegt in einem privaten Composable innerhalb CollectionScreen.kt. Falls iOS/Web die Formel über die Design-Tokens-API teilen möchten, könnten die 5 Stop-Anteile zu views.home.backgroundGradient.stops (ein Array) befördert werden. Für Parität nicht erforderlich — die Mathematik ist klein genug, um sie neu zu implementieren.

Verhalten

Initiales Laden

Bei der ersten Navigation zum Home: Page-Composition-Payload laden, TopBar sofort rendern (Skeleton-Hero + Skeleton-Reihen darunter), dann Inhalt rendern, sobald er aufgelöst wird. Das Hero-Karussell beginnt erst mit dem Auto-Advance, nachdem das erste Slide-Bild aufgelöst ist.

Scroll-Verhalten

Vertikales Scrollen blendet die Deckkraft des TopBar-Logos von 1 → 0 über die ersten component.btvTopBar.scrollFadeDistanceDp = 120dp des Scrolls aus und lässt die Cast- und Konto-Icons vollständig sichtbar. Die Hintergrundfarbe der Leiste blendet im selben Bereich von transparent zu semantic.{mode}.background.canvas.

Tab-Reta

Das Antippen des Home-Tabs, während Home bereits aktiv ist, scrollt den Inhalt mit der plattformüblichen Smooth-Scroll-Animation (≤300ms) nach oben.

Pull to Refresh

Seit Iteration 2 implementiert: PullToRefreshBox (Material 3) umschließt den Inhalt; die Geste löst onRefresh aus und der Indikator verschwindet, sobald der Page-Payload nicht mehr im Loading-Zustand ist.CollectionScreen.kt:157–166

Leere / Fehlerzustände

Wenn der Page-Composition-Payload fehlschlägt: TopBar + zentrierter Text "Inhalt konnte nicht geladen werden" mit einem Wiederholungs-Button rendern. Keine Skeletons.

Composition-API-Kontrakt

Der Bildschirm konsumiert den Page-Payload (GET /api/v1/pages/{slug} → PlaylistCollection):

Feld	Typ	Bedeutung
`id`	`String`	Seiten-Slug (z. B. `home`, `mediathek`, `leseplan`).
`title`	`String?`	Optionaler Seitentitel.
`sections`	`List<Section>`	Servergesteuerte Abschnittssequenz; pro Abschnitt siehe den jeweiligen Komponenten-Kontrakt.
`appearance.gradientColorDark` / `gradientColorLight`	`String?` (Hex)	Quellfarbe des Hintergrund-Gradient-Bleeds pro Modus. Hat Vorrang vor der extrahierten Hero-Farbe (`resolvePageGradientSource`); fehlt der Wert, ist die extrahierte Hero-Farbe der Fallback, sonst Canvas.
`appearance.backgroundColorDark` / `backgroundColorLight`	`String?` (Hex)	Seitenhintergrund pro Modus (Basis, TopBar-Fade-Ziel und Gradient-Konvergenzpunkt zugleich). Fallback: Token `bg.canvas` (`#080D16` / `#F8F9FA`). Vom Server aus `PAGE_BACKGROUND` (assemblyService) befüllt — muss mit dem Token und der color-engine-Canvas übereinstimmen.

PlaylistCollectionModels.kt (CollectionAppearance) · CollectionScreen.kt:98–110, 133–140 · playlist-api/src/types/playlist.ts

Referenz

Home mobile, dark — Mobil · Dunkel · Scrollposition 0

Home mobile, light — Mobil · Hell · Scrollposition 0

Home tablet, dark — Tablet · Dunkel · Scrollposition 0

Home tablet, light — Tablet · Hell · Scrollposition 0

TopBar

Umfang Iteration 1 Sticky

Persistente Leiste, die oben am Home- (und anderen Top-Level-)Bildschirmen verankert ist. Beherbergt das Marken-Logo, einen Chromecast-Trigger und den Konto-/Burger-Button, der den MenuDrawer öffnet.

Visuelle Spezifikation

Aufbau

Sticky-Leiste, oben am Home-Bildschirm verankert. Beherbergt das Marken-Logo (links), Chromecast-Trigger (rechts) und das Konto-/Burger-Icon, das den MenuDrawer öffnet. Der Hintergrund blendet aus transparent ein, sobald der Nutzer die Seite darunter scrollt.

Mobil & Tablet — gleiche Struktur, breakpoint-bewusstes Padding Leistenhöhe 56dp · Logohöhe 22dp