CSS変数（カスタムプロパティ）が反映されないときの対処

定義のスコープが届いていない

カスタムプロパティは定義した要素とその子孫でしか参照できません。特定のセレクタの中だけで定義した変数を、別の無関係な要素でvar()しても値は入らず無効になります。全体で使う変数は:rootに定義するのが基本です。

コンポーネント単位で上書きしたい変数は、その親要素に定義します。どこで定義し、どこから呼んでいるかの親子関係を意識すると、効かない原因の多くが説明できます。

var()の書式とフォールバック

var()は第2引数にフォールバック値を渡せます。var(--main, #333)のように書くと、--mainが未定義のときに#333が使われます。これを入れておくと、変数が届かない場面でも完全に崩れるのを防げます。

値が反映されないとき、まずフォールバック付きで書いて切り分けると、変数が未定義なのか値そのものが不正なのかを判断しやすくなります。

症状別チェック表

CSS変数（カスタムプロパティ）が反映されないは、症状を分けずに直そうとすると原因探しが長引きます。まず「自分だけで起きるのか」「全員で起きるのか」「特定ブラウザだけか」「差し替え後だけか」を切り分けます。

確認順序を固定すると、相対パス、ファイル名、キャッシュ、認証、外部読み込みのどこで止まっているかが見えます。修正後はローカル確認だけで終わらせず、実際の共有URLで再表示して、相手と同じ条件で直ったことを確認します。

• 自分だけ表示されない: キャッシュ、ログイン状態、ブラウザ拡張、端末幅を確認する
• 全員で表示されない: ファイル構成、相対パス、大文字小文字、アップロード漏れを見る
• 一部だけ崩れる: CSS/画像/JSごとに読み込みエラーを分ける
• 差し替え後だけ古い: URL、キャッシュ、更新対象ファイルの取り違えを確認する

変数の値が不正・型が合っていない

カスタムプロパティは値を検証せずそのまま代入するため、単位の付け忘れや余計な文字が混ざると、最終的なプロパティで無効になり無視されます。例えば--gap:16;のように単位がないとmarginなどで使えません。

calc()と組み合わせるときは、変数に単位が含まれているかを意識します。--gap:16px;ならcalc(var(--gap) * 2)が機能しますが、単位なしだと計算が破綻します。

変数の名前そのものの打ち間違いも見落としがちです。定義側と参照側で--main-colorと--maincolorのように綴りがずれていると、参照側は未定義扱いになり静かに無効化されます。定義名と呼び出し名を突き合わせて確認してください。

切り分けの手順

スコープ・書式・値の順に確認すると効率的です。

1. 変数を呼ぶ要素が定義要素の子孫になっているか確認する
2. 全体共通の変数は:rootに定義し直す
3. var(--x, フォールバック)を付けて未定義かどうか切り分ける
4. 値に単位やスペルの誤りがないか確認する
5. calc()利用時は変数に単位が含まれているか確認する

効かない原因の共有はレビューで早まる

CSS変数の不具合はスコープという見えない関係が絡むため、コードだけ送られても再現に時間がかかります。問題が起きている画面そのものを共有すると、相手は実際の表示を見ながら原因を当てられます。

ギガサイト便なら、問題のあるHTML一式をドロップして発行された〇〇.giga-site.comのURLを共有すれば、レビュアーが手元で同じ崩れを確認できます。同じURLのまま修正版に差し替えれば、直る前後を同じリンクで見比べられます。社外に出せない検証は認証を併用してください。