Theme Variables
This reference is the compact lookup table for SCSS variables, their theme.json sources, and defaults. For an annotated architecture overview see Variables & Tokens.
Sources
| File | Purpose |
|---|---|
abstract/variables/bootstrap.scss | Bootstrap overrides, binds $sw-* tokens to Bootstrap defaults |
abstract/variables/custom.scss | Guppy-specific tokens (delivery status, product images, focus, icons…) |
theme.json | Admin configuration, populates $sw-* tokens |
Setting variables in a child theme
Set the variables in the child theme's own variables file, imported by its overrides.scss, which loads before Guppy's. Guppy's variables are !default, so the child theme's value wins, also over a theme field that feeds the same variable.
Brand colors
| SCSS | theme.json | Default | Use |
|---|---|---|---|
$sw-color-brand-primary | sw-color-brand-primary | #215AFF | Primary |
$sw-color-brand-secondary | sw-color-brand-secondary | #0B1845 | Secondary |
$sw-background-color | sw-background-color | #FFFFFF | Background |
$sw-border-color | sw-border-color | #CFD1D7 | Borders |
$sw-text-color | sw-text-color | #1B1F29 | Text color |
$sw-headline-color | sw-headline-color | #1B1F29 | Headlines |
Greyscales
| SCSS | Default |
|---|---|
$sw-color-gray-100 | #F9F9F9 |
$sw-color-gray-200 | #EEEEEE |
$sw-color-gray-300 | #BCC1C7 |
$sw-color-gray-400 | #CED4DA |
$sw-color-gray-500 | #ADB5BD |
$sw-color-gray-600 | #798490 |
$sw-color-gray-700 | #495057 |
$sw-color-gray-800 | #4A545B |
$sw-color-gray-900 | #212529 |
Typography
| SCSS | theme.json | Default |
|---|---|---|
$sw-font-size-base | sw-font-size-base | 1rem |
$sw-h1-font-size | sw-h1-font-size | 32px |
$sw-h2-font-size | sw-h2-font-size | 24px |
$sw-h3-font-size | sw-h3-font-size | 20px |
$sw-h4-font-size | sw-h4-font-size | 18px |
$sw-h5-font-size | sw-h5-font-size | 16px |
$sw-h6-font-size | sw-h6-font-size | 15px |
$sw-h1-line-height | sw-h1-line-height | 44px |
$sw-h2-line-height | sw-h2-line-height | 36px |
$sw-h3-line-height | sw-h3-line-height | 32px |
$sw-h4-line-height | sw-h4-line-height | 28px |
$sw-h5-line-height | sw-h5-line-height | 24px |
$sw-h6-line-height | sw-h6-line-height | 21px |
$body-secondary-color | guppy-text-secondary-color | $sw-text-color while the field is empty |
$headings-font-family | sw-font-family-headline | $sw-font-family-headline |
$sw-h6-line-height applies to h6 / .h6 since 2.9.0 (before: Bootstrap's 1.2), see Config Schema → Typography.
$headings-font-family was null before 2.9.0 and got the same value from the Storefront skin, so the output is unchanged. To change the headings font, use the "Fonttype headline" field; no SCSS is needed. Only a headings font that differs from the field needs $headings-font-family in the child theme's own abstract/variables/bootstrap.scss, imported by its overrides.scss before Guppy's.
$body-secondary-color (--bs-secondary-color) colours .text-muted, .text-body-secondary, .form-text, captions, the breadcrumb divider and current item, disabled nav links, list group action/disabled items, the toast header and the disabled range thumb. A child theme's own value wins over the field. The dark colour mode ([data-bs-theme="dark"]) keeps its own value.
Container and padding
| SCSS | Default |
|---|---|
$guppy-container-width-default | 1400px |
$guppy-container-width-fluid | 100% |
$guppy-container-width-sm | 1230px |
$guppy-container-default-padding-x-mobile | 10px |
$guppy-container-default-padding-x-sm | 24px |
$guppy-container-default-padding-x-md | 48px |
$guppy-container-default-padding-x-lg | 48px |
$guppy-container-default-padding-x-xl | 48px |
$guppy-container-default-padding-x-xxl | 48px |
Container padding (.container* classes)
Since 2.9.0 the horizontal padding of the .container* classes has its own variables in custom.scss:
| SCSS | Default |
|---|---|
$guppy-container-padding-x-mobile | $guppy-block-padding-x-mobile (10px) |
$guppy-container-padding-x-sm | $guppy-block-padding-x-sm (24px) |
$guppy-container-padding-x-md | $guppy-block-padding-x-md (48px) |
$guppy-container-padding-x-lg | $guppy-block-padding-x-lg (48px) |
$guppy-container-padding-x-xl | $guppy-block-padding-x-xl (48px) |
$guppy-container-padding-x-xxl | $guppy-block-padding-x-xxl (48px) |
The defaults equal the CMS block padding, so the output is unchanged. Set them to change the container padding without touching the CMS block padding; $guppy-block-padding-x-* stays available. Bootstrap's $container-padding-x does not drive the container padding in Guppy: Bootstrap's make-container() uses it for the .container* padding, which Guppy overrides. It still sets the toast spacing and, in Guppy, the negative margin of .cms-block-product-description-reviews below sm. Grid gutters come from $grid-gutter-width.
CMS section padding
| SCSS | theme.json | Default |
|---|---|---|
$guppy-cms-section-padding-x | guppy-cms-section-padding-x | 48px |
$guppy-cms-section-padding-y | guppy-cms-section-padding-y | 48px |
$guppy-cms-section-padding-y-2x | guppy-cms-section-padding-y-2x | 96px |
Buttons and inputs
| SCSS | theme.json | Default |
|---|---|---|
$sw-input-btn-font-size | sw-input-btn-font-size | 16px |
$sw-input-btn-border-radius | sw-input-btn-border-radius | 4px |
$sw-input-btn-font-weight | sw-input-btn-font-weight | normal |
$guppy-input-border-color | guppy-input-border-color | $sw-border-color while the field is empty |
$guppy-input-border-color (since 2.9.0) drives $input-border-color, $form-check-input-border (1px solid) and $dropdown-border-color, and through them .form-control, .form-select, .form-check-input, .dropdown-menu, .input-group-text, the header search buttons and the filter panel toggles. Bootstrap derives $dropdown-divider-bg and $dropdown-dark-border-color (and through it $dropdown-dark-divider-bg) from $dropdown-border-color, so the dropdown dividers and the dark dropdown follow too; $form-select-border-color follows $input-border-color. A child theme that sets $input-border-color itself keeps its value. Form controls need 3:1 contrast against the background (WCAG 1.4.11).
Button sizes
Since 2.9.0, in custom.scss:
| SCSS | Default | Use |
|---|---|---|
$guppy-btn-min-height | 48px | min-height and min-width of .btn, height and min. width of pagination items, height of the offcanvas close button, size of the product configurator options |
$guppy-btn-min-height-sm | 40px | .btn-sm |
$guppy-btn-min-height-lg | 48px | .btn-lg, .btn-group-lg > .btn and, through its @extend .btn-lg, .btn-buy; the .btn-lg rule is only emitted when the value differs from $guppy-btn-min-height |
$guppy-btn-buy-padding-y | $btn-padding-y | Buy button (.btn-buy) |
$guppy-btn-buy-padding-x | $btn-padding-x | Buy button |
$guppy-btn-buy-font-size | $btn-font-size | Buy button |
$guppy-btn-buy-line-height | $btn-line-height | Buy button |
The defaults equal the previous fixed values, so the output is unchanged. Lowering $guppy-btn-min-height shrinks all controls listed above. The $guppy-btn-buy-* variables size the buy button without changing the other buttons.
Border radius
Since 2.9.0 the radius set is derived from one base value (bootstrap.scss, section "Borders"):
| SCSS | theme.json | Default |
|---|---|---|
$guppy-border-radius-base | guppy-border-radius | 0.25rem (field 4px) |
$border-radius | – | $guppy-border-radius-base |
$border-radius-sm | – | base × 0.6 (0.15rem) |
$border-radius-lg | – | base × 1.5 (0.375rem) |
$border-radius-xl | – | base × 3 (0.75rem) |
$border-radius-2xl | – | base × 6 (1.5rem) |
$guppy-logo-radius | – | $border-radius-lg (footer logos) |
$guppy-slider-arrow-radius | guppy-slider-arrows-round | $border-radius * 2; $border-radius-pill when the switch is on |
The field converts px to rem (/16), keeps rem, and reads a unitless value as px; an empty field or another unit gives 0.25rem. All variables are !default: a child theme's own $guppy-border-radius-base wins over the field and scales the whole set; a child theme that sets only $border-radius keeps its value, while the derived radii keep following the field. $border-radius-xxl (.rounded-5, 2rem) and $border-radius-pill are not set by Guppy. Payment text logos carry .rounded-2 (the base radius). $guppy-slider-arrow-radius applies to .splide-slider .splide__arrow and .splide__toggle (image slider, image gallery, Splide slider elements); core product and cross-selling sliders (.base-slider-controls-*) are not affected. Set it to 50% in a child theme for round arrows; its value wins over the switch.
Icons
| SCSS | Default | Use |
|---|---|---|
$icon-base-size | 22px | Base size |
$icon-base-color | currentColor | Inherits text color |
$icon-accessibility-touch-size | 44px | Min. touch target (WCAG 2.5.5) |
Phosphor glyphs for UI controls
With the switch guppy-ui-icons-phosphor on (since 2.9.0), these Bootstrap variables (bootstrap.scss, section "Forms & Inputs") get Phosphor glyphs in the bold weight as data URIs:
| SCSS | Glyph | Where |
|---|---|---|
$btn-close-bg | x | .btn-close |
$form-select-indicator | caret-down | .form-select |
$form-check-input-checked-bg-image | check | checkbox tick |
$accordion-button-icon, $accordion-button-active-icon | caret-down | .accordion-button (no Guppy or core template renders it) |
$form-feedback-icon-valid | check-circle | validation icon, only with $enable-validation-icons: true (Guppy: false) |
$form-feedback-icon-invalid | warning-circle | validation icon, as above |
Each viewBox crops Phosphor's 256 grid so the glyph covers the area of Bootstrap's glyph (within 10 %). The colours come from Bootstrap's own colour variables, and Bootstrap's escape-svg() runs at the use sites. Radio, indeterminate checkbox, switch and the dark-mode variants keep Bootstrap's glyphs. The values are !default, so a child theme's own value for any of them (or their colour variables) wins. A child theme inherits the switch value from Guppy unless it stores its own. With the switch off the output is unchanged.
Product images
| SCSS | Default | Use |
|---|---|---|
$product-image-height | 240px | Default height |
$product-image-height-lg | fit-content | Height on large screens |
$product-image-aspect-ratio | 10/9 | Aspect ratio |
$product-image-background | $sw-color-product-image | Background |
Accessibility
| SCSS | Default | Use |
|---|---|---|
$focus-outline-width | 2px | Focus outline width |
$focus-outline-color | guppy-focus-color, else $sw-color-brand-primary | Focus outline color (focus-style(), --bs-btn-focus-outline-color) |
$focus-outline-offset | 2px | Distance from element |
$focus-outline-box-shadow | 0 0 0 2px #fff | Additional shadow |
$focus-ring-color | guppy-focus-color, else $primary, with $focus-ring-opacity (0.6) | Bootstrap focus ring (--bs-focus-ring-color) |
$input-btn-focus-box-shadow | 0 0 $focus-ring-blur $focus-ring-width, colour as above with $guppy-input-btn-focus-opacity | Focus shadow of form fields and buttons |
$guppy-input-btn-focus-opacity | 0.25 | Opacity of that focus shadow |
$input-focus-border-color | guppy-focus-color, else $sw-color-brand-primary | Focus border of form fields, the header search field and its button |
$guppy-modal-close-size | null | Fixed size of the modal close button |
The theme field guppy-focus-color (since 2.9.0) feeds the four focus variables; empty keeps the primary colour, so the output is unchanged. $input-focus-border-color also feeds $form-select-focus-border-color, $form-check-input-focus-border and $form-switch-focus-color. Bootstrap's $input-btn-focus-color-opacity is not set by Guppy, and the focus shadows of the validation states keep $focus-ring-opacity. All are !default, so a child theme's own value wins. The focus indicator needs 3:1 contrast (WCAG 1.4.11).
Changed in 2.9.0: focus shadow and header search focus
$input-btn-focus-box-shadow used to be a fixed 0 0 0 0.2rem with opacity .25. It now follows $focus-ring-width, $focus-ring-blur and $guppy-input-btn-focus-opacity; with Guppy's values the output is unchanged. A child theme that sets $focus-ring-width or $focus-ring-blur now also changes this shadow, so it matches its focus ring. To keep the previous shadow, set $input-btn-focus-box-shadow in the child theme. The focus border of the header search field and its button (.header-search-input:focus) now follows $input-focus-border-color instead of the primary colour, so a child theme that sets $input-focus-border-color changes it too.
$guppy-modal-close-size (since 2.9.0): while null, .modal-header .btn-close keeps Bootstrap's sizing from $modal-header-padding-y/-x (10px). When set, for example to 44px for a larger touch target, the button gets exactly this width and height (box-sizing: border-box, no shrinking), and its vertical margins become -$modal-header-padding-y (Bootstrap: half of it); the horizontal margin stays. The header only grows when the button exceeds the title line plus both paddings: with 44px and 10px padding it is 44px high instead of 36px.
Delivery status
| SCSS | Default |
|---|---|
$guppy-delivery-shipping-free-color | #023B5A |
$guppy-delivery-shipping-free-background | #CEEDFE |
$guppy-delivery-available-color | #154634 |
$guppy-delivery-available-background | #D3F2E7 |
$guppy-delivery-restock-color | #5D3B00 |
$guppy-delivery-restock-background | #FFEFD4 |
$guppy-delivery-soldout-color | #303030 |
$guppy-delivery-soldout-background | #EEEEEE |
Badges
| theme.json | Default |
|---|---|
guppy-badges-new-background-color | #22C087 |
guppy-badges-new-color | #FFFFFF |
guppy-badges-top-seller-background-color | #F89C00 |
guppy-badges-top-seller-color | #FFFFFF |
guppy-badges-discount-background-color | #E10036 |
guppy-badges-discount-color | #FFFFFF |
guppy-badges-out-of-stock-background-color | #EEEEEE |
guppy-badges-out-of-stock-color | #303030 |
Alerts
| theme.json | Default |
|---|---|
guppy-alert-color-success | #D3F2E7 |
guppy-alert-color-info | #CEEDFE |
guppy-alert-color-warning | #FFEFD4 |
guppy-alert-color-danger | #FDE2E7 |
| SCSS | Default | Use |
|---|---|---|
$guppy-alert-outline-color | #303030 | Outline of alerts (guppy-alert-alert-outline-active), was a fixed value before 2.9.0 |
$guppy-alert-success-text-color | null | Fixed text and icon colour of success alerts |
$guppy-alert-info-text-color | null | Same for info alerts |
$guppy-alert-warning-text-color | null | Same for warning alerts |
$guppy-alert-danger-text-color | null | Same for danger alerts |
While a text colour variable is null, the alert keeps the light or dark brightness filter of the field guppy-alert-color-<state>-text, so the output is unchanged. When set, that state's icon and text use the colour and the filter is dropped, regardless of the light/dark field. Links inside the alert keep their link colour.
Mixins (selection)
| Mixin | Purpose |
|---|---|
focus-style | Consistent focus outline |
line-height($value) | Responsive line height |
rlh($value, $property) | RLH variant with property choice |
button-adaptive-hover($base-color) | Hover only for (hover: hover) |
text-ellipsis | Single-line ellipsis |
text-clamp($lines) | Multi-line ellipsis |
visually-hidden | Screen-reader-only |
Functions
| Function | Purpose |
|---|---|
px-to-rem($px) | Pixels to rem |
strip-unit($value) | Strip a unit |
shade-color($color, $weight) | Darken color (Bootstrap) |
tint-color($color, $weight) | Lighten color (Bootstrap) |
shift-color($color, $weight) | Lighten / darken based on lightness (Bootstrap) |
Related
- Variables & Tokens: annotated architecture overview.
- Config Schema: full
theme.jsonfield reference. - Twig Blocks: templates that consume these variables.