Hyvä Child Theme Creator
This skill creates a complete Hyvä child theme with the proper directory structure, configuration files, and Tailwind CSS build setup.
Command execution: For commands that need to run inside the development environment (e.g., bin/magento), use the hyva-exec-shell-cmd skill to detect the environment and determine the appropriate command wrapper.
Workflow Step 1: Gather Theme Information
Prompt the user to provide the following information:
Vendor Name: The vendor/company namespace (e.g., "Acme", "MyCompany")
Must be PascalCase Used in composer package name and directory structure If there are existing Vendor name folders in app/design/frontend or app/code/ offer those in lower case as suggestions
Theme Name: The name of the theme (e.g., "customTheme", "StoreTheme")
Must be PascalCase or camelCase Used in theme registration and directory name Must not be present as a subdirectory in app/design/frontend Step 2: Detect Parent Theme
If the user has specified a parent theme, use that. The parent can be:
A Hyvä default theme: Hyva/default-csp or Hyva/default An existing Hyvä child theme: {Vendor}/{ThemeName} from app/design/frontend/
If the user has NOT specified a parent theme, discover available options by invoking the hyva-theme-list skill to find all Hyvä themes in the project.
Present the user with options to select a parent theme:
Hyvä default themes: Hyva/default-csp (if installed) or Hyva/default Existing Hyvä child themes: List themes returned by the skill as {Vendor}/{ThemeName}
Parent theme paths for later steps:
Hyvä default themes: vendor/hyva-themes/magento2-default-theme-csp or vendor/hyva-themes/magento2-default-theme Child themes: app/design/frontend/{Vendor}/{ThemeName} Step 3: Create Theme Directory Structure
Create the theme directory at app/design/frontend/
app/design/frontend/
Step 4: Create Configuration Files registration.php
/Title formatting: Split PascalCase theme names into separate words (e.g., StoreTheme → Store Theme). The title should read as
Adjust
Hyva/default-csp or Hyva/default for Hyvä default themes
{ParentVendor}/{ParentThemeName} for child theme parents (e.g., Example/baseTheme)
composer.json
{
"name": "
Package name rules:
Convert
Adjust the require dependency to match the parent theme:
For Hyvä default themes: hyva-themes/magento2-default-theme-csp or hyva-themes/magento2-default-theme For child theme parents: Use the parent's composer package name (from its composer.json), or omit if the parent theme is not a composer package Step 5: Copy and Configure Tailwind
Create the web directory and copy the tailwind folder from the parent theme, excluding node_modules (copied node_modules contain broken symlinks and must be installed fresh):
mkdir -p app/design/frontend/
Where
vendor/hyva-themes/magento2-default-theme-csp for Hyvä default-csp vendor/hyva-themes/magento2-default-theme for Hyvä default app/design/frontend/{ParentVendor}/{ParentTheme} for child theme parents
Update web/tailwind/hyva.config.json to include the parent theme path(s) in Tailwind content scanning.
For Hyvä default theme parent:
{ "tailwind": { "include": [ { "src": "vendor/hyva-themes/magento2-default-theme-csp" } ] } }
For child theme parent: Include both the immediate parent AND the root Hyvä theme to ensure all template classes are scanned:
{ "tailwind": { "include": [ { "src": "app/design/frontend/{ParentVendor}/{ParentTheme}" }, { "src": "vendor/hyva-themes/magento2-default-theme-csp" } ] } }
If the child theme parent already has additional includes in its hyva.config.json, copy those to maintain the full inheritance chain.
Step 6: Install Dependencies and Build CSS
Use the hyva-compile-tailwind-css skill to install dependencies and build CSS for the newly created theme at app/design/frontend/
Step 7: Enable the Theme
Inform the user they can enable the theme via:
Magento Admin: Content > Design > Configuration
Or via CLI: bin/magento config:set design/theme/theme_id
Run setup upgrade to register the theme:
bin/magento setup:upgrade bin/magento cache:flush
Troubleshooting No Hyvä themes found (Step 2)
Cause: Hyvä theme packages not installed in the project. Solution: Install Hyvä themes via Composer: composer require hyva-themes/magento2-default-theme or hyva-themes/magento2-default-theme-csp.
Parent theme path doesn't exist (Step 5)
Cause: The selected parent theme directory is missing or path is incorrect. Solution: Verify the parent theme exists before running rsync. Check that Composer packages are properly installed with composer install.
Tailwind folder missing in parent (Step 5)
Cause: The parent theme doesn't have a web/tailwind directory (possible with very old or custom themes). Solution: Fall back to copying the tailwind folder from vendor/hyva-themes/magento2-default-theme-csp/web/tailwind instead.
npm install fails (Step 6)
Cause: Node version mismatch, network issues, or corrupted package-lock.json. Solution:
Check Node version (requires Node 16+): node --version Delete node_modules and package-lock.json, then retry npm install npm build fails (Step 6)
Cause: Invalid paths in hyva.config.json or missing purge targets. Solution:
Verify all paths in hyva.config.json exist in the project Check for JSON syntax errors in the config file Ensure parent theme paths are correct Output
After successful creation, provide a summary:
Theme location: app/design/frontend/