Customising with a child theme

For developers

Brand colours, extra fonts and project-specific styling belong in a child theme that inherits from Base Theme. You keep receiving Base Theme updates, and your changes survive them. Never edit the Base Theme files in vendor/ or custom/plugins/.

The theme is built for this: every visual decision flows from one token layer, so a child theme changes a few variables instead of restyling components.

Shopware mechanics, not a Base Theme API

Child themes, theme.json inheritance and configInheritance are standard Shopware features — see Theme inheritance. The examples below follow Base Theme's file layout; they are not part of the theme's own test suite, so check the result in light and dark mode.

1. Create the child theme

bin/console theme:create MyShopTheme

Edit src/Resources/theme.json of the new theme:

{
  "name": "MyShopTheme",
  "author": "My agency",
  "views": ["@Storefront", "@Plugins", "@KmhBaseTheme", "@MyShopTheme"],
  "style": [
    "app/storefront/src/scss/overrides.scss",
    "@KmhBaseTheme",
    "app/storefront/src/scss/base.scss"
  ],
  "script": ["@KmhBaseTheme"],
  "asset": ["@KmhBaseTheme", "app/storefront/src/assets"],
  "configInheritance": ["@KmhBaseTheme"]
}

• @KmhBaseTheme in style expands to Base Theme's overrides.scss, @Storefront (with all plugins) and base.scss — so your overrides.scss runs before everything and your base.scss after everything.
• configInheritance makes the child theme inherit Base Theme's settings (layout, components, logos …) in the theme manager.
• Remove script entries for a main.js you do not use; Base Theme ships no JavaScript bundle.

Install, activate and assign it:

bin/console plugin:refresh
bin/console plugin:install --activate MyShopTheme
bin/console theme:change --all MyShopTheme

2. Change the palette (compile time)

All palette variables in Base Theme's abstract/_palette.scss are !default. Set them in your overrides.scss and Base Theme picks up your values everywhere — Bootstrap variables, CSS tokens and components:

// MyShopTheme/src/Resources/app/storefront/src/scss/overrides.scss

// Primary action (buttons, buy button, checked controls, selected state)
$color-action:        #0042a0;
$color-action-hover:  #00367f;
$color-action-active: #002b66;
$color-action-text:   #ffffff;
$color-selected:      #0042a0;
$color-focus-ring:    #0042a0;

// Neutral scale — $mono-0 (white) … $mono-1000 (black), e.g. a warmer grey
$mono-50:  #f7f6f4;
$mono-100: #eeece8;

Useful variables: $mono-0 … $mono-1000, $color-text-primary/-secondary/-muted, $color-bg-base/-subtle/-muted, $color-surface, $color-border(-subtle/-strong/-input), $color-action*, $color-disabled-*, $color-focus-ring, $color-selected(-bg), $color-success/-warning/-danger/-info and their -text, -bg, -border shades, $color-rating-empty. Keep text at 4.5:1 and form borders at 3:1 contrast.

3. Adjust dark mode

Dark mode re-values the CSS tokens under [data-theme='dark'] with fixed colours, so compile-time variables do not reach it. Override the tokens in your base.scss:

// MyShopTheme/src/Resources/app/storefront/src/scss/base.scss

[data-theme='dark'] {
    --color-action:        #7aa7ff;
    --color-action-hover:  #9bbcff;
    --color-action-active: #b5ceff;
    --color-action-text:   #000000;
    --color-selected:      #7aa7ff;
    --color-focus-ring:    #7aa7ff;
}

Order matters for runtime overrides

:root and [data-theme='dark'] have the same specificity and both match <html> in dark mode. If you also override tokens on :root in base.scss, put your [data-theme='dark'] block after it — otherwise your light values win in dark mode too.

Prefer compile-time variables for light mode: a few Bootstrap utilities use the SCSS values directly, which a :root override does not reach.

4. Fonts

Base Theme uses the Inter font that Shopware already self-hosts. For another font, self-host it in the child theme — no third-party CDN:

1. Put the file in MyShopTheme/src/Resources/app/storefront/src/assets/fonts/.

2. Declare it in your base.scss:

   @font-face {
       font-family: 'Brand Sans';
       font-style: normal;
       font-weight: 100 900;
       font-display: swap;
       src: url('#{$sw-asset-theme-url}/bundles/myshoptheme/assets/fonts/brand-sans.woff2') format('woff2');
   }

3. In Content → Themes → MyShopTheme → Typography set Base font and/or Headline font to 'Brand Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif.

Asset URLs follow Shopware's theme assets guide.

5. Restyle a component

Use the tokens instead of fixed values, so your rules follow dark mode and the radius setting automatically:

.my-promo-banner {
    padding: var(--space-6);
    background: var(--color-bg-subtle);
    border: 1px solid var(--color-border);
    border-radius: var(--radius-lg);
    color: var(--color-text-primary);
    box-shadow: var(--shadow-sm);
}

Token reference: Architecture & tokens → Design tokens.

6. Override templates

Extend Base Theme's templates like any other — sw_extends resolves through the views order. Keep parent() in the blocks Base Theme uses (see Template overrides), especially layout_header_actions_account (dark-mode button) and layout_head_stylesheet / base_body_script (dark-mode scripts).

{# MyShopTheme/src/Resources/views/storefront/layout/footer/footer.html.twig #}
{% sw_extends '@Storefront/storefront/layout/footer/footer.html.twig' %}

{% block layout_footer_brand %}
    {{ parent() }}
    <p class="text-muted">Since 1998</p>
{% endblock %}

7. Compile and check

bin/console theme:compile
bin/console cache:clear

Check key pages in light and dark mode, on desktop and phone. The Playwright suite from the Base Theme repository runs against any storefront: E2E_BASE_URL=https://staging.example.com npx playwright test — see Tests.