Theme Assets

Each Stencil theme’s assets/ directory contains CSS, JavaScript, and image assets that help create the design of storefront pages. A minimal 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 755 (drwxr-xr-x).
  • Set newly added files to permission 644 (rw-r--r--).
  • 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

  • Directory: assets/
File PathDescription
assets/fontsThe fonts/ subdirectory contains local versions of theme-specific fonts.
cornerstone/assets/iconsThe icons/ subdirectory contains .svg files for icons used within a theme.
cornerstone/assets/imgThe /img/ subdirectory contains images used in the theme’s display – background images, sprites, and other images not related to store content. You would typically reference these image assets using Stencil's cdn Handlebars helper. For example, generically: <img src="{{cdn 'assets/img/image.jpg'}}"> Or, with a realistic file name: <img src="{{cdn 'assets/img/size-chart.png'}}">.

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 /img/ subdirectory. So, for example, use references of the form background: url('../img/header-bg.png'); rather than references of the form: background: url('/assets/img/header-bg.png');
cornerstone/assets/jsThe /js/ subdirectory contains general JavaScript files used in the theme.
cornerstone/assets/scssThe /scss/ subdirectory contains theme-specific CSS resources.
cornerstone/assets/layouts/The <theme-name>/assets/scss/layouts/ subdirectory contains .scss files that provide default styling for major layout components of theme pages. You can see the /layouts/ subdirectory’s internal structure on the Cornerstone GitHub Repository.
cornerstone/assets/settings/The <theme-name>/assets/scss/settings/ subdirectory contains SCSS variables for your framework. Files here map directly to components. If present, these variables override defaults in consumed libraries. The /settings/ subdirectory’s internal structure can be viewed at the Cornerstone GitHub Repository.

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, _settings.scss, that imports all other variables that have been broken into logical files, such as _colors.scss, _typography.scss, and _z-index.scss.
cornerstone/assets/utilities/The <theme-name>/assets/scss/utilities subdirectory contains mixins and tools, beyond the Citadel library, that help create UI’s. You can apply these CSS snippets to your HTML for quick prototyping when you need a unique, yet repeatable, style.

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 .u-truncatedText, or by applying the mixin @include u-truncatedText;.
cornerstone/assets/scss/componentsThe components subdirectory contains the 4 following subdirectories:
cornerstone/assets/scss/components/citadelRead about the Citadel directory below.
cornerstone/assets/scss/components/foundationThe /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/stencilRead about the stencil directory below.
cornerstone/assets/scss/components/vendorThe /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.

Citadel subdirectory

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:

  • cornerstone/assets/scss/settings/citadel/
  • cornerstone/assets/scss/components/citadel/

The 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 PatternClass 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 PatternComponent 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 PatternClass 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 PatternVariable Name Example
Mixin Name Design PatternMixin 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;

Stencil subdirectory

The /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.

SubdirectoryUI Element/Purpose
accountCustomer account details
addressBoxCustomer shipping addresses
addReturnAdd a product-return request
bannersBanners displayed across storefront’s top and bottom
blockerPosition .blocker element above another element, to prevent a user action
compareLayout for product-comparison table
facetedSearchFaceted-search toggle (on/off), navigation list, and filters
facetLabelLabels for faceted-search display
heroCarouselCarousel of prominent (“hero”) images
navPagesStyles for page navigation, with responsive layout
navUserStyles for cart counter, quick search
productCarouselCarousel of product images
productReviewsStyles for product reviews
productViewProduct display (with thumbnails suppressed for mobile/tablet), product details, product options (size, color, etc.), product sharing
quickViewQuick-view modal window for a selected product
ribbonTop-right text badges, for messages like “On sale”
socialLinksStyles for social-media links
tagsStyles for blog-post tags
toggleLinkStyles for collapsible/expandable components
writeReviewStyles for product-review submission form


Sample apps

Additonal resources

Did you find what you were looking for?