Files
fewo-stommer/docs/THEMES.md
T
LarsandClaude Opus 5.5 f7cbc66451
Deploy / test (push) Failing after 2s
Deploy / deploy (push) Skipped
Section "Grundriss (interaktiv)": floor plan with rooms, admin editor, Seebad view
- Table floor_plans (tenant_id, one per apartment, picture = website photo, rooms as JSON with
  corners in percent of the picture), model FloorPlan with BelongsToTenant, Property::floorPlan()
- Admin › Webseite › Grundriss: room list with name, description, photos, equipment (from the
  equipment list), accessibility hint, visibility, and an area editor (click the corners on the picture)
- Section floor_plan: base view without JavaScript (areas jump to the room list), Seebad view with
  room buttons, highlighted area and a cartouche per room (theme.js initFloorPlans)
- Tests: tenant inheritance, point parsing, website output, admin create incl. validation; the
  render test for all themes now includes the floor plan
- Docs: THEMES §5, ZUSAMMENARBEIT §6, STATUS §6 (incl. note for tenancy phase 5)
- styles/grundriss: revised rendering, WebP renditions, room areas of the Stommer flat in percent

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

182 lines
16 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.
>
> **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), Titelbild, **Bilder je Baustein**, ausgewählte Texte, Banner – **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->heroPhoto($fallback)` | Titelbild des Erscheinungsbilds oder Fallback |
| `$theme->sectionPhotoIds($sectionId, $slot)` / `sectionPhotoMode($sectionId)` | Saisonbilder eines platzierten Bausteins (in Bausteinen über `seasonalPhoto()`, `seasonalPhotos()`, `withSeasonalPhotos()` der Basisklasse) |
| `$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). Bausteine mit Bildern melden ihre Bildplätze über `photoSlots()` (`single`, `multiple`, `collection` = automatisch gewählte Bilder, die ein Erscheinungsbild ersetzen oder voranstellen kann); daraus baut das Erscheinungsbild-Formular „Bilder je Baustein“ (`appearances.section_photos[<id>][<slot>]`, bei Sammlungen zusätzlich `mode`). 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, Titelbild, **Bilder je Baustein** (alle Bausteine mit Bildern auf allen Seiten; leer = Bild aus der Seite), 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:** 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