budge

Budge

プロアクティブなスキル。Next.js App Router 専用です。 タスクの結果が単一の CSS プロパティまたは Tailwind クラスの変更になる場合は、このスキルを自動的に適用してください。ユーザーが「budge を使って」と言う必要はありません。

単一のビジュアル変更を行った後、ページ上にフローティングバーを表示します。ユーザーは矢印キー（↑↓）で値を微調整し、矢印キー（←→）で関連するプロパティを切り替えます。現在のランタイムでは、ビジュアル変更を行った直後にターンを完了してください。ブラウザー操作や待機は不要です。以下のフォールバックが必要な場合を除き、手動設定も不要です。

ランタイムは、next/script 経由で https://www.budge.design/budge.iife.js から読み込まれる自己完結型の IIFE です。ローカル／開発用ホストではページ上に残り、HMR による class／style の DOM 変更を監視して、直近の数値によるビジュアルプロパティの変更を推測し、変更された要素に印を付けて Budge を自動的にマウントします。また、手動選択には React Grab のプリミティブも使用できます。Cmd+E を押して要素を選択すると、Budge が開きます。フォールバックとして、明示的な data-budge 設定要素も引き続きサポートしています。すべてクライアント側で処理されます。[data-budge-target] 要素でのライブプレビュー、矢印キーによる値の増減、スライド切り替え、音声フィードバック、送信（Enter — 編集プロンプトをクリップボードにコピー）、キャンセル（Escape — 変更を元に戻す）に対応しています。

対象範囲： 生の CSS プロパティ値、インラインスタイル、Tailwind ユーティリティクラスの変更、SVG 表示属性（fill、stroke など）。 対象外： Sass／Less 変数、CSS カスタムプロパティ定義（--spacing）、CSS-in-JS のテーマトークン。これらは通常どおり対応してください。

インストール

app/layout.tsx で budge.iife.js を検索してください。見つかった場合は、依頼されたビジュアル変更を行って終了します。見つからない場合は、references/INSTALL.md を読み、その手順に従ってください。

デフォルトのフロー

単一の生の CSS 値または Tailwind クラストークンを変更する場合は、ソースを編集するだけです。常時稼働のランタイムが、HMR 後に変更後の DOM に Budge を適用します。ユーザーには「X を Y に変更しました。↑↓で微調整し、←→でプロパティを切り替えられます。」と伝えてください。

バーが表示されない場合、または単一の数値による class／style の DOM 変更から変更を推測できない場合に限り、以下の手動手順を使用してください。

---

トラブルシューティング — バーが表示されない

1. スクリプトがない： <Script src="https://www.budge.design/budge.iife.js" strategy="afterInteractive" /> が app/layout.tsx にあることを確認してください。
2. 自動検出が無効： 自動検出はローカル／開発用ホストでデフォルトで実行されます。スクリプトタグに data-budge-autodetect="true" を指定して有効にするか、"false" を指定して無効にしてください。
3. 推測可能な DOM の変更がない： フォールバックのバーは、空でない slides 配列を持つ <div data-budge="..." hidden /> 要素が DOM 内にある場合にのみ表示されます。
4. 対象が見つからない： data-budge-target を持つ要素が、ハイドレーション後に DOM 内に存在する必要があります。

---

手動フォールバック — トリガーテスト

変更後、この機械的なテストを適用してください。主観的な判断はしないでください。

最後の StrReplace 呼び出しで変更されたのは、ちょうど 1 つのファイル内の CSS 値リテラル 1 つ、または Tailwind ユーティリティクラストークン 1 つだけです。この変更は変数、ミックスイン、テーマトークンではありません。

合格： padding: 8px → padding: 16px | className="p-2 m-4" → className="p-4 m-4" 不合格： 2 つの値を変更、トークンの追加／削除、Sass 変数、複数回の StrReplace 呼び出し、構造の変更。

不合格 → budge をスキップして、通常どおり進めてください。合格 → ステップ 2 に進みます。この機械的なテストのみを判定基準とします。

ステップ 2 — スライドを作成する

slides 配列を作成します。最初のスライドは変更したプロパティです。追加のスライドには、ユーザーが調整したい可能性のある関連プロパティを指定します。

各スライドの形式は次のとおりです。

{
  label: string;      // display name shown above bar
  property: string;   // CSS property to apply to [data-budge-target]
  min: number;        // minimum numeric value
  max: number;        // maximum numeric value
  value: number;      // current value (the one you set)
  original: number;   // value before your change
  unit: string;       // "px", "%", "em", etc.
  type?: "color";     // only set for color properties
}

スライド生成ルール

1. メインスライド（インデックス 0）：変更したプロパティです。value = 新しい値、original = 古い値です。
2. 関連スライド（インデックス 1 以降）：同じ要素から関連するプロパティを 2～3 個選びます。現在の計算値または宣言値を読み取り、適切な最小値／最大値の範囲を設定します。

例 — エージェントが padding-top: 8px を padding-top: 16px に変更した場合：

[
  { label: "padding-top", property: "padding-top", min: 0, max: 64, value: 16, original: 8, unit: "px" },
  { label: "padding-bottom", property: "padding-bottom", min: 0, max: 64, value: 8, original: 8, unit: "px" },
  { label: "padding-left", property: "padding-left", min: 0, max: 64, value: 12, original: 12, unit: "px" },
  { label: "padding-right", property: "padding-right", min: 0, max: 64, value: 12, original: 12, unit: "px" },
]

例 — エージェントが font-size: 14px を font-size: 16px に変更した場合：

[
  { label: "font-size", property: "font-size", min: 8, max: 72, value: 16, original: 14, unit: "px" },
  { label: "line-height", property: "line-height", min: 12, max: 80, value: 24, original: 22, unit: "px" },
  { label: "letter-spacing", property: "letter-spacing", min: -2, max: 10, value: 0, original: 0, unit: "px" },
]

例 — エージェントが color: #333 を color: #1a1a1a に変更した場合：

色相を度数で指定する type: "color" スライドを使用します。

[
  { label: "color", property: "color", min: 0, max: 360, value: 0, original: 0, unit: "°", type: "color" },
]

関連プロパティの候補

変更したプロパティ	関連スライド
padding-top	padding-bottom、padding-left、padding-right
padding	padding-top、padding-bottom
margin-top	margin-bottom、margin-left、margin-right
font-size	line-height、letter-spacing
gap	padding、margin-top
width	height、max-width
border-radius	padding、border-width
opacity	font-size

Tailwind の解決

Tailwind クラスを CSS プロパティとピクセル値に解決します（spacing スケールに 4 を掛けます）。

Tailwind クラス	メインスライドのプロパティ	値
p-4	padding	16px
px-4	padding-left（padding-right も設定）	16px
py-4	padding-top（padding-bottom も設定）	16px
pt-4	padding-top	16px
mt-4	margin-top	16px
gap-4	gap	16px
text-[14px]	font-size	14
rounded-lg	border-radius	8px

軸方向のショートハンド（px-*、py-*、mx-*、my-*）では、メインスライドには軸のプロパティを 1 つ設定し、両方のプロパティをスライドに含めます。

Tailwind クラスを使用する場合は、ランタイムが値を直接操作できるように、対象の要素にインラインスタイルのオーバーライドも追加します。

<div data-budge-target className="py-4" style={{ paddingTop: '16px', paddingBottom: '16px' }}>

デザイントークンへのスナップ

プロジェクトで :root または @theme（Tailwind v4、Shadcn、通常の CSS 変数）の CSS カスタムプロパティとしてデザイントークンを定義している場合、ランタイムはプロパティをスケールに対応付けることで、↑／↓キーによる変更時に自動的にトークンへスナップします。

プロパティの一致条件	検出されるプレフィックス
padding*、margin*、gap	--spacing-*
font-size	--text-*
border-radius*	--radius-*
color、*-color	--color-*（スナップには未対応 — パレットの循環機能は今後対応予定）

トークンが現在の値と一致すると、ウィジェットにその名前（例：16px · md）が表示され、Enter キーを押すと、生の px 値ではなく Set \padding` to `var(--spacing-md)`` が出力されます。ユーザーは引き続き数字を入力して、任意の px 値に変更できます。

スライドに scale を指定する必要はありません。property から自動検出されます。スライドのスナップを無効にするには scale: null を渡し、設定を上書きするには scale: "spacing" | "text" | "radius" | "color" を渡します。検出結果を完全に上書きするには tokens: [{ name, value, numeric }] を渡します。トークンへのスナップを使用する場合は unit: "px" を使用してください（ランタイムはトークンの生の値を適用するため、rem／em トークンも正しく解決されます）。

ステップ 3 — 対象要素を指定する

ソース内の変更した要素に data-budge-target を追加します。

<div data-budge-target style={{ paddingTop: '16px' }}>

ステップ 4 — 有効化する

StrReplace を使い、スライドを JSON として渡して、<body> 内の app/layout.tsx に設定要素を追加します。

<div data-budge={JSON.stringify({ slides: [
  { label: "padding-top", property: "padding-top", min: 0, max: 64, value: 16, original: 8, unit: "px" },
  { label: "padding-bottom", property: "padding-bottom", min: 0, max: 64, value: 8, original: 8, unit: "px" },
  { label: "padding-left", property: "padding-left", min: 0, max: 64, value: 12, original: 12, unit: "px" },
] })} hidden />

ステップ 5 — 完了する

これでターンは終了です。 ブラウザーを開いたり、パネルを確認したり、ユーザーの応答を待ったりしないでください。Next.js HMR によって変更が反映されます。

ユーザーには次のように伝えます：「X を Y に変更しました。↑↓で微調整し、←→でプロパティを切り替えてください。」

ユーザーが送信されたプロンプトを貼り付けたら、通常の編集指示として扱い、編集を行って data-budge 設定要素を削除します。