Files
fewo-stommer/docs/THEMES.md
LarsandClaude Opus 5.5 4c9e6992f4
Deploy FeWo mit PipelineManager / deploy (push) Successful in 3m45s
Design Stufe 2: Tipp-Karten zum Umdrehen, Sommer/Winter-Vergleich, Galerie mit weichem Vergroessern
- Baustein "Ausflugstipps" (tips): Karten mit Foto vorne, Tipp/Weg/beste Zeit hinten; Seebad als Ansichtskarten
- Baustein "Sommer/Winter-Vergleich" (compare): Trennlinie ziehen, Tastatur ueber Range-Input, einmaliger Hinweis-Schwenk
- Lightbox: Foto waechst aus der Vorschau, Blaettern (Pfeile, Tasten, Wischen), Zaehler, Bildunterschrift; partials/lightbox
- Bewegung reduzieren: Ueberblenden statt Drehen, kein Schwenk, keine Zoom-Animation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-30 21:05:16 +01:00

21 KiB
Raw Permalink Blame History

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 (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

{
  "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.
  • 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, $video (App\Models\Video|null: stumme Schleife statt des Fotos – @include('theme::partials.video-loop', ['video' => $video, 'class' => …])), $freeStays (Liste arrival, departure (CarbonImmutable), nights, total (Cent), url – @include('theme::partials.free-stays')), $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: <a href="{{ $photo->url('lg') }}" data-lightbox data-alt="…" data-caption="{{ $photo->caption }}"> mit Vorschau-<img>. Das Foto wächst aus der Vorschau und schrumpft beim Schließen zurück; die Links eines Abschnitts bilden eine Reihe (Pfeile, Pfeiltasten, Wischen, „3 von 12“). Dialog: partials/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). videoChapter – Kapitel eines Rundgang-Videos mit diesem Raum: seconds, time, label oder null → Link <a href="#" hidden data-tour-link="{{ seconds }}">, den theme.js nur zeigt, wenn ein Rundgang auf derselben Seite ist). Rendert nichts ohne Bild oder Räume. Daten: Admin › Webseite › Grundriss (FloorPlan)
tour Rundgang (Video) $eyebrow, $heading, $text, $video (Video|null – ohne Video rendert nichts), $chapters (Liste seconds, time „0:16“, label, room), $layout (wide|left|right). Pflicht-Markup für theme.js: data-tour am Abschnitt, <video controls preload="none"> (lädt erst beim Start), [data-tour-start] (Start-Overlay, hidden), [data-tour-chapters] (hidden, ohne JS unsichtbar), [data-tour-seek="<Sekunden>"] je Kapitel (aktuelles bekommt aria-current="true"). Daten: Admin › Webseite › Videos
tips Ausflugstipps (Karten zum Umdrehen) $eyebrow, $heading, $text, $signature (z. B. „Brigitte“ oder null), $tips (Liste title, photo – Photo|null, tip, way, bestTime). Pflicht-Markup für theme.js: [data-flip] je Karte > [data-flip-inner] > [data-flip-face="front"] und [data-flip-face="back"] (mit id), Knöpfe [data-flip-toggle] (hidden, aria-controls). Ohne JS stehen beide Seiten untereinander; die verdeckte Seite ist inert; mit „Bewegung reduzieren“ wird überblendet (Mechanik in theme-base.css)
compare Sommer/Winter-Vergleich $eyebrow, $heading, $text, $first, $second (Photo|null, beide unabhängig vom Erscheinungsbild – ohne beide rendert nichts), $firstLabel, $secondLabel. Pflicht-Markup: [data-compare] (Seitenverhältnis, darin das zweite Foto), [data-compare-first] (erstes Foto, bis --split sichtbar), [data-compare-handle], <input type="range" min="0" max="100" hidden data-compare-range class="sr-only"> für Tastatur und Screenreader. theme.js: Ziehen/Tippen, einmaliger kurzer Schwenk beim Hinscrollen (nicht bei „Bewegung reduzieren“)
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, $showSteps (bool), $steps (Titel ⇒ Erklärung: Anfrage → Angebot → Annahme, eine echte Abfolge) – bindet <livewire:booking-request :property="$property" /> ein (links Kalender, Daten und Preis, rechts das Anfrageformular)
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). Videos (App\Models\Video, Admin › Webseite › Videos: Datei MP4/WebM bis 100 MB, Standbild, Abspielgeschwindigkeit – Vorlagen setzen data-playback-rate="{{ $video->playbackRate() }}" am <video>, theme.js wendet sie an –, Kapitel „Min:Sek – Bezeichnung – Raum im Grundriss“) wählen Bausteine mit videoSelect() und holen sie mit video(). Einmaliges Einblenden: data-reveal an einem Element → theme.js setzt ready und beim Hinscrollen shown; das Theme gestaltet beide Zustände in @media (prefers-reduced-motion: no-preference) (Seebad: Sonnenaufgang des Trenners). Ohne JS oder mit „Bewegung reduzieren“ bleibt der Endzustand.

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

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.

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