Theme development best practices

This topic describes the recommended approaches and things to consider when working on a custom theme.

These approaches give higher chances to avoid conflicts and issues with your theme after your Magento instance get updated or upgraded, or a custom extension is installed.

Theme development best practice

1. When inheriting from a default Magento theme, rather extend, than override the default styles: whenever possible, put your customizations in the _extend.less or _theme.less file, instead of overriding a .less file from a parent theme.

2. Customize or create new .xml layout files instead of customizing and overriding .phtml templates. For example, if you need to create a new container, it is better to add an .xml file and create it there, than override a template. Some other customizations that can be performed using layout instructions are the following:

   • change the position of a block or container using <move>
   • remove a block or container using the remove or display attribute of the <referenceBlock>/<referenceContainer> instruction
   • reorder blocks and container using the before/afterattributes of the <referenceBlock>/<referenceContainer> instruction
   • change the HTML tag or CSS class for the existing container using <referenceContainer> element

   For details about working with layouts see the Layout chapter of this Guide.

3. Reuse the markup and design patterns from the default Magento files by referencing the existing .phtml templates (templates hints can help) or copy-pasting HTML markup to your custom templates.

4. Use <theme_dir>/etc/view.xml to change image types sizes or add your own types. See Configure images properties for details. Use this file also to customize product gallery widget
5. If you need to change the wording in user interface, add custom CSV dictionary files instead of overriding .phtml templates.

Keep in mind, that after Magento instances, updates or upgrades something can change in default templates, layouts, and styles. So it is recommended to check if the changes affected the files overridden in your theme and copy changes if any, to your templates, layouts, and styles.