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, extend the default styles instead of overriding them. 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>.
    • add/remove a block or container by setting the remove attribute to true or false, or the display attribute to true or false within the <referenceBlock>/<referenceContainer> instruction.
    • change the HTML tag or CSS class for the existing container using <referenceContainer> element.
    • add fonts, images, and JavaScript files in the <theme_dir>/web/ directory.

    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 updating or upgrading Magento instances, there may be changes to default templates, layouts, and styles. So it is recommended to check if those changes affect any files overridden in your theme and if so, copy the changes to your templates, layouts, and styles.