hyva-ui-component

Hyva UI 组件

通过将文件从 {hyva_ui_path}/components/ 复制到 app/design/frontend/{Vendor}/{Theme}/，将基于 Hyva UI 模板的（非 CMS）组件应用到 Hyvä 主题。

路径变量： {hyva_ui_path} = vendor/hyva-themes/hyva-ui（默认值）或用户提供的自定义路径。

命令执行： 对于需要在开发环境中运行的命令（例如 bin/magento 命令），请使用 hyva-exec-shell-cmd 技能检测环境并确定合适的命令包装器。

步骤 0：验证 Hyva UI 是否已安装

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 文件的目录。

步骤 1：确定主题路径

使用 hyva-theme-list 技能查找现有的 Hyvä 主题。筛选结果，仅保留位于 app/design/frontend/ 中的主题（排除供应商主题）。

提示用户选择：

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

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

1. 先使用 hyva-child-theme 技能创建新主题
2. 技能完成后，继续使用新创建的主题路径

如果用户选择现有主题： 继续使用所选主题路径：app/design/frontend/{Vendor}/{Theme}

步骤 2：列出或选择组件

如果未指定组件或用户要求列出组件，仅显示 references/components.md 中的 “Non-CMS Components (Template-Based)” 部分。

不要列出或提及：

• CMS 组件（accordion、card、categories、error-page、generic-content、order-confirmation、shortcuts、testimonial、usp、product-data/C-highlights）
• 插件（alpine-collapse、splidejs、sticky-header、tailwind-v3-design-tokens、tailwind-v4）

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

步骤 3：显示变体

变体：A=基础版，B=增强版，C=高级版，D=专用版。使用以下命令列出：ls {hyva_ui_path}/components/{component}/

步骤 4：读取组件 README

复制前务必先读取 {hyva_ui_path}/components/{component}/{variant}/README.md。向用户说明：依赖项、配置选项和特殊要求。

步骤 5：复制组件文件

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

# 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
# check: {theme_path}/Magento_Catalog/templates/product/view/gallery.phtml

将每个文件标记为以下其中一种：

• created：复制前目标文件不存在
• updated：目标文件已存在（将被覆盖）

然后复制：

cp -r {hyva_ui_path}/components/{component}/{variant}/src/* {theme_path}/

src/ 目录包含 Magento 模块文件夹（Magento_Theme/、Magento_Catalog/ 等），这些文件夹会直接映射到主题结构。对于已有的布局 XML 文件，请合并内容，而不是覆盖。

步骤 5.5：添加 XML 配置选项

检查 README 是否包含 XML 配置（查找 <var name="、etc/view.xml）。

如果找到：

1. 提取第一个包含带有默认值的 <var name= 元素的 XML 代码块
2. 确定模块属性（例如 module="Magento_Catalog"）
3. 添加到 {theme_path}/etc/view.xml：
   • 如果文件不存在：创建包含完整 <view> 结构的文件
   • 如果存在 <vars module="...">：在其中添加 <var> 元素
   • 如果缺少此部分：在 </view> 前添加新的 <vars module="...">
4. 通知：“已将配置选项及其默认值添加到 {theme_path}/etc/view.xml。”

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

步骤 6：处理依赖项

检查 README 中的依赖项并自动安装（不要询问用户选择插件）：

• 插件依赖项： 从 {hyva_ui_path}/plugins/{plugin}/src/ 复制所需文件（例如，用于图库/D-splide 的 splidejs）
• 组件依赖项： 先应用依赖组件
• 外部包： 例如，composer require hyva-themes/magento2-hyva-payment-icons

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

• 重新构建 Tailwind： 始终询问：“是否需要重新编译 Tailwind CSS 样式？”绝不自动构建——外部工具可能已经在处理此事。如果用户希望编译，请使用 hyva-compile-tailwind-css 技能，并指定目标主题。

步骤 8：输出摘要

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

8.1：列出修改的文件

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

• （已创建）：文件之前不存在，是新创建的
• （已更新）：文件之前已存在，现已被覆盖

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)

8.2：XML 配置表

如果已将 XML 配置添加到 {theme_path}/etc/view.xml，请直接根据 README 中的 <var> 块生成选项表。对于每个 <var name="...">value</var> 条目，输出一行并包含以下列：

• 选项：完整的点分隔选项路径（由嵌套的 <var> 名称组成），去掉共同的前缀段（例如，gallery. → 显示 nav、magnifier.enable）
• 值：标签之间的默认值
• 说明：如果有行尾内联 `` 注释，则填写其文本

输出示例（去掉 gallery. 等共同前缀）：

Option               | Value      | Description
---------------------+------------+---------------------------------------------------
nav                  | thumbs     | Gallery navigation style (false/thumbs/counter)
magnifier.enable     | false      | Turn on/off magnifier (true/false)

创建文档时，请将相同的数据呈现为 Markdown 表格。

步骤 9：最后步骤

1. 检查复制的模板，进行针对商店的定制

快速参考

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

完整组件目录请参见 references/components.md（仅向用户展示非 CMS 部分）。