Erste Schritte mit dem Theme Builder
Anlaufstelle: guppy-theme-builder.vercel.app. Daten bleiben im Browser; nichts wird auf Server hochgeladen.
1. Builder öffnen und Metadaten ausfüllen
Direkt nach dem Öffnen erscheint das Metadaten-Formular. Pflichtfelder:
| Feld | Beschreibung | Validierung |
|---|---|---|
technicalName | PascalCase, kein Leerzeichen, z. B. AcmeGuppyChildTheme | Regex ^[A-Z][A-Za-z0-9]+$ |
label | Anzeigename des Themes | Pflicht |
author | Wird zu Composer-Vendor-Slug | Fallback custom bei nicht eindeutigem Slug |
guppyVersion | Constraint-String | Default ^2.2 |
description | Lokalisiert für de-DE und en-GB | Pflicht je Sprache |
Konvention
Der technicalName sollte auf Theme enden. Der Builder warnt sonst, ist aber kein hartes Stop.
2. Theme-Variablen befüllen
Im Tab Theme Variables (~176 Felder, gegliedert in 5 Sub-Tabs):
- General: Brand-Farben, Borders, Backgrounds, System-Status, Graustufen.
- Typography: Font-Families, Headlines, Display-Größen, Linkfarben.
- UI Components: Buttons, Inputs, Badges, Alerts.
- Layout: Container-Breiten, Section-Padding pro Viewport, Header-/Footer-/Productcard-Varianten.
- Advanced: Detailpage, Produktbilder, Slider, Lieferstatus, Block-Padding.
Bidirektionale Synchronisation
Felder, die durch Guppy verwaltet werden (z. B. font-family-base ↔ sw-font-family-base), bleiben im Bootstrap-Editor read-only und referenzieren das jeweilige Guppy-Feld.
3. Bootstrap-Variablen anpassen (optional)
Im Tab Bootstrap Variables stehen ~80 Bootstrap-5-Felder direkt zur Verfügung. Anwendungsfall: Du willst tiefer ins Layout-System eingreifen, als die Guppy-Theme-Variablen erlauben.
4. Assets hochladen
Tab Assets, fünf Slots:
| Slot | Pflicht? | Empfehlung |
|---|---|---|
| Plugin-Icon | ja | PNG, 512×512, ≤ 2 MB |
| Theme-Preview | ja | JPEG/PNG/WebP, 1280×720, ≤ 5 MB |
| Logo | optional | SVG/PNG/JPEG/WebP, 320×120, ≤ 3 MB |
| Favicon | optional | ICO/PNG, 64×64, ≤ 1 MB |
| Share-Image | optional | SVG/PNG/JPEG/WebP, 512×512, ≤ 3 MB |
Größenabweichungen werden als Info-Hinweise angezeigt, sie blockieren den Export nicht.
5. Fonts hinzufügen (optional)
Tab Fonts: .woff/.woff2-Dateien hochladen. Der Builder generiert automatisch passende @font-face-Regeln in base/_fonts.scss. Hochgeladene Familien stehen anschließend in den Typography-Feldern zur Auswahl.
6. Snippets, Spacer-Map, Icon-Mappings (optional)
- Snippets: Übersetzungs-Keys (de/en) für Storefront-Texte.
- Spacer-Map: Custom-
$spacers-Einträge (Key + Wert). - Icon-Mappings: Shopware-Icon-Name ↔ Phosphor-Icon (Weight + Pack).
7. Snapshot speichern (empfohlen)
Über Save Snapshot lädst du eine .guppy-builder.json-Datei herunter. Sie enthält den vollständigen Builder-Stand und lässt sich später wieder importieren.
Snapshot ist die Versionskontrolle
Da der Builder keinen Account und keinen Server-Storage hat, ist der Snapshot deine einzige Versionskontrolle. Sichere ihn (z. B. in deinem Repo).
8. Export
Per Klick auf Export ZIP erzeugt der Builder das fertige Plugin und lädt es als <TechnicalName>.zip herunter. Die ZIP enthält neben allen Plugin-Dateien auch .guppy-builder.json für späteres Re-Import.
Nächste Schritte
- Konfiguration: vollständige Feldreferenz.
- Workflow: Installation und iterative Weiterentwicklung.