Each Stencil theme’s
assets/ directory contains the files and subdirectories that you can view on the Cornerstone GitHub Repository (opens in a new tab).
In parts of your theme's directory tree where you are free to add new subdirectories and files, be sure to:
- Set newly added directories to permission
- Set newly added files to permission
- Without these permissions, running your theme locally will fail, with multiple error messages. Bundling your theme will also fail, blocking its upload to a store.
Cornerstone assets directory
To avoid unexpected 404 errors on your production store, we recommend that you use short relative paths in your SCSS to reference images in your
|cornerstone/assets/scss||The /scss/ subdirectory contains theme-specific CSS resources.|
The nested subdirectory for your chosen framework contains a file that includes that framework’s variables. For example, in the default Stencil theme, this file is: /settings/foundation/_foundation.scss.
Within each subdirectory nested at the ultimate level is one primary file,
Every utility in this subdirectory will have both a class and a mixin. For example, consider the utility truncatedText: You can use it by applying the class
|cornerstone/assets/scss/components||The components subdirectory contains the 4 following subdirectories: |
|cornerstone/assets/scss/components/citadel||Read about the Citadel directory below.|
|cornerstone/assets/scss/components/foundation||The /components/vendor/ subdirectory contains the consumed version of framework components from your chosen provider. There is some renaming of these components to match Stencil naming conventions.|
|cornerstone/assets/scss/components/stencil||Read about the stencil directory below.|
|cornerstone/assets/scss/components/vendor||The /components/vendor/ subdirectory contains the consumed version of framework components from your chosen provider. There is some renaming of these components to match Stencil naming conventions.|
Stencil themes include an internal pattern library called Citadel, which consumes the ZURB Foundation framework. Foundation provides the basis for creating responsive themes. Citadel extends the Foundation framework’s mixins and components to provide Stencil’s own mixins, extensible components, and utilities. The designstyle language underlying these Citadel resources is the Sass/SCSS preprocessor. Citadel resources are named according to BEM and SUIT CSS conventions. Classes are named functionally, rather than based on visual presentation or content. Citadel is based specifically on Foundation 5.5.3, which installs with the Stencil framework. We do not support Foundation 6.x, due to breaking changes introduced between versions 5.x and 6.x.
Citadel design patterns reside in
cornerstone/assets/scss/components/. Citadel assets bundled with Cornerstone are located in the following subdirectories:
components/citadel subdirectory contains Citadel-specific resources. The resources are named according to our style guide, which follows BEM and SUIT CSS naming conventions. Class names are structured, and hyphens are meaningful (that is, hyphens are not used merely to separate words). Here are some prototypes and examples:
|Citadel Component Name Design Pattern||Class Name Example|
|componentName||.dropdown or .buttonGroup|
|componentName--modifierName||.dropdown--dropUp or .button--primary|
Components vs utilities
Our naming scheme makes an architectural distinction between components and utilities. Components are defined as custom elements that enclose specific semantics, styling, and behavior. Component names are in camel case. Our syntax for naming them is as follows:
|Component Name Design Pattern||Component Name Example|
Utility classes are defined as low-level, structural and positional traits. Utilities can be applied directly to any element. Multiple utilities can be used together, and utilities can be used alongside component classes.
To make HTML patterns as reusable as possible, we have used utility classes sparingly, reserving them for component-level styling.
Our syntax for naming utilities is camel case, prefixed with a u- namespace:
|Utility Name Design Pattern||Class Name Example|
Variables and mixins
Citadel variables and mixins follow similar naming conventions.
Variables are things that can change over time. Their names are in camel case, and show context.
|Variable Name Design Pattern||Variable Name Example|
|Mixin Name Design Pattern||Mixin Name Example|
|Mixins follow regular camel-case naming conventions. Namespacing is not universally required for mixins. However, where a mixin has been created for a utility, its name matches the utility’s name, including u- namespacing||@mixin buttonVariant; @mixin u-textTruncate;|
/components/stencil/ subdirectory contains CSS files unique to Stencil themes, which are used to create specific page elements within the themes. You can view this subdirectory and all its children in the Cornerstone Theme GitHub Repository.
This subdirectory’s children contain CSS for the following page elements.
|account||Customer account details|
|addressBox||Customer shipping addresses|
|addReturn||Add a product-return request|
|banners||Banners displayed across storefront’s top and bottom|
|blocker||Position .blocker element above another element, to prevent a user action|
|compare||Layout for product-comparison table|
|facetedSearch||Faceted-search toggle (on/off), navigation list, and filters|
|facetLabel||Labels for faceted-search display|
|heroCarousel||Carousel of prominent (“hero”) images|
|navPages||Styles for page navigation, with responsive layout|
|navUser||Styles for cart counter, quick search|
|productCarousel||Carousel of product images|
|productReviews||Styles for product reviews|
|productView||Product display (with thumbnails suppressed for mobile/tablet), product details, product options (size, color, etc.), product sharing|
|quickView||Quick-view modal window for a selected product|
|ribbon||Top-right text badges, for messages like “On sale”|
|socialLinks||Styles for social-media links|
|tags||Styles for blog-post tags|
|toggleLink||Styles for collapsible/expandable components|
|writeReview||Styles for product-review submission form|
- Cornerstone GitHub Repository (opens in a new tab) (BigCommerce GitHub)
- Getting Started With Foundation 5 (opens in a new tab) (Zurb)
- BEM (opens in a new tab) (Get BEM)
- SUIT CSS (opens in a new tab) (GitHub)
- Customizing a Theme (Assets Directory) (opens in a new tab) (YouTube)
- BigCommerce Sass Styling Guide (opens in a new tab) (BigCommerce GitHub)