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

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

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

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

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

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:

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

告知用户可通过以下方式启用主题：

Magento后台：内容 > 设计 > 配置

或通过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

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

创建成功后，提供以下摘要：

主题位置：

app/design/frontend/<Vendor>/<ThemeName>/

父主题：所选的父主题（例如

Hyva/default-csp

、

Hyva/default

或

{Vendor}/{ThemeName}

）

自定义后续步骤：
- 通过创建匹配路径来覆盖模板
- 在
```
web/tailwind/tailwind-source.css
```
  中自定义Tailwind
- 开发时运行
```
npm run watch
```
- 部署前运行
```
npm run build
```