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

14 KiB
Raw 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.


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

{
  "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), $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)
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

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