# 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](THEMES.md) > **Vor dem Start:** [ZUSAMMENARBEIT.md](ZUSAMMENARBEIT.md) lesen – die Design-Session arbeitet auf dem Branch `theme/` und nur im eigenen Theme-Ordner; Wünsche an die Anwendung gehen in ZUSAMMENARBEIT.md §5, Änderungen am Vorlagen-Vertrag stehen in §6. > **Kurz:** Ein neues Design entsteht als **zusätzliches Theme** in einem eigenen Ordner `resources/themes//`. Das vorhandene Theme **„Ostsee-Licht“ wird nicht verändert**. Das neue Theme erbt alles, was es nicht selbst mitbringt, wird mit `php artisan themes:check ` 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) 1. **Nur im eigenen Ordner arbeiten:** `resources/themes//**`. Zusätzlich erlaubt: `package.json`/`package-lock.json` für **selbst gehostete Schriften** (`@fontsource/*`). Alles andere bleibt unangetastet, insbesondere `resources/themes/ostsee-licht/**`, `app/**`, `config/**`, `database/**`, `routes/**`, `resources/views/livewire/**`. 2. **Neues Theme immer mit `php artisan themes:make ` anlegen.** Der Befehl erzeugt das korrekte Format und überschreibt nie einen vorhandenen Ordner. 3. **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](THEMES.md)). 4. **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-black` auf Fotos und Overlays. 5. **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. 6. **Pflicht-Markup erhalten** (§6): Verfügbarkeitssuche, Buchungsformular, Lightbox, rollierende Angebote, Echtheitshinweis der Bewertungen, JSON-LD, `noindex` in der Vorschau. 7. **Fertig ist ein Theme erst, wenn** `php artisan themes:check ` ohne Fehler, `npm run build` fehlerfrei und `php artisan test --compact` grün ist und die Checkliste in §10 abgehakt ist. ## 2. Schnellstart ```bash git checkout main && git pull && git checkout -b theme/ # eigener Branch (ZUSAMMENARBEIT.md §2) 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 --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// ├── 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 (, 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/.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` ```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//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) ```css @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 `@apply` auf eigene Klassen). - `theme-base.css` des Eltern-Themes liefert: Schriften von Ostsee-Licht, das Mapping aller Tokens auf Tailwind-Farben (`--color-: var(--)`), 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`. **Wer `theme-base.css` nicht importiert, muss all das selbst bereitstellen.** `themes:check` prüft Mapping und Quellen. - **Nicht** `../ostsee-licht/theme.css` importieren, sondern `theme-base.css`. Die Quellen gibt das neue Theme selbst an. ### 3.3 `theme.js` ```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:check` fü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: ``, also etwa `[data-appearance=silvester] .hero-overlay { … }`. Schlüssel: `standard`, `sommer`, `winter`, `weihnachten`, `silvester` (Slug des Namens). - **Neues Token:** in `theme.json › tokens` (mit `label`, `default`) und in `theme.css › @theme inline` als `--color-: var(--);` 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.` mit fertigen Variablen. **Welche Variablen es gibt, steht verbindlich in [THEMES.md](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:** `$theme` und `$sectionId`. `$sectionId` für `id`/`aria-labelledby` verwenden, 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 => true` nur 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/.blade.php` legen und mit `@include('theme::partials.')` 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 `