budge

Budge

主动式技能。仅适用于 Next.js App Router。 如果任务仅涉及修改一个 CSS 属性或 Tailwind 类，请自动使用此技能。用户不应需要说“使用 budge”。

进行单次视觉更改后，你会在页面上显示一个浮动栏。用户可以用方向键（↑↓）微调数值，用方向键（←→）切换相关属性。在当前运行时中，进行视觉更改后请立即结束当前轮次——不要与浏览器交互，不要等待，也不要手动配置，除非需要使用下方的备用方案。

运行时是一个独立的 IIFE，通过 next/script 从 https://www.budge.design/budge.iife.js 加载。在本地/开发环境的主机上，它会保留在页面中，监视由 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 后将 Budge 关联到生成的 DOM 更改。告诉用户：“我已将 X 更改为 Y。使用 ↑↓ 微调，使用 ←→ 切换属性。”

仅当浮动栏未出现，或无法从一次数值型 class/style DOM 变更中推断出更改时，才使用以下手动步骤。

---

故障排除 — 浮动栏未出现

1. 缺少脚本： 确认 app/layout.tsx 中存在 <Script src="https://www.budge.design/budge.iife.js" strategy="afterInteractive" />。
2. 自动检测已禁用： 默认情况下，自动检测会在本地/开发环境的主机上运行。可在 script 标签上添加 data-budge-autodetect="true" 强制启用，或设置为 "false" 将其禁用。
3. 无法推断 DOM 更改： 只有当 DOM 中存在一个带有非空 slides 数组的 <div data-budge="..." hidden /> 元素时，备用浮动栏才会出现。
4. 未找到目标： 带有 data-budge-target 的元素必须在水合后位于 DOM 中。

---

手动备用方案 — 触发测试

进行更改后，执行此机械测试。不要使用主观判断。

最后一次 StrReplace 调用恰好只修改了一个 CSS 值字面量，或恰好只修改了一个 Tailwind 工具类标记，并且仅涉及一个文件。该更改不是变量、混合宏或主题令牌。

通过： padding: 8px → padding: 16px | className="p-2 m-4" → className="p-4 m-4" 未通过： 修改了两个值、添加/删除了标记、修改了 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 个相关属性。读取其当前计算值/声明值。使用合理的最小值/最大值范围。

示例 — Agent 将 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" },
]

示例 — Agent 将 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" },
]

示例 — Agent 将 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 属性和像素值（间距比例 × 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-*），将主幻灯片设为其中一个轴向属性，但要将两个属性都作为幻灯片包含进来。

对于 Tailwind 类，还要在目标元素上添加内联样式覆盖，以便运行时可以直接操作该值：

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

设计令牌吸附

如果项目将设计令牌定义为 :root 或 @theme 上的 CSS 自定义属性（Tailwind v4、Shadcn、普通 CSS 变量），运行时会根据属性与比例的匹配，自动将 ↑/↓ 步进值吸附到这些令牌：

属性匹配	发现的前缀
padding*、margin*、gap	--spacing-*
font-size	--text-*
border-radius*	--radius-*
color、*-color	--color-*（暂不吸附——调色板循环将在后续支持）

当令牌与当前值匹配时，控件会显示令牌名称（例如 16px · md），按 Enter 会发出 Set \padding` to `var(--spacing-md)``，而不是原始 px 值。用户仍可输入数字，改用任意 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 在 <body> 内向 app/layout.tsx 添加配置元素，并将幻灯片作为 JSON 传入：

<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 配置元素。