Creating an Magento 2 child theme

Magento 2 has significant changes to the directory and file structure for themes.

Magento 2 - folder structure

Creating the theme directory

  • app/design/frontend
  • /vendor-name/
  • /package/
  • app/design/frontend/crewd/dark/

Declaring the theme

Create a file named theme.xml, this should contain the theme name and the parent theme if applicable, the theme preview image can also be specified here.

You can copy the theme.xml from another theme folder or create your own

<theme xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
     <title>crewd - dark</title>
title your theme’s name
parant the parent theme if applicable
media > preview_image the path to the theme’s preview image

Optional – Making your theme a Composer package

If you plan to distribute the theme using a composer package will make it easier for people to install the custom theme, you can specify any required packages in which composer can install / update for the user to ensure the theme installs correctly.

create app/design/frontend/crewd/dark/composer.json

    "name": "magento/theme-frontend-custom-default",
    "description": "N/A",
    "require": {
        "php": "~5.5.0|~5.6.0|~7.0.0",
        "magento/theme-frontend-luma": "100.0.*",
        "magento/framework": "100.0.*"
    "type": "magento2-theme",
    "version": "100.0.2",
    "license": [
    "autoload": {
        "files": [

Registering the theme

To register the theme, we need to create a registration.php file within the package folder: app/design/frontend/crewd/dark/

This file should contain


Configuring images

Image sizes within the storefront are configured within the view.xml file. This file is required for a theme, but is optional if the theme has a parent theme which contains the view.xml configuration file.

This should be located within a folder named etc within your package folder: app/design/frontend/crewd/dark/etc/

You can copy this file from the default Magento blank/luma theme, when you look at the file contents you can see all the various elements that can be changed for your theme. If you have any specific image sizes in mind you can then change them in this file.

Static files

Within your theme you will highly likely use multiple static files (fonts, javascript, stylesheets and images). These should be stored in separate folders within a web folder.

  • app/design/frontend/crewd/dark/web/
  • /css
  • /fonts
  • /images
  • /js

Theme logo

In Magento 2 the default format and name of the theme logo is logo.svg. Which if found within the /web/images directory it will automatically recognized as the theme logo.

If you want the logo to either be located elsewhere or named differently you need to declare it within the default.xml file.


<page xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
        <referenceBlock name="logo">
                <argument name="logo_file" xsi:type="string">images/crewd-logo.png</argument>
                <argument name="logo_img_width" xsi:type="number">300</argument> 
                <argument name="logo_img_height" xsi:type="number">100</argument>
Magento 2 - folder structure

Theme files

Theme files fall into two categories these are:

Static view files

These are sent from the server to the user’s browser without any processing, these files should be located within

  • app/design/frontend/crewd/dark/
  • /media
  • /web
  • /css
  • /fonts
  • /images
  • /js

Dynamic view files

These files are processed by the server before being sent to the user’s browser, these files should be located within

  • app/design/frontend/crewd/dark/
  • /Magento_<module>
  • /web
  • /layout
  • /templates
  • /web
  • /css
  • /source

Applying the theme

Once the files and folders have been uploaded, you can apply the theme

Magento 2 - Themes section
  1. Go to Content > Design > Themes – Make sure that your theme appears within the theme list
  2. Go to Stores > Configuration > Design
  3. Click on the Design Theme tab, select the theme within the dropdown list
  4. Click Save Config
Magento 2 - Configuration section

Cache Management

Magento 2 - Cache management

Whilst working on a theme, it’s best to disable the system cache – System > Tools > Cache Management. Select LayoutsBlocks HTML output and Page Cache types and in actions set to disable.

Magento 2 - Store front