z-index競合のデバッグ：ステップバイステップガイド

z-index問題のデバッグ

z-indexの問題は最もフラストレーションの溜まるCSSバグの1つです。高いz-index値にもかかわらず要素が他の上に表示されません。これらの問題を診断し修正するための体系的なアプローチを紹介します。

ステップ1：スタッキングコンテキストの確認

z-index障害の最も一般的な原因は予期しないスタッキングコンテキストです。ブラウザDevToolsを使用してスタッキングコンテキストツリーをトレースします。

// コンソールでのクイックチェック：要素がスタッキングコンテキストを形成するか？
function hasStackingContext(el) {
  const style = getComputedStyle(el);
  return (
    style.position !== 'static' && style.zIndex !== 'auto' ||
    parseFloat(style.opacity) < 1 ||
    style.transform !== 'none' ||
    style.filter !== 'none' ||
    style.isolation === 'isolate' ||
    style.willChange === 'transform' ||
    style.willChange === 'opacity'
  );
}

ステップ2：祖先チェーンのトレース

問題のある要素からルートまでDOMを遡ります。スタッキングコンテキストを作成するすべての祖先を特定します。

ステップ3：兄弟コンテキストの比較

z-indexは同じスタッキングコンテキスト内の要素のみを比較します。

ステップ4：一般的な罠の確認

/* 罠1：positionの欠如 */
.element {
  z-index: 9999; /* positionなしでは効果なし！ */
}

/* 罠2：親がoverflow: hidden */
.parent { overflow: hidden; }
.child { z-index: 9999; } /* 視覚的にクリップされる */

/* 罠3：祖先のtransform */
.ancestor { transform: translateX(0); }
.descendant { position: fixed; z-index: 9999; }

予防

このツールのようなものを使ってz-indexスケールを事前に定義し、CSS変数を一貫して使用し、CSSにスタッキングコンテキスト境界を説明するコメントを追加します。