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 istdocs/milestones/M030-hell-dunkel-modus/.
Hinweis zur PLAN.md-Annahme:
M030/PLAN.mdnennt „next-themesbereits in Boilerplate-Deps". Das ist falsch verifiziert —next-themestaucht in der Boilerplate nur inapps/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_preferenceEnumsystem | light | dark, Defaultsystem - 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 beisystem(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 (keinmodel TenantBranding/Branding/TenantThemeinprisma/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)
- 3-Wert-Theme-Preference statt binär —
User.lightOrDarkModeistlight/dark. Spec verlangt Enumsystem | light | darkmit Defaultsystem. → Feld erweitern/migrieren (Forward-Only-Migration),Theme-Enum + Normalisierungs-Helfer umsystemergänzen. system-Auflösung überprefers-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.- Live-Reaktivität bei
system— kein Client-Listener für OS-Theme-Wechsel während offener Session (C.2) vorhanden. - SSR-Cookie für No-Flash bei
system— heute kommt der Modus aus der Server-Session (nur eingeloggt). Fürsystem/nicht-eingeloggt + No-Flash braucht es Cookie/Header-Lesung vonprefers-color-schemeserver-seitig (C.3). Neu. - 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 insettings/profile(nicht nur User-Menü). - Capacitor Status-Bar / Splash theme-aware — Plugins (
@capacitor/status-bar,@capacitor/splash-screen) sind installiert, aber keinStatusBar.setStyle(...)-Aufruf inapps/mobile/src(C.4). Native-Hook komplett neu. - i18n-Key
system—components.themeToggle.modeLabelhat nurlight/dark;system+ Spec-Klartexte fehlen.
Phase 2 (E.1-E.6) — alles als Vorlage vorhanden, aber neu zu bauen
TenantBranding-Tabelle (Felder perAppConfiguration-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(übertenant.admin) +branding.white_label(Enterprise-Gate via M27) — neu. - White-Label: custom_domain (Caddy-Cert), custom fonts,
theme_variablesJSONB, hide-hivegrid-branding — neu (ThemeConfig-Parser als Vars-Vorlage). - Email-Branding (E.2):
@toolctrl/brandmail-tokens als Basis, tenant-scoped erweitern.
Empfohlenes Vorgehen (Phase 1 zuerst)
- Daten-Layer:
User.lightOrDarkMode→ 3-Wert-Preference erweitern. Forward-Only-Migration mit Inverse-SQL-Kommentar; Defaultsystem; bestehendenull-Werte →system. (accounts.prisma:17) - Auflösungs-Helfer neu:
resolveEffectiveTheme(pref, prefersColorSchemeHeader/Cookie)aufbauend aufuserThemePreference.server.ts-Normalisierung. Reihenfolge nach Spec C.1. - SSR-No-Flash erweitern:
root.tsx:97-100umbauen —dark-Klasse zusätzlich aus aufgelöstemsystem-Wert (Cookie/Header) setzen, nicht nur aus Session. Cookie-Name (offener Spec-Punkt) festlegen. - Client-Reaktivität:
matchMedia-Listener fürsystem-Modus (neu) — bei OS-Wechseldark-Klasse live toggeln (C.2), Cookie aktualisieren. - UI-Picker:
ThemeSelector.tsx/DarkModeToggle.tsxals Vorlage → 3-Optionen-Picker mit Spec-Klartext; posten an/preferences(vorhandene Action erweitern). Einbau insettings/profile+ optional User-Menü (nav-user.tsx). - Audit/Events: vorhandenes
user.preferences.updated-Event (root.tsx:197) für neuen 3-Wert weiterverwenden. - i18n:
system-Label + Klartexte (de zuerst, AV #4 — alle Strings extern). - Capacitor (C.4): Native-Hook neu —
@capacitor/status-barStatusBar.setStyle(Style.Dark/Light)+ Splash an aufgelösten Modus koppeln (apps/mobile/src). Soft-dependency auf M168. - Feature-Flag: Modul über Flag abschaltbar machen (DoD);
DARK_MODE_IN_APP-Konstante als Vorbild. - Phase 2 erst nach eigener Detail-Spec; dann
settings/theme.tsx+AppConfiguration-Branding-Shape +@toolctrl/brandals 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 inpackages/ui-hivegrid(Subframe-Design pflicht, Memoryfeedback_subframe_mandatory). - Sidebar/Settings-Wiring:
packages/ui-hivegrid/src/app-shell/sidebar.config.tsist Single-Source (INTEGRATION-CONTRACTS §1); Mandant-Settings unterapp.hivegrid.de/settings/<modul>/...(§ Route-Tabelle). Phase 1 ist eine Profil-Settings-Sektion, kein eigener Sidebar-Top-Eintrag — explizit dokumentieren (DoD-Ausnahme).