AI-friendly デザインガイドライン#

このページは、AI-Turtle（生成 AI）と相性の良いデザインデータを作るための指針です。
生成 AI の精度を高めるには、それに合わせたデータ構造が必要です。
この手順を守ることで、人間にも AI にも扱いやすいデータになります。

「AI-Turtle 独自設定」と付いているものは、AI-friendly とは別に、AI-Turtle 側の設定によって実現可能にしている機能になります。必要に応じて活用してみてください。

チェックリスト#

• テキストノードをオートレイアウト化している
• レイヤー名は役割を表す名前にして、HTML タグに結びつけやすくなっている
• Figma のレイヤー構造を、可能な範囲で HTML ツリーに寄せている
• SP と PC でツリー構造が同一になっている
• フレームの幅を固定幅にしていない
• 不要な要素は削除、または非表示にしている
• バリアブルモードは「Auto」になっている（もしくは未設定）
• AI-Turtle を使う場合は必要に応じてレイヤー名に <h1> や <Campaign> などを付けて実装方針を指示できている

テキストをオートレイアウト化する#

テキストを直置きすると、生成時に取りこぼされることがあります。
親フレームでオートレイアウト化すると、この問題を防げます。
特に理由がなければ、基本的にオートレイアウト化することを推奨します。

推奨	非推奨
テキストがオートレイアウト化されている。	テキストノードが直置きされている。

レイヤー名には意味を持たせる#

生成 AI は文脈が分からない場合、div タグを多用します。
見出しには「タイトル」や「heading」、説明文には「description」などの名前を使うと、適切な HTML タグが選ばれやすくなります。
Frame123 のような自動名よりも、役割を示す名前にしてください。

• 見出しなら … タイトル、heading など
  • h1, h2 などで実装されやすい
• 説明文なら … リード文、description など
  • p で実装されやすい

推奨	非推奨
意味のあるレイヤー名になっている。	機械的なレイヤー名になっている。

HTML ツリー構造に合わせる#

Figma のレイヤー構造が HTML のツリーと近いほど、AI-Turtle の出力精度は高くなります。
例えば、table > tbody > tr > td > コンテンツ のように構造をそろえると、正しいタグで実装される可能性が高まります。
ただし保守性も考慮して、無理のない範囲で適用します。

より良い	普通
Figma のレイヤー構造と HTML のツリー構造が合っている。	Figma のレイヤー構造と HTML のツリー構造が異なっている。

SP と PC の構造をそろえる#

AI-Turtle はメディアクエリーの実装も可能ですが、SP と PC で構造が異なると制御が難しくなります。
行や列の配置は、レスポンシブ対応を前提に同じ階層構造にそろえましょう。
これにより、プロンプトの余計な指示が不要になる上に、デザインデータの一括置換がしやすいなどの恩恵があります。

SP と PC で構造が違う例#

SP	説明
	すべての子要素がフラットに置かれている。

PC	説明
	子要素が2つずつグループ化されている。

最大幅は Max width で指定する#

最大幅 800px の場合、Fixed width = 800 にすると固定幅となり、実装崩れの要因になります。
Max width = 800px とし、幅は Fill container に設定してください。
この方法ならスムーズにレスポンシブ実装をすることができます。

推奨	非推奨
Max width + Fill で設定されている。	Fixed width で設定されている。

不要な要素は非表示か削除する#

opacity = 0 で見えなくすると、その要素も HTML に出力されます。
不要な要素は削除するか、非表示にしてください。
これにより、精度の低下を防げます。

推奨	説明
	不要な要素を非表示にしている。

非推奨	説明
	不要な要素を opacity = 0 にしている。

バリアブルモードは Auto に戻す#

Figma にはバリアブルモードという機能があります。

バリアブルモード（Figma 公式ドキュメント）

Turtle もこのバリアブルモードを実装していて、例えば typography の xs を有効にすると SP 表示時の文字サイズをエミュレートできます。

この機能はデザインレビュー時に便利ですが、AI-Turtle にとっては精度を下げる一因になります。

Turtle はデフォルトでレスポンシブタイポグラフィに対応しており、画面幅に応じて文字サイズが変わります。
SP で文字サイズが小さくなるのはこのためです。
SP, PC の各 CSS で別々の文字サイズを設定しているわけではありません。あたっているスタイルは1つだけです。

このエミュレート状態で AI-Turtle を走らせると、その（小さい）文字サイズでコーディングされてしまいます。
前述の通り、文字が小さくなるのはレスポンシブだからであって、小さめの px が指定されているわけではありません。

AI-Turtle を使う際はバリアブルモードはデフォルト状態（Auto）に戻しておいてください。

推奨	非推奨
バリアブルモードがデフォルト (Auto) になっている。	バリアブルモードが xs になっている。

HTML タグを指定する （AI-Turtle 独自設定）#

Figma のレイヤー名に <h1> や <p> を付けると、そのタグで実装されます。
タグは小文字で始める必要があります。
見出しや説明文など、タグを明確にしたい場合に利用します。

前述の「意味のあるレイヤー名」と似ていますが、こちらの方がより確実です。
デザイン時にタグの種類まで設計できているなら是非利用してみてください。

カスタムコンポーネントを指定する （AI-Turtle 独自設定）#

レイヤー名に <Campaign> のように書くと、その名前のカスタムコンポーネントが定義されます。
コンポーネントの名前は大文字で始める必要があります。
エンジニアと連携してローカルコンポーネントを定義する際に役立ちます。