hyva-ui-component

Hyva UI コンポーネント

{hyva_ui_path}/components/ から app/design/frontend/{Vendor}/{Theme}/ にファイルをコピーし、テンプレートベース（非 CMS）の Hyva UI コンポーネントを Hyvä テーマに適用します。

パス変数： {hyva_ui_path} = vendor/hyva-themes/hyva-ui（デフォルト）またはユーザーが指定したカスタムパス。

コマンドの実行： 開発環境内で実行する必要があるコマンド（例：bin/magento コマンド）では、hyva-exec-shell-cmd スキルを使用して環境を検出し、適切なコマンドラッパーを決定してください。

Step 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 ファイルが格納されているディレクトリです。

Step 1：テーマのパスを特定

hyva-theme-list スキルを使用して、既存の Hyvä テーマを検索します。結果を app/design/frontend/ 内のテーマだけに絞り込みます（vendor のテーマは除外）。

ユーザーに次の選択肢を提示します。

• 既存の Hyvä テーマ：スクリプトが返したテーマを選択肢として一覧表示します（例：Example/winterWonderTheme）
• 新しいテーマを作成：新しい子テーマを作成する選択肢を必ず含めます

ユーザーが「新しいテーマを作成」を選択した場合：

1. まず hyva-child-theme スキルを使用して、新しいテーマを作成します
2. スキルの完了後、新しく作成したテーマのパスを使用して続行します

ユーザーが既存のテーマを選択した場合： 選択したテーマのパスを使用して続行します：app/design/frontend/{Vendor}/{Theme}

Step 2：コンポーネントを一覧表示または選択

コンポーネントが指定されていない場合、またはユーザーがコンポーネントの一覧表示を求めた場合は、references/components.md の 「非 CMS コンポーネント（テンプレートベース）」セクションのみを表示します。

一覧表示または言及してはいけないもの：

• 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 コンパイラーを必要とするため、このスキルによる直接インストールの対象外です。

Step 3：バリエーションを表示

バリエーション：A＝基本、B＝拡張、C＝高度、D＝特化。次のコマンドで一覧表示します：ls {hyva_ui_path}/components/{component}/

Step 4：コンポーネントの README を読む

コピーする前に、必ず {hyva_ui_path}/components/{component}/{variant}/README.md を読みます。依存関係、設定オプション、特別な要件をユーザーに提示します。

Step 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 ファイルがある場合は、上書きせずに内容をマージします。

Step 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 以外のセクションのみを表示します）。