Structure and contents of a storefront theme

A theme is composed of CSS, Javascript, HTML, components, and graphics files. When working on files, you must store them in the appropriate subfolders within the main theme folder.

Certain files are required as the minimum for any theme. After you have created them, you can add other files to expand the theme.

The Storefront Toolkit supports a setup command that creates a file structure with a sample theme. You can use this as the basis for your own theme. See the base theme overview video for a tour of this file structure.

Top-level folders

There are four top-level folders in a theme, each of which may contain several subfolders for different types of files:

• /Assets Contains subfolders for CSS files, fonts, images, and JavaScript files.
• /Content Contains subfolders for layouts (page layouts that you can extend), macros (components), and pages (storefront pages, such as Home, Listing, and others).
• /Header-footer Contains HTML templates and CSS files specific to the header and footer.
• /Translations Contains YAML localization files for mapping translated text to items on the pages.

If you have enabled custom component creation, your theme may also include the following top-level folders:

• /customComponents Contains subfolders for custom components.

• /node_modules Contains subfolders for Storybook documentation. This folder also contains all the npm libraries that you can install (that is, the @appdirect/sfb-theme-components library).

All the files in your theme should either be saved to the main theme folder, or to a subfolder within one of these top-level folders.

Required files

There are certain files that the marketplace requires as the minimum in any theme in order to present the storefront correctly. These include the following files:

• The theme-index.css file in themes/themeName/assets/css/theme/
• The global-index.css file in themes/themeName/assets/css/platform-global/
• The home.html file in themes/themeName/content/pages/home/
• The listing.html file in themes/themeName/content/pages/listing/
• The profile.html file in themes/themeName/content/pages/profile/
• The header-index.css file in themes/themeName/header-footer/css
• The design-properties.json file in themes/themeName/

These files appear in both base themes (classic and Plaza).

The CSS files are generated automatically from the SASS files (see below) when you start the Storefront Toolkit with the theme. The other files are created along with the theme.

important

When you want to modify a theme, make changes in the SASS files. Do not make changes directly in the CSS files, as they are overwritten when the toolkit is activated or when the theme is packaged for export.

Required stylesheets

There are three main cascading style sheet (CSS) files available that you can use to style your theme.

provides SASS support with the developer tool, which can make a stylesheet easy to read and update. SASS offers features such as functions, variables, and imports. The SASS files are automatically compiled each time the style sheet is updated when the developer tool is running, or each time the theme is packaged.

The following three main SASS files are required:

• The header-index.scss file (in themes/themeName/header-footer/css)---This file provides completely encapsulated CSS for the header and footer.
• The theme-index.scss file (in themes/themeName/assets/css/theme/)---This is the main theme stylesheet.
• The global-index.scss file (in themes/themeName/assets/css/platform-global/)---This CSS overrides the administration pages (MyApps page and Dashboard). Note that this file does not affect the storefront display.

These files appear in both base themes (classic and Plaza).

When you want to modify a theme, you make changes in these SASS files. These changes are then written to the corresponding CSS files when the toolkit is activated, or when the theme is packaged for export.

Page objects

The marketplace supports a number of page objects that you can add to your storefront pages to represent variable content, such as the overview text for a product or its starting price. For a list of the page objects available for the different pages in a theme, see Use page objects and its related subtopics.

While working with the Toolkit, you can use the Data Viewer feature of the developer toolbar to import real data (see Use AppDirect data), and then use the data to populate these objects for your storefront display. This feature provides a better idea of what your storefront will look like in production.

Now that you know the required folders, files, and CSS for your themes, see Create the Home page to start building a theme for your storefront.