hyva-child-theme

Hyvä 子テーマ作成ツール

このスキルは、適切なディレクトリ構成、設定ファイル、Tailwind CSS のビルド設定を備えた完全な Hyvä 子テーマを作成します。

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

ワークフロー

ステップ 1：テーマ情報の収集

以下の情報をユーザーに入力してもらいます。

ベンダー名：ベンダー／会社の名前空間（例：「Acme」、「MyCompany」）

• パスカルケースにする必要があります
• composer パッケージ名とディレクトリ構成で使用されます
• app/design/frontend または app/code に既存のベンダー名のフォルダーがある場合は、小文字表記を候補として提示します

テーマ名：テーマの名前（例：「customTheme」、「StoreTheme」）

• パスカルケースまたはキャメルケースにする必要があります
• テーマの登録とディレクトリ名で使用されます
• app/design/frontend 内にサブディレクトリとして存在していてはいけません

ステップ 2：親テーマの検出

ユーザーが親テーマを指定している場合は、それを使用します。親テーマには以下を指定できます。

• Hyvä のデフォルトテーマ：Hyva/default-csp または Hyva/default
• 既存の Hyvä 子テーマ：app/design/frontend/ の {Vendor}/{ThemeName}

ユーザーが親テーマを指定していない場合は、hyva-theme-list スキルを呼び出して、プロジェクト内で使用できるテーマをすべて確認します。

親テーマを選択できるよう、以下の候補をユーザーに提示します。

• 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}

ステップ 3：テーマのディレクトリ構成の作成

app/design/frontend/<Vendor>/<themeName>/ に、以下のテーマディレクトリを作成します。

app/design/frontend/<Vendor>/<themeName>/
├── registration.php
├── theme.xml
├── composer.json
└── web/
    └── tailwind/
        └── (copied from parent theme)

ステップ 4：設定ファイルの作成

registration.php

<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

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

theme.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>

タイトルの書式： パスカルケースのテーマ名を単語ごとに分割します（例：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

{
    "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> をケバブケースに変換します（例：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 パッケージ名（その composer.json から取得）を使用します。親テーマが composer パッケージでない場合は、省略します。

ステップ 5：Tailwind をコピーして設定する

web ディレクトリを作成し、親テーマから tailwind フォルダーをコピーします。node_modules は除外してください（コピーされた node_modules には壊れたシンボリックリンクが含まれており、新たにインストールする必要があります）。

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ä default テーマを親テーマにする場合：

{
    "tailwind": {
        "include": [
            { "src": "vendor/hyva-themes/magento2-default-theme-csp" }
        ]
    }
}

子テーマを親テーマにする場合： すべてのテンプレートクラスを確実にスキャンするため、直近の親テーマと Hyvä のルートテーマの両方を含めます。

{
    "tailwind": {
        "include": [
            { "src": "app/design/frontend/{ParentVendor}/{ParentTheme}" },
            { "src": "vendor/hyva-themes/magento2-default-theme-csp" }
        ]
    }
}

子テーマの親テーマの hyva.config.json にすでに追加のインクルード設定がある場合は、継承チェーン全体を維持するため、それらもコピーしてください。

ステップ 6：依存関係をインストールして CSS をビルドする

hyva-compile-tailwind-css スキルを使用して、新しく作成した app/design/frontend/<Vendor>/<ThemeName>/ のテーマに依存関係をインストールし、CSS をビルドします。

ステップ 7：テーマを有効にする

次の方法でテーマを有効にできることをユーザーに伝えます。

1. Magento 管理画面：Content > Design > Configuration
2. または CLI：bin/magento config:set design/theme/theme_id <theme_id>

テーマを登録するため、セットアップアップグレードを実行します。

bin/magento setup:upgrade
bin/magento cache:flush

トラブルシューティング

Hyvä テーマが見つからない（ステップ 2）

原因：プロジェクトに Hyvä テーマのパッケージがインストールされていません。 解決策：Composer で Hyvä テーマをインストールします：composer require hyva-themes/magento2-default-theme または hyva-themes/magento2-default-theme-csp。

親テーマのパスが存在しない（ステップ 5）

原因：選択した親テーマのディレクトリがないか、パスが正しくありません。 解決策：rsync の実行前に、親テーマが存在することを確認してください。Composer パッケージが composer install で正しくインストールされていることを確認します。

親テーマに Tailwind フォルダーがない（ステップ 5）

原因：親テーマに web/tailwind ディレクトリがありません（非常に古いテーマやカスタムテーマでは、この場合があります）。 解決策：代わりに vendor/hyva-themes/magento2-default-theme-csp/web/tailwind から tailwind フォルダーをコピーします。

npm install が失敗する（ステップ 6）

原因：Node のバージョン不一致、ネットワークの問題、または package-lock.json の破損です。 解決策：

• Node のバージョンを確認します（Node 16 以降が必要です）：node --version
• node_modules と package-lock.json を削除してから、npm install を再試行します

npm build が失敗する（ステップ 6）

原因：hyva.config.json のパスが無効、またはパージ対象が見つかりません。 解決策：

• hyva.config.json のすべてのパスがプロジェクト内に存在することを確認します
• 設定ファイルに JSON 構文エラーがないか確認します
• 親テーマのパスが正しいことを確認します

出力

作成が正常に完了したら、次の概要を提示します。

• テーマの場所：app/design/frontend/<Vendor>/<ThemeName>/
• 親テーマ：選択した親テーマ（例：Hyva/default-csp、Hyva/default、または {Vendor}/{ThemeName}）
• カスタマイズの次のステップ：
  • 対応するパスを作成してテンプレートをオーバーライドする
  • web/tailwind/tailwind-source.css で Tailwind をカスタマイズする
  • 開発時は npm run watch を実行する
  • デプロイ前に npm run build を実行する