- Special offers: kinds (rule, fixed dates, gap filler), package price, priority, highlight;
GapFinder detects calendar gaps (optionally waiving the minimum stay); OfferShowcase decides
what the website advertises and prices fixed dates/gaps with PriceCalculator; offers section
shows them side by side, as a list or rotating; hero can show the top offer. Appearances no
longer carry a featured offer.
- Sections get stable ids; appearances set photos per section ("Bilder je Baustein") and
sections can be limited to appearances. Photo pickers show thumbnails everywhere.
- Themes: themes:make (scaffold, never overwrites), themes:check (contract, build, markup,
colours, external resources, WCAG contrast), themes:preview (signed links per page and
appearance), signed ?theme= preview and preview action in the site form, inherited colour
tokens in the admin. Base CSS split into theme.css + reusable theme-base.css.
- docs/THEME-ERSTELLUNG.md: binding guide for building additional themes elsewhere.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
20 KiB
Neues Theme erstellen – verbindliche Bauanleitung
Stand: 22.10.2026 · gilt für jede Design-Sitzung (z. B. auf dem privaten Rechner mit dem Skill/Plugin frontend-design) · Architektur und Datenverträge: THEMES.md
Kurz: Ein neues Design entsteht als zusätzliches Theme in einem eigenen Ordner
resources/themes/<key>/. Das vorhandene Theme „Ostsee-Licht“ wird nicht verändert. Das neue Theme erbt alles, was es nicht selbst mitbringt, wird mitphp artisan themes:check <key>geprüft, per Vorschau-Link angesehen und erst dann im Admin für die Website ausgewählt. Zurück geht es jederzeit durch Auswahl des alten Themes.
1. Grundregeln (nicht verhandelbar)
- Nur im eigenen Ordner arbeiten:
resources/themes/<key>/**. Zusätzlich erlaubt:package.json/package-lock.jsonfür selbst gehostete Schriften (@fontsource/*). Alles andere bleibt unangetastet, insbesondereresources/themes/ostsee-licht/**,app/**,config/**,database/**,routes/**,resources/views/livewire/**. - Neues Theme immer mit
php artisan themes:make <key>anlegen. Der Befehl erzeugt das korrekte Format und überschreibt nie einen vorhandenen Ordner. - Nur Optik: Blade-Vorlagen, CSS, etwas JavaScript, Farb-Tokens. Keine Datenbankabfragen, keine Geschäftslogik und keine neuen PHP-Klassen in Vorlagen. Daten kommen fertig aufbereitet aus den Bausteinen (Variablen siehe THEMES.md §4–5).
- Farben nur über Tokens (
bg-accent,text-muted…), nie fest (#123456,text-blue-700,bg-[#…],style="color:#…"). Sonst wirken die saisonalen Erscheinungsbilder nicht. Ausnahme ohne Saisonbezug:text-white/bg-blackauf Fotos und Overlays. - Nichts von fremden Servern laden: keine Google Fonts, CDNs, externen Skripte, eingebetteten Karten oder Videos von Drittanbietern. Grund: DSGVO, und die Seite kommt so ohne Cookie-Banner aus.
- Pflicht-Markup erhalten (§6): Verfügbarkeitssuche, Buchungsformular, Lightbox, rollierende Angebote, Echtheitshinweis der Bewertungen, JSON-LD,
noindexin der Vorschau. - Fertig ist ein Theme erst, wenn
php artisan themes:check <key>ohne Fehler,npm run buildfehlerfrei undphp artisan test --compactgrün ist und die Checkliste in §10 abgehakt ist.
2. Schnellstart
git pull # aktuellen Stand holen
composer install && npm ci # einmalig auf dem Rechner
cp .env.example .env && php artisan key:generate # einmalig, lokale SQLite-Datenbank …
touch database/database.sqlite # … als leere Datei anlegen (PowerShell: New-Item database/database.sqlite)
php artisan migrate:fresh --seed # Testdaten: Wohnung, Seiten, 5 Erscheinungsbilder
php artisan photos:import <Ordner> --manifest=database/data/wordpress-photos.csv # optional: echte Fotos (siehe BETRIEB.md)
php artisan themes:make ostsee-nacht --name="Ostsee-Nacht" --description="Dunkel, ruhig, großformatige Fotos"
# → resources/themes/ostsee-nacht/ (erbt zunächst alles von Ostsee-Licht)
npm run dev # oder npm run build
php artisan serve # http://localhost:8000 · Admin: /admin (admin@example.com / password, 2FA beim ersten Login einrichten)
php artisan themes:preview ostsee-nacht # Vorschau-Links: jede Seite × jedes Erscheinungsbild
php artisan themes:check ostsee-nacht # Prüfung gegen diese Anleitung
Key wählen: Kleinbuchstaben, Ziffern und Bindestriche; Ordnername gleich Key, z. B. ostsee-nacht, kuestenmagazin. Der Key ist dauerhaft, weil die Website ihn speichert. Der Anzeigename (name) darf sich ändern.
3. Aufbau eines Themes
resources/themes/<key>/
├── theme.json Manifest (Pflicht)
├── theme.css Vite-Einstiegspunkt CSS (Pflicht, sobald das Theme eigenes CSS hat – themes:make legt es an)
├── theme.js Vite-Einstiegspunkt JS (Pflicht zusammen mit theme.css)
├── README.md kurze Beschreibung, welche Vorlagen überschrieben sind
└── views/
├── layouts/app.blade.php optional: Grundgerüst (<head>, Banner, Kopf, Inhalt, Fuß, Lightbox)
├── page.blade.php optional: Ausgabe der Bausteine einer Seite
├── partials/ optional: banner, header, footer, image, mobile-booking-bar + eigene Includes
└── sections/<baustein>.blade.php optional: je Baustein eine Vorlage (Liste in §5)
Vererbung: Jede Vorlage, die im Theme fehlt, kommt vom Eltern-Theme (parent) und zuletzt vom Basis-Theme „Ostsee-Licht“. Ein frisch angelegtes Theme sieht daher genauso aus wie Ostsee-Licht. Man überschreibt Schritt für Schritt nur, was anders werden soll. Für ein komplett neues Design werden in der Regel alle Vorlagen überschrieben. Ausgangspunkt ist dann jeweils die gleichnamige Datei aus resources/themes/ostsee-licht/views/: in den eigenen Ordner kopieren und umgestalten, das Original nicht ändern.
3.1 theme.json
{
"key": "ostsee-nacht",
"name": "Ostsee-Nacht",
"version": "0.1.0",
"parent": "ostsee-licht",
"description": "Dunkel, ruhig, großformatige Fotos",
"assets": {
"css": "resources/themes/ostsee-nacht/theme.css",
"js": "resources/themes/ostsee-nacht/theme.js"
},
"tokens": {
"ground": { "label": "Hintergrund", "default": "#0F1A22" },
"accent": { "label": "Akzent (Buttons, Hervorhebungen)", "default": "#E8B04A" }
}
}
| Feld | Regel |
|---|---|
key |
= Ordnername, ^[a-z0-9]+(-[a-z0-9]+)*$ |
name, description |
erscheinen im Admin bei der Theme-Auswahl |
version |
MAJOR.MINOR.PATCH; bei jeder Auslieferung erhöhen |
parent |
in der Regel ostsee-licht; auch ein anderes installiertes Theme ist möglich |
assets.css / assets.js |
genau resources/themes/<key>/theme.css bzw. theme.js: Nur diese Dateien baut vite.config.js automatisch. Hat ein Theme eigene Assets, ersetzen sie die des Eltern-Themes vollständig (deshalb importieren beide Dateien das Eltern-Theme, §3.2/3.3). |
tokens |
Farbwerte als #RRGGBB mit deutschem label. themes:make übernimmt alle geerbten Tokens; die Defaults sind neu zu setzen. Alle 12 Basis-Tokens müssen in der Kette vorhanden sein. Neue Tokens sind erlaubt (§4). |
3.2 theme.css (so legt themes:make sie an)
@import 'tailwindcss';
@import '../ostsee-licht/theme-base.css'; /* Schriften, Token-Mapping, Basis-Klassen des Eltern-Themes */
/* eigene Schriften – selbst gehostet */
@import '@fontsource/fraunces/400.css';
/* Vorlagen, deren Tailwind-Klassen gebaut werden – alle drei Zeilen sind Pflicht */
@source '../ostsee-licht/views'; /* geerbte Vorlagen */
@source '../../views/livewire'; /* Buchungs- und Bewertungsformular */
@source './views'; /* eigene Vorlagen */
@theme inline {
--font-display: 'Fraunces', Georgia, serif;
--font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
/* neues Token: */
--color-glow: var(--glow);
}
@layer components {
.heading-display { /* Basis-Klassen dürfen neu definiert werden */ }
}
- Tailwind v4 (kein
tailwind.config.js, keine@applyauf eigene Klassen). theme-base.cssdes Eltern-Themes liefert: Schriften von Ostsee-Licht, das Mapping aller Tokens auf Tailwind-Farben (--color-<token>: var(--<token>)), Formular-Grundstile, Fokusrahmen,prefers-reduced-motion. Dazu kommen die Klassen, die geerbte Vorlagen und die Formulare nutzen:.eyebrow,.heading-display,.btn-primary,.btn-accent,.prose-theme,.reveal. Wertheme-base.cssnicht importiert, muss all das selbst bereitstellen.themes:checkprüft Mapping und Quellen.- Nicht
../ostsee-licht/theme.cssimportieren, sonderntheme-base.css. Die Quellen gibt das neue Theme selbst an.
3.3 theme.js
import '../ostsee-licht/theme.js'; // Lightbox, Verfügbarkeitssuche, rollierende Angebote
// eigene, kleine Verbesserungen – progressive enhancement: ohne JS muss alles funktionieren
Kein Framework (React/Vue/Alpine-Komponenten), keine externen Skripte. Livewire/Alpine lädt das Layout bereits für das Buchungsformular.
4. Farben und Tokens
- Das Layout gibt die Tokens als CSS-Variablen aus (
:root{--accent:#…}). Die Reihenfolge ist: Theme-Standard → Website (Admin › System › Websites › Farben) → Erscheinungsbild (Admin › Webseite › Erscheinungsbilder › Farben). - Basis-Tokens (Bedeutung nicht umdeuten, nur neu einfärben):
| Token | Tailwind | Verwendung |
|---|---|---|
ground |
bg-ground |
Seitenhintergrund |
surface |
bg-surface |
Karten, Formulare |
ink |
text-ink |
Haupttext |
muted |
text-muted |
Nebentext |
line |
border-line |
Linien, Rahmen |
accent / accent-ink |
bg-accent / text-accent-ink |
Buttons, Hervorhebungen / Text darauf |
band / band-ink / band-muted |
bg-band … |
dunkles Band (z. B. Lage) |
banner / banner-ink |
bg-banner … |
Hinweis-Banner oben |
- Kontraste (WCAG 2.2 AA, ≥ 4,5 : 1) werden von
themes:checkfür die Theme-Standards (Fehler) und für jedes aktive Erscheinungsbild der Datenbank (Warnung) geprüft. Paare: ink/muted/accent auf ground und surface, accent-ink auf accent, band-ink/band-muted auf band, banner-ink auf banner. Bei Warnungen in den Erscheinungsbildern die Saisonfarben im Admin anpassen oder die Theme-Standards so wählen, dass die Saisons passen. - Saisonale Feinheiten im CSS:
<html data-appearance="weihnachten">, also etwa[data-appearance=silvester] .hero-overlay { … }. Schlüssel:standard,sommer,winter,weihnachten,silvester(Slug des Namens). - Neues Token: in
theme.json › tokens(mitlabel,default) und intheme.css › @theme inlineals--color-<token>: var(--<token>);mappen. Es erscheint dann automatisch als Farbfeld im Admin.
5. Bausteine und Vorlagen
Jede Seite ist eine Liste von Bausteinen, die die Vermieterin im Admin anordnet. Für jeden Baustein rendert das System theme::sections.<key> mit fertigen Variablen. Welche Variablen es gibt, steht verbindlich in THEMES.md §5. Die Vorlagen von Ostsee-Licht sind die Referenz-Implementierung.
Datei (views/…) |
Baustein / Zweck |
|---|---|
sections/hero |
Titelbereich mit Verfügbarkeitssuche, optional Top-Angebot |
sections/facts |
Eckdaten |
sections/text_image |
Text mit bis zu 3 Bildern |
sections/gallery |
Bildergalerie mit Lightbox |
sections/amenities |
Ausstattung |
sections/location |
Lage & Umgebung |
sections/prices |
Preise & Saisons |
sections/offers |
Sonderangebote (nebeneinander / Liste / rollierend) |
sections/booking |
Kalender & Anfrage (Livewire) |
sections/reviews |
Gästebewertungen |
sections/host |
Gastgeberin |
sections/faq |
Häufige Fragen |
sections/cta |
Abschluss mit Aufruf |
sections/contact |
Kontakt |
sections/rich_text |
Fließtext (Impressum, Datenschutz …) |
layouts/app, page, partials/* |
Grundgerüst, Kopf, Fuß, Banner, Bild-Helfer, mobile Buchungsleiste |
Regeln für Vorlagen:
- Immer vorhanden:
$themeund$sectionId.$sectionIdfürid/aria-labelledbyverwenden, weil ein Baustein mehrfach auf einer Seite stehen kann. - Leere Daten abfangen: Bausteine ohne Inhalt (keine Angebote, keine Bewertungen, kein Foto) rendern nichts bzw. einen ruhigen Platzhalter. Nie mit Fehlern abbrechen.
- Bilder immer über
@include('theme::partials.image', ['photo' => $photo, 'sizes' => '(min-width: 1024px) 50vw, 100vw', 'class' => '…', 'eager' => false]). Das liefert responsives WebP (640/1280/2048 px) und Alt-Text aus dem Admin.eager => truenur für das erste große Bild der Seite. - Saisonbilder je Baustein und Bausteine nur in bestimmten Erscheinungsbildern regelt das System. Vorlagen nehmen einfach
$photo/$photos. - Texte kommen aus dem Admin. Feste Texte in Vorlagen nur für Bedienelemente („Preis berechnen“, „Schließen“); auf Deutsch, per „Sie“.
- Eigene Teil-Vorlagen nach
views/partials/<name>.blade.phplegen und mit@include('theme::partials.<name>')einbinden. - Buchungs- und Bewertungsformular (
resources/views/livewire/*.blade.php) sind für alle Themes gemeinsam und nicht änderbar. Sie nutzen nur Token-Klassen und.btn-*; ein Theme passt sie über Tokens und die Basis-Klassen an.
6. Pflicht-Markup (wird von themes:check geprüft)
| Vorlage | Muss enthalten | Warum |
|---|---|---|
layouts/app |
@vite($theme->assets()), {!! $theme->cssVariables() !!} in <style>, @livewireStyles, @livewireScripts, @stack('head'), @yield('content'), data-appearance="{{ $theme->appearanceKey() }}" am <html>, <meta name="robots" content="noindex"> wenn $theme->isPreview || ! app()->isProduction(), Vorschau-Hinweis, <dialog id="lightbox"> mit img, [data-caption], [data-close], Sprunglink #inhalt |
Assets, Farben, Buchung, SEO-Schutz, Lightbox, Barrierefreiheit |
page |
Ausgabe von $sections ({!! $section->render() !!}) und JSON-LD aus $structuredData per @push('head') |
Inhalt, Google |
partials/header |
$theme->menu('main') (Links ->url(), Text ->label()), Button zur Buchung |
Navigation |
partials/footer |
$theme->menu('footer') (Impressum, Datenschutz) |
Rechtspflicht |
sections/hero |
GET-Formular an route('booking.create') mit data-availability-search und Feldern name="anreise", name="abreise" (Y-m-d), name="personen" |
Suche → Buchungsseite |
sections/booking |
<livewire:booking-request :property="$property" /> |
Kalender, Preis, Anfrage |
sections/gallery |
Links <a href="{{ $photo->url('lg') }}" data-lightbox data-alt="{{ $photo->alt_text }}"> |
Lightbox |
sections/offers |
Umsetzung von $display: bei rotating die Attribute data-rotator (Container), data-rotator-slide (je Angebot, außer dem ersten hidden), data-rotator-prev/-next, data-rotator-dot="<index>" mit aria-selected |
rollierende Angebote (theme.js) |
sections/reviews |
Hinweis: „Bewertungen über unsere Webseite können nur Gäste mit einer Buchung bei uns abgeben …“ (Wortlaut sinngemäß, muss „nur Gäste“ enthalten) | § 5b UWG |
sections/faq |
FAQ-JSON-LD per @push('head') |
|
partials/mobile-booking-bar |
auf dem Handy immer erreichbarer Buchungs-Button | Konversion |
7. Schriften, Bilder, Icons, Bewegung
- Schriften:
npm install @fontsource/<schrift>(oder@fontsource-variable/<schrift>), intheme.cssimportieren, in@theme inlineals--font-display/--font-sanssetzen. Höchstens zwei Familien und wenige Schnitte (Ladezeit). Lizenz: nur Open-Font-Lizenzen (Fontsource sind OFL). - Bilder: nur Fotos aus dem Admin (Webseite › Fotos). Dekorative Grafiken als Inline-SVG in der Vorlage oder als Datei im Theme-Ordner, eingebunden über
{{ Vite::asset('resources/themes/<key>/img/…') }}. Damit Vite diese Dateien baut, intheme.jseinmalimport.meta.glob(['./img/**'], { eager: true, query: '?url' });ergänzen. Keine Bild-URLs von fremden Servern. - Icons: Inline-SVG; Heroicons sind über Blade verfügbar (
<x-heroicon-o-sparkles class="size-5" />, kommt mit Filament). - Bewegung: nur mit Zweck;
@media (prefers-reduced-motion: no-preference)und@supports (animation-timeline: view())als Verbesserung. Ohne Animation und ohne JS muss alles vollständig funktionieren. Kein Autoplay-Video mit Ton; Video nur stumm, mit Standbild und nicht beiprefers-reduced-data.
8. Qualität
Es gelten THEMES.md §8:
- Mobil zuerst (ab 360 px).
- LCP unter 2,5 s.
- WCAG 2.2 AA mit Kontrasten, Tastaturbedienung, sichtbarem Fokus und genau einem
h1je Seite. - Reduced Motion wird respektiert.
- SEO-Ausgaben bleiben erhalten.
9. Prüfen, ansehen, einbinden
- Prüfen:
php artisan themes:check <key>. Rote Punkte (✗) sind Fehler und müssen behoben werden, gelbe (!) sind Hinweise. - Ansehen, ohne etwas umzuschalten:
php artisan themes:preview <key>gibt für jede Seite signierte Links aus: „heute“ und je Erscheinungsbild (Standard, Sommer, Winter, Weihnachten, Silvester). Im Admin geht das auch unter System › Websites › Theme: Theme wählen, dann „Vorschau“ (öffnet einen neuen Tab), noch nicht speichern. Vorschauseiten sindnoindex. Klickt man in der Vorschau auf einen Menülink, verlässt man sie; deshalb für jede Seite den eigenen Link verwenden. - Bauen und testen:
npm run buildundphp artisan test --compact. Der Testtest_installed_themes_fulfil_the_theme_contractlässt die Suite rot werden, wenn ein Theme die Prüfung nicht besteht. - Einreichen: Commit (nur
resources/themes/<key>/**, ggf.package*.json) und Push nach Gitea. - Ausliefern:
bash scripts/deploy.sh staging deploy(Testbetrieb https://stommer.info, siehe BETRIEB.md). Die Vorschau-Links funktionieren dort genauso (php artisan themes:preview <key>überbash scripts/deploy.sh staging artisan themes:preview <key>). - Auswählen: Admin › System › Websites › Website bearbeiten › Theme wählen › Speichern. Die Farbfelder darunter zeigen jetzt die Tokens des neuen Themes.
- Zurück: dort das vorherige Theme wählen. Alle Themes bleiben installiert; es wird nichts überschrieben.
10. Checkliste vor Abschluss
- Theme mit
themes:makeangelegt;resources/themes/ostsee-licht/**unverändert (git status) themes:check <key>ohne Fehler; Warnungen bewertet- Alle Seiten (
/,/wohnung,/kuehlungsborn,/buchen,/kontakt,/impressum,/datenschutz) auf Handy (360 px), Tablet und Desktop geprüft - Alle 5 Erscheinungsbilder über
themes:previewgeprüft (Silvester ist dunkel, Kontraste!) - Buchungsablauf in der Vorschau durchgespielt: Termin wählen → Preis erscheint → Anfrage absenden
- Sonderangebote in allen drei Darstellungen (Baustein-Einstellung) angesehen
- Tastatur: alles erreichbar, Fokus sichtbar; Reduced Motion an → keine Animation
- Nur selbst gehostete Schriften, keine externen Anfragen (Browser-Netzwerkanalyse)
npm run buildfehlerfrei,php artisan test --compactgrünREADME.mddes Themes: welche Vorlagen überschrieben sind, Schriften, Besonderheiten;versionerhöht
11. Gut zu wissen
- Tailwind-Klassen werden themeübergreifend gesammelt: Das Vite-Plugin sammelt beim Build die Klassen aller Themes, deshalb kann die CSS-Datei jedes Themes auch Klassen der anderen enthalten. Das ist harmlos (etwas größer). Eigene Schriften, Tokens und Komponenten-Stile bleiben dagegen im jeweiligen Theme, das ist geprüft.
- Strato hat ein Datei-Limit: Bilder im Theme-Ordner sparsam einsetzen; Fotos gehören in den Admin.
- Ein Theme pro Website: Weitere Vermieter mit eigener Domain können später ein anderes Theme nutzen (Admin › Websites).
12. Auftrag für die Design-Sitzung (zum Kopieren)
Lies
CLAUDE.md,docs/THEME-ERSTELLUNG.mdunddocs/THEMES.mdvollständig. Erstelle mit dem Skillfrontend-designein neues, zusätzliches Theme für die Ferienwohnung Stommer in Kühlungsborn. Lege es mitphp artisan themes:make <key> --name="…" --description="…"an und arbeite ausschließlich inresources/themes/<key>/(pluspackage.jsonfür@fontsource-Schriften). Verändereresources/themes/ostsee-lichtnicht. Kopiere die Referenzvorlagen ausresources/themes/ostsee-licht/viewsin dein Theme und gestalte sie neu. Halte dabei den Vorlagen-Vertrag (THEMES.md §5) und das Pflicht-Markup (THEME-ERSTELLUNG.md §6) ein. Nur Token-Farben, keine externen Quellen, mobil zuerst, WCAG 2.2 AA. Prüfe laufend mitphp artisan themes:check <key>und sieh jede Seite in allen Erscheinungsbildern überphp artisan themes:preview <key>an. Abschluss: Checkliste §10,npm run build,php artisan test --compact, Commit nur der Theme-Dateien.Gestalterische Leitideen: siehe THEMES.md §10.