Theme Architecture Deep Dive

Theme Directory Structure

Magento 2 themes reside in app/design/frontend/:

app/design/frontend/
└── Vendor/
    └── ThemeName/
        ├── theme.xml
        ├── registration.php
        ├── web/
        │   ├── css/
        │   │   └── source/
        │   │       └── _extend.less
        │   ├── js/
        │   │   └── custom.js
        │   ├── images/
        │   │   └── logo.svg
        │   └── fonts/
        │       └── custom-font.woff2
        ├── Magento_Catalog/
        │   └── templates/
        │       └── product/
        │           └── list.phtml
        ├── media/
        │   └── preview.jpg
        └── i18n/
            ├── en_US.csv
            └── fr_FR.csv

Vendor/Theme Naming

• Vendor: Your company or namespace (e.g., Amazon, Google)
• Theme: Theme name (e.g., Prep, Storefront)
• Combined: Amazon_Prep
• Directory: app/design/frontend/Amazon/Prep/

Key Files

Basic theme.xml

<?xml version="1.0"?>
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/theme.xsd">
    <title>Amazon Prep Theme</title>
    <parent>Magento/luma</parent>
    <media>
        <preview_image>media/preview.jpg</preview_image>
    </media>
</theme>

theme.xml Elements

Without Parent (Standalone Theme)

<?xml version="1.0"?>
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/theme.xsd">
    <title>Custom Standalone Theme</title>
</theme>

With Custom Layout

<?xml version="1.0"?>
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/theme.xsd">
    <title>Amazon Prep Theme</title>
    <parent>Magento/blank</parent>
    <layout>1column</layout>
</theme>

The <layout> element sets the default layout for all pages using this theme.

Basic registration.php

<?php

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/Amazon/Prep',
    __DIR__
);

How It Works

1. Magento scans app/design/frontend/*/ for registration.php files
2. Each file registers the theme in the component registry
3. Theme becomes available in admin under Content → Design → Themes
4. Theme ID format: frontend/Vendor/Theme

Registration After Theme Creation

After creating theme.xml and registration.php:

# Register the theme
bin/magento setup:upgrade

# Verify registration
bin/magento theme:list

Unregistering a Theme

// In registration.php, just delete the theme directory
// Then run:
bin/magento setup:upgrade
bin/magento cache:clean

Multiple Themes

Each theme has its own registration:

app/design/frontend/Amazon/Prep/
├── registration.php  (frontend/Amazon/Prep)

app/design/frontend/Amazon/PrepKids/
└── registration.php  (frontend/Amazon/PrepKids)

How Fallback Works

Magento uses a fallback chain to resolve files:

Custom Theme → Parent Theme → Blank Theme → Magento Core

Visual Fallback Chain

Amazon/Prep (custom)
    ↓ fallback
Magento/luma
    ↓ fallback
Magento/blank
    ↓ fallback
Magento/core (base)

File Resolution Example

When loading Magento_Catalog::product/list.phtml:

1. Check: app/design/frontend/Amazon/Prep/Magento_Catalog/templates/product/list.phtml
2. Check: app/design/frontend/Magento/luma/Magento_Catalog/templates/product/list.phtml
3. Check: app/design/frontend/Magento/blank/Magento_Catalog/templates/product/list.phtml
4. Use: vendor/magento/module-catalog/view/frontend/templates/product/list.phtml

Static Asset Fallback

For CSS/JS/images:

1. pub/static/frontend/Amazon/Prep/en_US/css/source/_extend.less
2. pub/static/frontend/Magento/luma/en_US/css/source/_extend.less
3. pub/static/frontend/Magento/blank/en_US/css/source/_extend.less
4. vendor/magento/theme-frontend-blank/web/css/source/_extend.less

Fallback Configuration

# Check current theme
bin/magento dev:theme:list

# View fallback chain
bin/magento dev:theme:show-fallback Amazon/Prep

Important Notes

• Fallback only works for files, not for entire templates
• Your theme files override parent theme files
• Static files are published to pub/static/ during deployment