Horizon UIデザインキットからShopifyテンプレートJSONを自動生成する
先日公開したHorizonテーマのUIデザインキットには、デザイン検証以外にもう一つの意図があります。テーマエディタで設定可能なセクション名やブロック名をFigmaのコンポーネント名と1:1で対応させることで、AIが各要素を正しく判別し、テンプレートJSONとして出力できるようにしています。
キット内のセクションやブロックのパーツを並べれば、Figma MCPのget_design_contextで構造データを取得し、命名規則に基づいてShopifyのテンプレートファイルに変換する、という流れです。
テンプレートJSONとLiquidコードについて
Shopifyのテーマには「テンプレートJSON」と「Liquidコード」の2つのレイヤーがあります。
-
テンプレートJSON（
templates/*.json）：どのセクションをどの順番で配置し、各設定をどうするか。テーマエディタで編集する部分 -
Liquidコード（
sections/*.liquid）：セクション自体の見た目や動きを定義するコード。開発者が書く部分
今回自動化するのはテンプレートJSONの方です。テーマのコードには一切触れないので、テーマのアップデートとも干渉しません。
コード改修せずテンプレート設定にとどめる理由
Horizonは従来のShopifyテーマとは構造がかなり異なります。ロジックファイルと描画ファイルが複雑に分散されており、CSSとJavaScriptによる疎結合のイベント制御が随所に使われています。この特殊な設計のため、中途半端にコードをいじると思わぬところに影響が出るリスクがあります。
それ以上に、Horizonはアップデートのたびに性能やUIが改善されているテーマなので、コードを直接変更してしまうとその恩恵を受けられなくなります。テーマ更新時にコンフリクトが発生し、更新を見送り続けるか、差分を手作業でマージし続けるか、という運用負荷を抱えることになります。
そう考えると、カスタマイズのレベルをテーマエディタで設定可能な範囲にとどめておく方が、長期的には健全な運用になるのではないかと思っています。テンプレートJSON（セクションの構成と設定値）だけを自動化するアプローチは、この考え方に基づいています。
ワークフロー全体の流れ
- Figmaデザインキット上でテンプレートを組む
- Figma MCPでデザインの構造データを取得（Claude Code）
- 命名規則に基づいてテンプレートJSONに変換（Claude Code）
- 画像をShopify Filesにアップロード（Claude Code）
- 商品・コレクション・ブログを割り当て（Claude Code）
- テーマに反映（Claude Code）
つまりFigmaでデザインを行なったあとの工程はすべてClaudeが担います。これをClaude Codeのスキルとして定義し、コマンドで実行できるようにしています。
命名規則がすべてを決める
この仕組みの精度を決めるのは、Figma上のコンポーネント名です。get_design_contextは各要素のレイヤー名やコンポーネント名を構造データとして返してくれます。
コンポーネント名がShopifyテーマの構造と一致していれば変換は単純なマッピングで済みますが、一致していなければAIが推測する必要があり精度が落ちます。
UIデザインキットの設計段階から以下の命名規則を採用しました。
| Figma コンポーネント名 | Shopify テンプレートJSON |
|---|---|
section:{type}:{variant} |
セクション type + settings |
block/{category}/{type} |
ブロック type |
たとえばFigma上で「カルーセル4列」のセクションを配置すれば、名前の:carousel-4colの部分から自動的に"layout_type": "carousel", "columns": 4が生成されます。バリアントを切り替えるだけで、JSONの設定も変わります。
この命名規則はキットの設計段階で決めた「契約」のようなもので、AIはこの契約に従って機械的に変換するだけです。推測に頼らないので結果が安定します。
実行例：12セクションのストアトップページ
デザインキット上で12セクション構成のホームページテンプレートを組み、Claude Codeのスキルで変換しました。
| # | Figma フレーム名 | セクション |
|---|---|---|
| 1 | section:hero |
hero |
| 2 | section:product-list:carousel-4col |
product-list（カルーセル4列） |
| 3 | section:media-with-content:editorial |
media-with-content（エディトリアル） |
| 4 | section:collection-list:bento |
collection-list（ベントー） |
| 5 | section:section:pull-quote |
汎用セクション（引用） |
| 6 | section:product-list:grid-4col |
product-list（グリッド4列） |
| 7 | section:featured-product |
featured-product |
| 8 | section:section:image-with-text |
汎用セクション（画像+テキスト） |
| 9 | section:featured-blog-posts:carousel-3col |
featured-blog-posts（3列） |
| 10 | section:section:email-signup |
汎用セクション（メール登録） |
| 11 | section:section:faq |
汎用セクション（FAQ） |
| 12 | section:section:icons-with-text |
汎用セクション（アイコン+テキスト） |
約15回のget_design_context呼び出しで12セクション・約60ブロックのテンプレートJSONが生成され、11枚の画像もShopify Filesに自動アップロードされました。
セクションの基本構成だけでなく、意図的に追加したデフォルトには存在しないブロックもしっかり拾ってくれます。たとえばヒーローセクションにaccordionブロックを追加したり、テキスト付きメディアにproduct-recommendationsブロックを追加した場合でも、Figma上のコンポーネント名からそれを判別して、テンプレートJSON上に正しく反映されます。
ブロック構造の再現レベルについて
ただし、現時点ではHorizonのネストブロック構造を完全にFigmaパーツとして再現しているわけではありません。デザインキットをさらに作り込んで全ブロック階層をパーツ化すれば、より精密な変換も可能になるかもしれませんが、いまは曖昧な部分を残しつつClaude Codeの判断に任せている状態です。
前提と制約
- 命名規則に準拠したデザインキットが必要：任意のFigmaファイルからは変換できない。Horizonの場合、38種のセクションtypeと92種のブロックtypeのマッピングテーブルを用意。初期構築には工数がかかるが、一度作れば繰り返し使える
-
staticブロックの扱い：
_product-cardや_collection-cardのようなstaticブロックはblock_orderに含めてはいけない等の制約があり、テーマごとの個別対応が必要 - Figma MCPのレート制限：Starter/View/Collabは月6回（実質使用不可）、Organization（Dev/Full）は1日200回、Enterprise（Dev/Full）は1日600回。今回は約15回なのでOrganizationなら十分