icon-design

アイコンデザイン

SVG と CSS を使って、一貫性があり、アクセシブルで、美しいアイコンシステムを作成します。

前提条件

• .agents/design-context.md を読みます（design-context を参照）。Brand Marks の「Icon Style」フィールド（例：「アウトライン、2px のストローク、丸い端」）で、描画するすべてのアイコンの塗りつぶし、ストローク幅、端点／結合部のスタイルを設定します。共有カラー・トークンのセマンティックカラー（--success-*、--error-* など）を使用します。
• プロジェクトですでにアイコンライブラリ（Lucide、Heroicons、Phosphor、Material Symbols）を使用している場合は、別のスタイルを混在させず、そのグリッドとストロークに合わせます。新たに描画するより、ライブラリのアイコンを優先して使用してください。

---

ステップ 1：SVG アイコンの基本

基本テンプレート

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"
  width="24" height="24" fill="none" stroke="currentColor"
  stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
  
</svg>

主な属性

属性	値	理由
fill	none	デフォルトでアウトラインアイコンにする
stroke	currentColor	CSS からテキストの色を継承する
stroke-width	2	すべてのアイコンで一貫させる
stroke-linecap	round	親しみやすく、モダンな印象にする
stroke-linejoin	round	一貫性を保つため、linecap と合わせる
viewBox	0 0 24 24	標準の 24px グリッド

---

ステップ 2：アイコングリッドシステム

グリッドサイズ

グリッド	用途	ストローク幅
24x24	デフォルトの UI アイコン	2px（軽めのセットでは 1.5px）
20x20	コンパクトな UI、フォームフィールド	1.5px
16x16	インラインテキスト、バッジ	1.5px（または塗りつぶし）
32x32	機能アイコン、ナビゲーション	2-2.5px
48x48	イラストアイコン、ヒーロー	3px

可能な限り、各サイズをそれぞれ独自のグリッド上に整数ピクセル座標で描画します。24px のアイコンを CSS で 16px に縮小すると、ストロークも縮小され（2px が 1.33px になり）、ぼやけます。そのため、16px のバリエーションを描画するか、パスに vector-effect="non-scaling-stroke" を使用します。

キーラインの形状（24x24、Material スタイル）

• ライブエリア：20x20（各辺に 2px の余白）。この余白は視覚的なはみ出しの調整だけに使います
• 円：直径 20x20
• 正方形：18x18（同じサイズの正方形より円のほうが小さく見えるため、正方形は小さめに描画します）
• 縦長の長方形：16w x 20h、横長の長方形：20w x 16h

CSS によるサイズ指定

.icon { width: 1.5rem; height: 1.5rem; flex-shrink: 0; display: inline-block; vertical-align: middle; }
.icon-sm { width: 1rem; height: 1rem; }
.icon-md { width: 1.25rem; height: 1.25rem; }
.icon-lg { width: 2rem; height: 2rem; }
.icon-xl { width: 3rem; height: 3rem; }

---

ステップ 3：視覚的な位置合わせの補正

形状	補正
三角形／再生	約 1px 右にずらす（視覚的な重心を考慮）
円	正方形より約 10% 大きく描画する（キーラインは 20 対 18）
縦長の形状	垂直方向の中央に配置し、必要に応じて Y 位置をわずかにずらす
先端が尖った形状	先端をグリッド境界より少し上に伸ばす

セット全体でストローク幅を同一に保ちます。ストロークを変えるのではなく、サイズと位置で視覚的に補正してください。ストロークの太さの不揃いは、セットの一貫性を損なう最も目立つ要因です。

---

ステップ 4：アイコンのスタイル

アウトライン（ストロークベース）

最も汎用性が高く、あらゆるサイズで使えて、拡大縮小にも適し、視覚的な重さも控えめです。fill="none" stroke="currentColor" を使用します。

塗りつぶし（ソリッド）

視覚的な重さが増します。アクティブ状態／選択状態や小さなサイズに適しています。fill="currentColor" を使用します。

デュオトーン（二色）

主線のストロークに、透明度を下げた副色の塗りつぶし領域を組み合わせます。複雑さを抑えながら奥行きを加えます。

.icon-duotone { --icon-primary: currentColor; --icon-secondary: currentColor; }
.icon-duotone .icon-bg { fill: var(--icon-secondary); opacity: 0.15; }
.icon-duotone .icon-fg { stroke: var(--icon-primary); fill: none; }

角丸と角張った形状

丸みのある形状（stroke-linecap: round）は親しみやすく、モダンな印象を与えます。角張った形状（stroke-linecap: square/butt）は精密で技術的な印象を与えます。どちらかを選び、アイコンセット全体に適用してください。混在させないでください。

ステップ 5：意味に基づくアイコンの選択

操作	アイコン	備考
閉じる	X	常にコンテナーの右上に配置します
戻る	左矢印	または左シェブロン
メニュー	3 本の横線	ハンバーガーメニュー
検索	虫眼鏡	通常、検索入力欄に配置します
設定	歯車	またはフィルター設定にはスライダー
ユーザー	人のシルエット	円と頭の形
通知	ベル	ドットバッジを付けることもできます
削除	ゴミ箱	確認を伴う操作に使用します
編集	鉛筆	または四角と鉛筆
追加	プラス	FAB では円で囲みます
共有	ボックスから上向きの矢印	または分岐矢印
ダウンロード	下向き矢印と横棒	下向きシェブロンとは区別します
チェック／完了	チェックマーク	確認済みの状態では円で囲みます
情報	円の中の i	青の意味色
警告	！付きの三角形	黄／アンバーの意味色
エラー	X の入った円	赤の意味色

---

ステップ 6：カスタム SVG アイコンのテクニック

パスデータのコマンド

• M：移動、L：線を引く、H/V：水平線／垂直線
• C：三次ベジェ曲線、A：円弧、Z：パスを閉じる
• 相対座標には小文字を使用します（多くの場合、短くなります）

プリミティブからの構築

<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
     stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
  <polyline points="3 11 12 3 21 11"/>
  <path d="M5 10v9a1 1 0 0 0 1 1h4v-6h4v6h4a1 1 0 0 0 1-1v-9"/>
</svg>

---

ステップ 7：アイコンとテキストの配置

/* Inline alignment */
.icon-text { display: inline-flex; align-items: center; gap: 0.5rem; }
.icon-text .icon { width: 1.25em; height: 1.25em; flex-shrink: 0; }

/* Button with icon */
.btn-icon { display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.625rem 1.25rem; }
.btn-icon .icon { width: 1.25em; height: 1.25em; margin-left: -0.125em; }

/* Icon-only button */
.btn-icon-only { display: inline-grid; place-items: center; width: 2.75rem; height: 2.75rem; padding: 0; border-radius: 0.5rem; } /* 44px target */

---

ステップ 8：アニメーションアイコン

ホバー時の回転

.icon-interactive { transition: transform 0.2s ease; }
.icon-interactive:hover { transform: rotate(90deg); }

読み込みスピナー

.icon-spinner { animation: spin 1s linear infinite; }
@keyframes spin { to { transform: rotate(360deg); } }

チェックマークの描画

pathLength="1" はパスの長さを正規化するため、測定する必要はありません：

<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
  <path class="draw" pathLength="1" d="M5 12.5l4.5 4.5L19 7.5"/>
</svg>

.draw { stroke-dasharray: 1; stroke-dashoffset: 1; animation: draw 0.4s var(--ease-out, ease-out) forwards; }
@keyframes draw { to { stroke-dashoffset: 0; } }
@media (prefers-reduced-motion: reduce) { .draw { animation: none; stroke-dashoffset: 0; } }

ホバー時の回転も同様にラップします。スピナーはモーションを減らす設定でも回転を続けてかまいません（装飾ではなく状態を伝えるためです）が、回転を遅くするか、透明度を点滅させる表示に切り替えてください。

---

ステップ 9：アイコンのアクセシビリティ

ルール

1. 装飾用アイコン（テキストラベルの隣にあるアイコン）：aria-hidden="true" focusable="false"
2. 意味のあるアイコン（単独で使うアイコン）：ボタンに aria-label を指定し（内部の SVG に aria-hidden="true" を指定）、または SVG 内で <title> を使い、role="img" aria-labelledby を指定します
3. 重要な操作をアイコンだけに頼って伝えてはいけません。必ずテキストによる代替を用意します
4. アイコンボタン：24x24px は最小ターゲットサイズであり、WCAG 2.2 AA の基準（SC 2.5.8）です。44x44px（Apple HIG、WCAG AAA 2.5.5）または 48x48dp（Material）を目指してください
5. 意味を伝えるアイコンは、背景に対して 3:1 のコントラスト比が必要です（SC 1.4.11）

.icon-button { min-width: 44px; min-height: 44px; display: inline-grid; place-items: center; }

---

ステップ 10：一般的な UI アイコンのパターン

バッジインジケーター

.icon-with-badge { position: relative; display: inline-block; }
.icon-badge {
  position: absolute; top: -4px; right: -4px;
  width: 10px; height: 10px; background: var(--error-500);
  border-radius: 50%; border: 2px solid var(--bg-primary, white);
}

ステータスインジケーター

.status-icon { position: relative; }
.status-icon::after {
  content: ''; position: absolute; bottom: 0; right: 0;
  width: 8px; height: 8px; border-radius: 50%; border: 2px solid var(--bg-primary, white);
}
.status-icon--online::after  { background: var(--success-500); }
.status-icon--offline::after { background: var(--gray-400); }
.status-icon--busy::after    { background: var(--error-500); }

ステータスドットは色だけで状態を示します。テキストラベルまたは aria-label（「オンライン」）を組み合わせ、リングには white ではなく var(--bg-primary) を使用して、ダークモードでも正しく表示されるようにしてください。

---

アイコンセットを検証する

16、20、24、32px の各サイズで、明るい背景と暗い背景の両方に、テキストラベルの隣へすべてのアイコンを表示したスクラッチパッド HTML ページをレンダリングし、スクリーンショットを撮影します（npx playwright screenshot --full-page "file://$PWD/icons.html" icons.png）。Read で画像を確認し（16px の 4 倍拡大版も確認）、アイコン全体の視覚的な重みが均等か、線幅が統一されているか、viewBox の端で図形が切れていないか、図形がキーポイントに揃っているか、16px で認識できるかをチェックします。

---

クイックリファレンス

1. 一貫した viewBox（デフォルトは24x24）を使用し、ライブエリアには2pxのパディングを設けます。
2. スタイル（アウトライン、塗りつぶし、デュオトーン）を1つ選び、セット全体で統一します。
3. アイコンにテキストの色を継承させるため、stroke="currentColor"を使用します。
4. ストローク幅は一定に保ちます（24x24では2px）。
5. 三角形や円には視覚的な補正を加えます。
6. テキストとインラインで配置するアイコンのサイズにはem単位を使用します。
7. 装飾用アイコンには必ずaria-hidden="true"を追加します。
8. アイコンのみのボタンには必ずaria-labelを追加します。
9. タッチターゲットは44x44pxを目指します（24x24pxはWCAG 2.2 AAの最小サイズです）。
10. 描画アニメーションにはstroke-dasharrayとstroke-dashoffsetを使用します。