ui4-review

UI4 レビュー

CSS の変更をレビューし、トークン違反を自動修正します。

---

重要: パレットトークンとセマンティックトークン

--ramp-* トークンは生のカラーパレットです（例: --ramp-white-1000、--ramp-blue-500）。これらはセマンティックトークンを定義するために colors.css 内でのみ使用されます。

--color-* トークンはコンテキストを認識するセマンティックトークンです（例: --color-bg、--color-text-brand）。これらはライト/ダークテーマを自動的に処理します。

コンポーネントと要素は常に --color-* セマンティックトークンを使用すべきであり、--ramp-* パレットトークンを直接使用してはいけません。

/* ❌ BAD - using raw palette */
background: var(--ramp-white-1000);

/* ✅ GOOD - using semantic token */
background: var(--color-bg);

---

プロセス

ステップ 1: 変更された CSS ファイルを取得する

git status --porcelain | grep '\.css$'

または、特定のファイルが指定されている場合は、それを直接使用します。

ステップ 2: 並列での違反検出

これらの grep 検索を並列で実行して、すべての違反タイプを一度に検出します:

# 1. SCSS Nesting Violations (BEM patterns that don't work in CSS)
grep -n '&__\|&--' "$FILE"

# 2. Hardcoded Spacing (px/rem values that should be tokens)
grep -nE ':\s*[0-9]+px|:\s*[0-9.]+rem' "$FILE"

# 3. Hardcoded Colors (hex, rgb, rgba - includes box-shadow)
grep -nE '#[0-9a-fA-F]{3,8}|rgba?\(' "$FILE"

# 4. Legacy Theme Variables
grep -nE 'var\(--theme-|var\(--style-|var\(--base\)' "$FILE"

# 5. Old Token Names (pre-UI4 naming)
grep -nE '\-\-bg-default|\-\-bg-secondary|\-\-text-default|\-\-text-secondary|\-\-icon-default|\-\-icon-secondary|\-\-border-default|\-\-border-strong' "$FILE"

# 6. Raw Palette Usage (should use semantic tokens instead)
# Skip this check for colors.css which defines the semantic tokens
grep -nE 'var\(--ramp-' "$FILE"

6 つの grep コマンドをすべて 1 つの並列バッチで呼び出し、その結果を分析します。

注意: 生の --ramp-* 違反はコンポーネントの CSS ファイルでのみ報告され、セマンティックトークンを定義するために使用されている colors.css 内では報告されません。

ステップ 3: 優先度に応じた自動修正

1. SCSS ネスト（CSS を完全に壊す）— 最初に修正
2. レガシー変数（非推奨）— 新しいトークンに置き換える
3. 古いトークン名（UI4 以前）— --color-* の命名に変換する
4. 生のパレットの使用（コンポーネント内の --ramp-*）— セマンティックな --color-* トークンに置き換える
5. ハードコードされた値（スペーシング、色、角丸）— トークンに置き換える

ステップ 4: レポート

修正後、以下を報告します:

• 検出された違反の合計数
• 自動修正された違反
• 手動レビューが必要な違反（明確に一致するトークンがないもの）

---

違反リファレンス

SCSS ネスト（CSS を壊す）

パターン	問題	修正
&__element	BEM 要素の連結	フラットな .block__element セレクターを使用する
&--modifier	BEM モディファイアの連結	フラットな .block--modifier セレクターを使用する
.child { .parent--mod & }	親参照	.parent--mod .child に移動する

動作するもの: &:hover、&:focus、&::before、& .child

---

スペーシングトークン

値	トークン
4px / 0.25rem	--spacer-1
8px / 0.5rem	--spacer-2
12px / 0.75rem	--spacer-2-5
16px / 1rem	--spacer-3
24px / 1.5rem	--spacer-4
32px / 2rem	--spacer-5
40px / 2.5rem	--spacer-6

丸めのルール — 常に最も近いトークンに丸めます:

ピクセル範囲	トークン	備考
0-2px	--spacer-0	0 を使用する
3-6px	--spacer-1 (4px)	5-6px は 4px に丸められる
7-10px	--spacer-2 (8px)	10px は 8px に切り下げられる
11-14px	--spacer-2-5 (12px)	13.33px は 12px に丸められる
15-20px	--spacer-3 (16px)	15px、20px はどちらも 16px に丸められる
21-28px	--spacer-4 (24px)
29-36px	--spacer-5 (32px)	30px は 32px に丸められる
37-48px	--spacer-6 (40px)

ルール: 40px 以下の値には、常に単一のトークンを使用します（calc() は使わない）。40px を超える値には、スペーシングトークンとともに calc() を使用します。

例外: 0、パーセンテージ、auto、inherit、-1px（クリップのオフセット用）

---

ストローク幅トークン

値	トークン
1px	--stroke-width-small

---

角丸トークン

値	トークン
2px / 0.125rem	--radius-small
5px / 0.3125rem	--radius-medium
13px / 0.8125rem	--radius-large
9999px	--radius-full

---

エレベーショントークン (ボックスシャドウ)

packages/ui/src/css/elevations.css で定義されています。

ボックスシャドウにハードコードされた rgba() を絶対に使用しないでください。 代わりにエレベーショントークンを使用してください:

トークン	用途
--elevation-300-tooltip	ツールチップ、小さなフローティング要素
--elevation-400-menu-panel	メニュー、ドロップダウン、フローティングパネル
--elevation-500-modal-window	モーダル、ダイアログ、フルオーバーレイ

/* ❌ BAD - hardcoded shadow */
box-shadow: 0 -2px 16px -2px rgba(0, 0, 0, 0.2);

/* ✅ GOOD - elevation token */
box-shadow: var(--elevation-400-menu-panel);

エレベーションはライト/ダークテーマに合わせて自動的に調整されます。

---

セマンティックカラートークン (UI4 命名)

すべてのセマンティックカラーは --color- プレフィックスを使用します。default カテゴリとバリアントは暗黙的です。

旧名	新名 (UI4)
--bg-default	--color-bg
--bg-secondary	--color-bg-secondary
--bg-hover	--color-bg-hover
--bg-selected	--color-bg-selected
--bg-brand	--color-bg-brand
--bg-danger	--color-bg-danger
--bg-success	--color-bg-success
--bg-warning	--color-bg-warning
--text-default	--color-text
--text-secondary	--color-text-secondary
--text-tertiary	--color-text-tertiary
--text-brand	--color-text-brand
--text-danger	--color-text-danger
--text-success	--color-text-success
--icon-default	--color-icon
--icon-secondary	--color-icon-secondary
--icon-tertiary	--color-icon-tertiary
--icon-brand	--color-icon-brand
--icon-danger	--color-icon-danger
--border-default	--color-border
--border-strong	--color-border-strong
--border-selected	--color-border-selected
--border-brand	--color-border-brand

---

レガシー変数 (直ちに置き換えてください)

レガシー	置き換え
--theme-elevation-0	--color-bg
--theme-elevation-50	--color-bg-secondary
--theme-elevation-100	--color-border
--theme-text	--color-text
--style-radius-m	--radius-medium

var(--base) の変換: レガシートークン = 20px。次を使用して変換してください:

元の値	ピクセル	置き換え
var(--base) * 0.4	8px	var(--spacer-2)
var(--base) * 0.5	10px	calc(var(--spacer-1) * 2.5)
var(--base) * 0.6	12px	var(--spacer-2-5)
var(--base)	20px	calc(var(--spacer-4) * 0.833)
var(--base) * 2	40px	var(--spacer-6)

完全な変換表については ui4 スキルのステップ 1 を参照してください。

---

動作

違反を報告するだけにしないでください。replace_string_in_file または multi_replace_string_in_file を使用して直ちに修正してください。

違反に明確なトークンの一致がない場合 (例: 3px や異常な rem 値)、手動レビューのためにフラグを立ててください。ただし推測はしないでください。

各違反について:

1. 正確な行と値を特定する
2. 正しいトークンの置き換えを判断する
3. replace_string_in_file を使用して直ちに修正する
4. 修正された内容を報告する

フラグを立てるだけ (修正しない) の条件:

• 一致するトークンが存在しない (例: 18px のバッジサイズ)
• 値が意図的なもの (例: 1px のボーダー、0)
• 置き換えが曖昧

空の CSS ファイル: 移行後にコンポーネントの CSS ファイルが空になる場合 (すべてのスタイルが Button のような共有コンポーネントで処理されるようになった場合)、CSS ファイルを削除し、コンポーネントからそのインポートを削除してください。

---

出力形式

自動修正後、次を報告してください:

## Auto-Fixed

✅ Collapsible/index.css:9 — `height: 2rem` → `height: var(--spacer-5)`
✅ Collapsible/index.css:120 — `width: 2rem` → `width: var(--spacer-5)`

## Flagged (Manual Review)

⚠️ ErrorPill/index.css:15 — `height: 1.125rem` (18px) — no matching token

---

概要

すべての修正後、簡単な概要を示します：

ファイル	修正済み	フラグ付き
Collapsible/index.css	2	1
ErrorPill/index.css	0	2