theme-skill

概要

このスキルは、JSON のみの変更で Shopify テーマを更新する際に使用します。対象ファイルには、templates/*.json、JSON セクションデータ、config/settings_data.json、config/settings_schema.json、および JSON ファイル内のスキーマで定義されたセクションやブロックの設定が含まれます。

既存の Liquid スキーマは読み取り専用の参照情報として扱ってください。カスタム Liquid の記述、作成、変更は行わず、sections/、blocks/、snippets/、assets/、その他のテーマコードのパスに新しいファイルを追加しないでください。

対象テーマにすでに用意されているセクション、ブロック、ネストされたブロック構造、設定のみを使用してください。テーマの既存の JSON テンプレート、セクションタイプ、ブロックタイプ、スキーマ設定では要望されたデザインを表現できない場合は、その不足点を伝え、JSON のみで実現できる最も近い案を提案してください。

使用する場面

次のようなタスクでは、このスキルを使用してください。

• product.json、index.json、page.contact.json など、templates/ 内の Shopify JSON テンプレート
• ブロックベースのテーマにおいて、blocks/ にある既存のテーマブロックを参照するセクション JSON
• config/settings_data.json、config/settings_schema.json、セクション設定、ブロック設定を通じて安全に表現できるテーマデザイン設定
• 要求されたコントロールが Shopify の JSON 設定スキーマに含まれる場合の、config/settings_schema.json におけるグローバル設定スキーマの更新
• テーマの JSON 設定とスキーマですでに公開されている、レイアウト、コンテンツ、色、タイポグラフィ、余白、表示、動作の調整
• スクリーンショット、デザインモックアップ、または文章による要望を、対象テーマがサポートする最も近い JSON のみの構造に反映する場合

使用しない場面

次の用途には、このスキルを使用しないでください。

• チェックアウトのブランディングや Checkout UI 拡張機能
• extensions/ 内のテーマアプリ拡張機能のコード
• 新しいセクション、ブロック、スニペット、スキーマ、テーマアセットなど、Liquid の .liquid ファイルの作成や編集
• テーマがそのルートで JSON を採用していない場合の、Liquid の .liquid テンプレートの置き換え
• デザインの実現を目的とした、新しいセクションタイプ、ブロックタイプ、スニペット、JavaScript、スタイルシート、アセット、Liquid スキーマの作成

テーマで ビルド手順により JSON テンプレート、設定データ、設定スキーマを生成している場合は、そのテーマの README を読み、JSON／設定の信頼できるソースを編集してください。信頼できるソースが Liquid、JavaScript、CSS、または JSON 以外のテーマコードである場合は、そのタスクがこのスキルの対象外であることを伝えてください。

クイックスタート

1. 要件を把握する — プロンプトや画像を解析し、レイアウト、列／行、コンテンツの種類、スタイルを確認します（入力が視覚的な場合は、デザイン画像とモックアップを参照してください）。
2. JSON のみに限定する — 既存の Liquid スキーマは読み取り専用の参照として扱います。config/settings_data.json や config/settings_schema.json も含め、グローバルデザイン設定が依頼に含まれる場合に限り、Shopify JSON のみを編集します。
3. 使用可能なブロックタイプを確認する — blocks/ を一覧表示し、親の {% schema %} を読み取って、使用するすべての type がこのテーマに存在することを確認します（必須。詳しくは以下を参照）。
4. （任意）同梱の例を確認する — examples/ がある場合は、examples/README.md の参照する最適な例の選び方に従います。ワークスペースのテーマとインデックス済みの各例を比較し、最も適合するファイルを最大 1 つ開きます。適合するものがない場合は、代わりにワークスペースのテーマ内にある既存の templates/*.json からパターンをコピーします。同梱の例にある type 文字列は、対象テーマで使用可能なセットに存在することを確認するまで出力しないでください。
5. 実際のブロックに対応付ける — 使用可能なセットの中からのみタイプを選び、テンプレートレベルの JSON では既存の sections/*.liquid からセクションの type を特定します。
6. スキーマを分析する — 既存の各ブロックまたはセクションの {% schema %} を読み取り、使用可能な子要素、設定 ID、タイプ、デフォルト値、プリセットを確認します。
7. グローバル設定を確認する — 新しいページ、ホームページ、ランディングページ、スクリーンショット／モックアップの再現では、テンプレートを作成する前に config/settings_schema.json と config/settings_data.json を読み取ります。テンプレートのみの変更をユーザーが明示的に求めている場合を除き、デザインに合わせるために必要なときは、アクティブなグローバルのタイポグラフィ、色、カラースキーム、角丸、境界線、ボタンのデフォルト設定を更新します。
8. 設定台帳を作成する — JSON を作成する前に、出力する予定のすべてのグローバル、セクション、ブロック設定について、スキーマの制約を記録します。
9. テーマデザイン設定を適用する — 色、タイポグラフィ、余白、境界線、動作を、対象テーマで宣言されている実際のグローバル／セクション／ブロック設定に対応付けます。
10. JSON をコンパイルする — Shopify のテンプレート構造に従って、有効な sections、ネストされた blocks、order／block_order 配列を作成します。
11. 厳格なアップロード検証を行う — JSON テンプレートの編集では Theme Check を省略し、完了前に Shopify の厳格なアップロードバリデーターを使用します。

ワークフロー

ステップ 1 — ユーザーの要件を把握する

テキストから：

• レイアウト：グリッド、フレックス、スライダー、インラインなど
• 列数／行数
• コンテンツ：画像、ボタン、テキスト、商品カードなど
• スタイル：余白、色、レスポンシブな挙動

画像から：

• 視覚的なレイアウト、列と行、要素とその関係、余白と配置
• 視覚的な階層（見出しと本文、CTA の違い）、おおよその配置（左／中央／右）、コンテンツのカテゴリ（ヒーロー、カード、ロゴ、フッターなど）
• 曖昧な点 — 正確なブレークポイント、フォントサイズ、ピクセル単位の余白は静止画像から確実に読み取れません。推測せず、その旨を伝えてください。

デザイン画像とモックアップ

ユーザーがスクリーンショット、Figma のエクスポート、デザインモックアップを提供した場合：

• 抽出する情報： 構造（セクション、列、積み重ね順）、コンテンツの種類、定性的な余白のリズム（詰まった印象か、ゆったりした印象か）。別途指定がない限り、ピクセル単位の正確な値は抽出しません。
• まずグローバル設定を確認する： ページ全体のモックアップやブランド固有のページでは、タイポグラフィ、配色、カラースキーム、グラデーション、ボタンのスタイル、角丸、境界線、グローバルな余白の既定値を最初に更新する必要があるため、config/settings_data.json を確認してください。ユーザーがテンプレートのみの作業を明示的に依頼している場合、または既存のグローバル設定がモックアップにすでに合致している場合に限り、この作業を省略します。
• ソースファイル内の画像は無視する： スクリーンショット、Figma のエクスポート、モックアップ、その他のソースファイルから画像アセットをコピー、切り抜き、再作成、ダウンロード、複製、生成、捏造しないでください。画像は、画像／メディアブロックを配置する場所の判断にのみ使用してください。
• 空の画像ブロックまたはセクションを使用する： デザインでヒーロー、商品、ライフスタイル、ロゴ、装飾用の画像が必要な場合は、有効な画像／メディアブロックまたはセクションを追加し、画像設定は省略するか空欄にしてください。最終的な画像は、ユーザーまたは販売者がテーマエディターで提供するものとします。
• 明示されたアセットのみを設定する： ユーザーが既存のテーマアセットのファイル名、Shopify のメディア ID／参照、すでに選択されているセクション設定、またはストアフロントのアセットとして使用するよう明示的に指定したファイルを提供した場合に限り、画像／メディアの値を設定してください。
• 画像だけから具体的な Shopify の type 文字列、設定キー、列挙値を推測しないでください。必ず対象テーマの Discover allowed block types と照合してください。
• 制限事項： JSON テンプレートでは、あらゆる視覚的な詳細を表現できるわけではありません。任意のタイポグラフィ、個別の CSS、新しいマークアップ、または新しい動作が必要な場合は、このスキルの範囲外で Liquid／テーマコードの開発が必要になることがあります。そのコードはここでは実装せず、既存のスキーマで定義された JSON 設定だけではデザインを再現できない場合は、その旨を伝えてください。
• テーマで利用可能なブロックや設定だけではデザインを構築できない場合は、不足点を明示し、実現可能な範囲で最も近い構成を提案してください。

ステップ 2 — 使用可能なブロックタイプを確認する

JSON で type を指定したり出力したりする前に、必ず確認してください。これは、すべての type がテーマに存在することを検証するルールを満たすための実践的な方法です。

1. blocks/ 内のファイルを一覧表示します — テーマブロックを使用するテーマでは、blocks/<name>.liquid のベース名が有効なブロック type であることが一般的です（スキーマで確認してください）。
2. テンプレートで追加または編集する各セクションと、その中にネストする各ブロックファイルの {% schema %} を読みます。親が許可するすべてのブロック type（親に対する Shopify のルールに従い、特定のタイプ、@theme、@app など）を集めます。
   • ブロックがテーマ内のどこかに存在するかどうかだけでなく、親子の直接の各関係を検証してください。レイアウトブロックが特定のアイテムラッパーブロックのみを許可する場合、コンテンツブロックがテーマ内の別の場所で有効なテーマブロックであっても、直接の子にはできません。その子ブロックが許可している場合は、許可された子ブロックの下にネストする必要があります。
   • 明示的な blocks 配列は許可リストとして扱います。一般的なテーマブロックを許可するのは @theme のみです。特定のリストで許可されるのは、リストにあるタイプと、リストに含まれる @app のみです。

   _ プレフィックスに関する注意: ファイル名が _ で始まるブロック（例：_stat-bar.liquid）は、presets があっても、親スキーマの @theme に一致しない場合があります。Shopify theme check では、_ で始まるブロックはプライベート／静的なブロックとして扱われ、親の blocks 配列で明示的に指定する必要がある場合があります。@theme のみを宣言する親の中に _ で始まるブロックをネストする前に、既存のテンプレートやプリセットを確認し、前例があるか検証してください。前例がない場合は、親スキーマを編集せず、別の既存の許可されたブロックを選ぶか、この依頼には JSON のみのこのスキルの範囲外となる Liquid／テーマコードの作業が必要であると伝えてください。

3. 使用可能なタイプの集合を作成します — 親スキーマで許可される blocks/ 内のタイプ、親の blocks 配列で宣言されるタイプ、テンプレートレベルの sections に対する sections/<type>.liquid のセクション type 値を統合します。
4. この集合に含まれるタイプのみを使用してください。ユーザーが求めるレイアウトを実現できる既存ブロックがない場合は、最も近い実在のタイプを提案するか、同じテーマ内の動作するテンプレートをコピーするか、新しいブロックまたはセクションの追加は JSON のみの編集の範囲外であるテーマ開発作業だと伝えてください。

ステップ 3 — 同梱の例を確認する（任意）

このスキルパッケージに examples/ がある場合は、examples/README.md の「参照する最適な例の選び方」に従ってください。

• ワークスペースのテーマを、各インデックス付きの例と比較します（テーマ名、README、blocks/ のベース名と、例で説明されているタイプの重なり）。
• パターンと JSON サンプルを確認するために開けるファイルは、最も一致するもの1 つまでです。
• 該当するものがない場合は、代わりにワークスペースのテーマ内にある既存の templates/*.json のパターンをコピーします。
• 同梱の例にある type 文字列は、対象テーマの使用可能なタイプの集合に含まれるまで、絶対に出力しないでください。

ステップ 4 — 要件を実在するブロックに対応付ける

ステップ 2 で確認した使用可能なタイプの集合の範囲内で、次の作業を行います。

• テーマの blocks/ ディレクトリとセクションスキーマを検索し、レイアウトとコンテンツの要件に合うブロックを探します。
• テンプレートレベルのセクションについては、sections/ を一覧表示し、JSON の type をセクションファイルに対応付けます（通常は sections/<type>.liquid のベース名です）。

ステップ 5 — ブロックとセクションのスキーマを分析する

各ブロックまたはセクションについて、{% schema %} を確認します。

1. ネストされたブロック — "blocks": [{ "type": "@theme" }]、特定のタイプ、"blocks": [] のどれに該当するかを確認します。出力するネストの各階層について、親から子への対応表を作成し、JSON を記述する前に、各子が直近の親のスキーマに適合するかを確認します。
2. 設定 — 必須か任意か、デフォルト値、タイプを確認します。以下に注意してください。
   • range — 設定が visible_if で非表示になっている場合でも、値は min + (N * step) に正確に一致する必要があります。ここで、N は整数です。min: 10, max: 48, step: 2 の範囲では 13 は拒否されます（14 を使用します）。min: 100, step: 5 の範囲では 158 は拒否されます（160 または 155 を使用します）。設定をコピーまたは新規作成するときは、JSON を記述する前に最も近い有効なステップを計算します。
   • select — 値は options[].value の文字列のいずれかに完全一致する必要があります。有効な CSS に見える場合でも、値を独自に作成しないでください。検証に通るのは、一覧にある値だけです。
   • visible_if — visible_if で制御される設定は、非表示でもアップロード時に検証される場合があります。制御する設定が有効にしている場合を除き、非表示のカスタム専用設定は省略することを推奨します。非表示の設定をエディターのデフォルトとして残す場合も、移行先のスキーマにおける range と select の制約を満たす必要があります。
3. プリセット — 推奨される設定です。

JSON を記述する前に、スキーマ設定の台帳を作成する

出力する各セクションまたはブロックタイプについて、設定する予定の各設定に関するスキーマの制約を収集します。無効な値がテンプレートに入り込まないよう、JSON の下書きや変更を始める前に行ってください。

• range — min、max、step を記録し、すべての値を min + (N * step) に正規化します。
• select — options[].value の正確な文字列を記録し、それらの値のみを使用します。
• 型付き設定 — checkbox、number、text、richtext、image_picker、url、collection、product、blog、page に必要な JSON 値の型を記録します。
• visible_if 設定 — 検証を省略しないでください。Shopify はアップロード時に非表示の設定を検証する場合があるため、非表示のカスタム専用設定は省略するか、値を正規化してください。

アップロード時にのみ問題となる範囲の落とし穴は、テーマによって異なります。バンドルされた参照例を選択したら、その参照例を確認し、テーマ固有の設定項目や、よくある検証エラーを把握してください。テーマにかかわらず、出力する範囲の値はすべて、対象スキーマの min、max、step に適合する必要があります。

新しいページやモックアップでは、グローバル設定をまとめて確認します

スクリーンショット、Figma のエクスポート、ブランドのリファレンス、その他のビジュアルモックアップをもとにページを作成または大幅に改訂する場合は、通常の初回作業にグローバル設定の確認も含めます。セクションが正しくても、有効なテーマのタイポグラフィ、色、角丸、ボタンのデフォルト設定が別のブランドのままだと、ページ全体の見た目が意図と異なる場合があります。

対象のテンプレートを編集する前に、次の手順を行います。

1. config/settings_schema.json を読み、実際のグローバル設定 ID、設定タイプ、範囲の制約、選択肢、カラースキームの構造を確認します。
2. config/settings_data.json を読み、有効な current の値と既存の color_schemes を確認します。
3. モックアップと有効なグローバル設定を比較します。
   • タイポグラフィ：本文フォント、見出しフォント、基本サイズ、スケール比、見出しの行の高さ、見出しの大文字・小文字、ボタンのタイポグラフィ。
   • 色：本文の前景色／背景色、プライマリ／セカンダリ／ターシャリボタンの色、モバイルバー、オーバーレイの色、リンク。
   • カラースキーム：セクションの背景色、前景色、境界線、ホバー時の色、グラデーション。
   • 形状と境界線：ボタンの角丸、入力欄の角丸、要素／カードの角丸、境界線の幅。
   • ページ全体に影響するデフォルト設定：余白、間隔、ボタンのサイズ／スタイルのデフォルト設定、テーマ固有のデザイントークン。
4. ビジュアルの方向性がこれらのグローバル値に左右される場合は、config/settings_data.json を更新します。その後、スキーマで定義された設定を使って、テンプレートのセクション／ブロックに実際のグローバル設定を割り当てます。

ページ全体のビジュアルを作り込む場合は、次の順序で設定します。

• まずグローバル設定：ブランドシステム全体に関わるタイポグラフィのスケール、パレット、カラースキーム、グラデーション、ボタンのデフォルト設定、角丸、境界線のデフォルト設定。
• 次にセクション設定：背景スキームの割り当て、間隔、余白、配置、動作など、ページの構成に関わる設定。
• 最後にブロック設定：特定の見出しサイズ、局所的な色の上書き、局所的な配置、一度限りの表示ルールなど、個別の例外。

初回の作業では、通常の本文、ラベル、ボタン、商品カードのテキストにブロックレベルのカスタムフォントサイズを使用しないでください。テーマのデフォルトのタイポグラフィトークンとグローバルなタイポグラフィ設定を優先します。ブロックレベルのカスタムフォントサイズは、意図的なディスプレイ見出しや、ユーザーが正確なアートディレクションを求めている場合に限って使用します。

テーマが settings_data.json のカスタムカラースキームに対応している場合は、独自のモックアップパレットやグラデーションに合わせて、名前付きスキームを新規作成または更新することを優先します。その後、color_type: "custom" や color_scheme_custom など、スキーマでサポートされている設定を使ってセクションに割り当てます。カラースキームの構造を推測して作成せず、有効なテーマデータにある既存のスキームの構造に合わせてください。

ステップ 6 — テーマのデザイン設定を適用する

任意の custom_css よりも、スキーマで定義されたデザイン設定を優先します。関連するスキーマを先に読み、対象のテーマに存在する設定キーと値のみを出力してください。custom_css は、対象のスキーマで JSON 設定としてすでに公開されており、かつユーザーが CSS レベルの調整を明示的に求めている場合にのみ使用します。それ以外の場合、CSS に関する要件は JSON のみの対象範囲外として扱ってください。

グローバルデザイン設定（config/settings_schema.json と config/settings_data.json）：

• サイト全体の色、タイポグラフィシステム、スペーシングのデフォルト、角丸、境界線のデフォルトなど、ストア全体に広く影響する変更にはグローバル設定を使用します。
• テーマエディターに表示するグローバル設定の定義には config/settings_schema.json を、設定の有効な値には config/settings_data.json を使用します。
• グローバル値を編集する前に、両方のファイルを読み込んでください。既存の current オブジェクトの構造を維持し、設定 ID、値の型、デフォルト値、選択肢がスキーマとデータで一致するようにしてください。
• 新しいページ、ホームページ、ランディングページ、またはページ全体のビジュアルモックアップを作成する場合、現在のグローバル設定が求められるビジュアルの方向性に合わなければ、デフォルトで config/settings_data.json を更新してください。タイポグラフィ、パレット、カラースキーム、角丸、境界線、ボタンのデフォルトを調整するために、ユーザーからの追加プロンプトを待たないでください。
• ページのモックアップで特徴的なセクション背景やグラデーションが必要な場合は、色を繰り返しローカルで上書きするのではなく、config/settings_data.json の名前付き color_schemes とセクションへの割り当てを優先してください。
• タイポグラフィには、グローバルなタイプ設定と、デフォルトのリッチテキスト／ボタンのトークンを優先してください。ユーザーがローカルでの正確なアートディレクションを求めない限り、通常のテキストにはカスタムブロックフォントサイズを使用しないでください。ローカルでのカスタムサイズ指定は、例外的なヒーロー／ディスプレイ見出しに限ってください。
• グローバルスキーマ設定を追加または変更する場合は、周囲のスキーマグループ構造と Shopify の設定タイプに従ってください。カスタム Liquid、JavaScript、CSS、新しいセクションやブロックを追加するための抜け道として、設定スキーマの変更を使用しないでください。
• 任意のユーティリティクラス値やトークン名を作成しないでください。スキーマに記載された選択肢を使用してください。テーマの既存の設定データ構造が新しいカラースキーム ID に対応している場合は、説明的な ID を使用し、既存のスキームに一致する完全な設定オブジェクトを作成してください。
• 求められるデザインによってストアのビジュアルシステムが確立または変更される場合は、グローバルな変更を使用してください。ストア全体に影響させない、1つのセクションに限定した小規模な調整には、セクション／ブロック設定を優先してください。

セクション設定（sections/*.liquid）：

• セクションのスキーマで対応している場合は、スペーシング、幅、マージン、色、境界線、配置、表示／非表示、動作、背景メディアなど、レイアウトやスタイルの広範な設定にセクション設定を使用します。
• select の値は、スキーマで定義された選択肢と完全に一致させてください。ピクセル値の文字列、CSS ユーティリティ文字列、アニメーション名、クラス名を独自に作成しないでください。
• セクションに custom_css があり、ユーザーが CSS レベルの調整を明示的に求めている場合は、たとえば .rte { text-transform: uppercase; } のように、セレクターを含む完全な CSS ルールを記述してください。単独の宣言やセレクターのないルールは使用せず、スタイルシートファイルも追加または編集しないでください。

ブロック設定（blocks/*.liquid）：

• セクション内でのローカルなビジュアル調整には、スペーシング、色、境界線、形状、タイポグラフィ、レイアウト、表示／非表示、継承、アニメーションなど、ブロックのスキーマで対応している設定を使用します。
• ブロックで親セクション／コンテナーのスタイルを使用する場合は、継承設定を尊重してください。ローカルの色、タイポグラフィ、境界線を上書きするのは、対象ブロックのスキーマでその設定が定義されており、デザイン上必要な場合に限ります。
• タイポグラフィ、レイアウト、アニメーションの設定はブロックごとに異なります。すべての設定 ID、範囲のステップ、選択肢、列挙型に相当する文字列が、対象ブロックのスキーマに一致することを確認してください。
• レイアウトコンテナブロックでは、子要素に制限がある場合がよくあります。許可される子要素について各親ブロックのスキーマに従い、ネストのパターンをコピーする場合は、同じ対象テーマまたは一致が確認された同梱の例からのみコピーしてください。
• コピー先のブロックスキーマで同じ設定 ID が定義され、同じ値が許可されていない限り、あるブロックタイプの設定を別のブロックタイプにコピーしないでください。

ステップ 7 — JSON 構造をコンパイルする

Shopify の JSON テンプレートの形式に従います。テーマに Cursor ルール（例：.cursor/rules/templates.mdc、blocks.mdc、schemas.mdc）が含まれている場合は、編集対象のプロジェクトでそのルールに従います。

テンプレートの構造：

{
  "sections": {
    "<sectionId>": {
      "type": "<sectionType>",
      "settings": {},
      "blocks": {
        "<blockId>": {
          "type": "<blockType>",
          "name": "t:blocks.block_name",
          "settings": {},
          "blocks": {},
          "block_order": []
        }
      },
      "block_order": ["<blockId>"]
    }
  },
  "order": ["<sectionId>"]
}

ブロックインスタンス ID：

• 役割を表すわかりやすい接頭辞（例：layout、container、item、image、text）を使用し、テーマの既存の JSON で使われている規則に合わせます。
• ブロックインスタンス ID の先頭に _ を付けないでください。プライベートなブロック タイプ の先頭には _ を付けられます（例："type": "_grid-products"）が、そのブロックの JSON オブジェクトキーには "grid_products_best" のような有効なインスタンス ID を指定する必要があります。
• 必要に応じて、短く一意なサフィックスを付けます。
• テンプレート内（およびスキーマのルールに従い、ネストされた各 blocks スコープ内）で ID が一意になるようにします。

静的ブロックと block_order：

• 静的ブロック（"static": true）は親の blocks オブジェクトで宣言しますが、その親の block_order には記載しないでください。
• block_order は、動的に並べ替え可能な兄弟ブロック専用です。親に静的な子ブロックのみが含まれる場合は、"block_order": [] を使用するか、既存のテンプレートの形式で省略が許容されていれば省略します。
• 完了前に、各兄弟の block_order と blocks を照合します。リストされた ID はすべて存在し、"static": true を持つブロックオブジェクトを指していない必要があります。

設定（ブロックベースのテーマ）：

• レイアウトブロックには、列数、行数、間隔、パディング、レスポンシブ動作の設定が公開されていることがよくあります。対象スキーマで宣言されている設定 ID と値のみを使用します。
• テーマでブロックの name に翻訳キーを使用している場合は、それを優先します。例："t:blocks.image"。
• 色と間隔の設定は、テーマのデザインシステムに合わせます。

テンプレート全体の置き換えに関するガード：

JSON テンプレート全体を置き換えた後は、Shopify が生成したファイルヘッダーコメントを除去してファイルを解析し、トップレベルの JSON オブジェクトがちょうど 1 つであることを確認します。新しい閉じ波括弧の後に、以前のテンプレートのコピーが追加されたままにならないようにしてください。

node -e "const fs=require('fs'); const s=fs.readFileSync('templates/index.json','utf8').replace(/^\/\*[\s\S]*?\*\/\s*/, ''); JSON.parse(s);"

リッチテキストの内容に関するルール：

Shopify は、richtext と text（rich）設定の HTML をサニタイズします。使用できるタグと属性は限られています。

• 使用可能なタグ： p、h1～h6、ul、ol、li、a、br、strong、em、span
• style 属性は使用できません — <span style="color: red"> は削除されます。利用可能な場合は、スキーマで定義されたリッチテキスト設定またはタイポグラフィ設定を使用します。それ以外の場合は、インラインスタイル、スタイルシートのルール、カスタム Liquid、新しいアセットを追加せず、対応できない点として記載してください。
• リッチテキスト内のインライン要素に class 属性は使用できません。
• 既存の JSON 設定では対応できず、1 つのテキストブロック内で色付きテキストが必要なデザインの場合、これは テーマコードのカスタマイズが必要な項目です。インラインスタイル、スタイルシートのルール、カスタム Liquid、新しいアセットを追加せず、その旨を記載してください。

ステップ 8 — 検証する

完了前に、以下の検証チェックリストを実行します。

JSON テンプレートを編集した場合は shopify theme check を省略し、代わりに Shopify のアップロードバリデーターで検証します。

shopify theme push --strict --only templates/<name>.json

ホームページの場合は、次を使用します。

shopify theme push --strict --only templates/index.json

これはドライランではありません。検証に合格すると、指定したファイルがアップロードされます。そのテンプレートをアップロードしても問題ない場合にのみ使用してください。

非対話型エージェントでは、テーマ選択プロンプトを回避してください。npm run dev または shopify theme dev がすでに実行中の場合は、その出力で preview_theme_id=<theme_id> を確認し、同じ開発テーマに対して検証します。

shopify theme push --strict --only templates/<name>.json --theme <theme_id>

テーマ ID を取得できず、コマンドでテーマを選択するプロンプトが表示される場合は、プッシュ先のテーマをユーザーに確認してください。

Theme upload complete の後に表示される templates/<name>.json のエラーは、コマンドの終了コードが 0 であっても、正式なエラーとして扱ってください。失敗した場合は、コンソールのエラーを正確に検証チェックリストに転記し、その種類のエラーを防ぐローカルガードを追加してから再試行してください。

npm run dev または shopify theme dev がすでに実行中の場合は、JSON テンプレート編集の実用的な検証ループとして、そのアップロードログを使用します。

1. 編集したテンプレートを保存するか、変更を加えて、開発サーバーが同期を試みるようにします。
2. 開発用ターミナルで Failed to upload file "templates/<name>.json" to remote theme を確認します。
3. その行の下に表示されるメッセージを、Shopify の検証結果として扱います。
4. 該当するエラーの種類を修正し、まだチェックリストに記載されていない場合は追加します。
5. 開発用ターミナルに同期成功が表示されるか、そのテンプレートの新たなアップロードエラーが表示されなくなるまで繰り返します。

すでに開発サーバーが起動している場合、重複して起動しないでください。既存のターミナル出力を優先して確認します。ローカルで防止すべき、アップロード時にのみ発生する JSON テンプレートの既知のエラーは次のとおりです。

• Invalid CSS value：カスタム CSS 配列の各項目は、単独の宣言ではなく、セレクターを含む完全な CSS ルールである必要があります。

• Setting '<id>' must be a step in the range：範囲設定は、visible_if で非表示になっている設定を含め、正確な min + (N * step) の値を使用する必要があります。

• Setting '<id>' can't be less than <min> または can't be greater than <max>：範囲設定は、非表示の設定も含め、スキーマの範囲内に収める必要があります。

• '<id>' is not a valid block id：ブロックインスタンス ID に無効な文字や先頭の _ を使用してはいけません。

• static block with id '<id>' must not be present in 'block_order'：兄弟の block_order から静的ブロック ID を削除します。

• JSON が有効である

• テンプレート全体を置き換える場合、Shopify が生成したファイルヘッダーのコメントを取り除いた後に、最上位の JSON オブジェクトが 1 つだけ含まれている。閉じかっこの後にテンプレートの内容が重複して追加されていない

• セクションとブロックのインスタンス ID が、それぞれのスコープ内で一意である

• ブロックインスタンス ID は _ で始まらない。_ プレフィックスを使用できるのはブロックの type 文字列のみである

• すべての block_order が、兄弟の blocks オブジェクトのキーと一致している

• "static": true のブロックが、兄弟の block_order に含まれていない

• 最上位の order に、レンダリングするすべてのセクションキーが含まれている

• 各 type が sections/ または blocks/ に存在し、親のスキーマで許可されている

• ネストされたブロックのタイプが親に対して有効である

• 設定キーと値の型が {% schema %} に一致している

• JSON 内に存在するすべての範囲設定値について、visible_if で非表示になっている値も含め、範囲値が有効なステップ（min + N*step）に一致している

• セレクト値が options[].value と完全に一致している

• モックアップからページを新規作成する場合や大幅に改訂する場合、config/settings_data.json を確認し、アクティブなグローバル設定がすでにデザインに一致しているため意図的に変更しない場合も含めて、更新の要否を判断している

• グローバルな settings_data.json の変更について、既存または変更対象の範囲値、セレクト値、値の型、完全なカラー スキーム オブジェクトが config/settings_schema.json に照らして検証されている

• ソースファイル内の画像は使用せず、ストアフロント用のアセット値が明示的に指定されていない限り、画像／メディアブロックまたはセクションは空にする

• リッチテキストのコンテンツ文字列に style 属性や class 属性が含まれていない

• _ プレフィックス付きブロックがネストされるすべての親で、@theme だけでなく、そのブロックが明示的に一覧に含まれている

エラー処理

問題	対処方法
ブロック／セクションが見つからない	blocks/ と sections/ を検索し、近い候補を提案します
入れ子が無効	親の {% schema %} の blocks 配列を読み直します
_ ブロックが許可されていない	ブロックには _ プレフィックスが付いています。既存の許可されたブロックを選ぶか、スキーマ／Liquid の作業はこの JSON 専用スキルの対象外であることを伝えます
style 属性が削除された	Shopify はリッチテキストをサニタイズします。利用可能な場合はスキーマで定義されたテキスト設定を使用し、それ以外の場合はテーマコードのカスタマイズが必要であることを伝えます
範囲のステップ違反	スキーマの step 値を読み、値を最も近い有効なステップに丸めます
非表示の範囲違反	非表示のカスタム専用設定を省略するか、それでも検証します。非表示の設定でもアップロード時の検証に失敗することがあります
範囲の最小値／最大値違反	別のテンプレートや例から設定をコピーする場合でも、値を対象スキーマの範囲内に保ちます
無効な選択値	スキーマの options 配列にある値のみを使用します。CSS 式を作り出さないでください
モックアップ画像がコピーされた	スクリーンショットから取得した画像値を削除し、有効な空の画像／メディアブロックでレイアウトを維持します
スキーマが大きすぎる	同じテーマの動作するテンプレートからパターンをコピーします
依頼が曖昧	変更するテンプレートファイルとセクション／ブロックのインスタンスを確認します
生成されたテーマ出力	信頼できる情報源のパスが JSON／設定データの場合に限り、そのソースを編集します。それ以外の場合は、テーマコードの作業はこのスキルの対象外であることを伝えます

参考資料

ファイル	用途
reference/shopify.md	公式ドキュメントへのリンク、ファイル名、プラットフォームの制限
examples/README.md	同梱のテーマ例の選び方、ファイルの一覧

テーマリポジトリでは、.agent/rules/ に templates.mdc、blocks.mdc、schemas.mdc などのプロジェクトルールがある場合は、それらも使用します。

参照元

このスキルの内容は、以下の Shopify ドキュメントページに基づいています。Shopify がこれらのページを更新した場合は、上記の対応するセクション（`` コメントで示されています）を確認してください。

Shopify ドキュメント	このファイル内のセクション
テーマのアーキテクチャ	このスキルを使用するタイミング
JSON テンプレート	ステップ 4 — JSON 構造を組み立てる、検証チェックリスト
セクション	許可されたブロックタイプを確認する、ステップ 3 — スキーマを分析する
セクションスキーマ	許可されたブロックタイプを確認する、ステップ 3 — スキーマを分析する
ブロック	許可されたブロックタイプを確認する
テーマブロック	許可されたブロックタイプを確認する、ステップ 3 — スキーマを分析する