Cornerstone Theme Overview

Relevant source files

• CHANGELOG.md
• assets/js/app.js
• assets/scss/checkout.scss
• assets/scss/optimized-checkout.scss
• assets/scss/theme.scss
• config.json
• package-lock.json
• package.json
• schema.json
• schemaTranslations.json
• templates/components/common/header.html
• templates/layout/base.html
• webpack.common.js

Purpose and Scope

This document introduces the BigCommerce Cornerstone theme, its role within the Stencil platform, core architectural concepts, and key technologies. It serves as the starting point for understanding how Cornerstone is structured and how its various systems work together to create a complete e-commerce storefront.

For detailed information about specific subsystems:

• Configuration and theming: see Configuration and Settings System
• Build pipeline and asset management: see Build System and Asset Pipeline
• Template rendering: see Frontend Rendering and Bootstrap
• Styling architecture: see SCSS Architecture and Styling
• JavaScript patterns: see JavaScript Module Architecture

What is Cornerstone

Cornerstone is the reference theme for BigCommerce's Stencil platform. It provides a fully-featured, production-ready storefront implementation that demonstrates best practices for building themes on the Stencil framework. Merchants can use Cornerstone directly or customize it to match their brand, while developers can use it as a foundation for building custom themes.

The theme is distributed as open-source software under the MIT license and is actively maintained by BigCommerce.

Sources: config.json1-10 package.json1-7 CHANGELOG.md1-6

Version and Metadata

Property	Value
Current Version	6.18.0
Template Engine	handlebars_v4
CSS Compiler	scss
License	MIT
Repository	https://github.com/bigcommerce/cornerstone

Sources: config.json2-4 config.json38 package.json4 package.json7

Key Features

Cornerstone includes extensive e-commerce functionality out of the box:

Customer-Facing Features

• Fully responsive design for mobile, tablet, and desktop
• Mega navigation with multi-tiered menu support
• Product filtering with faceted search capabilities
• Quick view and quick add to cart functionality
• Advanced product options including swatches and variant selection
• Product comparison table
• Wishlist management
• Product reviews and ratings
• Image zoom on product pages
• Homepage carousel with multiple slides
• Blog integration

Technical Features

• Persistent cart across sessions
• Customizable checkout styling
• CSRF protection
• Enhanced e-commerce analytics support
• Payment methods management (v2)
• Multi-language support (14 languages via schemaTranslations.json)
• Theme variations (Light, Bold, Warm)
• Lazy loading with LQIP (Low Quality Image Placeholders)

Sources: config.json12-36 config.json423-710

Architecture Overview

Cornerstone Theme Architecture - Configuration to Runtime

The architecture follows a clear separation of concerns across five layers:

1. Configuration Layer: Merchant-customizable settings that control appearance and behavior
2. Build System: Transforms source code into optimized bundles
3. Source Assets: Development files organized by type (JS, SCSS, templates)
4. Compiled Output: Production-ready assets served to browsers
5. Runtime Initialization: Bootstrap process that initializes the storefront

Sources: config.json1-710 webpack.common.js1-89 templates/layout/base.html1-97 assets/js/app.js1-99

Technology Stack

Core Dependencies

Cornerstone Dependency Graph

Key Libraries and Their Roles

Library	Version	Purpose	Usage Context
jquery	3.6.1	DOM manipulation foundation	Used throughout all client-side code
@bigcommerce/stencil-utils	6.19.0	API wrapper for Stencil platform	All server communication (cart, products, etc)
slick-carousel	1.8.1	Carousel functionality	Homepage hero, product image galleries
nod-validate	2.0.12	Form validation	Account forms, checkout, contact forms
lazysizes	5.2.2	Image lazy loading	Product images, homepage content
foundation-sites	5.5.3	Grid system and utilities	Layout structure throughout theme
@bigcommerce/citadel	2.15.1	BigCommerce UI framework	Component styling and patterns
easyzoom	2.5.3	Product image zoom	Product detail pages
focus-trap	6.3.0	Accessibility for modals	Modal dialogs, mobile menu
jstree	3.3.12	Tree navigation	Category filtering UI

Sources: package.json8-27 package.json29-68

Build System

The build process uses Webpack 5 with Babel transpilation:

• Entry Points: main (app.js), head_async (lazysizes), font (web fonts), polyfills
• Babel Configuration: ES6+ to ES5 with loose mode, tree-shaking enabled
• Output Bundles: theme-bundle.main.js, theme-bundle.head_async.js, theme-bundle.font.js
• Code Splitting: Dynamic imports for page-specific modules
• Optimization: Lodash tree-shaking, jQuery exposed globally

Sources: webpack.common.js12-18 webpack.common.js19-50 webpack.common.js61-77

File Structure Overview

cornerstone/
├── assets/
│   ├── js/
│   │   ├── app.js                          # Bootstrap entry point
│   │   ├── polyfills.js                    # Browser polyfills
│   │   └── theme/
│   │       ├── global.js                   # Global functionality
│   │       ├── account.js                  # Account pages
│   │       ├── auth.js                     # Login/registration
│   │       ├── cart.js                     # Cart page
│   │       ├── product.js                  # Product detail page
│   │       ├── category.js                 # Category/brand pages
│   │       └── common/                     # Shared utilities
│   ├── scss/
│   │   ├── theme.scss                      # Main stylesheet entry
│   │   ├── optimized-checkout.scss         # Checkout styling
│   │   ├── components/                     # Component styles
│   │   ├── layouts/                        # Layout styles
│   │   └── settings/                       # SCSS variables
│   └── dist/                               # Compiled output (generated)
├── templates/
│   ├── layout/
│   │   └── base.html                       # Master template
│   ├── components/
│   │   ├── common/
│   │   │   ├── header.html                 # Site header
│   │   │   ├── footer.html                 # Site footer
│   │   │   └── navigation-menu.html        # Navigation
│   │   └── products/                       # Product components
│   └── pages/                              # Page templates
├── config.json                             # Theme settings
├── schema.json                             # Theme Editor UI definitions
├── schemaTranslations.json                 # Localization for settings
├── package.json                            # Node dependencies
├── webpack.common.js                       # Webpack configuration
└── lang/                                   # Language files (14 languages)

Sources: assets/js/app.js1-99 assets/scss/theme.scss1-80 templates/layout/base.html1-97 config.json1-10

Template Engine and Rendering

Template Rendering and Client-Side Bootstrap Flow

The rendering process uses Handlebars v4 on the server side with the {{~inject}} helper to pass data to the client:

These injected values become available to JavaScript via context object in stencilBootstrap().

Sources: templates/layout/base.html37-50 templates/layout/base.html62-83 config.json4

JavaScript Module System

Cornerstone uses a dynamic import pattern for code splitting:

This pattern ensures only the JavaScript needed for the current page is loaded.

Sources: assets/js/app.js9-53 assets/js/app.js64-98

SCSS Architecture

Cornerstone uses an ITCSS (Inverted Triangle CSS) methodology with Citadel and Foundation frameworks:

Settings    → Variables, configuration
Tools       → Mixins, functions
Generic     → Normalize, resets
Elements    → Base element styles
Objects     → Layout patterns
Components  → UI components
Utilities   → Helper classes

The main SCSS entry point imports in order:

1. Citadel toolkit - Mixins and functions
2. Settings - Global variables and theme settings
3. Foundation framework - Grid system
4. Utilities - Helper classes
5. Components - UI components
6. Layouts - Page layouts

Theming Functions

Cornerstone provides special functions to access theme settings:

• stencilColor("setting-name") - Access color settings from config.json
• stencilFontFamily("setting-name") - Access font family settings
• stencilFontWeight("setting-name") - Access font weight settings
• stencilString("setting-name") - Access string settings
• stencilImage("setting-name", "size-name") - Access image settings

Example usage in assets/scss/optimized-checkout.scss19-29:

Sources: assets/scss/theme.scss1-80 assets/scss/optimized-checkout.scss1-382

Theme Variations

Cornerstone includes three pre-configured variations that demonstrate different styling approaches:

Variation	Industry Focus	Color Scheme	Key Differences
Light (default)	Home & Garden	Light neutrals	Clean, minimal aesthetic
Bold	Fashion & Jewelry	Dark with coral accents	High contrast, modern
Warm	Food & Beverage	Earth tones	Warm, inviting colors

Each variation overrides specific settings in config.json:

• Font families (body and headings)
• Color palettes (text, buttons, backgrounds)
• Component styling (carousel, cards, forms)
• Optimized checkout appearance

Variations are defined in config.json423-710 with metadata including:

• name - Variation display name
• id - Unique identifier
• demo_url - Live demo URL
• industries - Target industry tags
• settings - Overridden configuration values

Sources: config.json423-710 config.json45-68

Configuration System

The theme configuration system consists of three interconnected files:

config.json

Contains ~400 settings organized into:

• Metadata: Theme name, version, features
• Settings: All customizable values (colors, fonts, dimensions, behavior toggles)
• Variations: Pre-configured theme styles
• Resources: API resource limits
• Read-only files: Protected framework files

schema.json

Defines the Theme Editor UI that merchants see in the BigCommerce control panel. Each setting includes:

• type - Input type (color, font, select, checkbox, etc.)
• id - Matches key in config.json
• label - Internationalized via i18n. prefix
• options - Available choices for select/font inputs
• force_reload - Whether changing requires page reload

schemaTranslations.json

Provides translations for all Theme Editor labels in 14 languages:

• English (default)
• French (fr), Italian (it), Chinese (zh), German (de), Spanish (es)
• Dutch (nl), Portuguese (pt, pt-BR), Swedish (sv)
• Spanish regional (es-MX, es-419), Danish (da), Norwegian (no)
• Korean (ko), Polish (pl), Japanese (ja)

Sources: config.json1-710 schema.json1-100 schemaTranslations.json1-100

Next Steps

For developers starting with Cornerstone:

1. Understand the build system: See Build System and Asset Pipeline
2. Learn template structure: See Frontend Rendering and Bootstrap
3. Explore styling patterns: See SCSS Architecture and Styling
4. Study JavaScript architecture: See JavaScript Module Architecture
5. Customize theme settings: See Configuration and Settings System
6. Work with specific features:
   • Product display: Product System
   • Shopping cart: Shopping Cart
   • Customer accounts: Customer Account
   • UI components: UI Components and Features

For customization guidance, see the Developer Guide section.

Sources: CHANGELOG.md1-100 package.json1-80