audit-uiux-design-system

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

自由度：混在 — ステップ 0～3、5～6 は [HIGH freedom]、ステップ 4 の playwright キャプチャは [LOW freedom — run exactly] です。ブラウザーを使う前に protocol-browser-anti-stall を読んでください。ブレークポイントのみの場合は → audit-responsive を使用します。

推論の進め方

1. 観察 — トークンファイル、未加工の 16 進数コード、またはスクリーンショットを引用します
2. 解釈 — これはシステムトークンか、個別の実装か、AI らしさを示すものかを判断します
3. 分類 — トークン漏れ／コンポーネントの重複／状態の欠落／テンプレート化／適切
4. 重大度 — コアプリミティブの未加工の色 = P0、ホバーの欠落 = P1、角丸の小さな問題 = P2

具体例

観察： Button.tsx で bg-[#3B82F6] が使われています。globals.css には --primary があります。 解釈： プリミティブがトークンの SSOT を迂回しているため、ダークモードで切り替えられません。 分類： コアプリミティブでのトークン漏れです。 重大度： P0 — すべてのボタンで 16 進数コードがハードコードされています。 指摘事項： Button.tsx | 色トークン | P0 | bg-primary に置き換えます。

報告前の自己批評 [LOW freedom — do not skip]

1. まずトークンを確認 — 2 つ目のスケールを作らないでください
2. 証拠を提示 — .playwright-mcp/ 内のスクリーンショット、または引用したクラスを示してください
3. 重大度を正当化 — P0 = コアプリミティブがトークンを使っていない、またはコントラストが使用不能
4. 適切な担当先 — デスクトップが直線的に並ぶ場合 → audit-responsive、WCAG のキーボード操作 → audit-accessibility
5. 手作りの個性 — テンプレートの画一性を高める提案は避けてください

テンプレート化を防ぐ

提案では好みを尋ねるのではなく、何を避けるべきかを明示してください。その分野で受賞歴のあるサイトを調査し、リズムを変化させ（py-16 を一律に使わない）、各コントロールに独自のホバー／フォーカス／アクティブ／無効状態を与え、個性を表すトークン（角丸、タイポグラフィの語り口）を定義します。指摘すべきデフォルトの例 — 最初の草案が採用したものをもとに、このリストを拡張してください：セクションのパディングが一律、汎用的または紫色のグラデーション、同じ大きさのカード 3 枚／アイコン・タイトル・説明の 3 列レイアウトをデフォルトにする、クリーム色またはオフホワイトのページ背景、見出し中の斜体のアクセント語、「01/02/03」の番号付きセクションラベル、等幅フォントのラベル、ボタンをすべてピル形にする、唯一のタイポグラフィの語り口として Inter/Roboto を使う、空状態に lorem を使う、角丸を一律にする、手を加えずに既製のイラストを使う。

---

ステップ 0：デザインシステムを自動検出する

0a. CSS フレームワークの検出

シグナル	テクノロジー
tailwindcss v3 + tailwind.config.*	Tailwind CSS v3
tailwindcss v4 + CSS 内の @theme	Tailwind CSS v4
*.module.css ファイル	CSS Modules
styled-components または @emotion/styled	CSS-in-JS
@chakra-ui/react	Chakra UI
@mui/material	Material UI
@mantine/core	Mantine

0b. コンポーネントライブラリの検出

Glob: **/components/ui/*.tsx → shadcn/ui
Glob: **/components/ui/*.vue → Vue component lib
Glob: **/components/ui/*.svelte → Svelte component lib
Grep: "from '@radix-ui" glob "*.{ts,tsx}" output_mode "count"
Grep: "from 'lucide-react" glob "*.{ts,tsx}" output_mode "count"
Grep: "from '@heroicons" glob "*.{ts,tsx}" output_mode "count"
Grep: "from 'react-icons" glob "*.{ts,tsx}" output_mode "count"

0c. デザイントークンの検索

Glob: **/tailwind.config.*
Glob: **/app/globals.css
Glob: **/styles/tokens.*
Glob: **/theme.*
Grep: "--primary|--secondary|--accent|--muted" glob "*.css"

トークンのソースを読み、色、スペーシング、タイポグラフィ、角丸、シャドウを抽出します。

0d. 禁止パターンの確認

Grep: "NEVER|FORBIDDEN|DO NOT" glob "**/*README*" -i

0e. 検出結果の記録

DESIGN SYSTEM DISCOVERY:
- CSS framework: [Tailwind v3/v4 / CSS Modules / Styled Components / etc.]
- Component library: [shadcn/ui / Radix / MUI / Chakra / custom]
- Icon library: [Lucide / Heroicons / react-icons / mixed]
- Token source: [file path]
- Colors defined: [count]
- Typography scale: [list]
- Spacing base: [4px / 8px / etc.]
- Border radius: [list]
- Shadow levels: [list]
- Dark mode: [YES — class/media / NO]
- Forbidden patterns: [list from README]

---

ステップ 1：デザインシステムのベストプラクティスを調査する

1a. Context7 — コンポーネントライブラリのドキュメント

context7:resolve-library-id
{
 "libraryName": "<DETECTED_COMPONENT_LIBRARY>",
 "query": "component variants accessibility patterns"
}

次に、解決した ID を使ってドキュメントを取得します。CSS フレームワークのドキュメントも取得します。

1b. Firecrawl — デザインシステムの標準

firecrawl:firecrawl_search
{
 "query": "<COMPONENT_LIBRARY> design system audit token compliance best practices [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

追加のクエリ：

トピック	クエリ
トークン準拠	design token audit <CSS_FRAMEWORK> consistency
コンポーネントパターン	<FRAMEWORK> component modularity composition patterns
ダークモード	<CSS_FRAMEWORK> dark mode implementation best practices

1c. Firecrawl — 受賞歴のある参考サイト

firecrawl:firecrawl_search
{
 "query": "<PRODUCT_TYPE> website design award Awwwards Muzli [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

firecrawl:firecrawl_search
{
 "query": "<PRODUCT_TYPE> SaaS UI design inspiration unique not generic [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

際立ったサイトを 2～3 件スクレイピングし、グリッドの崩し方、特徴的なモーション、タイポグラフィの語り口、アクセントの使い方を確認します。

---

ステップ 2：トークン準拠の監査

2a. カラートークン

ルール	標準	確認方法
セマンティックな命名	primary、secondary、destructive、muted、accent	コンポーネントに生の hex/rgb 値がないこと
CSS 変数	hsl(var(--primary)) または oklch()	すべての色が変数を参照していること
前景色のペア	すべての背景色に *-foreground があること	テキストのコントラストが維持されていること
ダークモード	すべてのトークンにダークモード用のバリアントがあること	.dark クラスまたは @media
ステータスカラー	success、warning、error、info が定義されていること	アラート、バッジ、トースト全体で一貫していること

違反を見つける：

Grep: "(#[0-9a-fA-F]{3,8}|rgb\(|rgba\(|hsl\([^v])" glob "*.tsx"
Grep: "\[(#|rgb|hsl)" glob "*.tsx"

2b. タイポグラフィトークン

ルール	標準
フォントファミリー	テーマ内で最大 2～3 種類
サイズスケール	一貫していること（text-sm、text-base、text-lg）
ウェイトスケール	限られたセット（font-normal、font-medium、font-semibold、font-bold）
見出しの階層	視覚的なウェイトと DOM 順序の両方で h1 > h2 > h3
任意のサイズ指定なし	text-sm がある場合に text-[14px] を使用しないこと

Grep: "text-\[" glob "*.tsx"
Grep: "font-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black)" glob "*.tsx" output_mode "count"

2c. 余白トークン

ルール	標準
基本単位	4px グリッド（Tailwind のデフォルト）
ギャップの一貫性	同じコンテキストでは同じ余白を使用すること
任意の値なし	p-3 がある場合に p-[13px] を使用しないこと

Grep: "(p|m|gap|space)-\[" glob "*.tsx"

2d. ボーダー、角丸、シャドウ

Grep: "rounded-\[" glob "*.tsx"
Grep: "shadow-" glob "*.tsx" output_mode "count"

---

ステップ 3：コンポーネントのモジュール性監査

3a. コンポーネントの健全性

ルール	標準
単一責任	1 つのコンポーネントにつき 1 つの目的
合成可能	小さな部品を組み合わせて大きなコンポーネントを構成できること
再利用可能	同じ UI には、どこでも同じコンポーネントを使用すること
props の一貫性	すべてで variant、size、disabled、className を使用すること
バリアントのパターン	スタイルのバリアントには cva() または同様のものを使用すること

3b. 重複したコンポーネントを見つける

Grep: "<button " glob "*.tsx" — raw buttons outside ui/ (should use Button)
Grep: "<input " glob "*.tsx" — raw inputs (should use Input)
Grep: "<select " glob "*.tsx" — raw selects
Grep: "<a " glob "*.tsx" — raw anchors (should use Link)

components/ui/* は除外してください。これらは正規のプリミティブです。

3c. コンポーネントの一貫性を確認する

Grep: "function (Button|Input|Modal|Dialog|Card)" glob "*.tsx" output_mode "files_with_matches"

3d. アイコンライブラリの混在

Grep: "from .lucide-react" glob "*.tsx" output_mode "count"
Grep: "from .@heroicons" glob "*.tsx" output_mode "count"
Grep: "from .react-icons" glob "*.tsx" output_mode "count"

---

ステップ 4：実環境でのビジュアル検証（playwright-cli）

4a. 移動してキャプチャする

PW="npx --yes @playwright/cli@latest"
$PW -s=ds-audit open --headed "http://localhost:<PORT>/<ROUTE>"
sleep 2
$PW -s=ds-audit snapshot                                              # verify content rendered
$PW -s=ds-audit screenshot --filename ".playwright-mcp/ds-<route>.png"  # visual evidence
$PW -s=ds-audit console                                               # check for errors

4b. ページごとの確認項目

確認項目	方法
トークンへの準拠	スクリーンショットで色や余白の不一致を確認
コンポーネントの再利用	スナップショットで共通プリミティブが使われているか確認
コンソールエラー	console でハイドレーションや CSS 変数の不足を確認
レイアウトシフト	インタラクションの前後でスナップショットを確認
ダークモード	ダークモードに切り替えて再撮影し、比較

4c. レスポンシブ確認

次の 3 つのビューポートでテストします。

• デスクトップ（1440px）
• タブレット（768px）
• モバイル（375px）

4d. ビジュアルアクセシビリティ

確認項目	方法
色のコントラスト	テキストは 4.5:1、大きなテキスト/UI は 3:1 — トークンペアの値から計算します（1 行のスクリプトまたは DevTools のアクセシビリティペインを使用）。スクリーンショットで確認できるのは使用されているペアであり、比率の測定はできません
フォーカスリング	要素を Tab キーで移動し、フォーカスインジケーターが表示されることを確認
セマンティック HTML	`Grep: "
代替テキスト	`Grep: "<(img

---

ステップ 5：マイクロインタラクションとユーザーフィードバック

5a. マイクロインタラクションの網羅性監査

各インタラクティブ要素を確認します。

要素	期待されるフィードバック	不足している場合の AI っぽさ
ボタン	ホバー：色の変化＋さりげない影の変化。アクティブ：押下時に scale(0.98)。読み込み中：ラベルをスピナーに置き換えるか、インラインインジケーターを表示	平坦で状態変化がない — 反応がなく感じられる
リンク	ホバー：即座に切り替えるのではなく、下線のアニメーションまたは色のトランジション	トランジションなしで色が瞬時に変わる
カード（クリック可能）	ホバー：浮き上がる（translateY ＋ 影が濃くなる）。色の変化だけでは不十分	色が変わるだけ、またはホバー効果がまったくない
入力欄	フォーカス：リングのアニメーションまたは境界線色のトランジション。アウトラインを置き換えるだけでは不十分	ブラウザーのデフォルトのアウトラインで、カスタムのフォーカス表示がない
トグル／スイッチ	状態遷移をアニメーション化し、瞬時に切り替えない。イージングで触覚的な感覚を表現	状態が瞬時に切り替わる
ドロップダウン／メニュー	即座に表示／非表示にするのではなく、スライドまたはフェードで開閉	トランジションなしで瞬時に表示される
トースト／通知	スライド＋フェードで表示し、フェードで消す。プログレス表示とともに自動で閉じる	瞬時に表示／非表示になる
モーダル／ダイアログ	背景をフェードさせ、コンテンツを拡大／スライドさせる。終了時は逆の動きにする。瞬時に表示しない	突然表示され、唐突に感じられる
タブ	即座に切り替えるのではなく、アクティブインジケーターを新しいタブへスライドさせる	色が瞬時に切り替わる
ツールチップ	少し遅延させる（200～300ms）とともにフェードインする。マウス移動時にちらつかせない	即座に表示され、ちらつき、遅延がない

コード内で確認する：

Grep: "transition-all|transition-colors|transition-opacity|transition-transform" glob "*.tsx" output_mode "count"
Grep: "hover:|group-hover:|focus-visible:" glob "*.tsx" output_mode "count"
Grep: "animate-|animation-|@keyframes|framer-motion|motion\." glob "*.tsx" output_mode "count"
Grep: "scale-|translate-|rotate-" glob "*.tsx" output_mode "count"

5b. インタラクション状態の網羅性

インタラクティブ要素ごとに、すべての状態が存在することを確認します。

States checklist per component:
□ Default (resting)
□ Hover (mouse over)
□ Focus-visible (keyboard navigation)
□ Active/pressed (during click)
□ Disabled (grayed, not clickable, cursor-not-allowed)
□ Loading (async action in progress)
□ Error (validation failed, destructive context)
□ Success (completed action)

不足している状態を見つける：

Grep: "focus-visible:|focus:" glob "*.tsx" output_mode "count"
Grep: "active:|pressed" glob "*.tsx" output_mode "count"
Grep: "disabled:|cursor-not-allowed|opacity-50" glob "*.tsx" output_mode "count"

5c. 視覚的なリズムと個性の監査

意図的な多様性と、均一な繰り返しを見分けます。

パターン	洗練された印象	テンプレートの印象
セクション間隔	コンテンツの種類に応じて変化する（ヒーロー：ゆったり、フォーム：詰める、CTA：広め）	すべてのセクションで同じ py-16
タイポグラフィのコントラスト	見出しと本文に大きな差をつける（例：48px → 16px）。ウェイトも組み合わせる	段階的なサイズで、どこでも同じウェイト
アクセントカラーの使用	すべての要素に使うのではなく、強調のために控えめに使う	すべてのボタン、リンク、アイコンにプライマリーカラーを使用
レイアウトの変化	セクションごとに異なるレイアウト（左にテキスト／右に画像、全幅、サイドバー）	同じ3列のカードグリッドを繰り返す
角丸	意図的に使い分ける（タグはピル型、カードは角丸、データテーブルは角張らせる）	すべてに同じ rounded-lg
影の深さ	階層的な浮き上がりを表現するため、複数の影レベルを使う	すべて同じ影、または影がない
余白	非対称なマージンで視覚的な流れと読みのリズムを作る	完全に対称で、機械的な間隔

---

ステップ6：アニメーションとダークモード

アニメーション

ルール	基準
再生時間の段階	150ms（マイクロ）、200ms（ホバー）、300ms（表示）、500ms（複雑） — すべて同じにしない
イージング	表示には ease-out、終了には ease-in、状態変化には ease-in-out — すべてを ease-in-out にしない
モーション低減	motion-safe: プレフィックスまたは prefers-reduced-motion
レイアウトシフトなし	トランジションによって CLS が発生しない
スタガー効果	リスト項目やカードグリッドは、すべて一度にではなく、遅延をつけて順次アニメーション表示する

Grep: "duration-[0-9]+" glob "*.tsx" output_mode "count"
Grep: "transition-" glob "*.tsx" output_mode "count"
Grep: "prefers-reduced-motion|motion-safe|motion-reduce" glob "*.tsx"
Grep: "stagger|delay-\[|animation-delay" glob "*.tsx" output_mode "count"

ダークモード

ルール	基準
すべてのトークンを切り替える	ダークモードで CSS 変数を変更する
ハードコードされた色を使わない	bg-white、text-black は使わず、セマンティックトークンを使う
境界線が見える	どちらのモードでも見える
コントラスト	ライトモードとダークモードの両方で WCAG に準拠する
後付けにしない	ダークモードは、色を反転しただけではなく、意図してデザインされているようにする。影はグローに、境界線は控えめな表示にする

Grep: "(bg-white|bg-black|text-white|text-black)" glob "*.tsx" output_mode "count"

---

出力テンプレート

## UI Design System Audit Report

**Date:** [date]
**Framework:** [detected]
**CSS:** [Tailwind v3/v4 / CSS Modules / etc.]
**Component library:** [shadcn / Radix / MUI / custom]
**Pages Audited:** [count]
**Issues Found:** [count]

---

### Design Token Compliance

| Token Category | Defined | Violations | Status |
|----------------|---------|------------|--------|
| Colors | [count] | [count] raw hex/rgb | [pass/warn/fail] |
| Typography | [count] | [count] arbitrary sizes | [pass/warn/fail] |
| Spacing | [count] | [count] arbitrary values | [pass/warn/fail] |
| Radii | [count] | [count] arbitrary radii | [pass/warn/fail] |
| Shadows | [count] | [count] inconsistent | [pass/warn/fail] |

---

### Component Health

| Component | Used In | Variants | Issues |
|-----------|---------|----------|--------|
| Button | [N] files | [N] | [notes] |
| Input | [N] files | [N] | [notes] |
| Card | [N] files | [N] | [notes] |

---

### Duplicate / Redundant Components

| Pattern | Locations | Recommendation |
|---------|-----------|----------------|
| Raw `<button>` | [files] | Use `<Button>` from `components/ui` |
| Custom modal | [file] | Use `<Dialog>` from `components/ui` |

---

### Visual Accessibility

| Criteria | Status | Issues |
|----------|--------|--------|
| Color contrast | [pass/warn/fail] | [details] |
| Focus indicators | [pass/warn/fail] | [details] |
| Alt text | [pass/warn/fail] | [details] |
| Semantic HTML | [pass/warn/fail] | [details] |

---

参考資料

• マイクロインタラクションの網羅性など