Magento 2: Theme Starter Best Practices

Intro:

Theming in Magento 2 is a powerfully customizable tool, and a crucial component of creating and maintaining a consistent brand aesthetic. However, with this freedom can come great complexity. Building a solid foundation of theming best-practices early on will save your developers time and frustration, create a frictionless brand experience for customers, and position you for years of success after launch. This article will primarily cover the best practices of setting up your first custom theme on Magento 2. 

Magento 2 is a highly customizable and configurable eCommerce platform. This flexibility comes with some serious complexity, and as they say: with great power comes great responsibility. Theming in Magento 2 provides ample flexibility for developers, but there are some tried and true best practices when setting up. Getting started off in the right direction and building a solid foundation will position you for a predictable front end build and years of successful maintenance and enhancement after launch.

Set Up Magento for Theming

When you’re working on theme development for Magento, have it set in developer mode. You’ll also want to have the Full Page cache and Block HTML cache turned off, and possibly the Layout cache as well (depending on how often you are making layout changes). I would recommend leaving the other caches on to speed up page loading. If your development system has Varnish enabled and you are running into caching issues when viewing the frontend, you may have to disable that as well.

If this is your first time doing any theme work on this installation of Magento, set up Grunt for it. Copy Gruntfile.js.sample to Gruntfile.js and package.json.sample to package.json. You can now run npm install to install all the dependencies for Grunt to run. Finally, copy grunt-config.json.sample to grunt-config.json and copy dev/tools/grunt/configs/themes.js to dev/tools/grunt/configs/local-themes.js to allow for adding custom themes.

Create a New Theme

Create a folder for your new theme at app/design/frontend/<Vendor>/<themename>. Following Magento conventions, the vendor should be capitalized (with camel case for multiple words, if necessary) and the theme name itself should be lowercase.

The two required files to create a new theme are theme.xml and registration.php. Copy these from an existing theme, and then change the relevant values. In registration.php, change the path parameter to the folder you created for your new theme. In theme.xml, change the title and parent nodes. The theme title is used internally in the admin configuration. See the next section for advice on choosing a parent theme.

Inside dev/tools/grunt/configs/local-themes.js you’ll want to select the entry for your new theme’s parent and copy it, and then change the main identifier and the name to the appropriate values for your new theme. The identifier here isn’t used for anything other than executing Grunt commands.

Once these basic theme files are set up, you can select the theme from the admin to apply it to the site. 

Which Parent Theme to Use

While you can certainly create a new theme entirely from scratch, it makes the most sense to use one of Magento’s native themes as the parent for your new theme, and Magento’s theme documentation is based on the assumption that you’ve done this.

Magento comes with two themes: Blank and Luma. Blank is intended to provide a neutral framework for you to build your customizations. Luma is the theme that you see in Magento marketing materials and demo sites; it has more opinionated styling than Blank does and is itself based on the Blank theme.

We would suggest that you use Blank as your parent theme unless you have a very specific reason to be using Luma (e.g., you are working with a design that looks like a variation of Luma). The Blank theme was intended for this purpose, and if you try to use Luma you will end up having to “undo” a lot of its custom styling to apply your own instead. Even if you’re working with a design that borrows certain elements of the Luma theme, you’re better off using Blank and just copying those specific elements out of the Luma theme into your custom theme.

Where to Begin

Now that you have a new, empty theme set up on your site, how should you get started modifying it for your needs? It may be tempting to jump right in with, say, writing new CSS for the header, but that’s not the best approach. We recommend starting with setting up as many global variables as you can.

Magento’s default themes have an underlying design / CSS framework controlled by variables - called the Magento UI library - similar in nature to popular frameworks like Bootstrap. There are hundreds of variables and it is possible to substantially change the look and feel of the site using these alone. This approach will mean that you’ll have less CSS to write overall, and the styles will be more consistent throughout the site.

Magento’s dedicated file for variable overrides is _theme.less, located at app/design/frontend/<Vendor>/<themename>/web/css/source/_theme.less. This is where all your variables should be set (or the files with your variables should be included in if you’re splitting them up into multiple files for better organization, which we recommend). Note that if you create this file in your theme, you’re overriding the file from the parent theme, so make sure to incorporate that file’s contents (preferably as a separate import) if the parent theme has this file. Blank doesn’t have a _theme.less, but Luma does.

Most of the variables that you’ll be modifying are from the Magento UI Library and are located at lib/web/css/source/lib/variables. Once you have tweaked as much of the site’s look and feel as possible via _theme.less, you are ready to move on and start adding/modifying other files in the theme as needed. Even as you progress through the theme, it is always best to check and see if the change you are planning to make can be accomplished by setting a variable.

Completing the Theme

Now that you have a foundation of best practices for building your first theme, the real work can begin. These best practices will allow you to focus on what’s most important: creating a storefront that deeply connects with your customer, and encourages them to convert. We know that creating your theme is only the first step in a major process. If you find yourself looking for more information, Magento’s own frontend developer guide is a great place to start. They also have coding standards for JavaScript, CSS/LESS, and HTML, as well as a separate JavaScript developer guide.