Magento theme structure

What's in this topic

A design theme is an important part of the Magento application. This topic describes the file structure of a Magento theme.

Magento theme location

Storefront themes are conventionally located under app/design/frontend/<Vendor>/. Though technically they can reside in other directories. For example Magento built-in themes can be located under vendor/magento/theme-frontend-<theme_code> when a Magento instance is deployed from the Composer repository.

Each theme must be stored in a separate directory:

app/design/frontend/<Vendor>/
├── <theme1>
├── <theme2>/
├── <theme3>
├--...

Theme components

The structure of a Magento theme directory typically would be like following:

<theme_dir>/
├── <Vendor>_<Module>/ 
│	├── web/
│	│	├── css/
│	│	│	├── source/
│	├── layout/
│	│	├── override/
│	├── templates/
├── etc/
├── i18n/ 
├── media/
├── web/
│	├── css/
│	│	├── source/ 
│	├── fonts/
│	├── images/
│	├── js/
├── composer.json 
├── registration.php 
├── theme.xml 

Let’s have a closer look at each particular sub-directory.

Directory	Required	Description
/<Vendor>_<Module>	optional	Module-specific styles, layouts, and templates.
/<Vendor>_<Module>/web/css/source	optional	Module-specific styles (.css and/or .less files). General styles for the module are in the _module.less file, and styles for widgets are in _widgets.less.
/<Vendor>_<Module>/layout	optional	Layout files which extend the default module or parent theme layouts.
/<Vendor>_<Module>/layout/override/base	optional	Layouts that override the default module layouts.
/<Vendor>_<Module>/layout/override/<parent_theme>	optional	Layouts that override the parent theme layouts for the module.
/<Vendor>_<Module>/templates	optional	This directory contains theme templates which override the default module templates or parent theme templates for this module. Custom templates are also stored in this directory.
/etc/view.xml	required for a theme, but optional if exists in the parent theme	This file contains images configuration for all storefront product images and thumbnails.
/i18n	optional	.csv files with translations.
/media	required	This directory contains a theme preview (a screenshot of your theme).
/web	optional	Static files that can be loaded directly from the frontend.
/web/css/source	optional	This directory contains theme less configuration files that invoke mixins for global elements from the Magento UI library, and theme.less file which overrides the default variables values.
/web/css/source/lib	optional	View files that override the UI library files stored in lib/web/css/source/lib
/web/fonts	optional	Theme fonts.
/web/images	optional	Images that are used in this theme.
/web/js	optional	Theme JavaScript files.
/composer.json	optional	Describes the theme dependencies and some meta-information. Will be here if your theme is a Composer package.
/registration.php	required	Required to register your theme in the system.
/theme.xml	required	The file is mandatory as it declares a theme as a system component. It contains the basic meta-information, like the theme name and the parent theme name, if the theme is inherited from an existing theme. The file is used by the Magento system to recognize the theme.

Theme files

Apart from the configuration file and theme metadata file, all theme files fall into the following two categories:

• Static view files
• Dynamic view files

Static view files

A set of theme files that are returned by the server to a browser as is, without any processing, are called the static files of a theme.

Static files can be located in a theme directory as follows:

<theme_dir>/
├── media/
├── web
│	├── css/ (except the "source" sub-directory)
│	├── fonts/
│	├── images/
│	├── js/

The key difference between static files and other theme files is that static files appear on a web page as references to the files, while other theme files take part in the page generation, but are not explicitly referenced on a web page as files.

Static view files that can be accessed by a direct link from the store front, are distinguished as public theme files.

Dynamic view files

View files that are processed or executed by the server in order to provide result to the client. These are: .less files, templates, and layouts.

Dynamic view files are located in a theme directory as follows:

<theme_dir>/
├── Magento_<module>/ 
│	├── web/
│	│	├── css/
│	│	│	├── source/
│	├── layout/
│	│	├── override/
│	├── templates/
├── web/
│	├── css/
│	│	├── source/