In chapter 3 we already briefly saw a theme's two core files. Now let's look at the full directory structure a Hyvä child theme grows into over time, and what each file actually does.

The mandatory theme files

• registration.php - registers the theme with Magento's ComponentRegistrar. Without this file, Magento doesn't even know the theme exists.
• theme.xml - contains the title, parent theme, and preview image. The <parent> value is the most important part here.
• composer.json - turns the theme into its own Composer package, including a dependency on the Hyvä parent theme.

view.xml: image sizes and gallery configuration

etc/view.xml defines things like image sizes (product images, gallery thumbnails) and configuration for the image optimizer. Hyvä themes already ship sensible defaults - custom adjustments (e.g. different image widths for the new team page we'll build later) go into the child theme's view.xml.

app/design/frontend/Mironsoft/default/
├── registration.php
├── theme.xml
├── composer.json
├── etc/
│   └── view.xml
├── Magento_Theme/
│   ├── layout/
│   │   └── default.xml
│   └── templates/
│       └── html/
│           └── header.phtml
├── Magento_Catalog/
│   └── templates/
│       └── product/
│           └── list.phtml
└── web/
    ├── tailwind/
    │   ├── tailwind.config.js
    │   ├── package.json
    │   └── src/styles.css
    └── images/
        └── logo.svg

The module folder convention: Magento_Theme, Magento_Catalog, ...

Notice that templates and Layout XML don't live flat inside the theme, but in subfolders named exactly like Magento modules (Magento_Theme, Magento_Catalog, Magento_Checkout, ...). That's not a Hyvä specialty - it's a normal Magento convention: a theme overrides templates per module, and the folder name shows which module is affected.

A custom module like the later Mironsoft_TeamPage (chapters 17-22), on the other hand, normally brings its own templates along - inside the module, under view/frontend/templates/ - not in the theme folder. The theme only overrides things when necessary.

web/tailwind: the CSS source

The web/tailwind/ folder contains the Tailwind build: package.json with the npm dependencies, tailwind.config.js (or, in Tailwind v4, primarily the @theme directive directly in CSS, see chapters 5 and 11), and the source CSS file the final styles.css is built from. This folder is never shipped to the browser directly - it's pure build input.