hyva-child-theme

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

theme.xml

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

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

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:

For child theme parent: Include both the immediate parent AND the root Hyvä theme to ensure all template classes are scanned:

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:

1. Magento Admin: Content > Design > Configuration
2. Or via CLI: bin/magento config:set design/theme/theme_id <theme_id>

Run setup upgrade to register the theme:

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