BigCommerce Stencil integration
The production target. shop.usaclean.com runs on a Stencil theme (forked from Cornerstone). This guide walks through wiring Caster tokens into the theme's SCSS pipeline so existing Stencil partials can consume them, then replacing component CSS over time.
my-theme/assets/scss/. If you're on an older Stencil or a custom theme, the file paths differ but the import mechanics are the same.
1 · Drop Caster files into the theme
Vendor the built outputs into your theme repo. Don't reference them from a remote URL — Stencil bundles SCSS at build time and needs local files.
my-theme/
├── assets/
│ └── scss/
│ ├── caster/ ← create this folder
│ │ ├── _tokens.scss ← from design-system/tokens/tokens.scss
│ │ └── _components.scss ← from design-system/components/components.css
│ │ (rename .css → .scss; add `@use` if needed)
│ └── theme.scss ← Stencil's main entry
├── stencil.conf.js
└── ...tokens.scss (not tokens.css) so existing Stencil $variable-based partials can consume Caster as Sass variables. The CSS variant is also available if you want CSS custom properties at the top of theme.scss for runtime theming.
2 · Wire it into theme.scss
Stencil's theme.scss compiles top-down. Caster tokens must come before any partial that references them.
// my-theme/assets/scss/theme.scss
// 1. Caster — TOKENS FIRST
@import "caster/tokens"; // defines $caster-* SCSS variables AND --caster-* CSS custom properties
// 2. (Optional) Caster components, if migrating en-masse
@import "caster/components"; // .btn, .pill, .product-card, etc.
// 3. Existing Stencil theme partials
@import "tools/tools";
@import "settings/settings";
// ...etc3 · Map existing theme variables to Caster tokens
Cornerstone-derived themes have hundreds of $color-*, $spacing-* variables. The cleanest migration: redefine those variables to reference Caster tokens, so all existing partials gain Caster values without rewrite.
// my-theme/assets/scss/settings/_settings.scss
// (or wherever the theme defines its color palette)
// BEFORE:
// $color-primary: #3B5998;
// $color-secondary: #f4f4f4;
// $color-success: #5cb85c;
// AFTER — bridge existing names to Caster:
$color-primary: $caster-color-brand-default;
$color-secondary: $caster-color-surface-subtle;
$color-success: $caster-color-feedback-success-default;
$color-error: $caster-color-feedback-error-default;
$color-text: $caster-color-text-default;
$fontSize-base: $caster-font-size-sm; // 16px body
$spacing-base: $caster-spacing-4; // 16px
// ...do this for the full theme palette in one sitting.After this single-file change, every existing Stencil partial that uses $color-primary now renders in Caster brand-blue. No template changes needed.
4 · Replace component CSS gradually
Stencil ships with its own .button, .productView, .card, etc. classes. Replace them on a per-component basis as you touch each template.
Per-component migration pattern
{{!-- my-theme/templates/components/products/card.html (Handlebars) --}}
{{!-- BEFORE — Stencil's built-in product-card --}}
<article class="card" data-event-type="product-click">
<figure class="card-figure">
<a href="{{url}}" class="card-figure__link">...</a>
</figure>
<div class="card-body">
<h4 class="card-title">{{name}}</h4>
<div class="card-text--price">{{price.without_tax.formatted}}</div>
</div>
</article>
{{!-- AFTER — Caster product-card --}}
<div class="product-card" data-event-type="product-click">
<a href="{{url}}" class="product-card__image">
<img src="{{getImage image 'productview_thumb_size'}}" alt="{{name}}">
</a>
<div class="product-card__body">
<div class="product-card__sku">SKU · {{sku}}</div>
<a href="{{url}}" class="product-card__name">{{name}}</a>
<div class="product-card__footer">
<div class="product-card__price">{{price.without_tax.formatted}}</div>
{{#if inventory.is_low_stock}}
<span class="stock-badge stock-low">Low</span>
{{else}}
<span class="stock-badge stock-in">In stock</span>
{{/if}}
</div>
</div>
</div>5 · Keeping the theme in sync with Caster updates
When Caster releases a new version (token tweak, new component), pull the rebuilt outputs into the theme. Three options:
Option A — Manual copy (simplest, lowest overhead)
Copy tokens.scss and components.css from the design-system repo into the theme repo when there's a new version. Commit both changes together. Fine for low-frequency updates.
Option B — Git submodule
Add the design-system repo as a submodule of the theme. Theme references caster-submodule/tokens/tokens.scss directly. Updates are git submodule update --remote.
Option C — npm package (heaviest, but unlocks versioning)
Publish the design-system as an internal npm package; theme depends on a pinned version. Best for multi-team setups. Out of scope for v0.4 but the build pipeline already supports it (the package.json just needs a publish config).
Stencil-specific gotchas
stencil push fails with "missing variable"
Caster tokens haven't been imported before the partial that uses them. Move @import "caster/tokens"; to the top of theme.scss.
Theme editor "color picker" controls overwrite Caster colors
BC's theme editor injects user-selected colors as inline styles or top-of-file variables, which can override Caster tokens. Either remove the picker controls from config.json, or accept the overrides and let merchants brand their store on top of Caster.
Hawksearch / app widgets bring their own CSS
Apps like Hawksearch inject styles late in the page. The --caster-* namespace prevents collisions on tokens, but apps' component CSS (e.g. their own .button) can still conflict. Scope your overrides via specific parent selectors when needed: .hawk-results .btn { ... }.
Critical CSS / above-the-fold optimization
Stencil supports critical-CSS extraction. Keep token definitions in the critical bundle (they're tiny, ~10kb, and everything else needs them). Defer the components CSS only if the page doesn't render any Caster components above the fold.
Migration checklist
Phased rollout. Each step is independently shippable.
- ✅ Phase 1 — drop
caster/_tokens.scssinto the theme, import intheme.scss. No visual change yet. - ⬜ Phase 2 — bridge existing theme color/typography variables to Caster tokens in
_settings.scss. Visual change: brand colors, type scale unify across the site. - ⬜ Phase 3 — replace high-traffic components (PLP card, PDP price, header, footer) with Caster classes. Per-template effort.
- ⬜ Phase 4 — replace remaining components opportunistically as templates get touched.
- ⬜ Phase 5 — delete legacy theme component CSS that's no longer referenced.