LPやコーポレートサイトを並行で触っていると、Figma バリアント 命名が案件ごとにバラバラになり、実装側が「Primaryってどの状態？」と毎回聞き返す——そんな週があります。私もWebディレクションと実装を兼ねるので、デザイン段階で名前を揃えておかないと、自分の未来の自分が困ります。
本記事は、大規模デザインシステムを新規構築する話ではありません。進行中の案件ファイルで、ボタン・入力欄・カードのバリアント名を実装と同じ言葉に寄せる運用に絞ります。コンポーネントライブラリ全体の整理はFigmaコンポーネント整理の手順に、エクスポートの話はWeb実装向け書き出しに任せ、ここでは命名とプロパティだけを片付けます。
この記事でわかること
- バリアントのプロパティ名・値を実装（props）と揃えるルール
- 8個を超えたら分割する判断と、命名の3階層上限
- Dev Modeで実装者が確認すべきチェックリスト
先に結論
- 向いている人: 小〜中規模のWeb制作で、FigmaからHTML/CSSやコンポーネント実装に渡す人。フリーランスで案件が2本以上並行している人。
- 向いていない人: すでに社内DSで命名規約が固定されている大規模チーム（本記事は上書き不要）。Figmaを使わず画像のみ渡す案件。
- 私のおすすめ: State / Size / Variant の3プロパティまでに抑え、値は英語小文字の
defaulthoverdisabledに統一してから、FigmaのDev Modeで1コンポーネントだけ試読する。
命名を揃えるのは地味ですが、実装の差し戻しが1回減るだけで、案件の後半がかなり楽になります。
この記事には、Google AdSense による広告およびアフィリエイトリンクが含まれる場合があります。紹介経由で購入や申し込みがあると、私に紹介料が入ることがあります。
なぜバリアント命名が実装のボトルネックになるか
Figmaのバリアントは、デザイナーにとっては「1コンポーネントに状態をまとめる便利機能」です。一方、実装では props や CSSクラス、場合によっては data属性 に落ちます。ここで言葉がズレると、次のようなやり取りが増えます。
- 「デザインの Secondary は、コードの
outlineで合ってますか？」 - 「Disabled は見た目だけ？ 操作不可も含みますか？」
- 「Mobileサイズは、768px未満全部ですか？」
私の案件では、命名を揃える前はボタン1種類の確認にSlackが3往復、揃えたあとはDev Modeのスクショ1枚で済むことが多いです（案件によります。一般論として、名前がpropsと一致していると会話が短くなりやすい、という話はFigma Code Layersの整理でも触れています）。
プロパティ名を3種類までに絞る
まず プロパティ名（Variantの列見出し）を増やしすぎないことが重要です。私が小規模案件で使う上限は次の3つです。
| プロパティ名 | 実装での対応例 | 入れる値の例 |
|---|---|---|
| State | :hover / aria-disabled |
default, hover, focus, disabled |
| Size | padding / font-size トークン | sm, md, lg |
| Variant | 見た目の系統 | primary, secondary, danger |
Icon や Theme を別プロパティにしたくなる場面はありますが、4列目を足す前に「別コンポーネントに分けられないか」を見ます。例えば、アイコン付きボタンとテキストのみボタンを1つの巨大バリアントにまとめるより、Button と ButtonWithIcon に分けた方が、命名も実装も短く済むことが多いです。
具体例を1段落足します。先月のコーポレート案件では、カードに「画像あり／なし／動画あり」を1プロパティ Media に入れていました。実装側は media=none|image|video を想定していたのに、デザイン側は NoImage と WithoutPhoto が混在し、Storybookのargsが増えました。プロパティを分けずに値のスペルだけ統一した時点で、差し戻しはほぼ止まりました。見た目の差が大きいなら、最初からコンポーネント分割すべきだった、という反省もあります。
値の命名ルール（英語・小文字・意味固定）
プロパティ名が決まったら、値を固定語彙にします。私のチーム内メモ（1人制作でも同じ）では次を守ります。
- 英語小文字とハイフン —
primary,secondary,sm,md（キャメルCaseは避ける） - Boolean風の名前を避ける —
isHoverよりhover（State列に置く） - 案件固有の略語を値に入れない —
clientA-blueはトークン側。Variant値はprimaryのまま - default は必ず1つ — 実装の初期propsと一致させる
日本語ラベルはレイヤー内のテキストや注釈フレームに書き、バリアント値には載せません。Dev Modeでコピーされるのは値側なので、日本語値は後から検索も置換もしにくいです。
私は「デザイン用の日本語」と「コード用の英語」を混ぜないように、値は英語だけに寄せています。
8個ルール：バリアント数が増えたら分割
Figmaコンポーネント整理でも触れている 8パターン超えたら分割 は、命名の話とセットです。バリアント数 State(4) × Size(3) = 12 になると、一覧で選ぶのも実装で網羅するのも大変です。
分割の目安は次のとおりです。
- 見た目の系統が違う → Variantで分けるのではなく 別コンポーネント
- レイアウト構造が違う → オートレイアウト設定が別なら分割
- 実装ファイルが別（Button / Link）→ Figmaも別コンポーネント
逆に、色だけ違うなら Variables やスタイルで持ち、バリアント列を増やさない方が、命名の保守コストは下がります。Figma Variablesの整理と役割分担すると、バリアントは「構造と状態」、Variablesは「色と余白」——と割り切れます。
実装前ハンドオフ：Dev Modeで見る5点
命名を直したら、Dev Mode（またはInspect）で実装者視点の確認を1回だけ回します。詳しいワークフローはFigma Dev Modeの進め方に任せつつ、バリアント命名だけのチェックリストは次です。
- 表示されているプロパティ名が、実装のprops名と一致しているか
- default が、ページで最も多い状態か
- disabled に見た目だけでなく、注釈で「操作不可」が書いてあるか
- hover / focus がキーボード操作を想定しているか（focusが無いと実装が足す）
- Size がブレークポイントと対応表で1行説明されているか
私は案件ファイルの先頭ページに _Handoff フレームを1枚置き、上記5点をチェックボックス付きで書きます。デザイン変更が入っても、命名だけは _Handoff を更新すれば、実装側の混乱が減ります。
失敗しやすいパターン
- Primary / Secondary を案件ごとに色の意味で使い分ける — 実装は毎回確認が必要になる。意味はドキュメント1行で固定する
- バリアント値にスペース —
Large Buttonよりlg。スペースは検索・コード生成で事故りやすい - 古いインスタンスを放置 — 命名を直しても、ページ上の古いインスタンスが旧値のまま残る。ライブラリ更新後に Review instances を実行する
- プラグイン出力と命名が別体系 — Code Connect等を使う場合は、プラグインが期待する名前を先に読む（Figmaと実装のレイヤー名）
価格やプランは執筆時点（2026年11月2日・日本時間）の情報です。Figmaの機能名やDev Modeの提供条件は変わることがあります。購入・契約前にFigma公式を確認してください。
今日から使える作業手順
- 進行中ファイルで いちばん使うボタン を1つ選ぶ
- プロパティを State / Size / Variant に再編（4列目があるなら分割を検討）
- 値を 英語小文字 に一括置換（旧インスタンスを更新）
_Handoffフレームに default と disabled のスクショ を貼る- 実装側（または未来の自分）に Dev Mode のリンクを1本渡す
最初の1コンポーネントだけで十分です。全部一度に直そうとすると、命名議論だけで1日溶けます。
案件ファイル内の共有テンプレ（コピー用）
命名ルールを口頭で伝えるより、フレーム1枚の表を _Handoff に置く方が、クライアントや外注デザイナーにも伝わりやすいです。私が使っている最小テンプレは次のとおりです（文言は案件で調整してください）。
| コンポーネント | State | Size | Variant | 実装メモ |
|---|---|---|---|---|
| Button | default / hover / focus / disabled | sm / md / lg | primary / secondary | props名と同一 |
| TextField | default / focus / error / disabled | md | — | errorはaria-invalid連動 |
表を更新した日付を 日本時間 で1行書いておくと、「いつから新命名か」が後から追えます。実装側が古いFigmaリンクを開いても、_Handoff の日付で判断できます。
よくある質問
Q. バリアント命名は日本語のままでも実装できますか？
A. 技術的には可能ですが、propsやクラス名は英語になることが多いので、二重管理になります。デザイン注釈は日本語、バリアント値は英語——と役割を分ける方が、小規模チームでもトラブルが少ないです。
Q. 8個ルールは厳しすぎませんか？
A. 目安です。6×2=12のように数が増えた時点で、実装ファイルを2つに分ける判断材料にしてください。命名が増えるほど、テストパターンも増えます。
Q. クライアント確認用に日本語ラベル付きバリアントを見せたいです
A. プレゼン用の複製ページを別に作り、そこだけ日本語注釈を足す方法が安全です。本番のコンポーネント命名は英語のまま維持し、確認後に複製ページをアーカイブします。
Q. 既存案件の命名を途中から変えると実装が壊れませんか？
A. これから触るコンポーネントから適用し、リリース済みページは旧名のまま残す期間を設けるのが現実的です。変更ログを _Handoff に1行書くだけで、実装側の置換範囲が明確になります。
まとめ
Figma バリアント 命名は、見た目の作業ではなく 実装との契約 に近い部分です。プロパティは3種類まで、値は英語小文字、8個を超えたら分割——この3つをボタン1つに試すだけでも、ハンドオフの会話は短くなりやすいです。
今日やること: いちばん使うボタンのバリアント一覧を開き、プロパティ名が State Size Variant のどれかに当てはまるか確認する。当てはまらない列があれば、分割か改名を1つだけ決める。
関連記事: Figmaコンポーネント整理の手順 / Figma Dev Modeワークフロー / 在宅Mac作業環境の柱
