hyva-child-theme

Create a Hyvä child theme in a Magento 2 project. This skill should be used when the user wants to create a new Hyvä child theme, set up a custom theme based on Hyvä, or initialize a new frontend theme directory structure. Trigger phrases include "create hyva child theme", "new hyva theme", "setup child theme", "create custom theme", "initialize theme".

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "hyva-child-theme" with this command: npx skills add hyva-themes/hyva-ai-tools/hyva-themes-hyva-ai-tools-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);

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:

  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:

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/<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
<!-- Copyright © Hyvä Themes https://hyva.io. All rights reserved. Licensed under OSL 3.0 -->

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

General

hyva-exec-shell-cmd

No summary provided by upstream source.

Repository SourceNeeds Review
127-hyva-themes
General

hyva-alpine-component

No summary provided by upstream source.

Repository SourceNeeds Review
123-hyva-themes
General

hyva-render-media-image

No summary provided by upstream source.

Repository SourceNeeds Review
122-hyva-themes
General

hyva-theme-list

No summary provided by upstream source.

Repository SourceNeeds Review
122-hyva-themes