AI エージェントにも守られる、デザインシステムのガイドラインの書き方。Figma の Guidelines から考える、項目・型・確かめ方

Figma の Guidelines でできること（2026年11月時点）

機能や条件は変わりやすいので、この節にまとめます。出典は Figma のヘルプ「Add guidelines files to a design library」と「What's new from Config India 2026」です。

ヘルプには、Figma MCP や外部のコーディングエージェントが Guidelines を読むという記載はありません。コード側への届け方は、あとの節で別に書きます。

エージェントが外すのは「判断」が書かれていないから

コンポーネントと変数のライブラリから、エージェントは「何があるか」は読み取れます。けれども、次のような判断はライブラリのどこにも書かれていません。

• 主ボタンと副ボタンを、どの場面で使い分けるか
• カードの内側とカード同士の間に、どの余白の変数を使うか
• 似たコンポーネント（たとえばトーストとバナー）のどちらを選ぶか
• この組み合わせだけは使わない、という禁止

人のデザイナーなら、レビューや過去の画面から少しずつ覚えていきます。エージェントは、書かれていないことは毎回推測するしかありません。だから、ガイドラインは「部品の説明書」ではなく「選び方の判断の記録」として書きます。

何を書くか：ファイルの分け方

Figma のヘルプは、ファイル名の例として overview.md、guidelines.md、components.md、examples.md、anti-patterns.md、best-practices.md を挙げています。どこから手をつけるかについては、色・余白・角丸から始めるのがよいとしています。これを踏まえると、最初の版は次の5つで十分です。

書くときのコツは3つです。

• 値ではなく変数の名前で書く。「16px」ではなく、ライブラリにある変数の名前で書きます。エージェントが変数を探す手がかりになります。変数の名前を役割で付けておけば（例：space/card-inset）、値を変えてもガイドラインを直さずに済みます。
• 選択肢を並べるだけにせず、推奨を1つ書く。ヘルプも、選べるものを説明するだけでなく、はっきりした推奨を書くよう勧めています。
• 例外のないルールは「使わない」と言い切る。「なるべく避ける」と書くと、エージェントは使ってよい場面を探します。

どう書くか：シナリオ・Do・Don't・理由の型

間違えやすい判断は、ヘルプが勧める「シナリオごとの Do と Don't」で書きます。1つのシナリオに、場面の説明、Do の例、Don't の例、その理由をそろえます。GOV.UK Design System が各コンポーネントに「When to use」と「When not to use」を並べ、Atlassian Design System がボタンの使い方を Do と Don't の対で示しているのと同じ考え方です。

components.md の1節の例です（説明用の作例です）。

## 元に戻せない操作の確認ダイアログ

場面：削除・解約・公開の取り消しなど、元に戻せない操作の直前に出すダイアログ。

- Do：実行のボタンは Button / Danger、取り消しは Button / Secondary。
  ボタンの文言は「削除する」のように操作を書く。
- Don't：Button / Primary を2つ並べる。実行のボタンを「OK」にする。
- 理由：Primary は「先に進む」操作の印。元に戻せない操作と同じ見た目にすると、
  押し間違いが起きやすい。文言が「OK」だと、何が起きるか分からない。

tokens.md の余白の節の例です（変数の名前と値は作例です）。

## 余白

- 余白は space/* の変数だけを使う。数値を直接書かない。
- カードの内側は space/card-inset、カード同士の間は space/card-gap、
  セクションの間は space/section。
- Don't：13px・18px など、変数にない値。カードの内側と外側を同じ変数にする。
- 理由：内側より外側を広くすると、どこまでが1枚のカードかが分かる。

コード側にも同じルールを届ける（Figma MCP・AGENTS.md）

画面を作るのが Figma agent だけとは限りません。エンジニアがコーディングエージェントで実装するなら、同じ判断をコード側にも渡す必要があります。2026年11月時点で、使える入口は次のとおりです。

おすすめは、ガイドラインの正本をリポジトリに1つだけ置くことです。たとえば design-guidelines/ に Markdown で書き、同じファイルを Figma のライブラリにアップロードし、AGENTS.md からも参照します。

<!-- AGENTS.md（抜粋） -->
## UI を作るとき
- 先に design-guidelines/ の overview.md・tokens.md・components.md・anti-patterns.md を読む。
- 色・余白・角丸は、デザイントークンの変数だけを使う。値を直接書かない。
- 迷ったら anti-patterns.md の禁止を優先する。

Figma 側だけを直して、コード側のルールが古いまま、というずれを防げます。

守られているかを確かめる

ガイドラインは、書いたら終わりではありません。エージェントに同じ依頼を出して、出てきた画面を確かめます。

1. 試す依頼を5本ほど決める。一覧、詳細、フォーム、確認ダイアログ、空の状態など、よく作る画面で。
2. ガイドラインを足す前と後で、同じ依頼を出す。変数にない値、選ぶべきでないコンポーネント、禁止の組み合わせを数えます。
3. 外れたら、その例を anti-patterns.md に足す。「何をしたか」「代わりに何をするか」「理由」の3つで書きます。
4. 量を確かめる。合計が推奨の 100KB を超えてきたら、重なっている記述をまとめます。

合計の大きさは、次のコマンドで確かめられます（Ubuntu 24.04 の bash で動作を確かめました）。

# design-guidelines/ の .md・.txt・.json の合計（バイト。100KB ≒ 100000 バイト）
find design-guidelines -type f \( -name '*.md' -o -name '*.txt' -o -name '*.json' \) \
  -exec cat {} + | wc -c

ガイドラインが長くなると、AI クレジットの消費が増えることがあります。量を増やすより、外れやすい判断に絞って書くほうが効きます。

まとめ：最初の1週間でやること

• □ よく外れる判断（色・余白・角丸、似たコンポーネントの選び分け）を書き出したか
• □ 値ではなく変数の名前で、推奨を1つに決めて書いたか
• □ 間違えやすい判断を「シナリオ・Do・Don't・理由」の型で書いたか
• □ 例外のない禁止を anti-patterns.md に言い切りで書いたか
• □ 正本を1つにして、Figma のライブラリと AGENTS.md・CLAUDE.md の両方に届けたか
• □ 試す依頼を決めて、足す前と後で比べたか

ガイドラインを「エージェントに読ませる文書」として書き直すと、新しく入ったメンバーにも伝わりやすい文書になります。ツールが変わっても、判断を言葉にしておいた分は残ります。

MODS BASE では、デザインシステムの整備や、AI を取り入れた制作の進め方のご相談も承っています。気になることがあれば、お気軽にお声がけください。

参考

• Add guidelines files to a design library（Figma Learn - Help Center）
• What's new from Config India 2026（Figma Learn - Help Center）
• Here's everything from Config India 2026（Figma Forum）
• Tools and prompts（Figma MCP Server Developer Docs）
• Add custom rules and instructions（Figma MCP Server Developer Docs）
• AGENTS.md
• How Claude remembers your project（Claude Code Docs）
• Rules（Cursor Docs）
• Radios – GOV.UK Design System
• Button - Usage - Components - Atlassian Design