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

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

<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

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

theme.xml

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

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

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):

bash

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:

json

{
    "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:

json

{
    "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:

bash

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

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

Parent theme: The selected parent (e.g.,

Hyva/default-csp

Hyva/default

, or

{Vendor}/{ThemeName}

)

Next steps for customization:
- Override templates by creating matching paths
- Customize Tailwind in
```
web/tailwind/tailwind-source.css
```
- Run
```
npm run watch
```
  for development
- Run
```
npm run build
```
  before deployment

hyva-child-theme

NPX Install

Tags

SKILL.md Content

Hyvä Child Theme Creator

Workflow

Step 1: Gather Theme Information

Step 2: Detect Parent Theme

Step 3: Create Theme Directory Structure

Step 4: Create Configuration Files

registration.php

theme.xml

composer.json

Step 5: Copy and Configure Tailwind

Step 6: Install Dependencies and Build CSS

Step 7: Enable the Theme

Troubleshooting

No Hyvä themes found (Step 2)

Parent theme path doesn't exist (Step 5)

Tailwind folder missing in parent (Step 5)

npm install fails (Step 6)

npm build fails (Step 6)

Output