ux-visibility-review

name	ux-visibility-review
version	1.0.0
description	色合いのキツさ・隣接要素の色被り・トーン不統一・視認性の悪さを使用感ベースのUX観点で検出し、修正案を標準出力に報告する。報告のみでコードは変更しない。WCAG コントラスト比など数値基準の準拠検証は style-review を使う

UX Visibility Review

実装コードからカラー定義と使用箇所を抽出し、「人間の目で見た時に見づらい・疲れる・区別しにくい」問題を検出するスキル。 WCAG 準拠の技術的検証ではなく、実際の使用感に基づくUXレビュー（WCAG 検証は /style-review の担当）。

ガードレール

• このスキルは 検出と報告のみ を行う。コードや色定義の修正は行わない（修正案を提示し、適用はユーザーの指示を待つ）

Quick Start

/ux-visibility-review [対象ディレクトリ]

対応プロジェクト

• Swift App: SwiftUI / AppKit（Color, NSColor, Asset Catalog）
• Electron App: CSS / テーマファイル（CSS変数, color プロパティ）

検出する問題

1. 色がキツい（目が疲れる）

高彩度・高明度の色が広い面積で使われていると視覚的に攻撃的になる。

検出基準（HSL ベース）:

• 彩度 (S) > 80% かつ 明度 (L) が 40〜60% の色 → 「ビビッドすぎる」
• 純色に近い原色（#FF0000, #00FF00, #0000FF 付近）がテキストや背景に使われている
• ネオンカラー（高彩度 + 高明度）が UI 部品に使われている

修正案の方向:

• 彩度を 10〜20% 下げる（鮮やかさを落としてトーンを揃える）
• 明度を調整して「落ち着いた」バリエーションを提案
• 例: #FF0000 → #DC2626（少しだけ暗く）、#00FF00 → #22C55E（彩度を落とす）

2. 隣接要素の色が似すぎて区別しにくい

横並び・縦並びで隣り合う UI 要素の色が近すぎると、境界が曖昧になり認知負荷が上がる。

検出基準（CIE ΔE 2000）:

• 隣接要素間の色差 ΔE < 5 → 「ほぼ同じに見える」（High）
• 隣接要素間の色差 ΔE < 10 → 「似ていて区別しにくい」（Medium）
• 背景色とボーダー色の ΔE < 5 → 「ボーダーが見えない」

隣接要素の推定方法:

• Swift: 同一 VStack/HStack/List 内の子ビュー同士
• CSS: 同一親セレクター内の兄弟要素、flex/grid コンテナの子要素
• タブバー・ナビゲーション・ツールバー内のアイテム同士

修正案の方向:

• 色相 (H) を 30° 以上離す
• 明度 (L) を 15% 以上離す
• ボーダーや余白で視覚的な区切りを追加する提案

3. 前景と背景のトーンが合っていない

テキスト色と背景色の「暖色/寒色」や「彩度レベル」が不統一だと違和感が生まれる。

検出基準:

• 背景が暖色系 (H: 0〜60°) なのにテキストが寒色系 (H: 180〜270°)、またはその逆で彩度が共に高い
• 背景がパステル調 (S < 30%, L > 80%) なのにテキストがビビッド (S > 70%)
• 同一画面内でトーン（暖色/寒色/無彩色）が3種以上混在

修正案の方向:

• 同一トーンファミリーに揃える提案
• 無彩色（グレースケール）をベースにしてアクセントカラーを1〜2色に絞る

4. 似た役割なのに異なる色

同じ意味の要素に別の色が使われていると、ユーザーが混乱する。

検出基準:

• 「プライマリボタン」相当の要素に2種以上の色が存在
• エラー表示に異なる赤系の色が複数使われている
• リンクテキストの色が画面ごとに異なる

修正案の方向:

• カラーパレットの統一（セマンティックトークンの提案）
• 「この色をこっちにも使えば統一される」という具体案

5. Dark モードでの色の破綻

Light モードでは問題ないが Dark モードに切り替えると破綻するパターン。

検出基準:

• Light で映える中間色が Dark 背景で沈む（テキストと背景の明度差 L < 30%）
• Dark モードなのに明るすぎる背景色（L > 40%）が残っている
• シャドウや微妙なグラデーションが Dark モードで消失（背景との ΔE < 5）

実行フロー

1. プロジェクト種別判定
   ├── *.xcodeproj / Package.swift → Swift App
   └── package.json / *.css → Electron App

2. カラー定義の抽出
   ├── Swift: Asset Catalog JSON + コード内 Color/NSColor/UIColor
   ├── CSS: 変数定義 (:root) + プロパティ値
   └── テーマファイル: エクスポートされた色定数

3. 色の使用コンテキスト分析
   ├── どの要素にどの色が使われているか
   ├── 隣接関係の推定（レイアウトコンテナの解析）
   └── Light/Dark 両モードでの色マッピング

4. 問題検出
   ├── HSL 変換して彩度・明度チェック
   ├── CIE ΔE 2000 で隣接色の色差計算
   ├── トーンの一貫性チェック
   └── セマンティック色の統一性チェック

5. 修正案の生成
   ├── 具体的な色コード（HEX）を提案
   ├── 変更前後の色差を数値で示す
   └── 標準出力に Markdown で報告

カラー抽出の具体的手順

Swift App

1. Glob: **/*.colorset/Contents.json → Asset Catalog の色定義
   - "components" の r/g/b/a 値を抽出
   - "appearances" から Light/Dark の色を分離
2. Grep: Color\(|\.foregroundColor|\.foregroundStyle|\.background|\.tint
   → コード内の色使用箇所
3. Grep: \.primary|\.secondary|\.accentColor → システムカラー使用
4. レイアウト構造: VStack/HStack/List/ForEach を追跡して隣接関係を推定

Electron/CSS

1. Glob: **/*.css, **/*.scss → スタイルファイル
2. Glob: **/theme*.{ts,js}, **/colors*.{ts,js} → テーマ定義
3. Grep: --[a-z-]*color|--bg-|--text-|--border- → CSS 変数
4. :root と prefers-color-scheme: dark の色を分離
5. flex/grid コンテナ内の子セレクターから隣接関係を推定

色差の計算

CIE ΔE 2000（隣接要素の区別しやすさ）

人間の色知覚に基づく色差指標。数値が大きいほど違って見える。

ΔE 値	体感
< 1	人間には区別不能
1〜5	注意すれば分かる程度
5〜10	一目で分かるが「似ている」
10〜25	明確に異なる色
> 25	全く別の色

HSL 分析（色のキツさ判定）

RGB → HSL 変換:
  H (色相): 0〜360°
  S (彩度): 0〜100%（0=無彩色, 100=純色）
  L (明度): 0〜100%（0=黒, 100=白）

「キツい色」= S > 80% かつ 40% < L < 60%

出力形式

## UX Visibility Review

### 概要
- プロジェクト種別: Swift App
- 検証ファイル数: 12
- 検出問題数: 7 (High: 2, Medium: 3, Low: 2)

---

### High: サイドバーのアイテム色が隣接で区別できない

**場所**: `Views/SidebarView.swift:34-52`
**問題**: `HStack` 内の `.labelColor (#3B82F6)` と `.iconColor (#4F8EF7)` の色差 ΔE = 3.2 で、ほぼ同じに見える
**修正案**:
- `.iconColor` を `#1D4ED8` に変更 → ΔE = 18.5（明確に区別可能）
- または `.labelColor` をグレー系 `#374151` にしてアイコンに色を持たせる

---

### High: アクションボタンの赤がキツすぎる

**場所**: `Styles/buttons.css:23`
**問題**: `.btn-danger` の `background-color: #FF0000` は彩度 100% の純色で、長時間の使用で目が疲れる
**修正案**:
- `#DC2626` に変更（S: 89%, L: 50% → 十分に「赤」だがトーンが落ち着く）
- Hover 時: `#B91C1C`

---

### Medium: ナビゲーションタブの選択/非選択が似ている

**場所**: `Components/TabBar.swift:18-25`
**問題**: 選択タブ `#2563EB` と非選択タブ `#3B82F6` の色差 ΔE = 7.8 — 区別はつくが弱い
**修正案**:
- 非選択を `#9CA3AF`（グレー系）にして明度差で区別 → ΔE = 32
- または非選択のテキストを細字にして色 + ウェイトで区別

---

### Low: ダークモードでセカンダリテキストが沈んでいる

**場所**: `Assets.xcassets/secondaryText.colorset/Contents.json`
**問題**: Dark モードの `#6B7280` は暗い背景 `#1F2937` に対して明度差が小さく読みにくい
**修正案**:
- Dark モードの secondaryText を `#9CA3AF` に変更（明度差 +15%）

severity 定義

severity	基準	例
High	隣接要素が区別できない (ΔE < 5)、または色がキツすぎて不快	同色のタブ、純色の大面積使用
Medium	区別しにくい (ΔE 5〜10)、トーン不統一、Dark モード破綻	似た青の並び、暖色寒色混在
Low	改善すれば快適になる	微妙な明度差の不足、パレット未統一

エラーハンドリング

状況	対応
カラー定義が見つからない	"カラー定義が検出できませんでした" と報告
隣接関係が推定できない	色の一覧を出して「手動で隣接確認を推奨」
CSS 変数が外部参照で解決不能	"解決不能" マーク + 手動確認推奨

連携エージェント

Agent	役割	起動条件
css-expert	CSS カラー分析、セレクター隣接解析	Electron/CSS プロジェクト
swiftui-macos-designer	SwiftUI ビュー構造・カラー分析	Swift プロジェクト