Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M31-branding.md
T

6.5 KiB

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
31 Branding / Theme 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-9
requirements-pur

Modul 31 — Branding / Theme

Detail-Spec gemäß LP-9. Phase 1 minimal: nur Light/Dark-Mode pro User. Voll-Branding (Logo, Farben, White-Label) ist Phase 2. Modul ist in Phase 1 bewusst fast leer.

Themenblöcke

A. Datenmodell (Phase 1)
B. Routes & Settings (Phase 1)
C. Theme-Auflösung (System/Light/Dark)
D. Permissions
E. Phase 2 / spätere Features

Block A — Datenmodell (Phase 1)

A.1 — User.theme_preference

Bestehendes/zu ergänzendes User-Feld:

  • theme_preference (Enum: system | light | dark, Default system)

Anwendung:

  • system → folgt OS-/Browser-Präferenz (prefers-color-scheme)
  • light → erzwingt Light-Theme
  • dark → erzwingt Dark-Theme

Persistierung:

  • Server-side in User.theme_preference
  • Client-side Cache in Cookie/LocalStorage für SSR-Konsistenz (verhindert Flash-of-Wrong-Theme)

A.2 — Keine weiteren Tabellen in Phase 1

In Phase 1 wird kein TenantBranding, kein Logo-Upload, keine Tenant-Farb-Tabelle angelegt. Voll-Datenmodell siehe Phase 2 (Block E).


Block B — Routes & Settings (Phase 1)

B.1 — User-Profile-Settings (/{tenant}/settings/profile/)

Theme-Auswahl:

  • Toggle/Picker mit drei Optionen: System / Hell / Dunkel
  • Sofortige Anwendung ohne Reload
  • Persistierung in User.theme_preference

Klartext:

  • Option System: „Folgt der Einstellung deines Geräts"
  • Option Hell: „Helles Design"
  • Option Dunkel: „Dunkles Design"

B.2 — Keine Tenant-Admin-Route in Phase 1

/{tenant}/admin/branding/ existiert in Phase 1 nicht. Erst Phase 2 (siehe Block E).


Block C — Theme-Auflösung

C.1 — Auflösungs-Reihenfolge

Beim Rendern einer User-Session:

  1. Wenn User eingeloggt + User.theme_preference = light → Light
  2. Wenn User eingeloggt + User.theme_preference = dark → Dark
  3. Sonst (system oder nicht eingeloggt): Browser-Media-Query prefers-color-scheme
  4. Fallback: Light

C.2 — Live-Reaktivität bei system

  • Wenn User theme_preference = system und OS-Theme wechselt während der Session, soll Theme live mitwechseln
  • Listener auf matchMedia('(prefers-color-scheme: dark)') Change-Event

C.3 — SSR-Konsistenz

  • Server rendert mit Theme-Klasse auf <html> basierend auf Cookie/Header
  • Verhindert Flash-of-Wrong-Theme beim Hydrate

C.4 — Anwendung in App und Capacitor

  • Web: über CSS-Variablen + Theme-Class auf <html> (Implementierungs-Detail Tailwind-dark:-Variants)
  • Capacitor (Modul 36): native Status-Bar / Splashscreen müssen Theme respektieren (Native-Hooks setzen)

Block D — Permissions

Permission-IDs

Phase 1 hat keine branding-spezifischen Permissions. User kann eigenes Theme jederzeit setzen.

Phase 2: branding.admin als eigene Permission, gegated über tenant.admin für Tenant-weite Branding-Settings.

Klartext-Fehler

In Phase 1 keine relevanten Fehler-Cases.


Phase 2 / spätere Features

E.1 — Tenant-Branding (Standard, alle Pläne)

Datenmodell — neue Tabelle TenantBranding:

  • tenant_id (PK, FK)
  • logo_file_id (FK auf File, optional)
  • primary_color (Hex-String, validiert)
  • accent_color_1 (Hex-String, optional)
  • accent_color_2 (Hex-String, optional)
  • tenant_display_name (überschreibt System-Default in UI, optional)
  • updated_at, updated_by_user_id

Routes:

  • /{tenant}/admin/branding/ — Verwaltungs-Seite

Funktionen:

  • Logo-Upload (PNG/SVG, max-Größe definiert)
  • Farb-Picker für Primärfarbe + 1-2 Akzentfarben mit Live-Preview
  • Tenant-Name-Override für UI-Anzeige
  • Branding-Anwendung in: Sidebar/Header-Logo, Email-Header, Customer-Portal, Login-Screen, Capacitor-Splashscreen
  • Reset-auf-Default-Funktion

Permission: branding.admin (über tenant.admin)

E.2 — Outbound-Email-Templates mit Branding

  • System-Email-Templates erben Tenant-Logo + Primärfarbe
  • Header-/Footer-Bereiche im Template-System branding-bewusst
  • Marketing-Emails (Modul 10) übernehmen Branding standardmäßig, optional override

E.3 — Custom-Login-Screen

  • Tenant-Logo + ggf. Hintergrund-Bild auf /login wenn Tenant-Subdomain/-Slug erkannt
  • Phase 2 für alle Pläne

E.4 — Custom-Splashscreen für Capacitor-App

  • Tenant-Logo als Splashscreen in iOS/Android-Builds
  • Generierung pro Tenant über Build-Pipeline (Implementierungs-Detail) oder dynamisches Theming beim App-Start

E.5 — White-Label-Modus (Enterprise only)

Funktionen:

  • Eigene Domain (crm.geerkens.de als CNAME zu app.hivegrid.de/{tenant})
  • Eigene Fonts (Upload von Webfonts oder Google-Fonts-Auswahl)
  • Vollständig anpassbares Theme (alle Farb-Variablen, nicht nur Primary/Accent)
  • Eigenes Email-Template-System (Tenant baut Templates selbst inkl. HTML)
  • HiveGrid-Branding entfernt (Footer, Email-Footer, Login-Page)
  • Custom-Domain-Workflow inkl. Cert-Management (Caddy-Auto-HTTPS)

Permission: branding.white_label — nur in Enterprise-Plan via Feature-Gate (Modul 27, Block F)

Datenmodell-Erweiterung TenantBranding:

  • custom_domain (String, validiert)
  • custom_font_file_ids[]
  • theme_variables (JSONB — alle CSS-Variablen)
  • email_templates_custom (Boolean Toggle)
  • hide_hivegrid_branding (Boolean Toggle)

E.6 — Branding-Preview vor Live-Schalten

  • Tenant-Admin sieht Vorschau vor Anwendung
  • Apply-Button schaltet live für alle User des Tenants

Architektur-Vorschriften (Querschnitt)

  • LP-9 — Spec-Tiefe: Phase 1 minimal gehalten, Phase 2 explizit umrissen
  • AV #4 — Alle Strings extern: Tenant-Name-Override aus DB, nicht hartkodiert (relevant für Phase 2)
  • LP-13 — EU-Stack: Logo-Storage über Scaleway-EU (Modul 23)

Detail-Spec-Status: DRAFT

Modul ist in Phase 1 bewusst minimal. Phase-2-Features sind grob umrissen für Roadmap-Klarheit; Detail-Spec für Phase 2 erfolgt vor Phase-2-Implementierung.

Offene Detail-Punkte (nicht-blockierend):

  • Konkrete CSS-Variable-Namen (Implementierungs-Detail Tailwind-Config)
  • SSR-Cookie-Name für Theme-Persistierung
  • Capacitor-Native-Hook für Status-Bar-Theming (Implementierungs-Detail)

Abhängige Module:

  • Modul 27 (Auth) — User.theme_preference-Feld
  • Modul 36 (Mobile/Capacitor) — Native-Status-Bar/Splashscreen-Theming
  • Phase 2: Modul 23 (Files) — Logo-Upload-Storage
  • Phase 2: Modul 27 (Auth, Block F) — Feature-Gate für White-Label-Enterprise