DOM Tweaker

開発中のページで要素を選び、Tailwind v4 のクラスをその場で試して、AI への引き継ぎ用 diff をコピーする方法。

DOM Tweaker とは

DOM Tweaker は、ホストページ上で Tailwind のユーティリティクラスを試すための、オプトイン式の開発ツールです。Alt+クリックによる要素選択、クラスエディター、@tailwindcss/browser のランタイム、変更前後をまとめた diff のコピー機能をひとつにまとめています。変更するのは表示中の DOM だけで、アプリケーションのソースファイルには書き込みません。

開発時の利用を前提としています

PanelConfig.domTweaker は applyEndpoint と同じように、開発者やサイト所有者の作業環境だけで有効にしてください。内部で使う @tailwindcss/browser は開発向けのランタイムであり、起動後はページ全体を対象とするコンパイラー、オブザーバー、スタイルを追加します。一般の本番ユーザーへ有効化したまま配布する機能ではありません。

操作の流れ

パネルヘッダーの DOM Tweaker トグルをオンにします。初回だけ Tailwind のブラウザーランタイムを遅延ロードします。
ホストページ上で Alt を押しながらポインターを動かし、編集したい要素を Alt+クリックします。
選んだ要素が枠で固定表示され、そのそばに編集アイコン（✎）が現れます。
編集アイコンからクラスエディターを開きます。既存クラスはチップの × で外せます。クラス名を入力すると Tailwind の候補が絞り込まれ、追加時の競合は tailwind-merge が整理します。
class 属性の変更はその場で DOM に反映されます。ホストのビルド済み CSS に存在しないユーティリティもブラウザーランタイムがコンパイルするため、再ビルドを待たずに見た目を確認できます。
DOM Tweaker diff を開き、セレクター、変更前後のクラス、追加／削除クラスを確認してコピーします。そのテキストを AI へ渡し、ソースコードへの反映を依頼できます。

diff は現在のページロード中に行った試行の記録です。AI に渡すときは、対象コンポーネントなどのソース情報も添えると、DOM 上の実験を永続的な変更へ落とし込みやすくなります。

有効化

PanelConfig に domTweaker を置いたときだけ、ヘッダーに操作項目が現れます。省略すると機能は表示されず、保存済みの有効状態も無視されます。

import { configurePanel } from '@takazudo/zdtp';

configurePanel({
  // ...PanelConfig の必須フィールド...
  domTweaker: {},
});

空のオブジェクトでは、組み込みの候補一覧と Tailwind のデフォルトテーマを使います。型とバリデーションの詳細は PanelConfig.domTweaker の設定を参照してください。

`themeCss` でホストのテーマを渡す

ホスト固有の Tailwind v4 テーマトークンをコンパイルや入力候補に使いたい場合は、domTweaker.themeCss に渡します。

configurePanel({
  // ...PanelConfig の必須フィールド...
  domTweaker: {
    themeCss: `
      @theme {
        --color-brand: oklch(0.62 0.2 285);
        --spacing-card: 1.5rem;
      }
    `,
  },
});

渡せるのはトークン／テーマ宣言だけです。通常は @theme ブロックを指定します。CSS のエントリーポイントを渡す場所ではなく、themeCss に @import がひとつでも含まれていると configurePanel がエラーにします。

@import を禁止している理由

DOM Tweaker は Tailwind の theme.css と utilities.css だけを読み込み、preflight は意図的に除外します。ホスト側の @import を受け付けないことで、Tailwind の一括エントリーや preflight がこの経路から混ざり、ホストページの既存スタイルをリセットする事故を防いでいます。

v1 は Tailwind モードのみ

初期案では、生の CSS 宣言を編集する「CSS モード」も検討しましたが、v1 では意図的に実装していません。DOM Tweaker が編集するのは Tailwind のユーティリティクラスだけです。隠し設定や切り替え忘れではなく、現在の製品スコープです。

制約

Tailwind v4 のホストだけが対象です。 @tailwindcss/browser v4 を使う実装で、Tailwind v3 との互換経路はありません。
厳格な CSP では動作しません。 style-src で unsafe-inline を許可していないページでは、DOM Tweaker が注入する UI 用／生成ユーティリティ用のスタイルがブロックされます。
v1 はソースファイルへ書き込みません。 エクスポートするのは AI への引き継ぎ用テキストで、クリップボードへコピーするだけです。トークン用のアプライパイプラインとは異なり、テンプレートやコンポーネントを探索して書き換える処理はありません。
対象は Light DOM です。 Shadow DOM のホストは v1 の範囲外で、ピッカーと Tailwind ランタイムはドキュメントの Light DOM を監視します。
一度起動したランタイムはページが終わるまで残ります。 トグルをオフにすると要素選択とエディターは止まりますが、ランタイム、オブザーバー、注入済みスタイルは破棄されません。完全に外すにはページを再読み込みします。
編集セッションはページロード単位です。 変更前の状態と diff はメモリ内だけに保持します。再読み込みや新しいドキュメントへの遷移後は、新しいセッションになります。
フレームワークの再レンダーが表示中の変更を上書きすることがあります。 フレームワークが class 属性を書き直すと、DOM 上のプレビューは失われます。ただし DOM Tweaker が記録した diff は残るため、そのままコピーできます。
同じドキュメントで同時に使えるのは 1 インスタンスです。 ランタイム、ピッカーのブリッジ、ポータルはドキュメント全体で共有します。複数のパネルが設定済みでも、最初に有効化したインスタンスがオフになるまで所有権を持ちます。