Files
fewo-stommer/docs/THEMES.md
LarsandClaude Opus 5.5 d2b1a853dc Banner zentral: je Website, Saison und Prioritaet, auch fuer Sonderangebote
Hinweise werden zu Bannern mit Website, Erscheinungsbildern, Prioritaet und
optionalem Sonderangebot (Text, Termin und Link aus dem Angebot, sichtbar nur
solange es beworben wird). Sonderangebote lassen sich mit einem Klick als Banner
zeigen; die Liste nennt das heute sichtbare Banner. Banner-Texte der
Erscheinungsbilder werden zu saisonalen Bannern.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 19:01:48 +01:00

183 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/<theme>/` 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=<id>)
│ Theme-Kette: Theme → Eltern-Theme → Basis-Theme ⇒ View-Namespace "theme::"
▼
PageController ──► Seite (Admin › Webseite › Seiten) = Liste von Bausteinen
│ └─ je Baustein: App\Themes\Sections\<X>Section::data() → theme::sections.<key>
▼
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/<key>/` | 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.<key>` |
| **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: <head>, Banner, Kopf, @yield('content'), Fuß, Lightbox
├── page.blade.php rendert die Bausteine einer Seite
├── partials/ header, footer, banner, image, mobile-booking-bar
└── sections/<key>.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 <key>` (ü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 <key>` (signiert, `?theme=<key>` und optional `&vorschau=<Erscheinungsbild-ID>`). 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 `<html>`; 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 `<head>` per `@push('head')`.
## 5. Bausteinkatalog – Vertrag der Vorlagen
Jede Vorlage `views/sections/<key>.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<string>), `$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: `<a href="{{ $photo->url('lg') }}" data-lightbox data-alt="…">` |
| `amenities` | Ausstattung | `$heading`, `$groups` (Bereich ⇒ Collection<Amenity>) |
| `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<Photo>, `amenities` – Collection<string>). 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 `<livewire:booking-request :property="$property" />` 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/<key>.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 "<Ordner mit Fotos>" # 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/<neues-theme>/**` (+ `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