# Theme-System – Architektur, Vorlagen-Vertrag, Übergabe Design Stand: 22.10.2026 · Basis-Theme: **„Ostsee-Licht“** (`resources/themes/ostsee-licht`) · Entscheidungen: `docs/KONZEPT.md` §4a > **Kurz:** Logik, Daten und Admin sind fertig und getestet. Ein Theme ist **nur Optik**: Blade-Vorlagen, CSS, ein wenig JS und Farb-Tokens. Für ein neues Design wird ausschließlich unter `resources/themes//` gearbeitet. > > **Neues Theme bauen:** verbindliche Schritt-für-Schritt-Anleitung in [THEME-ERSTELLUNG.md](THEME-ERSTELLUNG.md) (`themes:make`, `themes:check`, `themes:preview`). --- ## 1. Überblick ``` Anfrage ──► ResolveTheme (Middleware) │ Site per Domain (sonst Standard-Site) │ Erscheinungsbild per Datum (oder signierte Vorschau ?vorschau=) │ Theme-Kette: Theme → Eltern-Theme → Basis-Theme ⇒ View-Namespace "theme::" ▼ PageController ──► Seite (Admin › Webseite › Seiten) = Liste von Bausteinen │ └─ je Baustein: App\Themes\Sections\Section::data() → theme::sections. ▼ theme::page (@extends theme::layouts.app) ``` | Begriff | Wo | Was | |---|---|---| | **Site** | `sites`, Admin › System › Websites | Domain, Theme, Grundfarben, zugeordnete Wohnungen. Heute eine; weitere = weitere Vermieter mit eigener Domain. | | **Theme** | `resources/themes//` | Manifest `theme.json`, Vorlagen `views/`, `theme.css`, `theme.js` | | **Seite** | `pages`, Admin › Webseite › Seiten | Adresse, Menü (Haupt/Fuß/keins), SEO, **Bausteine** (Builder) | | **Baustein** (Section) | `app/Themes/Sections/*`, Katalog in `config/themes.php` | Admin-Formular + Datenaufbereitung; Darstellung: `theme::sections.` | | **Erscheinungsbild** (Appearance) | `appearances`, Admin › Webseite › Erscheinungsbilder | Jährlicher Zeitraum + Priorität; ersetzt Farben (Tokens), ausgewählte Texte, Banner; **Fotos gehören zu Erscheinungsbildern** (`photos.appearance_ids`, mehrere möglich, leer = ganzjährig) – **nicht** den Aufbau. Bausteine können auf Erscheinungsbilder beschränkt werden. Sonderangebote sind **unabhängig** davon (`OfferShowcase`) | Code: `app/Themes/` (Theme, ThemeFactory, ThemeRegistry, ThemeManifest, SectionRegistry, Sections/), `app/Http/Middleware/ResolveTheme.php`, `app/Http/Controllers/PageController.php`, `app/Providers/ThemeServiceProvider.php`. ## 2. Aufbau eines Themes ``` resources/themes/ostsee-licht/ ├── theme.json Manifest ├── theme.css Vite-Einstieg: @import 'tailwindcss' + theme-base.css + @source der Vorlagen ├── theme-base.css wiederverwendbar: Schriften, Token-Mapping, Basis-Klassen (Child-Themes importieren diese Datei) ├── theme.js kleine Verbesserungen (Lightbox, Suche) └── views/ ├── layouts/app.blade.php Grundgerüst: , Banner, Kopf, @yield('content'), Fuß, Lightbox ├── page.blade.php rendert die Bausteine einer Seite ├── partials/ header, footer, banner, image, mobile-booking-bar └── sections/.blade.php eine Vorlage je Baustein (siehe §5) ``` ### theme.json ```json { "key": "ostsee-licht", // eindeutig, = Ordnername empfohlen "name": "Ostsee-Licht", "version": "0.1.0", "parent": null, // Child-Theme: Key des Eltern-Themes "description": "…", "assets": { "css": "resources/themes/ostsee-licht/theme.css", "js": "resources/themes/ostsee-licht/theme.js" }, "tokens": { "accent": { "label": "Akzent", "default": "#2C5F7C" }, … } } ``` - **Vererbung:** Vorlagen, die ein Theme nicht hat, kommen vom Eltern-Theme, zuletzt vom Basis-Theme (`config('themes.base')`). Ein Child-Theme kann also mit einer einzigen Datei beginnen (z. B. nur `sections/hero.blade.php`). Hat ein Child-Theme keine eigenen `assets`, werden die des Eltern-Themes geladen – das reicht nur ohne eigene Vorlagen; sobald es Vorlagen gibt, braucht das Theme eigene `theme.css`/`theme.js` (sonst fehlen deren Tailwind-Klassen; `themes:check` meldet das). - **Neues Theme anlegen:** `php artisan themes:make ` (überschreibt nie etwas) → erscheint automatisch in Admin › System › Websites › Theme (mit „Vorschau“). `npm run build` baut alle Themes (`vite.config.js` liest die Ordner). Prüfen: `php artisan themes:check`; Vorschau-Links: `php artisan themes:preview ` (signiert, `?theme=` und optional `&vorschau=`). Details: [THEME-ERSTELLUNG.md](THEME-ERSTELLUNG.md). - **Plugins:** Ein Theme-Paket legt seinen Ordner unter einen Pfad aus `config('themes.paths')`. Themes werden **nie** über den Admin hochgeladen (Vorlagen sind ausführbarer Code). ## 3. Design-Tokens (Farben) - Definiert in `theme.json › tokens`; das Layout gibt sie als CSS-Variablen aus: `:root{--accent:#2C5F7C;…}`. - Reihenfolge: Theme-Standard → Site (Admin › Websites › Farben) → Erscheinungsbild (Admin › Erscheinungsbilder › Farben). Nur gültige Hex-Werte werden übernommen. - In `theme.css` sind die Tokens als Tailwind-Farben gemappt (`@theme inline`): `bg-ground`, `bg-surface`, `text-ink`, `text-muted`, `border-line`, `bg-accent`, `text-accent-ink`, `bg-band`, `text-band-ink`, `text-band-muted`, `bg-banner`, `text-banner-ink` – inkl. Deckkraft (`bg-accent/10`). - **Regel:** In Vorlagen keine festen Farben (`#…`, `text-blue-700`), immer Tokens – sonst funktionieren Saisons (z. B. dunkles Silvester) nicht. - Die Buchungs- und Bewertungsformulare (`resources/views/livewire/*.blade.php`) sind theme-neutral und nutzen nur diese Token-Klassen. - Neue Tokens: in `theme.json` ergänzen und in `theme.css › @theme inline` mappen; sie erscheinen automatisch als Farbfelder im Admin. ## 4. Was Layout und Vorlagen zur Verfügung haben `$theme` (`App\Themes\Theme`, im Layout via `app(\App\Themes\Theme::class)`, in Bausteinen als Variable): | Methode / Eigenschaft | Liefert | |---|---| | `$theme->site` | `Site` (Name, Locale, Einstellungen) | | `$theme->appearance` | aktuelles `Appearance` oder `null` | | `$theme->isPreview` | Vorschau-Modus (Layout setzt `noindex` und zeigt einen Hinweis) | | `$theme->appearanceKey()` | z. B. `weihnachten` – steht als `data-appearance` am ``; für saisonale CSS-Details nutzbar: `[data-appearance=silvester] .hero {…}` | | `$theme->text($key, $fallback)` | Text des Erscheinungsbilds oder Fallback (Schlüssel: `Appearance::OVERRIDABLE`) | | `$theme->banner()` | Das heute gezeigte Banner (`App\Themes\Banner`: `text`, `linkLabel`, `linkUrl`, `tone`) oder null | | `$theme->sharePhoto($sections)` | Vorschaubild beim Teilen und für Suchmaschinen: erstes zur Saison passendes Titelbild der Seite, sonst ein automatisches Foto der Wohnung | | `$theme->property()` | Hauptwohnung der Site | | `$theme->menu('main' \| 'footer')` | veröffentlichte Seiten des Menüs (`->url()`, `->label()`) | | `$theme->tokens()`, `cssVariables()`, `assets()` | für das Layout | Weitere Helfer: `@include('theme::partials.image', ['photo' => $photo, 'sizes' => '…', 'class' => '…', 'eager' => bool])` (responsives WebP mit `srcset` 640/1280/2048 px, Platzhalter wenn kein Bild), `\App\Support\Money::format($cents)`, `\App\Support\Content::get()/html()/photo()` (zentrale Texte, Admin › Texte), `route('booking.create')`, `route('home')`, `route('page', ['slug' => …])`. Layout-Variablen von `PageController`: `$title`, `$description`, `$ogImage`, `$structuredData` (JSON-LD), `$page`, `$sections`. Weitere Daten für `` per `@push('head')`. ## 5. Bausteinkatalog – Vertrag der Vorlagen Jede Vorlage `views/sections/.blade.php` bekommt **immer** `$theme` und `$sectionId` (eindeutige ID für `aria-labelledby`) und zusätzlich: | Key | Admin-Name | Variablen | |---|---|---| | `hero` | Titelbereich mit Suche | `$eyebrow`, `$title` (Text, `*Wort*` = Hervorhebung), `$text`, `$photo`, `$showSearch`, `$property`, `$featuredOffer` (`AdvertisedOffer`\|null: wichtigstes hervorgehobenes Angebot) – Suche als GET-Formular an `route('booking.create')` mit `anreise`, `abreise` (Y-m-d), `personen` | | `facts` | Eckdaten | `$heading`, `$property`, `$highlights` (Collection), `$fromPrice` (Cent\|null) | | `text_image` | Text mit Bildern | `$eyebrow`, `$heading`, `$text` (HtmlString\|null), `$photos` (≤3), `$imagePosition` (`left`\|`right`), `$linkLabel`, `$linkUrl` | | `gallery` | Bildergalerie | `$heading`, `$photos` – Lightbox: `` | | `amenities` | Ausstattung | `$heading`, `$groups` (Bereich ⇒ Collection) | | `floor_plan` | Grundriss (interaktiv) | `$heading`, `$text`, `$photo` (Grundriss-Bild, `Photo`), `$rooms` (Collection von Arrays: `key` – Anker-ID, `name`, `description`, `hint` – Barrierefreiheit, `points` – „x,y x,y …“ in **Prozent** des Bildes → SVG `viewBox="0 0 100 100" preserveAspectRatio="none"` über dem Bild, `photos` – Collection, `amenities` – Collection). Rendert nichts ohne Bild oder Räume. Daten: Admin › Webseite › Grundriss (`FloorPlan`) | | `location` | Lage & Umgebung | `$eyebrow`, `$heading`, `$text`, `$address`, `$mapUrl` (OpenStreetMap-Link, keine eingebettete Karte), `$photos` | | `prices` | Preise & Saisons | `$eyebrow`, `$heading`, `$text`, `$property`, `$seasons` (nächste 12 Monate), `$extras`, `$featuredSeason` (Name des Erscheinungsbilds) | | `offers` | Sonderangebote | `$heading`, `$display` (`grid`\|`list`\|`rotating`), `$offers` (Collection<`App\Pricing\AdvertisedOffer`>: `title`, `description`, `advantage`, `conditions`, `arrival`/`departure`/`nights()` bei festen Terminen und Lücken, `quote` + `regularTotal()` für „statt …“, `bookingUrl()`). Rollierend: `data-rotator`, `data-rotator-slide`, `data-rotator-prev/next/dot` (theme.js) | | `booking` | Kalender & Anfrage | `$heading`, `$text`, `$property` – bindet `` ein | | `reviews` | Gästebewertungen | `$heading`, `$reviews`, `$count`, `$average`, `$categories` – **Pflichthinweis** zur Echtheit (§ 5b UWG) muss sichtbar bleiben | | `host` | Gastgeber | `$heading`, `$quote`, `$text`, `$photo`, `$name` | | `faq` | Häufige Fragen | `$heading`, `$faqs`, `$answers` (ID ⇒ HtmlString) – erzeugt FAQ-JSON-LD | | `cta` | Abschluss mit Aufruf | `$title`, `$text`, `$photo`, `$buttonLabel`, `$buttonUrl` | | `contact` | Kontakt | `$heading`, `$text`, `$owner` (name, street, city, phone, email), `$address` | | `rich_text` | Fließtext | `$heading`, `$text` (HtmlString\|null; eigener Text oder zentraler Text wie Impressum) | Rich-Text-Variablen sind bereits bereinigt (HtmlString) und werden mit `{{ $text }}` ausgegeben. **Jeder platzierte Baustein** hat `data.id` (feste UUID, `Page::assignSectionIds` beim Speichern; Kopien bekommen eine neue) und `data.appearances` (Erscheinungsbild-IDs; leer = immer sichtbar, sonst nur in diesen – z. B. ein Weihnachts-Baustein). **Bilder in Bausteinen** (Basisklasse): `chosenPhotos()` = ausgewählte Fotos in ihrer Reihenfolge, nur veröffentlichte und zur Saison passende; `automaticPhotos()` = `Photo::automatic()` (Fotos der Wohnung des Bausteins und solche ohne Wohnung, nie Kategorie „Grundriss & Pläne“, zur Saison passend, Saisonfotos zuerst); `photoSourceFields()`/`sourcedPhotos()` = Wahl „automatisch“ oder „eigene Auswahl“ (`data.photo_source`, `data.photo_ids`). Titelbereich und Abschluss halten eine Liste `photo_ids`, gezeigt wird das erste passende Foto. Ein Foto gehört zu keinem (= ganzjährig) oder mehreren Erscheinungsbildern; dann erscheint es nur dort und vor den ganzjährigen. Alle Bildauswahlen nutzen `App\Filament\Forms\Components\PhotoSelect` (Vorschaubild + Beschreibung, nach Kategorie gruppiert). **Neuer Baustein** (auch als Plugin): Klasse `extends App\Themes\Sections\Section` (`key()`, `label()`, `icon()`, `schema()` = Admin-Felder, `data()` = Variablen) → in `config/themes.php › sections` eintragen → Vorlage `sections/.blade.php` im Basis-Theme anlegen (Test `test_base_theme_is_discovered_and_provides_a_view_for_every_section` erzwingt das). Unbekannte Bausteine werden auf der Seite übersprungen, nie ein Fehler. ## 6. Erscheinungsbilder - Felder: Name, Zeitraum `TT.MM.`–`TT.MM.` (jährlich, darf über Silvester laufen), Priorität, Standard, aktiv, Texte (`hero.eyebrow`, `hero.title`, `hero.text`, `cta.title`, `cta.text`), Farben. - Startset (Seeder): Standard · Sommer 01.06.–31.08. · Winter 01.11.–31.03. · Weihnachten 01.12.–25.12. (Prio 20) · Silvester 26.12.–03.01. (Prio 20). - **Fotos:** nicht mehr am Erscheinungsbild, sondern am Foto (Webseite › Fotos › „Zeigen in“, auch als Sammelaktion). Das Erscheinungsbild zeigt nur, wie viele Fotos ihm zugeordnet sind. Umstellung 29.10.2026: Titelbild und „Bilder je Baustein“ wurden in die Bausteine übernommen (Migration `give_photos_their_seasons`). - **Vorschau:** Admin › Erscheinungsbilder › „Vorschau“ = signierter Link (24 h), `noindex` – zeigt auch die Saisonfotos. - **Banner** (Admin › Webseite › Banner & Hinweise, Modell `Notice`, Auswahl `App\Themes\BannerResolver`): je Website oder für alle, optional nur in bestimmten Erscheinungsbildern (`appearance_ids`, mehrere), Zeitraum, Priorität. Es erscheint genau eines: höchste Priorität, dann das neueste. Ein Banner kann ein Sonderangebot bewerben (`special_offer_id`): Text, Termin und Link kommen dann aus dem Angebot, und es erscheint nur, solange `OfferShowcase` das Angebot bewirbt. Bei den Sonderangeboten erzeugt „Als Banner zeigen“ so ein Banner. Die Liste nennt das heute sichtbare Banner. Umstellung 29.10.2026: Banner-Texte der Erscheinungsbilder wurden zu Bannern, die auf ihr Erscheinungsbild beschränkt sind. ## 7. Assets, Schriften, Build - `npm run build` (bzw. `npm run dev`) baut je Theme `theme.css` + `theme.js` nach `public/build`. Auf Strato läuft kein Node: **Build lokal, Ergebnis mit deployen.** - Schriften werden **selbst gehostet** (npm `@fontsource/*`, Import in `theme.css`) – keine Anfragen an Google (DSGVO, kein Cookie-Banner nötig). Das Vite-Font-Plugin ist bewusst entfernt (Firmen-Proxy, DSGVO). - Keine externen Skripte/Iframes/CDNs ohne Einwilligungskonzept. ## 8. Qualitätsanforderungen (gelten für jedes Theme) - **Mobil zuerst**, ab 360 px nutzbar; Buchung immer erreichbar (mobile Buchungsleiste `partials/mobile-booking-bar`). - **Ladezeit:** Hauptbild mit `eager`/`fetchpriority`, alle übrigen `loading="lazy"`; LCP < 2,5 s; Video nur mit Standbild-Poster, stumm, nicht bei „Datensparen“. - **Barrierefreiheit (WCAG 2.2 AA):** Kontraste ≥ 4,5:1 (auch in allen Erscheinungsbildern!), sinnvolle Überschriften (h1 je Seite genau einmal), Fokus sichtbar, alles per Tastatur, `prefers-reduced-motion` respektieren (siehe `theme.css`). - **Bewegung** nur mit Zweck: progressive Enhancement (`@supports (animation-timeline: view())`), ohne JS/Animation muss alles funktionieren. - **SEO:** `$title`/`$description` ausgeben, JSON-LD beibehalten, sprechende `alt`-Texte kommen aus dem Admin. ## 9. Lokal starten und prüfen ```powershell php artisan migrate:fresh --seed php artisan photos:import "" # optional npm run dev # oder: npm run build php artisan serve # http://localhost:8000 · Admin: /admin (admin@example.com / password) php artisan test --compact # muss grün bleiben vendor/bin/pint --dirty --format agent # nur bei PHP-Änderungen ``` Saisons ansehen: Admin › Webseite › Erscheinungsbilder › „Vorschau“. ## 10. Übergabe: Auftrag für die Design-Sitzung (privater Rechner, Plugin `frontend-design`) **Ziel:** Ein **neues, zusätzliches Theme** auf wirklich herausragendem Niveau (Recherche & Ideen: Chat vom 22.10.2026, Zusammenfassung unten), angelegt mit `themes:make`, auswählbar im Admin – „Ostsee-Licht“ bleibt unverändert als Basis und Rückfall. **Verbindliche Anleitung und Auftragstext: [THEME-ERSTELLUNG.md](THEME-ERSTELLUNG.md).** **Arbeitsbereich:** nur `resources/themes//**` (+ `package.json` für `@fontsource`-Schriften). Die Livewire-Formulare `resources/views/livewire/*.blade.php` sind für alle Themes gemeinsam und werden nicht verändert. **Nicht anfassen:** `app/**` (außer ein neuer Baustein wird bewusst gebraucht – dann §5), Datenbank, Admin, `config/**`. **Leitideen aus der Recherche** (zur Auswahl/Kombination): 1. *„Ein Tag an der Ostsee“* – Startseite erzählt beim Scrollen einen Tag (Morgen Strand → Mittag Terrasse → Abend Hafen → Nacht Promenade), Licht/Farben wandern mit; Tag/Nacht-Stimmung nach Sonnenuntergang. (Live-Wetter/Wassertemperatur als späterer Baustein – Datenquelle mit kommerzieller Lizenz klären, z. B. DWD Open Data.) 2. *„Brigittes Kühlungsborn“* – redaktioneller Magazin-Stil, große Typografie, Gastgeber-Tipps. 3. *„Die Wohnung zum Anfassen“* – interaktiver Grundriss (SVG, Räume antippen), Drohnen-Video im Titelbereich, Preis-Kalender als Gestaltungselement. Vorbilder: Awwwards › Hotel & Restaurant (Tengile, White Desert, Explore Primland, Vander Hotel, Villa Aurelia), Sawday's, onefinestay. **Checkliste vor Abschluss:** - [ ] Alle 15 Bausteine gestaltet; alle Seiten (`/`, `/wohnung`, `/kuehlungsborn`, `/buchen`, `/kontakt`, `/impressum`, `/datenschutz`) auf Handy (360 px), Tablet und Desktop geprüft - [ ] Alle 5 Erscheinungsbilder per Vorschau geprüft (Kontraste! Silvester ist dunkel) - [ ] Nur Token-Farben in Vorlagen; neue Tokens in `theme.json` + `theme.css` - [ ] Reduced Motion, Tastaturbedienung, Fokus, Alt-Texte - [ ] `npm run build` fehlerfrei, `php artisan test --compact` grün - [ ] Neue Schriften selbst gehostet (`@fontsource/*`), keine externen Requests