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, MCPmanageBranding setidentity): site name, logo (picked from the media library), default locale, time zone (MCPtimeZone; 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 MCPmanageBranding setIdentity iconUrl.ShopIconServicesizes it on the image CDN: 64 × 64 for the browser-tab favicon, 180 × 180 for the home-screen icon. The olderfavIconPath/appleTouchIconPathkeys (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.icoor/apple-touch-icon.pngdirectly 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 tocustom-domain.bdgr.co.uk(the Cloudflare fallback origin; override with the global configcustomDomainCnameTarget), which must be DNS only, and a TXT record_badger-verify.<that exact host name>holding the shop'sbadger-verify=<token>value, which proves the domain is theirs (CustomDomainVerificationService; the token is the site-boundcustom-domain-verification-token). The record is per host name:www.example.comandexample.comeach 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 placeholder192.0.2.1plus a 301 Redirect Rule; elsewhere: the host's URL forwarding). Check DNS looks both records up without adding anything (CustomDomainVerificationService.check, aCustomDomainDnsCheck) 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 theHostheader, 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'sSSL_PENDING_DOMAINScontext 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'sSSL_ENABLEDproperty 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.
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-darkbackgrounds 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.