Configuration

The Theme Builder groups configuration into multiple areas. This page is the full field reference; for a guided tour see Getting Started.

Metadata

Field	Type	Required	Default	Description
technicalName	String	yes	–	PascalCase, regex ^[A-Z][A-Za-z0-9]+$. Determines plugin class + directory.
label	String	yes	–	Theme display name in the admin.
author	String	yes	–	Maps to Composer vendor slug; fallback custom if slug is ambiguous.
guppyVersion	String	yes	^2.2	Composer constraint for dmf/sw6-guppy-theme.
description.de-DE	String	yes	–	German plugin description.
description.en-GB	String	yes	–	English plugin description.

Theme variables (~176 fields)

Split into 5 sub-tabs:

General

Brand colors (primary, secondary), borders, backgrounds, system status (success/info/warning/danger), greyscale palette.

Typography

Font families (body, headlines), sizes (h1–h6, display 1–3), line heights, text color, headlines color, link colors.

UI Components

• Button colors/sizes
• Input borders
• Badge colors (new/top-seller/discount, with outline toggles)
• Alert backgrounds + text colors

Layout

• Container widths (default/fluid/narrow/wide/extra-wide)
• Section padding (desktop/tablet/mobile)
• Header/navigation/footer variants
• Product card configuration
• USP bar (toggle, colors, texts, social links)

Advanced

Detail page buybox styling, product images, sliders, delivery status colors, order item status colors, block padding.

Bi-directional Bootstrap sync

Fields marked guppyManagedBy: 'sw-*' (e.g. font-family-base ↔ sw-font-family-base) are read-only in the Bootstrap editor and reference the Guppy counterpart.

Bootstrap variables (~80 fields)

Direct access to Bootstrap 5 variables, grouped by category:

Category	Examples
Colors	primary, secondary, success, info, warning, danger, light, dark, body-color
Typography	font-family-base, font-family-sans-serif, font-size-base, font-weight-bold, line-height-base
Spacing	spacer, grid-gutter-width
Borders	border-radius (default, sm, lg, xl, pill), border-width
Shadows	box-shadow (default, sm, lg), enable-shadows toggle
Layout	Container widths, enable-negative-margins, grid breakpoints
Components	Button/input/card radii, link decoration, pagination, badge sizing
Feature flags	enable-rounded and other enable-* toggles

Validation

The builder validates Bootstrap field names against the known Bootstrap 5 variables. Typos are flagged in the UI.

Assets

Five slots, two of them required:

Slot	Required	Format	Recommended size	Max	Target in plugin
pluginIcon	yes	PNG	512 × 512	2 MB	src/Resources/config/plugin.png
themePreview	yes	JPEG/PNG/WebP	1280 × 720	5 MB	src/Resources/app/storefront/dist/assets/theme-preview.jpg
logo	no	SVG/PNG/JPEG/WebP	320 × 120	3 MB	populates sw-logo-desktop, sw-logo-tablet, sw-logo-mobile
favicon	no	ICO/PNG	64 × 64	1 MB	populates sw-logo-favicon
shareImage	no	SVG/PNG/JPEG/WebP	512 × 512	3 MB	populates sw-logo-share

Fonts

Upload .woff and .woff2 files. One directory per family is generated:

src/Resources/app/storefront/dist/assets/font/{family-slug}/{filename.woff2}

The @font-face rules end up in src/Resources/app/storefront/src/scss/base/_fonts.scss. Uploaded families become selectable in the typography fields.

Path resolution

@font-face paths use $app-css-relative-asset-path so fonts load correctly after theme:compile.

Custom SCSS variables

Name-value pairs appended to abstract/variables/custom.scss with !default:

$custom-spacer: 12px !default;
$brand-accent: #f49927 !default;

Adopted by the child theme's SCSS and overridable downstream.

Snippets

Translation keys for storefront text, in de-DE and en-GB. Land in:

src/Resources/snippet/de_DE/storefront.de-DE.json
src/Resources/snippet/en_GB/storefront.en-GB.json

Spacer map

Custom $spacers entries:

Field	Description
Key	numeric or named map key
Value	CSS value (e.g. 24px, 1.5rem)

Icon mappings

Shopware icon name ↔ Phosphor icon configuration:

Field	Description
Shopware name	Standard Shopware icon identifier
Phosphor icon	Target icon
Weight	thin, light, regular, bold, fill, duotone
Pack	Phosphor pack

Validation rules

Rule	Effect
technicalName must match ^[A-Z][A-Za-z0-9]+$	Required, no export otherwise.
technicalName should end with Theme	Warning, not blocked.
Required assets (pluginIcon, themePreview) must be present	Required, no export otherwise.
Asset dimensions checked against recommendations	Info hint, not blocked.
Bootstrap variable names validated against the Bootstrap 5 schema	Error in the UI.
Snapshot schema version migrated on import	Auto-migration v0–v7 → v8.

Snapshot

.guppy-builder.json contains:

• All 176 theme variable values
• All Bootstrap variables
• Asset metadata + base64 contents
• Font files (base64)
• Custom SCSS variables, snippets, spacer map, icon mappings
• Schema version (currently v8)

Re-import: load an existing snapshot via Load Snapshot in the builder. The form is fully restored.