この問題は、Laravel や WordPress の API とフロントエンドを接続したときに発生しやすい。レスポンスの値に応じて、バッジ、ボタン、通知、カードの背景色を変える設計は一般的である。しかし、値をそのまま Tailwind CSS のクラス名に変換すると、静的解析の仕様と衝突する。
Tailwind CSS で API 連携の動的 UI を安定して構築するには、クラス名を動的に生成するのではなく、状態とスタイルの対応関係をコード上に明示する必要がある。さらに、複数の状態を持つコンポーネントでは、clsx、tailwind-merge、class-variance-authority を組み合わせると、条件分岐とクラス競合を分離できる。
Tailwind CSSの静的解析が動的クラス生成を扱えない理由
Tailwind CSS は、実行時に CSS を生成する仕組みではない。ビルド時にプロジェクト内のソースコードを解析し、使用されていると判断したユーティリティクラスだけを出力する。
たとえば、ソースコード内に bg-blue-500 と明記されていれば、ビルド時にそのクラスが検出される。bg-red-500 も同様である。一方、次のような記述では事情が異なる。
bg-${color}-500
この文字列から、Tailwind CSS が bg-blue-500、bg-red-500、bg-green-500 を推測することはできない。静的解析の対象は完成したクラス名ではなく、ソースコード上で検出可能な文字列である。変数の実行時の値までは評価しない。
これは JIT コンパイラの不具合ではない。必要な CSS だけを生成するための設計上の制約である。クラス名の組み合わせを無制限に推測すれば、解析コストと出力 CSS のサイズが増える。Tailwind CSS は、クラス名を静的に検出できることを前提にしている。
動的な値と動的なクラス名を分ける
API 連携では、次の二つを分けて考える必要がある。
- 値が動的に変わること
- クラス名の構造が動的に変わること
たとえば、表示する記事タイトルや価格が API で変わっても、テキストとして表示するだけなら問題はない。textContent やテンプレートの値として扱えるからである。
一方、API が返した color の値をクラス名の一部として連結すると、クラス名の構造が実行時に変わる。ここで静的解析の対象から外れる。
実際の UI では、API の値をそのままクラス名にしない。API の状態を、あらかじめ定義した UI の状態へ変換する。たとえば、レスポンスの status が published、draft、error のいずれかであれば、それぞれを固定されたクラスセットに対応させる。
published を bg-green-100 text-green-800 に変換する処理は、クラス名の候補をソースコード上に明示できる。bg-${status}-100 のような連結とは異なり、Tailwind CSS が検出できる形になる。
マッピングは安全性の境界にもなる
API から受け取った文字列を、そのまま CSS クラスとして出力する設計には別の問題もある。バックエンドの入力値が想定外だった場合、表示が崩れる。入力値の管理範囲が広い場合は、予期しないクラス名を生成する可能性もある。
マッピングを挟むと、許可する状態を限定できる。
状態値 → 表示用の変種 → 固定されたクラスセットこの構造では、API の値と CSS の実装が直接結び付かない。未知の値は既定の状態へフォールバックできる。表示ロジックの検証範囲も狭くなる。
Tailwind CSSの動的UIでは、クラス名を生成するのではなく、APIの状態を固定されたクラスセットへ変換する。
APIレスポンスに応じたUI状態を設計する
API 連携の画面で必要になる状態は、成功と失敗だけではない。通信が始まる前、通信中、成功、空データ、失敗、再試行可能な状態を分ける必要がある。
特に非同期通信では、レスポンスの有無と通信状態を同じ条件式で扱うと、UI の責務が不明確になる。データが空なのか、まだ取得していないのか、取得に失敗したのかは、画面上で別の意味を持つ。
状態を分類する
API 連携コンポーネントでは、最低限、次の状態を区別する。
1. 初期状態
まだ通信を開始していない状態である。ページ表示直後のプレースホルダーや操作待ちの画面に使う。
2. ローディング状態
通信中である。ボタンを無効化し、二重送信を抑制する。既存データを残したまま、更新中であることだけを示す設計もある。
3. 成功状態
API が有効なレスポンスを返した状態である。データの内容に応じて、通常表示や状態別のバッジを描画する。
4. 空状態
通信は成功したが、表示対象が存在しない状態である。エラーとは異なるため、警告色で表示する必要はない。
5. エラー状態
通信失敗やレスポンスの形式不正が発生した状態である。再試行の操作や、利用者が次に取るべき行動を示す。
この分類をコンポーネントの変種に対応させると、UI の条件分岐を整理しやすい。たとえば、ローディング中は opacity-60 と pointer-events-none を使い、エラー時は border-red-300 と text-red-700 を適用する。
ただし、ローディング状態にエラー用の赤色を加えるような設計は避けるべきである。状態の意味と視覚表現が一致しなくなるからである。
APIの値を直接見た目に結び付けない
Laravel の API が次のような状態値を返すとする。
pendingprocessingcompletedfailed
これらをそのまま Tailwind CSS の色名として使うことはできない。状態名は業務上の意味であり、色名ではない。
フロントエンド側では、状態値を表示上の変種に変換する。
| APIの状態 | UIの変種 | 表示上の役割 |
|---|---|---|
pending | waiting | 処理待ちを示す |
processing | active | 処理中であることを示す |
completed | success | 正常完了を示す |
failed | danger | 処理失敗と再確認の必要性を示す |
| 未知の値 | neutral | 予期しない状態を安全に表示する |
この変換を入れることで、バックエンドの状態名が変わっても UI の実装を直接変更せずに済む。WordPress の REST API と Laravel の API で状態値の命名が異なる場合も、フロントエンド内の変種を共通化できる。
業務状態と視覚状態を一つの文字列で表現しようとすると、依存関係が増える。API の仕様変更が CSS の変更に波及するためである。変換層は小さくても、境界として機能する。
通信状態とデータ状態を分離する
API 連携では、loading と status を一つの変数で表さないほうがよい。たとえば、処理中のデータを表示しながら再取得する場合、通信状態は loading でもデータ状態は success のままである。
この二つを分離すると、次のような表現が可能になる。
- 既存のデータを表示したまま、更新中の表示だけを重ねる
- 初回取得時だけスケルトンを表示する
- 再取得時はボタンだけを無効化する
- エラー発生時も最後に取得したデータを保持する
逆に、一つの state だけで全状態を表そうとすると、条件分岐が増える。表示対象、操作可否、装飾、アニメーションが同じ分岐に混ざるためである。
Tailwind CSS のクラス設計でも、通信状態とデータ状態を別の変種として扱うほうが適切である。たとえば、variant は success や danger を表し、isLoading は透明度や操作可否だけを制御する。
clsxとtailwind-mergeでクラス競合を解決する
条件分岐の増加に伴って発生する問題が、クラスの重複である。
ベースとなるボタンに bg-blue-500 を指定し、API の状態に応じて bg-red-500 を追加すると、最終的なクラス文字列には両方が含まれる。Tailwind CSS のクラスは CSS の生成順やセレクタの扱いに影響されるため、文字列の後ろにあるクラスが必ずブラウザ上で優先されるとは限らない。
この問題を解決するのが tailwind-merge である。bg-blue-500 と bg-red-500 のように同じ分類で競合するクラスを解析し、後から指定されたクラスを残す。
clsx は条件付きクラスの組み立てを担当する。真偽値や配列、オブジェクトを使ってクラスを宣言的に記述できる。一方、tailwind-merge は、組み立てられたクラスの競合を解消する。
役割は異なる。
clsx：条件に応じたクラス文字列の構築tailwind-merge：Tailwind CSS の競合クラスの整理cva：コンポーネントの変種と条件の定義
この分離により、UI コンポーネントのクラス管理を一つの巨大なテンプレート文字列から切り離せる。
cnユーティリティを境界にする
実装では、clsx と tailwind-merge を組み合わせた cn 関数を用意するパターンがよく使われる。
概念上の処理は次の通りである。
cn(条件付きクラスの配列)
→ clsx でクラスを連結
→ tailwind-merge で競合を解消
→ 最終的なクラス文字列を返す
React や Vue のコンポーネントからは、内部の処理を意識せず cn を呼び出せる。クラス結合の規則を一箇所に集約できるため、コンポーネントごとの実装差が減る。
ただし、tailwind-merge は任意の CSS 競合をすべて解決するものではない。Tailwind CSS のユーティリティとして認識可能な競合関係が対象である。独自クラスや複雑なセレクタを混在させる場合は、期待通りに統合されない可能性がある。
また、クラスの競合が発生する設計そのものを見直す必要もある。ベースクラスと変種クラスで同じプロパティを重複して指定し続けると、tailwind-merge に依存する度合いが高くなる。競合解消は安全装置であり、スタイル設計の代替ではない。
class-variance-authorityでコンポーネントの変種を定義する
状態の種類が増えると、clsx だけでは条件式が散らばる。ボタン、バッジ、通知カードなどで同じ状態を扱う場合、コンポーネントの変種を宣言的に定義したほうが保守しやすい。
class-variance-authority、いわゆる CVA は、ベースとなるクラスと、変種ごとのクラスを分けて管理するためのユーティリティである。
コンポーネントの設計は、次のように分けられる。
- ベース：常に適用するレイアウトと形状
- 変種：成功、警告、エラーなどの意味
- サイズ：小、中、大などの寸法
- 条件付き状態：ローディング、無効化、選択中など
この構造では、API のレスポンスを変種の値に変換する処理と、変種に対応する CSS の定義を分離できる。
たとえば、API の failed を UI の danger に変換した後、CVA の variant="danger" に渡す。CVA 内には danger に対応する固定クラスが記述されている。Tailwind CSS の静的解析対象も明確になる。
変種とレスポンスの型を一致させない
TypeScript を使う場合、API のレスポンス型と UI コンポーネントの変種型を完全に同じにしないほうがよい。
API の型はバックエンドの契約を表す。UI の変種型は画面上の表現を表す。両者は関連するが、同一ではない。
たとえば、API が次の状態を返すとする。
pendingprocessingcompletedfailed
UI 側では、次の変種だけを持つ設計にできる。
neutralinfosuccessdanger
pending と processing を同じ info にまとめることも可能である。バックエンドの状態数と UI の見た目の種類を一致させる必要はない。
この変換を型で明示すると、未知の値に対する処理を実装しやすくなる。戻り値を neutral に固定すれば、API の追加状態が即座に画面崩壊へつながることを防げる。
CVAを使う基準
すべての要素に CVA を導入する必要はない。変種が一つしかない要素や、条件が単純な要素では、clsx と cn だけで十分である。
CVA が有効になるのは、次のような条件がある場合である。
- 状態の種類が複数ある
- サイズと状態を組み合わせる
- 同じ変種を複数の画面で再利用する
- API の状態と表示の状態を分離する
- TypeScript で許可する変種を制限する
反対に、変種が増え続けて一つの定義が巨大になる場合は注意が必要である。variant、size、intent、loading、selected を一つのコンポーネントに集約すると、組み合わせの数が増える。設定項目を増やすほど再利用性が上がるとは限らない。
UI の責務が異なる状態は、別のコンポーネントに分割するほうが合理的な場合がある。CVA はクラスの定義を整理する道具であり、コンポーネント境界を決める道具ではない。
clsxは条件をまとめ、tailwind-mergeは競合を解決し、CVAは状態の語彙を定義する。三つを同じ目的の道具として扱わないことが設計の出発点である。
Laravel・WordPress APIとTailwind CSSを接続する境界
Laravel の API と Vue.js、React を接続する場合、フロントエンドは JSON の構造だけでなく、状態値の意味も受け取る。WordPress REST API では、投稿の公開状態やカスタムフィールドの値を UI に反映することがある。
ここで問題になるのは、API のレスポンスがそのまま画面表示の仕様になることである。API の値を取得したコンポーネントが、値の解釈、エラー処理、クラス選択、表示テキストをすべて担当すると、依存関係が増える。
変換層を設ける
API から受け取ったデータは、画面用のモデルへ変換する。変換処理では次のような責務を担当する。
- API のフィールド名を画面側の名前へ変える
- 欠落した値に既定値を設定する
- API の状態値を UI の変種へ変換する
- 日付や数値を表示用に整える
- 未知の状態を安全な値へフォールバックする
この処理をコンポーネントのテンプレートに直接記述しない。テンプレートは表示に集中させる。状態の変換を関数または専用のアダプターに移すと、API 仕様の変更範囲を限定できる。
Laravel で API リソースを使う場合も、フロントエンドが受け取る形式を明確にする必要がある。データベースのカラム名をそのまま公開すれば、内部モデルと画面の依存関係が強くなる。UI に不要な値を返さないことも、状態管理の複雑化を防ぐ。
WordPress の REST API では、プラグインやカスタム投稿タイプによってレスポンスの形が変わる。取得したデータを共通の画面モデルに変換すれば、データソースが変わってもコンポーネントを再利用できる。
レスポンス遅延をクラス切替の基準にしない
API のレスポンス遅延に応じて、一定時間後にクラスを変える設計は慎重に扱う必要がある。バックエンドごとの遅延時間に共通の閾値があるとは限らないからである。
Laravel API と WordPress REST API では、処理内容、キャッシュ、データ量、ネットワーク条件が異なる。特定の時間を超えたら警告色に変えるような UI は、実際の障害ではない遅延をエラーのように見せる可能性がある。
ローディング表示は通信状態として扱う。異常判定は HTTP ステータス、タイムアウト、レスポンス形式、バックエンドが返す業務状態など、意味のある条件で行うべきである。
API 連携 UI の見た目を速度に連動させる場合も、まずは次の責務を分離する。
- 通信中であることの表示
- 通信が失敗したことの表示
- サーバー側の処理状態の表示
- 利用者の操作を制御する処理
この分離なしに色や透明度だけを変更すると、状態の意味が曖昧になる。
非同期通信UIでクラスを安定して切り替える
Axios などで API を呼び出す場合、リクエスト開始からレスポンス処理までに複数の状態変更が発生する。ボタンを押した直後にローディングへ切り替え、成功時は成功表示、失敗時はエラー表示へ切り替える。
このとき、表示クラスを直接書き換えるよりも、状態を更新してクラスを宣言的に決めるほうが保守しやすい。
処理の流れは次のようになる。
1. リクエスト開始時に isLoading を true にする。
2. 前回のエラー状態を消去する。
3. API のレスポンスを画面用モデルへ変換する。
4. 成功時は UI の変種を更新する。
5. 失敗時はエラー用の状態へ切り替える。
6. finally 相当の処理で isLoading を false に戻す。
重要なのは、isLoading の解除を成功時だけに置かないことである。エラー時に解除されなければ、ボタンが無効化されたままになる。通信終了後の共通処理は、成功と失敗の両方から実行される位置に置く。
ボタンのクラスと操作可否を分ける
ローディング中のボタンでは、見た目と操作可否を同時に変更することが多い。
opacity-60で視覚的に無効化するpointer-events-noneでポインター操作を抑制するdisabled属性でフォーム操作を制御するaria-busyなどで状態を補足する
ただし、クラスだけで操作を無効化してはいけない。pointer-events-none はポインター操作を抑制するが、キーボード操作やフォームの意味論まで置き換えるものではない。
UI の状態を見た目だけで表現すると、利用者の操作方法によって結果が変わる。disabled 属性や適切なアクセシビリティ属性を使い、Tailwind CSS は視覚表現に限定するほうが構造として明確である。
エラー状態はクラスだけで完結しない
エラーを赤色で表示するだけでは、原因と次の操作が分からない。API 連携では、エラー状態を少なくとも次のように分類したほうがよい。
- 認証が必要なエラー
- 入力値が不正なエラー
- 権限が不足しているエラー
- サーバー側の一時的なエラー
- ネットワークやタイムアウトのエラー
- レスポンス形式が想定外のエラー
すべてを同じ danger 変種にしても、表示の色としては成立する。しかし、再試行が可能か、入力を修正すべきか、ログインが必要かは異なる。
CVA の変種は視覚表現を整理するが、エラー分類そのものを代替しない。エラーの意味を変換層で整理し、その結果を UI へ渡す必要がある。
Shadow DOMとTailwind CSSを併用する場合の注意点
Web Components で Shadow DOM を使う場合、スタイルの適用範囲が通常のドキュメントとは分離される。Shadow DOM 内部の要素は、メインドキュメント側のスタイルから直接影響を受けない。
そのため、メインドキュメントで生成した Tailwind CSS のユーティリティクラスを、Shadow DOM 内の要素へ付けるだけでは期待通りに適用されない場合がある。
これは Tailwind CSS のクラス生成の問題とは別である。
- Tailwind CSS の問題：クラスがビルド時に検出されていない
- Shadow DOM の問題：生成済みの CSS が適用範囲の外にある
二つを混同すると、クラス名の書き方だけを修正して解決しない状態になる。
Shadow DOM内にスタイルを届ける方法
Shadow DOM と Tailwind CSS を併用する場合は、生成した CSS を Shadow Root 内へ読み込む設計が必要になる。具体的な方法は、ビルド構成や Web Components の実装方式によって異なる。
検討対象になるのは次のような構成である。
- 生成済みの CSS を Shadow Root 内に注入する
- Shadow DOM 専用のスタイルシートを生成する
- CSS カスタムプロパティを使って外部からテーマ値を渡す
- ユーティリティクラスではなくコンポーネント内部のスタイルを使う
- Shadow DOM を使わず、通常の DOM と命名規則で分離する
メインドキュメントの Tailwind CSS が自動的に Shadow DOM 内へ適用されるとは考えないほうがよい。ビルドが成功していても、スタイルのスコープが異なれば画面には反映されない。
API 連携コンポーネントを Web Components として配布する場合は、依存する CSS の持ち方を先に決める必要がある。アプリケーション内でだけ使う Vue や React のコンポーネントと、外部環境へ配布する Web Components では、スタイルの依存関係が異なる。
Shadow DOMではテーマ設計も変わる
Shadow DOM 内の要素に対して、アプリケーション側から Tailwind CSS のクラスを追加する設計は、通常のコンポーネントほど単純ではない。状態に応じてクラスを変える処理自体は実装できても、そのクラスに対応する CSS が Shadow Root 内に存在しなければ意味がない。
API の状態を色へ変換する場合は、CSS カスタムプロパティでテーマを渡す方法もある。たとえば、エラー状態を表す色や境界線の値をカスタムプロパティで定義し、Shadow DOM 内部の CSS がそれを参照する構成である。
ただし、この方法では Tailwind CSS のユーティリティクラスを直接使う設計とは異なる。コンポーネントをどの環境へ配布するのかによって、クラスベースの設計と変数ベースの設計を選択する必要がある。
動的UIの設計で避けるべき依存関係
Tailwind CSS と API を接続する場合、問題の中心はクラス名そのものではない。API のデータモデル、UI の状態、スタイルの定義が一つの処理へ集約されることがボトルネックになる。
次のような実装は短く見えるが、変更には弱い。
- API の値をそのままクラス名へ連結する
- テンプレート内で状態判定とクラス指定を繰り返す
- ローディング、成功、エラーを一つの状態値で管理する
clsxとtailwind-mergeの役割を分けない- すべての UI 状態を一つの巨大な C VA 定義へ集約する
- Shadow DOM 内でメインドキュメントの CSS が使えると仮定する
特に、クラス名を API から生成する設計は、Tailwind CSS の静的解析と正面から衝突する。許可するクラスを safelist などで追加する方法もあるが、状態が増えるたびに CSS の管理対象が広がる。まずは状態からクラスセットへのマッピングを明示するほうが、依存関係を制御しやすい。
Tailwind CSS の静的解析対象を広げる方法を使う場合でも、無制限の文字列生成を正当化する理由にはならない。クラスの候補が有限であること、生成対象が明確であること、不要な CSS を出力しないことを確認する必要がある。
実装方針を決めるための判断
API 連携で動的 UI を構築する場合、最初に決めるべきなのは利用するユーティリティではない。状態の境界である。
次の順番で設計すると、クラス管理の問題を後から修正する必要が減る。
1. API が返す業務上の状態を定義する。
2. API の状態を UI 用の状態へ変換する。
3. UI 用の状態に対応する固定クラスを定義する。
4. 通信状態とデータ状態を分離する。
5. clsx で条件を構築する。
6. tailwind-merge で競合を解消する。
7. 変種が増えた場合だけ C VA を導入する。
8. Shadow DOM を使う場合は CSS の適用範囲を別途設計する。
この順番を飛ばして、最初からクラス結合のユーティリティだけを導入しても、状態設計の曖昧さは残る。cn 関数はクラス文字列の整理には有効である。しかし、API の failed をどの UI 状態として扱うかまでは決めない。
コンポーネントの再利用性も、クラスの共通化だけでは決まらない。API の変換処理、状態の粒度、エラーの分類、スタイルのスコープが一致して初めて再利用可能になる。
動的UIの品質を決めるのは、クラスを短く書く技術ではない。APIの状態と画面の状態を別のモデルとして扱う設計である。
まとめ
Tailwind CSS で API 連携の動的 UI を構築する場合、bg-${color}-500 のような動的クラス生成は避ける必要がある。Tailwind CSS はビルド時にソースコードを静的解析するため、実行時に完成するクラス名を CSS として出力できない。
実装の中心は、API の値を固定された UI の変種へ変換することである。Laravel や WordPress の API が返す状態値を、そのままスタイルへ結び付けない。業務状態と視覚状態の間に変換層を置く。
使い分けは次の通りである。
clsx：条件に応じたクラスを組み立てるtailwind-merge：競合する Tailwind CSS クラスを整理するclass-variance-authority：コンポーネントの変種を型付きで定義するcnユーティリティ：クラス結合の処理を共通化する- Shadow DOM：CSS の適用範囲を別途設計する必要がある
得られる改善は、単純な記述量の削減ではない。API 仕様と CSS の依存関係を切り離し、未知の状態を安全に処理し、コンポーネントの変更範囲を限定できる点にある。
一方で、ユーティリティを増やすほど設計が自動的に良くなるわけではない。変種を過剰に定義すれば、状態の組み合わせが増える。tailwind-merge に依存しすぎれば、競合するクラスを生む構造自体が見えにくくなる。Shadow DOM を採用すれば、CSS の配布方法も追加で管理しなければならない。
Tailwind CSS の動的 UI は、クラス名の生成問題として扱うより、状態モデルの設計問題として扱うべきである。固定されたクラス、明確な変換層、分離された通信状態。この三つが揃えば、API の接続先が変わっても、フロントエンドの実装は安定する。