design-system-audit

デザインシステム監査スキル

このスキルでは、デザインシステムを体系的に監査します。対象となるのは、コンポーネントの網羅性、トークンの一貫性、ドキュメントの品質、アクセシビリティへの準拠、コントリビューションプロセス、導入状況です。出力は、デザインシステムチーム、デザイン部門のリーダー、または共有コンポーネントライブラリを評価するエンジニアリングチームが、そのまま利用できる形式です。

必要な入力

以下の情報が提供されていない場合は、ユーザーに確認してください。

• デザインシステムの名前と、対象となる製品
• 監査の範囲 — コンポーネントライブラリ／デザイントークン／ドキュメント／コントリビューションプロセス／すべて
• 現在のツール — Figma／Storybook／Zeroheight／独自ツール／組み合わせ？
• 利用チーム — デザイナーとエンジニアの人数、製品数
• 把握している課題 — チームから特に多く寄せられる不満
• ガバナンスモデル — 中央集権型チーム／分散型コントリビューター／専任チームなし
• 監査の目的 — 導入率の向上／ブランド変更の準備／新しいチームのオンボーディング／投資の正当化

プログラムによる補助

コントラスト比は目視では判断できません。AAの基準は4.5:1です。白に対する#777777は4.478（不合格）、#767676は4.54（合格）ですが、スクリーンショットをどれだけ見ても違いは判別できません。計算しましょう。

npx --yes notugly fix "#8ab4f8" "#ffffff"     # ratio, APCA, and the nearest passing colour
npx --yes notugly onepager <url> --out review.html   # every pairing, printable
npx --yes notugly vision                      # which colours merge for colour-blind viewers

notugly fixは、比率、APCAの明度コントラスト、そして選択済みの色に最も近い、基準を満たす色を返します。色相と彩度は同じです。これらの数値を推測せず、以下の表に入力してください。

決定論的で、依存関係はゼロ、モデル呼び出しもありません。そのため、実行に費用はかからず、毎回同じ結果が得られます。

トークンの一貫性とアクセシビリティのセクションでは、トークンファイルを直接指定してください。

npx --yes notugly tokens tokens.json    # W3C design tokens or a Figma variables export

これにより、不合格となる組み合わせが意味に基づいて示されます。たとえば、color.text.danger on surface.default is 2.99:1 — needs 4.5のように表示されます。これは担当者を割り当てられるバグであり、コントラストに関する一般的な注意事項ではありません。また、複数のトークン名で定義されている色にもフラグが立ちます。これは通常、システムがコピー＆ペーストを繰り返して成長した兆候です。

時間の経過による差分を把握するには、npx notugly watch <url> baseline.jsonを使うと、「新しい色」と「既存の色に0.003だけ異なる色（誰かがトークンを見つけられなかったために追加された色）」を区別できます。

出力構成

---

デザインシステム監査：[System Name]

対象製品： [製品／アプリの一覧] 監査範囲： [全体／コンポーネントのみ／トークンのみ／ドキュメント] 監査担当者： [名前／チーム] 日付： [日付] 関係者： [デザインリード、エンジニアリングリード、CPOなど]

---

全体の健全性スコア

項目	スコア（1～5）	状態
コンポーネントの網羅性	[X/5]	🟢/🟡/🔴
トークンの一貫性	[X/5]	🟢/🟡/🔴
ドキュメントの品質	[X/5]	🟢/🟡/🔴
アクセシビリティへの準拠	[X/5]	🟢/🟡/🔴
導入率	[X/5]	🟢/🟡/🔴
コントリビューションプロセス	[X/5]	🟢/🟡/🔴
全体	[X/5]	🟢/🟡/🔴

概要： [2～3文で記述します。デザインシステム全体の状態はどうですか？主な課題2つと、最大の強みは何ですか？]

---

1. コンポーネント網羅性の監査

評価方法： デザインシステムのコンポーネントと、製品で実際に使われているUIパターンを比較します。本番環境に存在するパターンのうち、システムに含まれていないものはすべて、網羅性のギャップです。

コンポーネント一覧

カテゴリ	含まれるコンポーネント	カバレッジ	不足しているもの
ナビゲーション	[Navbar, Sidebar, Breadcrumb, Tabs]	[80%]	[不足: Mega menu、mobile drawer]
フォームと入力	[Text input, Dropdown, Checkbox, Radio, Toggle, Date picker]	[90%]	[不足: Multi-select、Rich text editor]
フィードバックとアラート	[Toast, Banner, Modal, Tooltip]	[60%]	[不足: Inline validation、Progress indicator、Skeleton loader]
データ表示	[Table, Card, Badge, Avatar]	[50%]	[不足: Data grid、Stat card、Timeline、Gantt]
レイアウト	[Grid, Container, Divider, Spacer]	[70%]	[不足: Responsive breakpoint utilities]
ボタンとアクション	[Button, Icon button, FAB, Link]	[100%]	[なし]

カバレッジスコア: [本番環境の UI パターンのうち、デザインシステムがカバーしている割合: X%]

影響が最も大きい不足項目:

1. [システムに含まれていない、最もよく使われるパターン — 重複実装の最大の原因]
2. [...]
3. [...]

---

2. コンポーネント品質の監査

各コンポーネントについて、次の品質基準に照らして評価します。

コンポーネント	状態の網羅性	レスポンシブ対応	アクセシビリティ	ダークモード	Props のドキュメント	コードと Figma の一致
Button	✅	✅	✅	✅	✅	✅
Modal	⚠️ ローディング状態が未実装	✅	✅	❌	⚠️ 部分的	✅
Table	❌ ソート状態が未実装	❌ モバイルレイアウトなし	⚠️ aria-sort なし	❌	❌	⚠️ 差異あり
[Component]	[...]	[...]	[...]	[...]	[...]	[...]

凡例: ✅ 完全 — ⚠️ 部分的／一貫性なし — ❌ 未実装

重大な品質問題があるコンポーネント（ほかの作業より先に修正）:

• [...]

---

3. デザイントークンの監査

トークンのカバレッジ:

トークンの種類	定義済み	一貫して使用	問題
色	[定義済みトークン数: X]	[⚠️ — Figma でハードコードされた 16 進カラー値が 12 個見つかりました]	[製品間で CTA に primary-500 と primary-600 が一貫せず使用されています]
タイポグラフィ	[定義済みトークン数: X]	[✅]	[なし — すべての文字スタイルでトークンスケールが使用されています]
余白	[定義済みトークン数: X]	[⚠️ — X 個のコンポーネントでカスタムの余白が使用されています]	[X 個のコンポーネントで、エンジニアが余白トークンではなく任意の px 値を使用しています]
角丸	[定義済みトークン数: X]	[❌ — 未定義。各コンポーネントで値がハードコードされています]	[Button、card、modal で異なる角丸の値が使用されており、トークンがありません]
シャドウ／エレベーション	[定義済みトークン数: X]	[⚠️]	[異なるドロップシャドウ値が 3 種類使われています。エレベーションスケールはありません]
アニメーション／モーション	[定義済みトークン数: X]	[❌ — 未定義]	[コンポーネント間でトランジションの期間に一貫性がありません]

セマンティックトークンのレイヤー: [システムにはセマンティックトークン（例: color.blue.500 の上位にある color.action.primary）がありますか。それともプリミティブトークンのみですか？]

トークンの差異: [コードのトークンと Figma のトークンは同期していますか？ Token Studio、Style Dictionary などのツールを使うか、手動で比較してください。]

---

4. ドキュメント品質監査

コンポーネント／パターンごとの評価：

ドキュメントの種類	品質	課題
使用ガイドライン	[⚠️ — ガイドラインがあるコンポーネントはX%]	[ButtonとFormコンポーネントは文書化済み。NavigationとData Displayはほとんど文書化されていません]
Do / Don't の例	[❌ — ほとんどありません]	[意図が不明確なため、エンジニアがコンポーネントを誤用することが頻繁にあります]
アクセシビリティに関する注記	[⚠️ — 一部のコンポーネントに記載あり]	[形式に一貫性がなく、インタラクティブなコンポーネントにはアクセシビリティに関する注記がありません]
コード例	[✅ — Storybookのすべてのコンポーネントにコード例があります]	[...]
変更履歴	[❌ — コンポーネント単位の変更履歴がありません]	[破壊的変更が伝えられず、予期しないUIのリグレッションを引き起こしています]
移行ガイド	[❌ — ありません]	[新しいコンポーネントバージョンへのアップグレード方法がチームにわかりません]

ドキュメントのスコア： [完全で実用的なドキュメントがあるコンポーネントはX%]

ドキュメントについて、デザイナー／エンジニアから最もよく聞かれる不満： [例：「この用途でModalとDrawerのどちらを使うべきか見つけられない。ガイダンスがない」]

---

5. アクセシビリティ監査

WCAG 2.2への準拠状況：

基準	レベル	状況	影響を受けるコンポーネント
色のコントラスト（テキスト）	AA	[✅ / ⚠️ / ❌]	[例：❌ — 3つのコンポーネントで、無効状態のテキストが4.5:1の比率を満たしていません]
色のコントラスト（UIコンポーネント）	AA	[✅ / ⚠️ / ❌]	[...]
キーボード操作	AA	[✅ / ⚠️ / ❌]	[⚠️ — Modalのフォーカストラップが実装されておらず、Dropdownはキーボードで操作できません]
フォーカスの可視化	AA	[✅ / ⚠️ / ❌]	[...]
スクリーンリーダーのサポート（ARIA）	AA	[✅ / ⚠️ / ❌]	[❌ — Tableコンポーネントにaria-sortがなく、Iconボタンにaria-labelがありません]
タッチターゲットのサイズ	AA	[✅ / ⚠️ / ❌]	[⚠️ — X個のコンポーネントで、モバイルのタップターゲットが44×44px未満です]
動き／アニメーション	AA	[✅ / ⚠️ / ❌]	[...]

重大なアクセシビリティ上の阻害要因（次回リリース前に修正必須）：

1. [最も重大な問題 — 例：キーボード利用者がModalを閉じられない — フォーカストラップがありません]
2. [...]

---

6. 導入状況の監査

チーム／プロダクトごとの導入状況：

プロダクト／チーム	システムのコンポーネントの使用状況	システム外で作成されたカスタムコンポーネント	導入スコア
[Product A]	[UIのX%でシステムのコンポーネントを使用]	[Y個のカスタムコンポーネント]	[高／中／低]
[Product B]	[...]	[...]	[...]

チームが導入していない理由：

障壁	深刻度	根拠
[必要なコンポーネントが存在しない]	高	[チームのアンケートで最も多い理由]
[コンポーネントは存在するが、用途に合わない]	中	[Modalコンポーネントに、Product Bが必要とするX状態がありません]
[使い方を把握するにはドキュメントが不十分]	中	[...]
[システムの使用を徹底する人がおらず、独自に作るほうが簡単]	高	[...]
[システムがプロダクトの現在のビジュアル言語に追いついていない]	中	[...]

---

7. 貢献プロセスの監査

項目	現状	評価
貢献方法	[文書化済み／未文書化]	[✅ / ❌]
貢献の基準	[システムに追加する項目の明確な採用基準]	[⚠️ — 何をシステムのコンポーネントにし、何をローカルに留めるか、誰が決めるのか不明確です]
レビューのプロセス	[誰が貢献をレビューし、どれくらい時間がかかるか]	[❌ — 正式なレビューがなく、貢献が何週間も未レビューのままです]
リリース頻度	[システムのリリース頻度]	[⚠️ — 不定期で、決まった頻度がありません]
破壊的変更のポリシー	[破壊的変更の対応方法と告知方法]	[❌ — ポリシーがなく、破壊的変更が突然発生します]
バージョニング	[セマンティックバージョニングを採用しているか]	[✅ — すべてのパッケージでsemverを使用しています]

---

8. 優先順位付きの改善ロードマップ

優先度	取り組み	影響	工数	時期
P1	[X] 件の重大なアクセシビリティの問題（キーボード操作、ARIA）を修正する	重大 — 法的要件とユーザーへの影響	中	スプリント 1～2
P1	角丸とシャドウのトークンスケールを定義して実装する	高 — 不整合を解消	低	スプリント 1
P1	使用頻度の高い上位 10 個のコンポーネントを文書化する（使い方と推奨事項・非推奨事項）	高 — 導入を促進	中	スプリント 2～4
P2	スケルトンローダーとインライン検証コンポーネントを構築する（不足している上位 2 項目）	高 — 個別実装の重複を解消	高	第 2 四半期
P2	レビューの SLA を含む貢献プロセスを確立する	中 — 成長を促進	低	スプリント 3
P3	ダークモードのトークンサポート	中 — プロダクト間の同等性	高	第 3 四半期
P3	デザインとコードのトークン同期ツール（Token Studio / Style Dictionary）	中 — 乖離を低減	中	第 2～3 四半期

---

品質チェック

• デザインシステムと実際の本番 UI を比較して、カバレッジの不足を特定している（推測に頼っていない）
• アクセシビリティの問題について、具体的な WCAG 基準と影響を受けるコンポーネントを挙げている
• 導入の障壁を、インタビュー、アンケート、利用データなどの証拠で裏付けている（推測に頼っていない）
• 改善ロードマップに工数の見積もりがあり、影響に基づいて順序付けられている
• Figma だけでなく、Figma とコード（Storybook／実装）の両方を評価している
• デザイン、エンジニアリング、プロダクトの関係者が監査結果を確認している

アンチパターン

• コード実装を確認せず、Figma ライブラリだけを評価しないでください。Figma とコードの乖離は、デザインシステムで最もよくある、コストの大きい失敗の一つです
• チームにインタビューせずに導入状況を評価しないでください。監査ツールの指標では、チームがシステムを使わずにカスタムコンポーネントを構築する、人間側の理由を見落とします
• すべてのコンポーネントの不足を同等に扱わないでください。アルファベット順ではなく、カスタム実装に依存している本番画面の数に基づいて優先順位を付けてください
• ドキュメントの品質を監査する前に、コンポーネントの追加を推奨しないでください。ドキュメント化されていないコンポーネントは、コンポーネントがない場合よりも問題になることがあります
• 取り組みごとに明確な担当者を決めずに、改善を予定に組み込まないでください。担当者のいないデザインシステムの改善は、停滞することが少なくありません

使用例となるトリガーフレーズ

• 「デザインシステムの一貫性とカバレッジを監査してください」
• 「コンポーネントライブラリを確認して、不足している項目を特定してください」
• 「共有デザインシステムの健全性を評価してください」
• 「リブランドを行う前に、デザインシステムの監査を実施してください」
• 「デザインシステムの問題点と、最初に修正すべきことを教えてください」