Schritt für Schritt

Ein Theme fängt nie mit einer leeren Datei an. Das Gerüst enthält alle Verträge bereits richtig — wer daraus ein Theme macht, ändert nur das Aussehen.

Die Grundregel: erst messen, dann ändern. Fast alle Theme-Fehler erzeugen keine Fehlermeldung; die Seite sieht nur leer aus oder ein Knopf tut nichts.

1. Gerüst anlegen und prüfen

php artisan theme:new mein-theme --name="Mein Theme" --accent=#2b6cb0

php artisan theme:scan

Dann im Adminbereich unter Themes aktivieren und prüfen:

php artisan theme:doctor mein-theme

php artisan theme:smoke mein-theme

Erst wenn beides grün ist, mit der Optik anfangen. Das Gerüst bringt den Kaufweg mit — die einzige Stelle, an der ein Theme lautlos unverkäuflich werden kann.

2. Die Vorlage zerlegen

Wer eine Design-Vorlage umsetzt, geht sie Abschnitt für Abschnitt durch und beantwortet je Abschnitt eine Frage: Woher kommen diese Daten?

Antwort	Was zu tun ist
Es gibt einen Block, er sieht nur anders aus	Block-Override im Theme
Die Daten gibt es, aber keine passende Form	ein neuer Block im Core — nicht im Theme
Der Block kann fast alles, ein Feld fehlt	Schema-Feld im Core ergänzen
Die Daten gibt es im Shop nicht	erst die Funktion bauen — nichts erfinden

Diese Liste vor dem ersten Blade-Tag zu schreiben ist der eigentliche Zeitgewinn.

3. Für jeden Block: erst das Schema

php artisan blocks:schema hero

php artisan blocks:schema banner --all

Nennt Schlüssel, Vorgabewerte, erlaubte Auswahlwerte und Repeater-Felder; --all auch die geteilten Stil-Gruppen. Falsche Schlüssel laufen ohne Fehlermeldung durch — der Block nimmt seine Vorgaben, und man sucht den Fehler an der falschen Stelle.

4. Flächen festlegen

Alles, was der Händler sehen wird, gehört in eine Fläche: Startseite, Kopfzeile, Mobile Kopfzeile, Ankündigung, Fußzeile. Braucht das Theme mehr (z. B. eine Kategorieleiste), meldet es eine eigene Fläche an.

5. Stylen — und nach jeder CSS-Änderung veröffentlichen

Farben, Schriften, Abstände über die Design-Tokens. Die Theme-Dateien unter public/ werden beim Aktivieren nach public/themes/{slug} kopiert — wer CSS ändert und nichts sieht, hat meist nur nicht neu veröffentlicht:

php artisan tinker --execute="app(\Wavux\Core\Services\ThemeManager::class)->publishAssets('mein-theme', true);"

php artisan optimize:clear

6. Messen statt gucken

Auf jeder Seite bei mindestens 375, 820 und 1400 Pixeln Breite in der Browser-Konsole:

// Überlauf? Beide Zahlen müssen gleich sein.
document.documentElement.scrollWidth
document.documentElement.clientWidth
// Kaufweg vorhanden?
typeof addToCart          // "function"
!!Alpine.store('pdp')     // true auf Produktseiten

Ladezeit mit Lighthouse und gedrosselter CPU:

npx lighthouse https://deine-domain.de/ --only-categories=performance --preset=desktop --throttling.cpuSlowdownMultiplier=4 --view

Ziel: LCP unter 2,5 s, Total Blocking Time unter 200 ms, Layout-Sprung (CLS) unter 0,1.

7. Abnahme

Prüfen und ausliefern — Doctor, Rauchtest, Builder-Doctor, und von Hand: einen Artikel wirklich in den Warenkorb legen und die Startseite auf Handybreite ansehen.

Für eine KI oder einen Dienstleister

php artisan theme:kit

gibt Design-Tokens mit Werten, Breakpoints, alle Helfer, Hooks, theme.json-Schlüssel, Blöcke und einen Stil-Leitfaden aus — die Vorlage, die man einer KI gibt.

php artisan theme:bauplan --theme=nido

erzeugt eine einzige Übergabe-Seite: Auftrag, Grundlagen, ein vollständiges Referenz-Theme im Quelltext (jede Datei mit „das liegt fest, das ist frei”) und am Schluss die Prüfbefehle. Oben ein Knopf, der alles als reinen Text in die Zwischenablage legt.