Skip to content

Site Customization & Theming

A shop's look is set by choosing a platform theme, then adjusting it with the Design Brief, custom CSS, site identity, navigation style and Site Text. Tenants cannot edit or upload templates: every template ships with the platform.

Themes

Pick a theme at Admin → Settings → Theme (/admin/shopSettings/theme), or with MCP manageBranding settheme / listthemes. The change goes live as soon as it is saved. To try a theme, brief or stylesheet on the real shop first, privately, use Preview (MCP manageBranding previewTheme / previewDesignBrief / previewCustomCss, then publishPreview; see Theme and Style Preview). See Choosing a Theme.

Family Themes
Modern (Nova and the themes layered on it) Nova, Brock, Depot, Pop, Atelier, Spec, Ridge, Bistro, Diorama, Tend
Bespoke None shipped; a tenant-authored theme not based on Nova lands here

New sites start on Nova.

Layering. Nova is the root theme. Every other theme (ThemeContext) is an override theme with a base: templates resolve from the theme first, then its base, ending at Nova. Brock, for example, resolves brock → nova and only overrides the storefront templates it changes; Bistro and Tend are layered on Brock (bistro → brock → nova, tend → brock → nova). Emails aren't themed (see Transactional Email). See Theme Resolution.

All themes are responsive; there are no per-device settings.

Design Brief

The Design Brief (admin: Settings → Design brief) is the single screen for a tenant's visual identity. It captures four groups — voice, palette, typography and shape — and compiles them into CSS custom-property overrides that are written to $cssOverride$/theme.css and injected ahead of any hand-edited CSS by GlobalCSSThemeExtension. Editing the brief instantly re-styles the storefront: saving the brief or the custom CSS bumps css-override-version, which is both the stylesheet URL's cache-bust parameter and part of GlobalCSSThemeExtension's model cache key (BadgerExtension#cacheVersion), so the next page view on every node links the new file rather than waiting out the extension's five-minute cache.

Typography. The brief's font family becomes --font-family-base and --font-family-display. Multi-word names are quoted and, unless the brief already ends in a generic family, a matching fallback stack (sans, serif or monospace) is appended, so text never drops to the browser default while the webfont loads. The first family is fetched with a Google Fonts @import (weights 400–700, display=swap) unless it is a system font such as Georgia, Arial or Segoe UI.

Readable brand colours. Bring your brand; the shop stays accessible. The compiler checks every text and background pair the brief controls against WCAG 2.2 AA (a contrast of at least 4.5:1) and, where one fails, derives a readable shade for that use instead of rejecting the colour. The brand colours themselves always stay as fills.

Pair Token When the brief's colour fails
Text on primary, secondary and accent fills (buttons, badges) --color-on-primary, --color-on-secondary, --color-on-accent White if it reads, otherwise near-black #111827, otherwise black. For each, the text must also read on the colour's -dark hover shade; if no single text colour reads on both, the hover shade moves (less dark, or lighter), never the brand colour
The primary as text on the page (links, overlines, tabs, outline buttons) --color-primary-text, --color-primary-text-hover The primary darkened in small steps (lightened on a dark surface) until it reaches 4.5:1 on the surface (white when the brief sets none); the hover shade is a further step and passes too. Always written when the brief has a primary (the primary itself when it already reads), so a theme that sets these tokens to its own literal shade follows the brief
The brand accent on dark sections --color-on-dark-accent The first of secondary, accent and primary that reaches 4.5:1 on --color-dark-surface (or on the brief's surface when that is dark), otherwise the primary lightened until it does
White text on the dark hero gradient --gradient-brand-dark Each stop darkened until white text reaches 4.5:1; a gradient that already carries white text is unchanged
Headings and strong text --color-text-strong The brief's colour moved towards black (or white on a dark surface) until it reaches 4.5:1 on the surface

Each adjustment is reported in plain language, for example: *"Your primary #F5C400 is too light for text on white (1.6:1). Links and brand-coloured text use #8E7200 (4.6:1) instead; buttons keep

F5C400 with dark text."* The design brief page shows a Readability panel under the palette:

each colour as a swatch with the text the storefront puts on it and their contrast, and the list of adjustments, updated as you pick colours (it checks the palette without saving it) and again after saving. Over MCP, getDesignBrief and manageBranding setDesignBrief return the same report as contrast: allTextPassesAA plus the adjustments, each with the token, its role, the colour before and after, what it sits on, both ratios and the reason.

Existing briefs gained these tokens through a one-off recompile of every site's saved brief, so shops with a light primary (yellow, light cyan) now show darker links and dark button text.

Colour schemes

A block on any page can be drawn in one of the brief's colour schemes: a full-width band in the scheme's own background and text, so a page can alternate light, tinted, dark and brand-coloured sections. Pick one in the block's Colour scheme setting (every block edited with the standard block form has it; over MCP it is the block property colourScheme). The setting shows a tile per scheme in the shop's own colours and names; a scheme of the shop's own appears once the brief defines it. A block with no scheme is drawn exactly as before. Blocks that show nothing on the page themselves, such as Google Analytics, Hotjar and the Crisp chat loader, have no Colour scheme setting.

Each scheme has a name and five colours: background, text, links (accent), button background and button text. Every brief has four, which follow the palette until the shop changes a colour:

Scheme Key Derived from the palette
Default default The page's own colours: the surface, strong text, primary buttons
Subtle subtle A light tint of the primary on the surface, the same text and buttons
Inverse inverse The dark section ground with light text and the brand colour that reads on dark (white with dark text when the surface is already dark)
Brand brand A primary fill with the text that reads on it; buttons swap round (that text colour as the fill, the primary as their text)

A shop can add two of its own (custom-1, custom-2); one is in use once it has a background. When the shop picks a scheme's background (its own or a built-in's), the colours it leaves unset are worked out from that background instead: the strong text if it reads there (otherwise white or near-black), the primary as links (shaded until it reads), and primary buttons. The Colour schemes section of the design brief page shows each scheme as a small preview, with a colour picker per colour (the cross puts that colour back on the palette) and a name.

Scheme colours go through the same readability checks as the palette: text and links must reach 4.5:1 on the scheme's background and button text on the button and its hover shade. A colour that doesn't is moved until it does, and the Readability panel says so ("In your Loud colour scheme, the text #FFFFFF is hard to read on #FFE600 (1.2:1). It uses ... instead.").

How it is drawn: the block's wrapper (ui/slot, see Building extensions) gets the class bdgr-scheme-<key>, which turns it into a padded box (--slot-scheme-padding, default --space-12) in the scheme's --color-surface and --color-text-strong. The brief's stylesheet re-declares the colour tokens components read inside that box: --color-surface, --color-text-strong, --color-primary (the button colour), --color-primary-dark, --color-on-primary, --color-primary-text and its hover, and, when the scheme's ground isn't the page's, the grey ramp mixed from the scheme's text into its ground. Primary buttons inside the band follow --scheme-button-*, and links and headings with no class of their own take the scheme's link and text colours (the layered themes colour plain links and headings with their own ink tokens, which the shared ones don't reach). So any block styled with tokens follows its scheme with no template change; one with hard-coded colours (or its own colour setting, such as a hero's split-image colours or a JSON component's style.background) keeps them, inside the band.

A shop with no brief (or a brief with no primary colour) still has the four built-in schemes: Nova's ui-slot.css draws them from the theme's own tokens. The brief's default and subtle schemes are also left to the theme until the brief sets a surface colour or the shop changes them. Saved briefs were recompiled once (2026-11-16-recompile-design-briefs-for-colour-schemes.json) so every shop with a brief has its schemes' rules.

Over MCP, getDesignBrief returns schemes (every scheme with its colours filled in) and manageBranding setDesignBrief takes schemes: [{key, name?, background?, text?, accent?, buttonBackground?, buttonText?}], merged into the shop's schemes by key; a scheme sent with only its key goes back to the palette. The block field appears in extensions getSchema like any other.

Colour tokens for dark surfaces. Besides the palette, the compiler emits --color-on-dark-accent (see above) and, when the brief has a gradient, --gradient-brand-dark (the brand gradient with its stops darkened until white text reaches 4.5:1). The dark hero presets and the dark / gradient-dark / mesh-dark section backgrounds use them, so a brief alone restyles heroes, overlines and buttons on dark sections. The hero presets take every colour from the tokens (--gradient-brand-dark, --color-primary, --color-secondary, --color-surface); none is hard-coded.

The Shape language group controls:

Setting Drives Options
Corners --radius-* tokens Sharp, Soft (default), Pillowy
Shadow depth --shadow-* tokens Flat, Subtle (default), Deep
Product image shape --product-image-ratio token Square 1:1 (default), Portrait 3:4, Tall portrait 2:3, Landscape 4:3

Product image shape lets a retailer whose photography suits a taller or wider crop (e.g. fashion) switch the whole store away from the default square. The --product-image-ratio token is applied to product cards (collection, listing and search grids) and the product-page main gallery. Cards crop with object-fit: cover, so the grid stays perfectly aligned at any ratio; gallery thumbnails deliberately stay square. The setting only emits an override for non-square shapes — leaving it on Square keeps Nova's built-in 1 / 1 default, so existing stores are unaffected.

The brief can be filled in by hand, drafted through the page's AI chat (see AI Integration), or set by an agent with MCP manageBranding setdesignbrief.

Custom CSS

Admin → Settings → CSS editor (/admin/shopSettings/css-editor) is a code editor for the site's own stylesheet, saved by CustomCssService to $cssOverride$/global.css and served from /dynamic/css/…. GlobalCSSThemeExtension links the Design Brief's theme.css first and global.css after it, so hand-written CSS wins. Agents can set it with MCP manageBranding setCustomCss (up to 100,000 characters). Saving bumps css-override-version, so the change shows on the next page view.

Class names changed in October 2026. When the Brock-family themes' header, footer, mini basket, menus, listing toolbar, facet rail, pager and buttons became shared components, their classes were renamed (brock-footer__base is now nova-sitefooter__base, depot-btn--pri is nova-button--buy, and so on). A one-off update rewrote every site's stored stylesheet to the new names, and setCustomCss renames old names in CSS an agent sends, saying which in its response (customCss.notes). The admin CSS editor saves what you type, so use the current names there; the list is in the components guide. Selectors that match a JSON component by its inline style ([style*="shadow"]) need the json-component-inline-styles setting (see JSON components).

Old content that needs jQuery or Bootstrap's JavaScript

Since November 2026 the storefront themes don't load jQuery or Bootstrap's JavaScript bundle: the menus, mobile menu, mini basket, tooltips and basket popover work with plain browser features (<details>, <dialog>, popover), and pages start faster without the two render-blocking scripts. Bootstrap's stylesheet still loads, so Bootstrap classes in content look as they did.

Content a shop wrote itself can still depend on the scripts: an HTML block or page body with data-bs-toggle (a dropdown, tooltip, collapsing panel or pop-up window that opens on click), or a custom script that calls $(...) or jQuery. On such a site those parts stop responding. The fix is to rewrite them: a <details> element for a panel that opens and closes, a <dialog> for a pop-up, plain document.querySelector and fetch for scripts.

Until then, turn on Load jQuery and Bootstrap Scripts (storefront-legacy-scripts: Admin → Settings → Store and storefront → Storefront, or MCP manageSiteConfig). Every page of that site then loads both scripts in the <head>, as before, so inline scripts that call $(...) while the page loads keep working. Off by default, and it only affects the site that turns it on. StorefrontLegacyScriptsInterceptor puts legacyStorefrontScripts on the page model and Nova's fragment/legacy-scripts, included by every theme's head, loads the scripts.

Site identity and navigation

  • Site identity (/admin/shopSettings/site-identity, MCP manageBranding setidentity): site name, logo (picked from the media library), default locale, time zone (MCP timeZone; see Settings) and social account URLs.
  • Navigation style (on the theme page): fixed or static navbar (Nova), hide the site name next to the logo (also MCP manageBranding setidentity showSiteName:false; turn it on for a wordmark logo, as phones now show the name beside the logo too), sticky footer. Each theme shows only the options it supports. Header and footer designs come with the theme; there is no choice of styles.
  • Shop icon (favicon): chosen on Settings › Site identity from the media gallery (shop-icon-url), or with MCP manageBranding setIdentity iconUrl. ShopIconService sizes it on the image CDN: 64 × 64 for the browser-tab favicon, 180 × 180 for the home-screen icon. The older favIconPath / appleTouchIconPath keys (a file each, named by address) still win while set, and choosing an icon clears them; favIconOverride (raw <link> HTML) replaces the links altogether. All four are listed under Settings › Store. Browsers that ask for /favicon.ico or /apple-touch-icon.png directly are redirected to the same icons (the platform favicon, or a 404 for the touch icon, when there is none); these answers are cached for a day.
  • Custom domains: /admin/shopSettings/custom-domain. The shop owner types the address they are adding, and the page shows the exact records for it (updated as they type, each with a copy button): a CNAME from that host name to custom-domain.bdgr.co.uk (the Cloudflare fallback origin; override with the global config customDomainCnameTarget), which must be DNS only, and a TXT record _badger-verify.<that exact host name> holding the shop's badger-verify=<token> value, which proves the domain is theirs (CustomDomainVerificationService; the token is the site-bound custom-domain-verification-token). The record is per host name: www.example.com and example.com each need their own. On Cloudflare a proxied (orange cloud) CNAME gives visitors error 1014 "CNAME Cross-User Banned", and the page says so. A collapsible note covers sending the bare domain to www (on Cloudflare: a proxied A record to the placeholder 192.0.2.1 plus a 301 Redirect Rule; elsewhere: the host's URL forwarding). Check DNS looks both records up without adding anything (CustomDomainVerificationService.check, a CustomDomainDnsCheck) and says which TXT name it looked up and whether it was missing or held a different value (TXT records are public, so the values found are shown), and whether the CNAME points here, elsewhere, or can't be seen (not added yet, proxied by Cloudflare, or a flattened or ALIAS record on a bare domain). A refused add shows the same check. A domain without that TXT record, or one another shop already has, is refused. The owner adds it as a secondary domain or as the primary one; making an existing secondary domain primary needs no new proof, and each domain in the list has its own Check DNS. Any hostname reaches the shop and the tenant is resolved from the Host header, but the HTTPS certificate comes from Cloudflare, which only issues one once the hostname is registered under Custom Hostnames. That registration is manual for now: adding a domain posts a Slack alert naming the site and domain, and records the domain in the site's SSL_PENDING_DOMAINS context property (CustomDomainCertificates), so the owner's list shows it as "Being set up" and System → SSL certificates shows the shop as "Waiting" with the domains that need a Custom Hostname. Once it is active, a superadmin presses Mark as protected there, which sets the shop's SSL_ENABLED property and clears the waiting list (the domains then show "Secure"). The page's "What happens next" section tells the owner that this last step is done by Badger and can take a little while.

Site Text and the announcement bar

Admin → Settings → Site text (/admin/shopSettings/text) overrides any storefront message per locale, including email wording.

The announcement bar above the navigation, a call-to-action button in the header and a tagline are Admin → Settings → Storefront settings, which every theme reads (StorefrontChromeInterceptor puts them on each page):

Setting Key Notes
Show Announcement Band storefront-announcement-enabled On by default; off hides the bar whatever its message
Announcement storefront-announcement HTML allowed. When empty, the older Site Text nav.banner.message is used, so sites that set the bar that way keep it. Every theme hides the bar while there is no message
Header Button Text / Link storefront-header-cta-label, storefront-header-cta-url Shown in Nova's, Ridge's, Diorama's and Brock's header when both are set; the link must be a site path or an http(s), mailto: or tel: link
Header Link Text / Address storefront-header-link-label, storefront-header-link-url A quieter text link beside the button (e.g. Sign in), set on its own or with the button. Shown in Brock's header, the same links allowed
Tagline storefront-tagline Shown by themes that show one with the site name (Ridge)

There is one bar, with no scheduling.

A shop in more than one language

A site has one language (its locale, which also picks the storefront's built-in wording: messages_es for es_ES, and so on) and one set of products and pages. A shop in two languages is two sites, one per language, with the same products, prices and page addresses (the same seoNames), written in each language.

Language Sites (storefront-language-sites, Admin → Settings → Storefront) links them: one locale=address per line, this site included, e.g.

es_ES=https://lacamiseta.example
en_GB=https://en.lacamiseta.example

With two or more valid lines, every theme's header shows a flag menu (the current language's flag and code; each language named in itself, "Español", "English") that opens the page the shopper is on at the other site, and the head lists the sites as hreflang alternates. A line whose address isn't an absolute http(s) link is ignored. Flags are drawn for Spain, the UK, the US, Ireland, France, Italy, Belgium, Germany, the Netherlands and Portugal; other countries show their emoji flag. LanguageSitesInterceptor puts the menu on each page (languageSites, currentLanguage). The menu sits with the header's account and basket buttons, so it shows at every width, and it shows on a site that sells nothing too. Its text is the header.language.menu and header.language.title Site Text. The La Camiseta demo is the example.

Page layouts

Content pages pick a template on the page's edit screen: Standard, Empty Page, 9 by 3 (a right-hand rightSection slot) or 3 by 9 (a left-hand leftSection slot). Not every theme ships every layout (Brock has 9 by 3 only). Collections take an optional template name. Product, collection and search pages have one layout per theme, which you fill with extensions in its slots; see Extension System. Reusable slot layouts are stereotypes.

Content blocks that carry the brand on Modern themes:

  • Hero extension: presets centered, split image, video background, gradient, minimal and background effect (none, constellation, flow field, grid glow).
  • jsonComponent sections, with dark / gradient-dark / mesh-dark backgrounds driven by the brief's tokens; see JSON Components.
  • Nova and its family use cross-document view transitions and scroll reveal; these are not configurable.

Error pages

Create a CMS page with seoName 4xx or 5xx and the platform renders it for client or server errors, using the page's template. Without one, the built-in error/4xx.html / 5xx.html page is shown: a card with the shop's logo, a short explanation and a link home (the 500 page adds Try again), styled by the shop's theme stylesheet, in the shopper's language (error.page.* message keys, editable in Site text). An address that isn't connected to any shop shows error/shopNotFound.html, which is Badger's and loads nothing from the address itself.

Emails

Transactional email templates are fixed, but their branding is configurable under Admin → Settings → Orders and email → Email branding: logo URL, primary, secondary, accent and background colours, font family and footer text, with a test send. Subject lines are site config patterns (for example orderConfirmationSubjectPattern), and body wording follows Site Text. See Transactional Email.

Moving a design between sites

There is no standalone theme export. Site Data Transfer carries the theme choice, Design Brief, custom CSS and Site Text along with the rest of the site.

Not built

No theme or mobile preview before publishing, no tenant-editable or uploadable templates, no PDF invoices or packing slips (packing details go out by email), no per-element font choice and no branded loading animations.