- 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>
175 lines
14 KiB
Markdown
175 lines
14 KiB
Markdown
# 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
|