CSS 単位デバッグワークフロー

CSS 単位バグは「ほぼ正しい」レイアウトとして現れることが多いです。モバイルテキストがわずかに大きい、Figma からずれたスペーシング、意図した max に達しない clamp 値などです。

スタイルシート変更をマージする前に、短い検証ワークフローを実行してください。

ステップ 1：文脈を確認

前提を書き留めます。

• root font-size（html）
• ネストコンポーネントの親 font-size
• デザインレビューで使ったビューポート幅/高さ
• 仕様が px、rem、または混在か

前提が 1 つでも間違えれば、下流の変換はすべて間違います。

ステップ 2：1 つの真実の源から変換

1 つの正規入力（通常デザイン px）を選び、外向きに変換します。

24px @ 16px root → 1.5rem
24px @ 1440px viewport → 1.6667vw

rem トークンを :root やデザインシステムファイルに保存し、各コンポーネントで都度変換しないでください。

ステップ 3：3 幅で clamp をプレビュー

fluid 値では必ず確認：

• 最小ビューポート（例：320px）
• 中間ビューポート（例：768px）
• 最大ビューポート（例：1280px）

問いかけ：

• 最小でテキストは読めるか？
• スペーシングはオーバーフローせず意図した max に達するか？
• 曲線は滑らかか、ジャンプしないか？

ステップ 4：ブラウザでデザインと比較

DevTools の計算スタイルは rem や clamp で記述しても最終 px 値を示します。同じビューポート幅で計算 px をデザイン仕様と比較してください。

計算 px が異なる場合、ランダムオフセットではなく、まず文脈（root、親、ビューポート）を修正してください。

よくあるバグチェックリスト

症状	想定原因
rem 値が大きすぎる	root font-size 前提が間違っている
ネストテキストで em padding が爆発	親 font-size の複合
モバイルで vw テキストが小さすぎる	clamp 最小が欠落
% 幅が潰れる	親に明示的幅がない
clamp が max に達しない	ビューポート max が高すぎる

他ツールに頼るタイミング

• カラートークン：HEX/RGB/HSL 一貫性のためカラーコンバーター
• レイアウトブレークポイント：構造変更のためメディアクエリまたは container query
• デザインレビュー：最終ビジュアルパスのためブラウザ DevTools デバイスモード

単位変換ツールは数値参照フレームを解決します。レイアウトデバッグの代わりにはなりません。

要点

CSS 単位を型付きデータのように扱います。各値には文脈が付きます。文脈を確認し、1 つの真実の源から変換し、clamp 境界をプレビューし、ブラウザで計算 px を検証してください。

次のコンポーネントで PR を開く前に、CSS Unit Converter / Clamp Generator でこのワークフローを実行してください。