Getting Started with the Theme Builder
Entry point: guppy-theme-builder.vercel.app. All data stays in the browser; nothing is uploaded to a server.
1. Open the builder and fill in metadata
The metadata form appears right after you open the builder. Required fields:
| Field | Description | Validation |
|---|---|---|
technicalName | PascalCase, no spaces, e.g. AcmeGuppyChildTheme | regex ^[A-Z][A-Za-z0-9]+$ |
label | Display name | required |
author | Maps to Composer vendor slug | fallback custom if slug is ambiguous |
guppyVersion | Constraint string | default ^2.2 |
description | Localised for de-DE and en-GB | required per language |
Convention
technicalName should end with Theme. The builder warns if it doesn't, but doesn't block.
2. Fill in theme variables
In the Theme Variables tab (~176 fields, split into 5 sub-tabs):
- General: brand colors, borders, backgrounds, system status, greyscales.
- Typography: font families, headlines, display sizes, link colors.
- UI Components: buttons, inputs, badges, alerts.
- Layout: container widths, per-viewport section padding, header/footer/productcard variants, USP bar.
- Advanced: detail page, product images, sliders, delivery status, block padding.
Bi-directional sync
Fields managed by Guppy (e.g. font-family-base ↔ sw-font-family-base) are read-only in the Bootstrap editor and reference the corresponding Guppy field.
3. Adjust Bootstrap variables (optional)
The Bootstrap Variables tab exposes ~80 Bootstrap 5 fields directly. Use case: you need to reach deeper into the layout system than the Guppy theme variables allow.
4. Upload assets
Assets tab, five slots:
| Slot | Required? | Recommendation |
|---|---|---|
| Plugin icon | yes | PNG, 512×512, ≤ 2 MB |
| Theme preview | yes | 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 |
Dimension mismatches show up as info hints, they don't block the export.
5. Add fonts (optional)
Fonts tab: upload .woff/.woff2 files. The builder generates matching @font-face rules in base/_fonts.scss automatically. Uploaded families become available in the typography fields.
6. Snippets, spacer map, icon mappings (optional)
- Snippets: translation keys (de/en) for storefront text.
- Spacer map: custom
$spacersentries (key + value). - Icon mappings: Shopware icon name ↔ Phosphor icon (weight + pack).
7. Save a snapshot (recommended)
Save Snapshot downloads a .guppy-builder.json file containing the full builder state. You can re-import it later.
Snapshot is your version control
Because the builder has no account or server storage, the snapshot is your only form of version control. Keep it safe (e.g. in your repo).
8. Export
Clicking Export ZIP produces the finished plugin and downloads it as <TechnicalName>.zip. The ZIP includes .guppy-builder.json alongside all plugin files for later re-import.
Next steps
- Configuration: full field reference.
- Workflow: installation and iterative development.