hyva-ui-component

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hyva UI Component

Hyva UI组件

Applies Hyva UI template-based (non-CMS) components to a Hyvä theme by copying files from

{hyva_ui_path}/components/

app/design/frontend/{Vendor}/{Theme}/

Path variable:

{hyva_ui_path}

vendor/hyva-themes/hyva-ui

(default) or user-provided custom path.

Command execution: For any commands that need to run inside the development environment (e.g.,

bin/magento

commands), use the

hyva-exec-shell-cmd

skill to detect the environment and determine the appropriate command wrapper.

将基于Hyva UI模板的（非CMS）组件应用到Hyvä主题中，具体方式是将文件从

{hyva_ui_path}/components/

复制到

app/design/frontend/{Vendor}/{Theme}/

。

路径变量：

{hyva_ui_path}

vendor/hyva-themes/hyva-ui

（默认值）或用户提供的自定义路径。

命令执行： 对于需要在开发环境中运行的任何命令（如

bin/magento

命令），请使用

hyva-exec-shell-cmd

技能来检测环境并确定合适的命令包装器。

Step 0: Verify Hyva UI Installation

步骤0：验证Hyva UI安装

bash

ls vendor/hyva-themes/hyva-ui/components/ 2>/dev/null

If NOT found, offer options: (A) User provides custom extraction path, (B)

composer require --dev hyva-themes/hyva-ui

, (C) Download from https://hyva.io/my-account/my-downloads/

After install, refresh catalog:

<skill_path>/scripts/refresh_catalog.sh {hyva_ui_path} <skill_path>/references/components.md

Where

<skill_path>

is the directory containing this SKILL.md file.

bash

ls vendor/hyva-themes/hyva-ui/components/ 2>/dev/null

如果未找到，提供以下选项：(A) 用户提供自定义提取路径，(B)

composer require --dev hyva-themes/hyva-ui

，(C) 从https://hyva.io/my-account/my-downloads/下载

安装完成后，刷新目录：

<skill_path>/scripts/refresh_catalog.sh {hyva_ui_path} <skill_path>/references/components.md

其中

<skill_path>

是包含此SKILL.md文件的目录。

Step 1: Identify Theme Path

步骤1：确定主题路径

Use the

hyva-theme-list

skill to find existing Hyvä themes. Filter the results to only include themes in

app/design/frontend/

(exclude vendor themes).

Prompt the user to select:

Existing Hyvä themes: List themes returned by the script as options (e.g.,
```
Example/winterWonderTheme
```
)
Create new theme: Always include an option to create a new child theme

If user selects "Create new theme":

Use the
```
hyva-child-theme
```
skill to create the new theme first
Continue with the newly created theme path after the skill completes

If user selects an existing theme: Continue with the selected theme path:

app/design/frontend/{Vendor}/{Theme}

使用

hyva-theme-list

技能查找现有的Hyvä主题。过滤结果，仅包含

app/design/frontend/

中的主题（排除vendor主题）。

提示用户选择：

现有Hyvä主题：将脚本返回的主题列为选项（例如
```
Example/winterWonderTheme
```
）
创建新主题：始终包含创建新子主题的选项

如果用户选择“创建新主题”：

首先使用
```
hyva-child-theme
```
技能创建新主题
技能完成后，使用新创建的主题路径继续操作

如果用户选择现有主题： 使用选定的主题路径继续操作：

app/design/frontend/{Vendor}/{Theme}

Step 2: List or Select Component

步骤2：列出或选择组件

If no component specified or user asks to list components, show only the "Non-CMS Components (Template-Based)" section from

references/components.md

Do NOT list or mention:

CMS components (accordion, card, categories, error-page, generic-content, order-confirmation, shortcuts, testimonial, usp, product-data/C-highlights)
Plugins (alpine-collapse, splidejs, sticky-header, tailwind-v3-design-tokens, tailwind-v4)

These are internal dependencies or require the CMS Tailwind JIT compiler and are not applicable for direct installation via this skill.

如果未指定组件，或用户要求列出组件，请显示

references/components.md

中的仅“非CMS组件（基于模板）”部分。

请勿列出或提及：

CMS组件（手风琴、卡片、分类、错误页面、通用内容、订单确认、快捷方式、推荐语、USP、product-data/C-highlights）
插件（alpine-collapse、splidejs、sticky-header、tailwind-v3-design-tokens、tailwind-v4）

这些是内部依赖项，或需要CMS Tailwind JIT编译器，不适合通过此技能直接安装。

Step 3: Show Variants

步骤3：显示变体

Variants: A=Basic, B=Enhanced, C=Advanced, D=Specialized. List with:

ls {hyva_ui_path}/components/{component}/

变体：A=基础版，B=增强版，C=进阶版，D=专业版。使用以下命令列出：

ls {hyva_ui_path}/components/{component}/

Step 4: Read Component README

步骤4：查看组件README

Always read

{hyva_ui_path}/components/{component}/{variant}/README.md

before copying. Present to user: dependencies, configuration options, special requirements.

在复制之前，务必阅读

{hyva_ui_path}/components/{component}/{variant}/README.md

。向用户展示其中的依赖项、配置选项和特殊要求。

Step 5: Copy Component Files

步骤5：复制组件文件

Before copying, check which destination files already exist to track created vs updated:

bash

undefined

复制前，检查哪些目标文件已存在，以跟踪创建和更新的文件：

bash

undefined

List source files

列出源文件

find {hyva_ui_path}/components/{component}/{variant}/src -type f

For each source file, check if destination exists

对每个源文件，检查目标文件是否存在

e.g., for src/Magento_Catalog/templates/product/view/gallery.phtml

例如，对于src/Magento_Catalog/templates/product/view/gallery.phtml

check: {theme_path}/Magento_Catalog/templates/product/view/gallery.phtml

检查：{theme_path}/Magento_Catalog/templates/product/view/gallery.phtml


Track each file as either:
- **created**: Destination file did not exist before copy
- **updated**: Destination file already existed (will be overwritten)

Then copy:
```bash
cp -r {hyva_ui_path}/components/{component}/{variant}/src/* {theme_path}/

The

src/

directory contains Magento module folders (

Magento_Theme/

Magento_Catalog/

, etc.) that map directly to theme structure. For existing layout XML files, merge content rather than overwriting.


将每个文件标记为以下类型之一：
- **(created)**: 目标文件在复制前不存在
- **(updated)**: 目标文件已存在（将被覆盖）

然后执行复制：
```bash
cp -r {hyva_ui_path}/components/{component}/{variant}/src/* {theme_path}/

src/

目录包含与主题结构直接对应的Magento模块文件夹（

Magento_Theme/

、

Magento_Catalog/

等）。对于现有的布局XML文件，合并内容而非直接覆盖。

Step 5.5: Add XML Configuration Options

步骤5.5：添加XML配置选项

Check if README contains XML configuration (look for

<var name="

etc/view.xml

If found:

Extract the first XML block containing
```
<var name=
```
elements with default values
Identify the module attribute (e.g.,
```
module="Magento_Catalog"
```
)
Add to
```
{theme_path}/etc/view.xml
```
:
- If file doesn't exist: Create with full
```
<view>
```
  structure
- If
```
<vars module="...">
```
  exists: Add
```
<var>
```
  elements inside it
- If section missing: Add new
```
<vars module="...">
```
  before
```
</view>
```
Notify: "Added configuration options to
```
{theme_path}/etc/view.xml
```
with default values."

Preserve existing view.xml content and keep XML comments from README.

检查README中是否包含XML配置（查找

<var name="

、

etc/view.xml

）。

如果找到：

提取第一个包含带有默认值的
```
<var name=
```
元素的XML块
识别模块属性（例如
```
module="Magento_Catalog"
```
）
将其添加到
```
{theme_path}/etc/view.xml
```
中：
- 如果文件不存在：创建完整的
```
<view>
```
  结构
- 如果
```
<vars module="...">
```
  已存在：在其中添加
```
<var>
```
  元素
- 如果该部分缺失：在
```
</view>
```
  之前添加新的
```
<vars module="...">
```
通知用户："已将配置选项添加到
```
{theme_path}/etc/view.xml
```
，使用默认值。"

保留现有的view.xml内容，并保留README中的XML注释。

Step 6: Handle Dependencies

步骤6：处理依赖项

Check README for dependencies and install them automatically (do not ask the user to select plugins):

Plugin dependencies: Copy required files from
```
{hyva_ui_path}/plugins/{plugin}/src/
```
(e.g., splidejs for gallery/D-splide)
Component dependencies: Apply dependent components first

External packages: e.g.,

composer require hyva-themes/magento2-hyva-payment-icons

检查README中的依赖项并自动安装（无需让用户选择插件）：

插件依赖项： 从
```
{hyva_ui_path}/plugins/{plugin}/src/
```
复制所需文件（例如，图库/D-splide所需的splidejs）
组件依赖项： 先应用依赖的组件

外部包： 例如

composer require hyva-themes/magento2-hyva-payment-icons

Step 7: Ask to recompile styles

步骤7：询问是否重新编译样式

Rebuild Tailwind: Always ask: "Do you need to recompile Tailwind CSS styles?" Never automatically build — an external tool may already be handling this. If the user wants to compile, use the
```
hyva-compile-tailwind-css
```
skill with the target theme.

重建Tailwind： 始终询问："是否需要重新编译Tailwind CSS样式？" 切勿自动构建——外部工具可能已在处理此操作。如果用户需要编译，请使用
```
hyva-compile-tailwind-css
```
技能针对目标主题执行。

Step 8: Output Summary

步骤8：输出摘要

After applying all changes, output a summary of modifications:

应用所有更改后，输出修改的摘要：

8.1: List Modified Files

8.1：列出修改的文件

Display all files that were created or modified during this component installation. Use the tracking from Step 5 to label each file correctly:

(created): File did not exist before and was newly created
(updated): File already existed and was overwritten

Modified files:
  - {theme_path}/Magento_Catalog/templates/product/view/gallery.phtml (updated)
  - {theme_path}/Magento_Theme/templates/html/header.phtml (created)
  - {theme_path}/etc/view.xml (updated)

显示在此组件安装过程中创建或修改的所有文件。使用步骤5中的跟踪信息为每个文件正确标记：

(created): 文件之前不存在，是新创建的
(updated): 文件已存在，被覆盖

修改的文件：
  - {theme_path}/Magento_Catalog/templates/product/view/gallery.phtml (updated)
  - {theme_path}/Magento_Theme/templates/html/header.phtml (created)
  - {theme_path}/etc/view.xml (updated)

8.2: XML Configuration Table

8.2：XML配置表

If XML configuration was added to

{theme_path}/etc/view.xml

, parse the XML block from the README and display a table of options:

bash

undefined

如果已向

{theme_path}/etc/view.xml

添加XML配置，请解析README中的XML块并显示选项表：

bash

undefined

Extract the XML config block from README and parse it

从README中提取XML配置块并解析

php <skill_path>/scripts/parse_readme_xml.php --format=table < xml_block.txt


The table shows each option with columns:
- **Option**: The full option path without a common prefix (e.g., `magnifier.enable`)
- **Value**: The default value configured
- **Description**: Explanatory text from the XML comment

Example output (common prefix like `gallery.` is automatically stripped):


For markdown output (e.g., when creating documentation), use `--format=md`.

php <skill_path>/scripts/parse_readme_xml.php --format=table < xml_block.txt


该表显示每个选项，包含以下列：
- **选项**：不带公共前缀的完整选项路径（例如`magnifier.enable`）
- **值**：配置的默认值
- **说明**：XML注释中的解释文本

示例输出（自动去除公共前缀如`gallery.`）：


对于Markdown输出（例如创建文档时），使用`--format=md`。

Step 9: Final steps

步骤9：最终步骤

Review copied templates for store-specific customization

检查复制的模板，针对店铺进行特定定制

Quick Reference

快速参考

{hyva_ui_path}/components/{component}/{variant}/
├── README.md       # Instructions
├── media/          # Preview images
└── src/            # Files to copy to theme

See

references/components.md

for the full component catalog (only show non-CMS section to users).

{hyva_ui_path}/components/{component}/{variant}/
├── README.md       # 说明文档
├── media/          # 预览图片
└── src/            # 要复制到主题的文件

有关完整的组件目录，请查看

references/components.md

（仅向用户显示非CMS部分）。