SKILL.md

Hyvä Child Theme Creator

Name: hyva-child-theme
Author: hyva-themes

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/<Vendor>/<themeName>/ with:

app/design/frontend/<Vendor>/<themeName>/

├── registration.php

├── theme.xml

├── composer.json

└── web/

    └── tailwind/

        └── (copied from parent theme)

Step 4: Create Configuration Files

#### registration.php

<?php

declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register( ComponentRegistrar::THEME, 'frontend/<Vendor>/<themeName>', __DIR__);

#### theme.xml

<?xml version="1.0"?>

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">

    <title>Example Store Theme</title>

    <parent>Hyva/default-csp</parent>

</theme>

Title formatting: Split PascalCase theme names into separate words (e.g., StoreTheme → Store Theme). The title should read as <Vendor> <Theme Name Words> (e.g., Example/StoreTheme → Example Store Theme).

Adjust <parent> to match the selected parent theme:

Hyva/default-csp or Hyva/default for Hyvä default themes

{ParentVendor}/{ParentThemeName} for child theme parents (e.g., Example/baseTheme)

#### composer.json

{

    "name": "<vendor-lowercase>/<package-name>",

    "description": "Example Store Theme based on Hyvä",

    "type": "magento2-theme",

    "license": "proprietary",

    "require": {

        "hyva-themes/magento2-default-theme-csp": "*"

    },

    "autoload": {

        "files": [

            "registration.php"

        ]

    }

}

Package name rules:

Convert <ThemeName> to kebab-case (e.g., StoreTheme → store-theme)

Append -theme suffix only if the theme name doesn't already end with "theme"

Examples:

StoreTheme → store-theme (already ends with "theme", no suffix added)

CustomStore → custom-store-theme (suffix added)

myTheme → my-theme (already ends with "theme", no suffix added)

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/<Vendor>/<ThemeName>/web

rsync -a --exclude='node_modules' <parent_theme_path>/web/tailwind app/design/frontend/<Vendor>/<ThemeName>/web/

Where <parent_theme_path> is:

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/<Vendor>/<ThemeName>/.

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 <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.