4.04

Theme Structure

Describe theme locations, registration, folder structure, overrides, and required files for Composer/local themes.

Why This Matters: Understanding Magento theme structure is key to placing assets in the right place, leveraging theme inheritance (fallback), and registering themes correctly for upgrade-safe UI work.

Theme Structure Overview

mindmap root((Theme Structure)) Location app/design (local) vendor (Composer) Registration composer.json autoload.files registration.php theme.xml Folders etc (view.xml) i18n (translations) media (preview) web (assets) css / css/source fonts images js Overrides Module overrides in theme Fallback (inheritance)

Theme Locations

  • Local themes are stored in app/design.
  • Composer-based themes can be stored anywhere; by default are installed under vendor/.
  • Magento uses the Composer autoloader; themes can auto-register via Composer configuration.

How a Theme Registers

Composer executes files listed in autoload.files on bootstrap. For themes like Luma, this points to registration.php, which registers the theme with Magento.

  • composer.json (e.g., Magento/luma/composer.json): declares autoload.files → registration.php
  • registration.php (required): calls \Magento\Framework\Component\ComponentRegistrar::register() to register the theme
  • Component name format: adminhtml|frontend/Package/Theme
    Examples:
    • frontend/Bonlineco/Custom
    • frontend/Magento/luma
    • adminhtml/Magento/backend

Required Theme Files

  • theme.xml (required): Describes the theme; supports <title>, optional <parent>, and optional <media/preview_image>.
  • registration.php (required): Registers the theme with Magento.
  • composer.json (for Composer themes): Helps Composer install and autoload the theme.

Theme Folder Structure

Common folders inside a theme:

  • etc/ — Typically contains view.xml (e.g., Magento/luma/etc/view.xml) for theme configuration values (images, UI component settings, etc.).
  • i18n/ — Translations (e.g., Magento/luma/i18n/en_US.csv).
  • media/ — Usually has preview.jpg (Magento/luma/media/preview.jpg) for admin preview.
  • web/ — Public assets compiled to pub/static.
    • css/ — Base stylesheets exported to pub/static/[area]/[package]/[theme]/[locale]/css.
    • css/source/ — LESS sources; mixins and theme.less to override default variables.
    • fonts/ — Web fonts used by the theme.
    • images/ — Static theme images (e.g., icons), not frequently changing banners.
    • js/ — Theme-specific JavaScript.
Compilation Flow: LESS → var/view_preprocessed → compiled CSS → pub/static.
Recommendation: Prefer placing customizations in the appropriate Module_Name/web directory for functionality (e.g., checkout changes under Magento_Checkout/web) rather than at the root of the theme’s web/, unless it’s design-wide.

Module Overrides from a Theme

Themes can override module assets (templates, layout, etc.) by mirroring the module path under the theme directory.

app/design/frontend/Bonlineco/Custom/Magento_Catalog/templates/product/view/addtocart.phtml

This path overrides Magento/Catalog/view/frontend/templates/product/view/addtocart.phtml.

Further Reading

Exam Tips

  • Locations: Local: app/design; Composer: usually vendor/.
  • Registration: composer.json → autoload.files → registration.php → theme registered.
  • Required files: theme.xml, registration.php (Composer theme also has composer.json).
  • Key folders: etc/view.xml, i18n/*.csv, media/preview.jpg, web/css, web/css/source, web/images, web/fonts, web/js.
  • Overrides: Mirror module paths in the theme to override assets; rely on fallback.
Previous: 4.03 Modify Page Style Back to Overview