Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M31-branding.md
T

14 KiB

Boilerplate-Abgleich — M31 Branding / Theme

Feld Wert
Modul-ID M31
Name Branding / Theme
Milestones M030 (Hell/Dunkel-Modus + Capacitor-Status-Bar) — Phase 1. (Spec-Quelle _bmad-output/specs/M31-branding.md; LP-9. Phase-2-Features E.1-E.6 ohne eigenes Milestone in docs/milestones/.)
Block Block 1, Abschnitt 31.1 (_bmad-output/pflichtenheft/blocks/block1.md)
Reuse-Level Phase 1 medium — solide Light/Dark-Basis vorhanden, aber binär statt drei-modig; "system"-Modus + Live-Reaktivität fehlen
Reuse-Level Phase 2 medium-high — Tenant-Theme-Engine (Farben/CSS-Vars), System-Branding-Felder (Logo/Favicon) und Mail-Brand-Tokens existieren als starke Vorlage

WICHTIG zur Milestone-Benennung: Das Milestone-Verzeichnis docs/milestones/M031-feature-flag-schalter-lifecycle/ gehört NICHT zu diesem Modul (das ist Feature-Flags). Das fachlich passende Milestone für M31 Branding/Theme Phase 1 ist docs/milestones/M030-hell-dunkel-modus/.

Hinweis zur PLAN.md-Annahme: M030/PLAN.md nennt „next-themes bereits in Boilerplate-Deps". Das ist falsch verifiziert — next-themes taucht in der Boilerplate nur in apps/web/app/utils/build/buildWarningTriage.ts (Build-Warnungs-Triage) auf, NICHT als aktive Theme-Lib. Die reale Boilerplate nutzt ein eigenes Session/Cookie-basiertes Dark-Mode-System (siehe unten). Slice-Planung muss das korrigieren.


Was das Modul fachlich braucht (aus Spec)

Phase 1 (M030 / minimal):

  • A: User.theme_preference Enum system | light | dark, Default system
  • B: User-Settings-Route /{tenant}/settings/profile/ mit 3-Optionen-Picker, sofortige Anwendung ohne Reload
  • C: Theme-Auflösung (User-Pref → prefers-color-scheme → Light-Fallback), Live-Reaktivität bei system (matchMedia-Listener), SSR-No-Flash via Cookie/Header, Anwendung in Web (dark:-Class) + Capacitor (Status-Bar/Splash)
  • D: keine Permissions in Phase 1

Phase 2 (E.1-E.6, später): TenantBranding-Tabelle (Logo, primary/accent-color, display-name), /{tenant}/admin/branding/, Logo-Upload, Farb-Picker mit Live-Preview, Branding in Email/Portal/Login/Splash, White-Label (custom_domain, custom fonts, theme_variables JSONB), Permissions branding.admin + branding.white_label (Enterprise-Gate via M27).


Übernehmbar aus Boilerplate

Boilerplate-Pfad Was Wie nutzbar
prisma/schema/accounts.prisma:17 User.lightOrDarkMode String? — Per-User Hell/Dunkel-Präferenz anpassen — Feld existiert, ist aber binär (light/dark, nullable). Muss zu 3-Wert-Enum system|light|dark mit Default system erweitert/migriert werden
apps/web/app/root.tsx:97-100 SSR-Anwendung der dark-Klasse auf <html> aus userSession.lightOrDarkMode (gated über DARK_MODE_IN_APP) als-vorlage — No-Flash-Mechanik via Session vorhanden; muss um system-Auflösung (prefers-color-scheme) + Cookie-Header-Lesung erweitert werden
apps/web/app/root.tsx:184-213 Action toggleLightOrDarkMode (+ setTheme, setLocale): persistiert in User-DB + Session, feuert EventsService.create Audit-Event user.preferences.updated als-vorlage — Persist-Pfad + Audit-Wiring vorhanden; Toggle→3-Wert-Set umbauen
apps/web/app/routes/preferences.tsx Dedizierte /preferences-Action-Route, an die Toggle/Selector posten anpassen — Endpoint-Pattern wiederverwenden; Action für 3-Wert-Preference ergänzen
apps/web/app/utils/theme/userThemePreference.server.ts LIGHT_OR_DARK_MODES, normalizeLightOrDarkMode, nextLightOrDarkMode, persistUserLightOrDarkMode(userId, …) anpassen — Normalisierung/Persist als Basis; Enum um system erweitern, Auflösungs-Helfer (resolveEffectiveTheme) neu ergänzen
apps/web/app/components/ui/toggles/DarkModeToggle.tsx (DarkModeToggle, DarkModeSvgs) Binär-Toggle-Button mit i18n-Label + Analytics-Event als-vorlage — für 2-Wert; für Phase-1-Spec (3 Optionen) eher Picker (s. nächste Zeile)
apps/web/app/components/ui/selectors/ThemeSelector.tsx Dropdown/Select-Picker, postet setTheme an /preferences mit Analytics als-vorlage — Picker-Pattern (Dropdown + fetcher.submit) direkt für System/Hell/Dunkel-Auswahl übernehmbar; Optionen-Quelle austauschen
apps/web/app/components/layouts/sidebars/shadcn/nav-user.tsx:152-157 Theme-Toggle bereits in User-Menü der App-Shell verdrahtet (onThemeToggle, gated über DARK_MODE_IN_APP) als-vorlage — Einbau-Ort in Shell vorhanden; auf Picker/3-Wert anpassen
apps/web/app/application/Constants.ts:10 DARK_MODE_IN_APP = true — Schalter ob App-Bereich Dark-Mode bekommt 1:1 als Feature-Gate-Vorbild (Spec D verlangt Feature-Flag-Fähigkeit)
apps/web/app/application/enums/shared/Theme.ts enum Theme { LIGHT, DARK } anpassen — um SYSTEM erweitern
apps/web/app/locale/.../translations.json (components.themeToggle.modeLabel.light/dark, settings.theme.*, shared.theme) Vorhandene i18n-Keys de+en für Theme-Labels anpassen — system-Label ergänzen; Klartext aus Spec B.1 einsetzen
apps/mobile/package.json:25 (@capacitor/status-bar 7.0.1), @capacitor/splash-screen 7.0.1 Capacitor Status-Bar- + Splash-Plugins als Dependency installiert als-vorlage — Plugins vorhanden, aber keine theme-aware Nutzung (kein StatusBar.setStyle-Aufruf in apps/mobile/src) → Spec C.4 muss neu gebaut werden

Phase-2-relevante Vorlagen (Tenant-Branding / White-Label)

Boilerplate-Pfad Was Wie nutzbar
prisma/schema/accounts.prisma:187-188 Tenant.theme String? + Tenant.themeConfig String? (serialisierter JSON-String mit Farben inkl. darkColors, sidebar*) als-vorlage für Phase-2-TenantBranding (Farb-Override pro Tenant)
apps/web/app/utils/theme/ThemeConfig.ts (parseThemeConfig, ThemeConfig) Parst Tenant-themeConfig → CSS-Variablen (alle Farb-Slots inkl. dark, sidebar, radius, fontFamily) als-vorlage für Phase-2-Live-Theming / theme_variables JSONB (E.5)
apps/web/app/utils/theme/defaultThemes.ts (themeConfigurations, defaultThemes, defaultTheme="blue") ~20 vordefinierte Farbschemata (light+dark) als CSS-Var-Sets als-vorlage für Farb-Picker-Presets (E.1)
apps/web/app/themes.css (~86 KB) .theme-{name} + .dark.theme-{name} Klassen als-vorlage für Phase-2-CSS-Var-Theming
apps/web/app/routes/app.$tenant/settings/theme.tsx + apps/web/app/components/core/tenants/forms/UpdateTenantFormTheme.tsx Tenant-Theme-Verwaltungs-Route (update-theme-Action, Permission-gated app.settings.account.view/update, Live-Preview via themePreviewStore) als-vorlage für /{tenant}/admin/branding/ (E.1) — Route-/Form-/Permission-Pattern direkt adaptierbar
apps/web/app/stores/themePreviewStore.ts (useThemePreviewStore) Client-Store für Live-Preview-Override im Shell-Layout als-vorlage für „Preview vor Live-Schalten" (E.6)
apps/web/app/components/layouts/sidebars/shadcn/ShadcnSidebarLayout.tsx Liest Tenant-themeConfig + Dark-Mode → injiziert --sidebar* CSS-Variablen in Shell als-vorlage für Anwendung von Tenant-Branding in Sidebar/Header (E.1)
prisma/schema/core.prisma:6,23-27 (AppConfiguration.theme, brandingLogo, brandingLogoDarkMode, brandingIcon, brandingIconDarkMode, brandingFavicon) System-weite (nicht tenant-bezogene) Branding-Felder als-vorlage für Feld-Shape der Phase-2-TenantBranding-Tabelle (Logo + Dark-Logo + Icon + Favicon)
apps/web/app/utils/db/appConfiguration.db.server.ts:90,196,251-292 Load/Persist + Mapping branding.logo/logoDarkMode/icon/iconDarkMode/favicon als-vorlage für DB-Service-Layer Phase 2
apps/web/app/root.tsx:127-135 Favicon/Branding-Logo aus appConfiguration.branding ins <head> injiziert als-vorlage für Tenant-Branding-Anwendung (E.1)
packages/brand/src/index.ts (@toolctrl/brand) Brand-Tokens (productName, legal/support-Links, assets, mail.colors), createBrandTokens, resolveTransactionalBrandTokens, brandCssVariables als-vorlage für E.2 (Email-Branding mit Logo+Primärfarbe) — Mail-Color-Token-Resolution + CSS-Var-Export bereits fertig
prisma/schema/portals.prisma:14-15 (themeColor, themeScheme) + apps/web/app/modules/portals/db/portals.db.server.ts:176-209 Per-Portal themeColor/themeScheme (separates Customer-Portal-Theming) als-vorlage für E.3 Custom-Login/Portal-Branding (eigenständiges Konzept, nicht 1:1)

Vorhandene Daten-Modelle

Modell / Feld Pfad Deckung
User.lightOrDarkMode String? prisma/schema/accounts.prisma:17 Phase 1 A.1 — teilweise (binär statt 3-Wert-Enum, nullable statt Default system)
Tenant.theme String? prisma/schema/accounts.prisma:187 Phase 2 E.1 — Tenant-Farbschema-Auswahl
Tenant.themeConfig String? prisma/schema/accounts.prisma:188 Phase 2 E.1/E.5 — serialisierte Tenant-Theme-Vars (Whitelabel-Vorlage)
AppConfiguration.theme / brandingLogo / brandingLogoDarkMode / brandingIcon / brandingIconDarkMode / brandingFavicon prisma/schema/core.prisma:6,23-27 Phase 2 E.1 — System-Level Branding-Feld-Shape (Vorlage für TenantBranding)
Portal.themeColor / themeScheme prisma/schema/portals.prisma:14-15 Phase 2 E.3 — Customer-Portal-Theming (separat)

Existiert NICHT (muss in Phase 2 neu angelegt werden):

  • Keine TenantBranding-Tabelle (kein model TenantBranding/Branding/TenantTheme in prisma/schema/*.prisma).
  • Keine logoFileId/primaryColor/accentColor/custom_domain/theme_variables-Felder als eigene Tenant-Branding-Entität.
  • Branding ist heute system-weit (AppConfiguration), NICHT tenant-scoped.

Lücken / komplett neu zu bauen

Phase 1 (M030)

  1. 3-Wert-Theme-Preference statt binär — User.lightOrDarkMode ist light/dark. Spec verlangt Enum system | light | dark mit Default system. → Feld erweitern/migrieren (Forward-Only-Migration), Theme-Enum + Normalisierungs-Helfer um system ergänzen.
  2. system-Auflösung über prefers-color-scheme — existiert NICHT (grep prefers-color-scheme = 0 Treffer in apps/packages). Spec C.1 Schritt 3 + Live-Listener C.2 (matchMedia('(prefers-color-scheme: dark)')) komplett neu.
  3. Live-Reaktivität bei system — kein Client-Listener für OS-Theme-Wechsel während offener Session (C.2) vorhanden.
  4. SSR-Cookie für No-Flash bei system — heute kommt der Modus aus der Server-Session (nur eingeloggt). Für system/nicht-eingeloggt + No-Flash braucht es Cookie/Header-Lesung von prefers-color-scheme server-seitig (C.3). Neu.
  5. 3-Optionen-Picker an /{tenant}/settings/profile/ — Picker-Komponente existiert als Vorlage (ThemeSelector/DarkModeToggle), aber für 3 Optionen mit Spec-Klartext (B.1) neu zusammenzubauen; Einbau in settings/profile (nicht nur User-Menü).
  6. Capacitor Status-Bar / Splash theme-aware — Plugins (@capacitor/status-bar, @capacitor/splash-screen) sind installiert, aber kein StatusBar.setStyle(...)-Aufruf in apps/mobile/src (C.4). Native-Hook komplett neu.
  7. i18n-Key system — components.themeToggle.modeLabel hat nur light/dark; system + Spec-Klartexte fehlen.

Phase 2 (E.1-E.6) — alles als Vorlage vorhanden, aber neu zu bauen

  • TenantBranding-Tabelle (Felder per AppConfiguration-Shape) — neu.
  • /{tenant}/admin/branding/-Route — settings/theme.tsx-Pattern adaptieren.
  • Logo-Upload (PNG/SVG) via Files-Modul (M23/Scaleway) — neu verdrahten.
  • Permissions branding.admin (über tenant.admin) + branding.white_label (Enterprise-Gate via M27) — neu.
  • White-Label: custom_domain (Caddy-Cert), custom fonts, theme_variables JSONB, hide-hivegrid-branding — neu (ThemeConfig-Parser als Vars-Vorlage).
  • Email-Branding (E.2): @toolctrl/brand mail-tokens als Basis, tenant-scoped erweitern.

Empfohlenes Vorgehen (Phase 1 zuerst)

  1. Daten-Layer: User.lightOrDarkMode → 3-Wert-Preference erweitern. Forward-Only-Migration mit Inverse-SQL-Kommentar; Default system; bestehende null-Werte → system. (accounts.prisma:17)
  2. Auflösungs-Helfer neu: resolveEffectiveTheme(pref, prefersColorSchemeHeader/Cookie) aufbauend auf userThemePreference.server.ts-Normalisierung. Reihenfolge nach Spec C.1.
  3. SSR-No-Flash erweitern: root.tsx:97-100 umbauen — dark-Klasse zusätzlich aus aufgelöstem system-Wert (Cookie/Header) setzen, nicht nur aus Session. Cookie-Name (offener Spec-Punkt) festlegen.
  4. Client-Reaktivität: matchMedia-Listener für system-Modus (neu) — bei OS-Wechsel dark-Klasse live toggeln (C.2), Cookie aktualisieren.
  5. UI-Picker: ThemeSelector.tsx/DarkModeToggle.tsx als Vorlage → 3-Optionen-Picker mit Spec-Klartext; posten an /preferences (vorhandene Action erweitern). Einbau in settings/profile + optional User-Menü (nav-user.tsx).
  6. Audit/Events: vorhandenes user.preferences.updated-Event (root.tsx:197) für neuen 3-Wert weiterverwenden.
  7. i18n: system-Label + Klartexte (de zuerst, AV #4 — alle Strings extern).
  8. Capacitor (C.4): Native-Hook neu — @capacitor/status-bar StatusBar.setStyle(Style.Dark/Light) + Splash an aufgelösten Modus koppeln (apps/mobile/src). Soft-dependency auf M168.
  9. Feature-Flag: Modul über Flag abschaltbar machen (DoD); DARK_MODE_IN_APP-Konstante als Vorbild.
  10. Phase 2 erst nach eigener Detail-Spec; dann settings/theme.tsx + AppConfiguration-Branding-Shape + @toolctrl/brand als Startpunkte.

Notiz zu Layer-Disziplin (AGENTS.md / INTEGRATION-CONTRACTS)

  • Die Boilerplate-Vorlagen liegen in apps/web (RR7-Routen, Loader+Action+Component gemischt). HiveGrid-DoD verlangt: Loader baut View-Model, UI-Component (packages/ui-hivegrid/**) nur VM+Actions, keine Prisma-/Server-Imports im UI-Paket, Subframe via Adapter. → Vorlagen als Referenz für Logik, UI-Komponente neu in packages/ui-hivegrid (Subframe-Design pflicht, Memory feedback_subframe_mandatory).
  • Sidebar/Settings-Wiring: packages/ui-hivegrid/src/app-shell/sidebar.config.ts ist Single-Source (INTEGRATION-CONTRACTS §1); Mandant-Settings unter app.hivegrid.de/settings/<modul>/... (§ Route-Tabelle). Phase 1 ist eine Profil-Settings-Sektion, kein eigener Sidebar-Top-Eintrag — explizit dokumentieren (DoD-Ausnahme).