SCSS Architecture

Contents of this page:

• Directory Structure
• Abstract Layer
  • Functions
  • Mixins
  • Variables
• Component System
  • Product Box (product-box.scss)
  • Skip Link (skip-link.scss)
• Build System
  • Compilation Order
  • Main Entry (base.scss)
• Customization
  • Child Theme Overrides
  • Best Practices
• Responsive Breakpoints
  • Bootstrap Grid Breakpoints
  • Breakpoint Usage
  • Guppy Container Paddings per Breakpoint
• All Available Mixins
  • Layout Mixins
  • Typography Mixins
  • Accessibility Mixins
  • Button Mixins
• All Available Functions
  • Unit Conversion
  • Color Functions
• Theme Variables Overview
  • Color Variables
  • Gray Scale
  • Typography Variables
  • Accessibility Variables
• Practical Examples
  • Create Custom Component
  • Customize Product Card

The Guppy Theme uses a well-thought-out SCSS architecture that builds on the Bootstrap framework and is extended with custom components and functionalities.

Directory Structure

src/scss/
├── abstract/
│   ├── functions/
│   │   ├── boolean.scss
│   │   ├── px-to-rem.scss
│   │   └── strip-unit.scss
│   ├── mixins/
│   │   ├── button-adaptive-hover.scss
│   │   ├── focus-style.scss
│   │   └── rlh.scss
│   └── variables/
│       ├── bootstrap.scss
│       └── custom.scss
├── base/
│   ├── accessibility.scss
│   ├── base.scss
│   ├── container.scss
│   └── typography.scss
├── components/
│   ├── alert.scss
│   ├── badge.scss
│   ├── base-slider.scss
│   ├── breadcrumb.scss
│   ├── button.scss
│   ├── card.scss
│   ├── category-navigation.scss
│   ├── cms-block.scss
│   ├── cms-element.scss
│   ├── cms-section.scss
│   ├── delivery-information.scss
│   ├── filter-panel.scss
│   ├── forms.scss
│   ├── gallery-slider.scss
│   ├── guppy-theme-card-style.scss
│   ├── icon.scss
│   ├── image-slider.scss
│   ├── line-item.scss
│   ├── login.scss
│   ├── nav.scss
│   ├── offcanvas.scss
│   ├── pagination.scss
│   ├── payment-method.scss
│   ├── product-badges.scss
│   ├── product-box.scss
│   ├── product-slider.scss
│   ├── product-wishlist.scss
│   ├── quantity-selector.scss
│   └── shipping-method.scss
├── elements/
│   ├── skip-link.scss
│   └── splide-slider.scss
├── layout/
│   ├── account-menu.scss
│   ├── container.scss
│   ├── footer-minimal.scss
│   ├── footer.scss
│   ├── header-minimal.scss
│   ├── header.scss
│   ├── main-navigation.scss
│   ├── navbar.scss
│   ├── navigation-flyout.scss
│   ├── offcanvas-cart.scss
│   ├── top-bar.scss
│   └── usp-banner.scss
├── page/
│   ├── account/
│   │   ├── account.scss
│   │   ├── aside.scss
│   │   └── register.scss
│   ├── checkout/
│   │   ├── aside.scss
│   │   ├── cart.scss
│   │   ├── checkout.scss
│   │   ├── confirm.scss
│   │   └── finish.scss
│   ├── content/
│   │   └── breadcrumb.scss
│   └── product-detail/
│       ├── configurator.scss
│       ├── product-detail.scss
│       └── tabs.scss
├── skin/
│   └── shopware/
│       ├── abstract/
│       │   ├── variables.scss
│       │   └── variables/
│       │       ├── bootstrap.scss
│       │       ├── custom.scss
│       │       └── theme.scss
│       ├── base.scss
│       ├── base/
│       │   ├── base.scss
│       │   └── inter-fontface.scss
│       └── component/
│           ├── cms-block.scss
│           ├── cms-element.scss
│           ├── custom-select.scss
│           ├── modal.scss
│           ├── pagination.scss
│           ├── product-box.scss
│           ├── quickview-modal.scss
│           └── tab-menu.scss
├── base.scss
└── overrides.scss

---

Abstract Layer

Functions

px-to-rem.scss

Converts pixel values to rem units:

@function px-to-rem($px, $base-font-size: 16px) {
    @return ($px / $base-font-size) * 1rem;
}

// Usage
.example {
    font-size: px-to-rem(18px); // 1.125rem
    margin: px-to-rem(24px);    // 1.5rem
}

strip-unit.scss

Removes units from values:

@function strip-unit($value) {
    @return ($value / ($value * 0 + 1));
}

// Usage
$width: strip-unit(100px); // 100

boolean.scss

Helper functions for boolean operations:

@function is-true($value) {
    @return $value == true;
}

Mixins

RLH (Responsive Line Heights)

Extends the Bootstrap RFS system with responsive line heights:

@mixin rlh($values, $property: line-height) {
    @if $values != null {
        $val: rfs-value($values);
        $fluidVal: rfs-fluid-value($values);

        @if $val == $fluidVal {
            #{$property}: $val;
        } @else {
            @include _rfs-rule {
                #{$property}: if($rfs-mode == max-media-query, $val, $fluidVal);
                min-width: if($rfs-safari-iframe-resize-bug-fix, (0 * 1vw), null);
            }

            @include _rfs-media-query-rule {
                #{$property}: if($rfs-mode == max-media-query, $fluidVal, $val);
            }
        }
    }
}

// Shorthand
@mixin line-height($value) {
    @include rlh($value);
}

Usage:

h1 {
    @include line-height(1.2); // Responsive line-height
}

.title {
    @include rlh(1.5, line-height); // Explicit property
}

Focus Style

Unified focus styles for accessibility:

@mixin focus-style {
    outline-offset: $focus-outline-offset;
    outline: $focus-outline-color solid $focus-outline-width;
    box-shadow: $focus-outline-box-shadow;
}

Usage:

button:focus-visible {
    @include focus-style;
}

Button Adaptive Hover

Intelligent hover effects for buttons:

@mixin button-adaptive-hover($base-color) {
    &:hover {
        @media (hover: hover) {
            background-color: shade-color($base-color, 15%);
        }
    }
}

Variables

Bootstrap Variables (bootstrap.scss)

Comprehensive Bootstrap configuration with theme integration:

// Colors
$gray-100: $sw-color-gray-100 !default;
$gray-200: $sw-color-gray-200 !default;
// ... more gray tones

// Typography
$font-size-base: $sw-font-size-base !default;
$h1-font-size: $sw-h1-font-size !default;
$h2-font-size: $sw-h2-font-size !default;
// ... more font sizes

// Container
$container-max-widths: (xs: $guppy-container-width-default) !default;
$grid-gutter-width: 1.5rem !default;

// Buttons & Inputs
$btn-font-size: $sw-input-btn-font-size !default;
$btn-border-radius: $sw-input-btn-border-radius !default;
$btn-font-weight: $sw-input-btn-font-weight !default;

Custom Variables (custom.scss)

Guppy-specific variables:

// Icons
$icon-base-size: 22px !default;
$icon-base-color: currentColor !default;
$icon-accessibility-touch-size: 44px !default;

// Typography
$h1-line-height: $sw-h1-line-height !default;
$h2-line-height: $sw-h2-line-height !default;
// ... more line heights

// Product Images
$product-image-height: 240px !default;
$product-image-height-lg: fit-content !default;
$product-image-aspect-ratio: #{10/9} !default;
$product-image-background: $sw-color-product-image !default;

// Accessibility
$focus-outline-width: 2px !default;
$focus-outline-color: $sw-color-brand-primary !default;
$focus-outline-offset: 2px !default;
$focus-outline-box-shadow: 0 0 0 2px #fff;

---

Component System

Product Box (product-box.scss)

Extended product box styles:

.product-box {
    .product-image {
        aspect-ratio: $product-image-aspect-ratio;
        background-color: $product-image-background;

        img {
            object-fit: if($guppy-productcard-image-object-fit == 'cover', cover, contain);
        }
    }

    .product-badges {
        @if $guppy-badges-show-outline {
            .badge {
                border: 1px solid currentColor;
            }
        }
    }
}

Skip Link (skip-link.scss)

Accessible navigation:

.skip-link {
    position: absolute;
    left: -10000px;
    top: auto;
    width: 1px;
    height: 1px;
    overflow: hidden;

    &:focus {
        left: 0;
        z-index: 1010;
        width: auto;
        height: auto;
        padding: 0.5rem 1rem;
        background-color: $sw-color-brand-primary;
        color: white;
        text-decoration: none;
        font-weight: bold;
    }
}

---

Build System

Compilation Order

The theme uses a specific compilation order:

{
  "style": [
    "app/storefront/src/scss/overrides.scss",
    "@StorefrontBootstrap",
    "@Plugins",
    "app/storefront/src/scss/skin/shopware/base.scss",
    "app/storefront/src/scss/base.scss"
  ]
}

Main Entry (base.scss)

Main stylesheet:

// Functions & Mixins
@import "abstract/functions/px-to-rem";
@import "abstract/functions/strip-unit";
@import "abstract/functions/boolean";

@import "abstract/mixins/rlh";
@import "abstract/mixins/focus-style";
@import "abstract/mixins/button-adaptive-hover";

// Base Styles
@import "base/accessibility";
@import "base/base";
@import "base/typography";
@import "base/container";

// Components
@import "components/button";
@import "components/product-box";
@import "components/splide-slider";
// ... more components

// Layout
@import "layout/header";
@import "layout/footer";
@import "layout/navigation";
// ... more layout components

// Elements
@import "elements/skip-link";
@import "elements/splide-slider";

// Pages
@import "page/account/account";
@import "page/checkout/checkout";
@import "page/product-detail/product-detail";
// ... more pages

---

Customization

Child Theme Overrides

In a child theme, you can override specific styles:

// overrides.scss
// Override Guppy variables
$guppy-usp-background-color: #f8f9fa !default;
$product-image-height: 300px !default;

// Override Bootstrap variables
$primary: #007bff !default;
$secondary: #6c757d !default;

// base.scss
// Additional styles
.my-custom-component {
    background-color: $primary;

    .title {
        @include line-height(1.3);
    }
}

Best Practices

Variable Usage

// Good: Use theme variables
.custom-component {
    color: $sw-text-color;
    background-color: $sw-color-gray-100;
}

// Bad: Hardcoded values
.custom-component {
    color: #333;
    background-color: #f9f9f9;
}

Responsive Design

// Good: Use Bootstrap breakpoints
.custom-component {
    @include media-breakpoint-up(md) {
        display: flex;
    }
}

// Bad: Hardcoded breakpoints
.custom-component {
    @media (min-width: 768px) {
        display: flex;
    }
}

Accessibility

// Good: Use focus styles
.custom-button {
    &:focus-visible {
        @include focus-style;
    }
}

// Bad: Custom focus styles
.custom-button {
    &:focus {
        outline: 2px solid blue;
    }
}

---

Responsive Breakpoints

Bootstrap Grid Breakpoints

Guppy uses the standard Bootstrap 5 breakpoints:

Breakpoint	Class Infix	Dimension	Container max-width
Extra small	-	< 576px	100%
Small	sm	≥ 576px	540px
Medium	md	≥ 768px	720px
Large	lg	≥ 992px	960px
Extra large	xl	≥ 1200px	1140px
XXL	xxl	≥ 1400px	1320px

Breakpoint Usage

// Mobile-first: Styles from specific width
@include media-breakpoint-up(md) {
    // Styles for ≥ 768px
}

// Desktop-first: Styles up to specific width
@include media-breakpoint-down(lg) {
    // Styles for < 992px
}

// Range between two breakpoints
@include media-breakpoint-between(md, xl) {
    // Styles for 768px to 1199px
}

// Only for a specific breakpoint
@include media-breakpoint-only(lg) {
    // Styles only for 992px to 1199px
}

Guppy Container Paddings per Breakpoint

// Mobile (< 576px)
$guppy-container-default-padding-x-mobile: 10px;

// Small (≥ 576px)
$guppy-container-default-padding-x-sm: 24px;

// Medium (≥ 768px)
$guppy-container-default-padding-x-md: 48px;

// Large (≥ 992px)
$guppy-container-default-padding-x-lg: 48px;

// Extra Large (≥ 1200px)
$guppy-container-default-padding-x-xl: 48px;

// XXL (≥ 1400px)
$guppy-container-default-padding-x-xxl: 48px;

---

All Available Mixins

Layout Mixins

// Container width
@mixin make-container($padding-x: $container-padding-x) {
    width: 100%;
    padding-right: $padding-x;
    padding-left: $padding-x;
    margin-right: auto;
    margin-left: auto;
}

// Flex centering
@mixin flex-center {
    display: flex;
    align-items: center;
    justify-content: center;
}

Typography Mixins

// Responsive Line Height
@mixin line-height($value) {
    @include rlh($value);
}

// Text ellipsis (single line)
@mixin text-ellipsis {
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
}

// Text clamp (multi-line)
@mixin text-clamp($lines: 2) {
    display: -webkit-box;
    -webkit-line-clamp: $lines;
    -webkit-box-orient: vertical;
    overflow: hidden;
}

Accessibility Mixins

// Focus style (unified)
@mixin focus-style {
    outline-offset: $focus-outline-offset;
    outline: $focus-outline-color solid $focus-outline-width;
    box-shadow: $focus-outline-box-shadow;
}

// Visually hidden (for screen readers)
@mixin visually-hidden {
    position: absolute !important;
    width: 1px !important;
    height: 1px !important;
    padding: 0 !important;
    margin: -1px !important;
    overflow: hidden !important;
    clip: rect(0, 0, 0, 0) !important;
    white-space: nowrap !important;
    border: 0 !important;
}

Button Mixins

// Adaptive hover effect
@mixin button-adaptive-hover($base-color) {
    &:hover {
        @media (hover: hover) {
            background-color: shade-color($base-color, 15%);
        }
    }
}

// Button reset
@mixin button-reset {
    padding: 0;
    border: none;
    background: none;
    cursor: pointer;
    font: inherit;
    color: inherit;
}

---

All Available Functions

Unit Conversion

// Pixel to REM
@function px-to-rem($px, $base-font-size: 16px) {
    @return ($px / $base-font-size) * 1rem;
}

// Usage
.element {
    font-size: px-to-rem(18px);  // 1.125rem
    padding: px-to-rem(24px);     // 1.5rem
}

// Strip unit
@function strip-unit($value) {
    @return ($value / ($value * 0 + 1));
}

// Usage
$value: strip-unit(100px);  // 100

Color Functions

// Lighten/darken color (Bootstrap)
shade-color($color, $weight)   // Make darker
tint-color($color, $weight)    // Make lighter
shift-color($color, $weight)   // Automatic (based on lightness)

// Usage
.element {
    background-color: shade-color($primary, 20%);  // 20% darker
    border-color: tint-color($primary, 40%);       // 40% lighter
}

---

Theme Variables Overview

Color Variables

Variable	Default	Description
$sw-color-brand-primary	#215AFF	Primary color
$sw-color-brand-secondary	#0B1845	Secondary color
$sw-background-color	#FFFFFF	Background
$sw-border-color	#CFD1D7	Border color
$sw-text-color	#1B1F29	Text color
$sw-headline-color	#1B1F29	Headlines

Gray Scale

Variable	Default	Usage
$sw-color-gray-100	#F9F9F9	Backgrounds, footer
$sw-color-gray-200	#EEEEEE	Disabled elements
$sw-color-gray-300	#BCC1C7	Borders, dividers
$sw-color-gray-400	#CED4DA	Input borders
$sw-color-gray-500	#ADB5BD	Placeholders
$sw-color-gray-600	#798490	Secondary text
$sw-color-gray-700	#495057	Text
$sw-color-gray-800	#4A545B	Headlines
$sw-color-gray-900	#212529	Main text

Typography Variables

Variable	Default	Description
$sw-font-size-base	1rem	Base font size
$sw-h1-font-size	32px	H1 size
$sw-h2-font-size	24px	H2 size
$sw-h3-font-size	20px	H3 size
$sw-h4-font-size	18px	H4 size
$sw-h5-font-size	16px	H5 size
$sw-h6-font-size	15px	H6 size
$sw-h1-line-height	44px	H1 line height
$sw-h2-line-height	36px	H2 line height
$sw-h3-line-height	32px	H3 line height

Accessibility Variables

Variable	Default	Description
$focus-outline-width	2px	Focus border width
$focus-outline-color	$sw-color-brand-primary	Focus border color
$focus-outline-offset	2px	Distance from element
$focus-outline-box-shadow	0 0 0 2px #fff	Additional shadow
$icon-accessibility-touch-size	44px	Min touch target

---

Practical Examples

Create Custom Component

// _my-component.scss
.my-component {
    // Base styles with theme variables
    background-color: $sw-color-gray-100;
    border: 1px solid $sw-border-color;
    border-radius: $border-radius;
    padding: $spacer;

    // Responsive Typography
    .title {
        font-size: $sw-h3-font-size;
        @include line-height($h3-line-height);
        color: $sw-headline-color;
    }

    // Responsive Layout
    @include media-breakpoint-up(md) {
        display: flex;
        gap: $spacer * 2;
    }

    // Accessibility
    &:focus-visible {
        @include focus-style;
    }

    // Interactive elements
    .action-button {
        @include button-reset;
        @include button-adaptive-hover($sw-color-brand-primary);
    }
}

Customize Product Card

// overrides.scss (in child theme)
$product-image-aspect-ratio: #{4/3};  // 4:3 instead of 10:9
$product-image-height: 280px;
$guppy-productcard-image-object-fit: cover;

// base.scss (in child theme)
.product-box {
    // Add shadow
    box-shadow: $box-shadow-sm;
    transition: box-shadow 0.3s ease;

    &:hover {
        box-shadow: $box-shadow;
    }

    // Product name styling
    .product-name {
        font-weight: $font-weight-semibold;
        @include text-clamp(2);
    }

    // Highlight price
    .product-price {
        color: $sw-color-brand-primary;
        font-size: $font-size-lg;
    }
}