Files
fewo-stommer/docs/THEMES.md
T
Lars StommerandClaude Opus 5.5 66e82d61f5 Theme-System mit Basis-Theme Ostsee-Licht, Bausteinen und saisonalen Erscheinungsbildern
- Sites (Domain, Theme, Farben; mehrfähig für weitere Vermieter), Seiten aus Bausteinen mit Menüs, Erscheinungsbilder mit jährlichem Zeitplan, Priorität und signierter Vorschau
- Theme-Kern (app/Themes): Manifest, Registry, Vererbung (Child-Themes), Token-Farben als CSS-Variablen, Bausteinkatalog als Registry (config/themes.php)
- 15 Bausteine: Titelbereich mit Suche, Eckdaten, Text mit Bildern, Galerie, Ausstattung, Lage, Preise, Angebote, Kalender & Anfrage, Bewertungen, Gastgeber, FAQ, Abschluss, Kontakt, Fließtext
- Theme Ostsee-Licht: Layout, Kopf/Fuß, Banner, mobile Buchungsleiste, Lightbox, selbst gehostete Schriften, Reduced Motion
- Seiten Start, Wohnung, Kühlungsborn, Preise & Buchung, Kontakt, Impressum, Datenschutz; Sitemap, robots.txt, JSON-LD
- Admin: Seiten-Baukasten, Erscheinungsbilder, Websites
- Dokumentation docs/THEMES.md inkl. Übergabe für die Design-Sitzung

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 15:04:21 +02:00

175 lines
14 KiB
Markdown
Raw 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.
---
## 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), Titelbild, ausgewählte Texte, Banner, hervorgehobenes Angebot – **nicht** den Aufbau |
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 Tailwind v4 + Schriften + Token-Mapping
├── 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.
- **Neues Theme anlegen:** Ordner `resources/themes/<key>/` mit `theme.json` (+ optional eigene Assets) → erscheint automatisch in Admin › System › Websites › Theme. `npm run build` baut alle Themes (`vite.config.js` liest die Ordner).
- **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->heroPhoto($fallback)` | Titelbild des Erscheinungsbilds oder Fallback |
| `$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` – 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>) |
| `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`, `$offers` (öffentlich, ohne Code), `$featuredId` |
| `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.
**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, Titelbild, hervorgehobenes Angebot, Texte (`banner.text`, `banner.link_label`, `banner.link_url`, `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).
- **Vorschau:** Admin › Erscheinungsbilder › „Vorschau“ = signierter Link (24 h), `noindex`.
- Ohne Erscheinungsbild-Banner wird der neueste aktive Hinweis (Admin › Hinweis-Banner) gezeigt.
## 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:** Das Basis-Theme „Ostsee-Licht“ gestalterisch auf ein wirklich herausragendes Niveau heben (Recherche & Ideen: Chat vom 22.10.2026, Zusammenfassung unten), oder ein neues Theme als Child bzw. eigenständiges Theme anlegen und im Admin umschalten.
**Arbeitsbereich:** nur `resources/themes/<theme>/**` – dazu bei Bedarf die theme-neutralen Livewire-Formulare `resources/views/livewire/*.blade.php` (nur Klassen, keine Logik).
**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