Back to Details

hyva-child-theme

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Hyvä Child Theme Creator

Hyvä子主题创建器

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.
本技能可创建一个完整的Hyvä子主题，包含正确的目录结构、配置文件以及Tailwind CSS构建设置。
命令执行：对于需要在开发环境中运行的命令（如
bin/magento
），请使用
hyva-exec-shell-cmd
技能检测环境并确定合适的命令包装器。

Workflow

工作流程

Step 1: Gather Theme Information

步骤1：收集主题信息

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
提示用户提供以下信息：
供应商名称（Vendor Name）：供应商/公司的命名空间（例如"Acme"、"MyCompany"）
  • 必须采用PascalCase命名格式
  • 用于composer包名和目录结构
  • 如果
    app/design/frontend
    或
    app/code
    中已有供应商名称文件夹，将以小写形式提供这些名称作为建议
主题名称（Theme Name）：主题的名称（例如"customTheme"、"StoreTheme"）
  • 必须采用PascalCase或camelCase命名格式
  • 用于主题注册和目录名称
  • 不能是
    app/design/frontend
    中已存在的子目录

Step 2: Detect Parent Theme

步骤2：检测父主题

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}
如果用户指定了父主题，则使用该主题。父主题可以是：
  • Hyvä默认主题：
    Hyva/default-csp
    或
    Hyva/default
  • 已有的Hyvä子主题：来自
    app/design/frontend/
    的
    {Vendor}/{ThemeName}
如果用户未指定父主题，则调用
hyva-theme-list
技能查找项目中所有的Hyvä主题，以发现可用选项。
向用户展示可选择的父主题选项：
  • Hyvä默认主题：
    Hyva/default-csp
    （若已安装）或
    Hyva/default
  • 已有的Hyvä子主题：将技能返回的主题以
    {Vendor}/{ThemeName}
    格式列出
后续步骤使用的父主题路径：
  • Hyvä默认主题：
    vendor/hyva-themes/magento2-default-theme-csp
    或
    vendor/hyva-themes/magento2-default-theme
  • 子主题：
    app/design/frontend/{Vendor}/{ThemeName}

Step 3: Create Theme Directory Structure

步骤3：创建主题目录结构

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)
在
app/design/frontend/<Vendor>/<themeName>/
路径下创建主题目录，包含以下内容：
app/design/frontend/<Vendor>/<themeName>/
├── registration.php
├── theme.xml
├── composer.json
└── web/
    └── tailwind/
        └── (copied from parent theme)

Step 4: Create Configuration Files

步骤4：创建配置文件

registration.php

registration.php

php
<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register( ComponentRegistrar::THEME, 'frontend/<Vendor>/<themeName>', __DIR__);
php
<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

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

theme.xml

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
    )
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>
标题格式：将PascalCase格式的主题名称拆分为独立单词（例如
StoreTheme
→ 
Store Theme
）。标题格式应为
<Vendor> <Theme Name Words>
（例如
Example/StoreTheme
→ 
Example Store Theme
）。
调整
<parent>
标签以匹配所选的父主题：
  • 对于Hyvä默认主题，使用
    Hyva/default-csp
    或
    Hyva/default
  • 对于子主题父项，使用
    {ParentVendor}/{ParentThemeName}
    （例如
    Example/baseTheme
    ）

composer.json

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
    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
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"
        ]
    }
}
包名规则：
  • 将
    <ThemeName>
    转换为kebab-case格式（例如
    StoreTheme
    → 
    store-theme
    ）
  • 仅当主题名称未以"theme"结尾时，添加
    -theme
    后缀
  • 示例： 
    • StoreTheme
      → 
      store-theme
      （已以"theme"结尾，无需添加后缀）
    • CustomStore
      → 
      custom-store-theme
      （添加后缀）
    • myTheme
      → 
      my-theme
      （已以"theme"结尾，无需添加后缀）
调整
require
依赖项以匹配父主题：
  • 对于Hyvä默认主题：
    hyva-themes/magento2-default-theme-csp
    或
    hyva-themes/magento2-default-theme
  • 对于子主题父项：使用父主题
    composer.json
    中的composer包名；若父主题不是composer包，则省略该依赖

Step 5: Copy and Configure Tailwind

步骤5：复制并配置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.
创建web目录，并从父主题复制tailwind文件夹，排除
node_modules
（复制的node_modules包含损坏的符号链接，必须重新安装）：
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/
其中
<parent_theme_path>
为：
  • Hyvä default-csp主题：
    vendor/hyva-themes/magento2-default-theme-csp
  • Hyvä default主题：
    vendor/hyva-themes/magento2-default-theme
  • 子主题父项：
    app/design/frontend/{ParentVendor}/{ParentTheme}
更新
web/tailwind/hyva.config.json
，在Tailwind内容扫描中添加父主题路径。
对于Hyvä默认主题父项：
json
{
    "tailwind": {
        "include": [
            { "src": "vendor/hyva-themes/magento2-default-theme-csp" }
        ]
    }
}
对于子主题父项：同时包含直接父主题和根Hyvä主题，以确保扫描所有模板类：
json
{
    "tailwind": {
        "include": [
            { "src": "app/design/frontend/{ParentVendor}/{ParentTheme}" },
            { "src": "vendor/hyva-themes/magento2-default-theme-csp" }
        ]
    }
}
如果子主题父项的
hyva.config.json
中已有额外的include配置，请复制这些配置以保持完整的继承链。

Step 6: Install Dependencies and Build CSS

步骤6：安装依赖并构建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>/
.
使用
hyva-compile-tailwind-css
技能，在新创建的主题路径
app/design/frontend/<Vendor>/<ThemeName>/
下安装依赖并构建CSS。

Step 7: Enable the Theme

步骤7：启用主题

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:
bash
bin/magento setup:upgrade
bin/magento cache:flush
告知用户可通过以下方式启用主题：
  1. Magento后台：内容 > 设计 > 配置
  2. 或通过CLI命令：
    bin/magento config:set design/theme/theme_id <theme_id>
运行升级命令以注册主题：
bash
bin/magento setup:upgrade
bin/magento cache:flush

Troubleshooting

故障排除

No Hyvä themes found (Step 2)

步骤2中未找到Hyvä主题

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
.
原因：项目中未安装Hyva主题包。 解决方案：通过Composer安装Hyva主题：
composer require hyva-themes/magento2-default-theme
或
hyva-themes/magento2-default-theme-csp
。

Parent theme path doesn't exist (Step 5)

步骤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
.
原因：所选父主题目录缺失或路径错误。 解决方案：在运行rsync前验证父主题是否存在。使用
composer install
检查Composer包是否已正确安装。

Tailwind folder missing in parent (Step 5)

步骤5中父主题缺少tailwind文件夹

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.
原因：父主题没有
web/tailwind
目录（可能是非常旧的主题或自定义主题）。 解决方案：退而求其次，从
vendor/hyva-themes/magento2-default-theme-csp/web/tailwind
复制tailwind文件夹。

npm install fails (Step 6)

步骤6中npm install失败

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
原因：Node版本不匹配、网络问题或
package-lock.json
损坏。 解决方案：
  • 检查Node版本（要求Node 16+）：
    node --version
  • 删除
    node_modules
    和
    package-lock.json
    ，然后重新运行
    npm install

npm build fails (Step 6)

步骤6中npm build失败

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
原因：
hyva.config.json
中的路径无效或缺少清除目标。 解决方案：
  • 验证
    hyva.config.json
    中的所有路径在项目中是否存在
  • 检查配置文件中的JSON语法错误
  • 确保父主题路径正确

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 -->
创建成功后，提供以下摘要：
  • 主题位置：
    app/design/frontend/<Vendor>/<ThemeName>/
  • 父主题：所选的父主题（例如
    Hyva/default-csp
    、
    Hyva/default
    或
    {Vendor}/{ThemeName}
    ）
  • 自定义后续步骤：
    • 通过创建匹配路径来覆盖模板
    • 在
      web/tailwind/tailwind-source.css
      中自定义Tailwind
    • 开发时运行
      npm run watch
    • 部署前运行
      npm run build
<!-- Copyright © Hyvä Themes https://hyva.io. All rights reserved. Licensed under OSL 3.0 -->