Site Customization & Theming¶

BadgerCommerce provides comprehensive tools for customizing the look, feel, and behavior of your storefront to match your brand identity precisely.

Key Features¶

Theme System¶

• Responsive Themes: All themes are fully responsive for mobile, tablet, and desktop
• Theme Library: Selection of pre-built themes to start with
• Theme Customization: Easily modify existing themes to match your brand
• Theme Inheritance: Build on existing themes with selective overrides
• Theme Switching: Test and preview different themes before publishing

Visual Customization¶

• Brand Colors: Define primary and secondary color palettes
• Typography: Select and customize fonts for different text elements
• Spacing System: Consistent spacing throughout the site
• Component Styling: Customize the appearance of buttons, forms, and other UI elements
• Product Image Shape: Choose the aspect ratio for product imagery (square, portrait, tall portrait, landscape)
• Custom CSS: Apply advanced styling when needed

Design Brief¶

The Design Brief (admin: Shop 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.

Colour tokens for dark surfaces. Besides the palette, the compiler emits --color-on-dark-accent (the first of secondary, accent and primary light enough to read on a dark background, else a lightened primary) and, when the brief has a gradient, --gradient-brand-dark (the brand gradient with its stops darkened until white text is legible). 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:

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.

Layout Control¶

• Page Layouts: Define different layouts for different page types
• Header & Footer Customization: Multiple header and footer styles
• Sidebar Configuration: Optional sidebars with configurable content
• Grid System: Responsive grid for organizing page content
• Adaptive Layouts: Layouts that change based on device and screen size

Custom Templates¶

• Template Overrides: Override specific templates for customization
• Custom Page Templates: Create specialized templates for specific content
• Email Templates: Customize transactional email templates
• PDF Templates: Design custom invoice and packing slip templates
• Template Variables: Dynamic content insertion in templates

Global Elements¶

• Logo Management: Upload and position your brand logo
• Favicon: Custom browser favicon
• Loading Animations: Branded loading states
• 404 Pages: Customizable error pages
• Site-wide Banners: Announcement bars and promotional messages

Technical Implementation¶

The customization system is built using:

• Theme-based architecture with inheritance
• Template override capability
• CSS variable system for consistent styling
• Responsive design principles
• Component-based UI structure

Key components include: - GlobalCSSThemeExtension: Manages global styling - Template hierarchy with fallback mechanism - Site-specific resource repository - Media management for brand assets - Extension system for UI component customization

Integration Points¶

The customization system integrates with: - Extension System: For component-level customization - Content Management: For layout and content placement - Media Library: For brand assets and visuals - Multi-tenant System: For site-specific theming - Preview System: For testing changes before publishing

Administration¶

Site customization can be managed through: - Theme selection and customization interface - Visual style editor - Template management system - Brand asset manager - Layout configuration tools - Mobile preview and testing tools

Upcoming Features¶

• Enhanced theme builder with more customization options
• Improved mobile-specific customizations
• Theme export and import capabilities
• More pre-built themes and templates
• Advanced layout building tools