こんにちは、やまだゆうです。
今回はClaude Codeを使ってz-indexのグローバルレイヤーを導入したときに経験した失敗と学びについて共有します！
当初抱えていた問題と解決策
ぼくが開発に携わっていたWebアプリの技術スタックは次のようになっていました。
- フレームワーク：Next.js
- CSSフレームワーク：Tailwind CSS (v4)
- 開発体制：エンジニア5名
このアプリではコンポーネントごとに場当たり的にz-indexを使っていたため、z-indexを追加したり変更したりすると別のコンポーネントで描画しているUIが隠れてしまうという問題を抱えていました。
z-10やz-50といったキリの良い定義ならまだしも、これらの上に置きたいがためにz-11やz-60と定義された箇所があったりとひどい状況でした。
解決策を調査しているうちに以下の記事でグローバルレイヤー設計という概念を知りました。
z-indexの混乱を防ぐ：CSSレイヤー設計の原則と、破綻しない運用戦略 #UI設計 - Qiita
とても有効な解決策になりそうだったので、この記事を参考にClaude Codeにグローバルレイヤー設計を導入してもらいました。
@import "tailwindcss";
@theme inline {
--color-foreground: var(--foreground);
--color-background: var(--background);
--z-sticky: 10; /* ヘッダー */
--z-dropdown: 20; /* ドロップダウンメニュー */
--z-modal: 30; /* モーダル・ダイヤログ */
--z-overlay: 50; /* オーバーレイ */
}
Claude Codeが「これで解決します！」と自信満々に提案・実装してきたので、軽い動作確認をしてメインブランチにマージしました。
問題が発生：z-indexが効いてない！
ところが、実際にはこのz-indexの設定は効いておらず、ヘッダー上のドロップダウンメニューを開いたらコンテンツ部分の下に隠れしまう事象が発生してしまいました。
原因を調査しているうちに、実際にはこのように定義しなければいけないことにたどり着きました。
@import "tailwindcss";
@theme inline {
--color-foreground: var(--foreground);
--color-background: var(--background);
}
/* @themeではなく@utilityで定義する必要があった！ */
/* ヘッダー */
@utility z-sticky {
z-index: 10;
}
/* ドロップダウンメニュー */
@utility z-dropdown {
z-index: 20;
}
/* モーダル・ダイヤログ */
@utility z-modal {
z-index: 30;
}
/* オーバーレイ */
@utility z-overlay {
z-index: 50;
}
原因：Tailwindの仕様を正しく理解していなかった
びっくりなことに、Claude CodeがTailwindの基本的な仕様を理解していませんでした（ぼくもなんですが。。）
Tailwindには @themeに定義することで、自動でユーティリティクラスに反映されるものと反映されないものがあります。
例えば以下のようにcolorを@themeを定義することで背景の色（bg-**）やテキストの色（text-**）のユーティリティクラスに自動で定義されます。
/* --colorを指定することで、、 */
@theme {
--color-mint-500: oklch(0.72 0.11 178);
}/* --colorを指定することで、、 */
@theme {
--color-mint-500: oklch(0.72 0.11 178);
}
<!-- 背景やテキストの色に反映される -->
<div class="bg-mint-500">
<!-- ... -->
</div>
<p class="text-mint-500">テキスト</p><!-- 背景やテキストの色に反映される -->
<div class="bg-mint-500">
<!-- ... -->
</div>
<p class="text-mint-500">テキスト</p>
このことはちゃんとTailwindの公式ドキュメントに書いてありました。
▶ Theme variable namespaces - Tailwind CSS
z-indexはカスタムユーティリティを明示的に登録する必要がある
一方でz-indexは自動でユーティリティクラスに定義されません。カスタムユーティリティとして明示的にユーティリティクラスに登録する必要があります。
@utility z-sticky {
z-index: 10;
}
@utility z-dropdown {
z-index: 20;
}
@utility z-modal {
z-index: 30;
}
@utility z-overlay {
z-index: 50;
}
カスタムユーティリティの登録についてはこちらのドキュメントを参照してください。
▶ Adding custom utilities - Tailwind CSS
学んだこと
Tailwindの仕様をちゃんと知らなかったことはもちろんなのですが、一番の原因はClaude Codeにプロジェクト内の情報だけで実装させてしまったことだと思います。
初めてやることはClaude Codeに公式ドキュメントを参照させたうえで計画を立てさせれば、今回の失敗は防げたかもしれないです。