theme.json und Design-Tokens

Die Schlüssel

Schlüssel	Bedeutung
slug	Ordnername, klein, mit Bindestrich
name	Anzeigename im Adminbereich
version	SemVer, z. B. 1.0.0
author, description	frei; ein Satz Beschreibung
parent	Slug des Eltern-Themes (Child-Theme) — sonst weglassen
contract	Version des Core-Vertrags, gegen den gebaut wurde
requires	Mindestversion des Shops
requires_blocks	Blocktypen, ohne die das Layout bricht — fehlt einer, meldet der Doctor ROT
requires_plugins	Plugins, ohne die das Theme nicht läuft — ROT, wenn sie fehlen
supports	Fähigkeiten, die das Theme anbietet, z. B. quickview
design	tokens und presets — siehe unten
settings	Felder für Theme → Anpassen — nur Marke und Rahmen, nie Inhalte
regions	eigene Builder-Flächen — Eigene Flächen

Jedes Feld unter settings muss irgendwo gelesen werden (theme_setting('…') in einer View oder über eine Zuordnung in design.settings_map). Ein Feld ohne Wirkung meldet der Doctor.

Design-Tokens

Jeder Token wird als CSS-Variable --<name> ausgegeben. Im CSS mit var(--color-accent), in PHP mit design_token('color-accent'). Das Theme setzt eigene Werte unter design.tokens; was es nicht setzt, kommt aus der Vorgabe.

Gruppe	Tokens
Farben	color-primary, color-on-primary, color-secondary, color-on-secondary, color-accent, color-success, color-warning, color-danger, color-background, color-surface, color-text, color-text-muted, color-border
Schrift	font-heading, font-body
Schriftgrößen	text-xs 0.75rem · text-sm 0.875rem · text-base 1rem · text-lg 1.125rem · text-xl 1.375rem · text-2xl 1.75rem · text-3xl 2.25rem
Abstände	space-xs, space-sm, space-md, space-lg, space-xl, space-2xl
Rundungen	radius-sm, radius-md, radius-lg, radius-full
Schatten	shadow-sm, shadow-md, shadow-lg
Breiten	container-sm 760px · container-md 1080px · container-lg
Bewegung	transition-fast, transition-base

Die aktuellen Werte, die Core-Vorgaben und welche das aktive Theme überschreibt, nennt php artisan theme:kit.

Regeln

• Farben nie fest ins CSS schreiben. Entweder Token oder var(--blk-…, var(--color-…)). Feste Hex-Werte nehmen dem Händler „Anpassen” aus der Hand; der Doctor meldet sie.
• Schriftfamilien nur über font-heading und font-body. Nur dann lädt der Shop sie vorab — sonst zeichnet der Browser erst mit einer Ersatzschrift, und beim Tausch springt die Seite.
• Drei Rundungen, drei Schatten. Abstände aus der Skala, nicht aus dem Bauch.

Presets

design.presets legt Varianten für Blöcke fest, z. B. wie „Button primär” und „Button sekundär” aussehen. Im Builder wählt der Händler die Variante; wie sie aussieht, bestimmt das Theme.

Breakpoints

Gerät	Breite
Tablet	bis 1024 px
Mobil	bis 767 px

Diese beiden Werte nutzt der Builder für Werte je Gerät (Innen- und Außenabstand, Schriftgröße, Ausrichtung). Ein Theme darf eigene Breakpoints haben, sollte diese aber kennen — sonst springt ein Block bei 1024 px um und das Theme drumherum bei 960 px.

Schriften

Schriften lokal einbinden: Dateien unter Schriften & Assets hochladen oder per php artisan fonts:vendor holen, die Familie in font-heading/font-body nennen. Keine Google-Fonts-Links — sie übertragen die IP-Adresse jedes Besuchers.