# 变量生成规则（写变量）

用于 `get_variables` / `agent_update_variables` / `agent_remove_variable`。HTML 引用规范见 `variable-import.md`。

## 1. 零容忍硬红线

1. **绝对禁止创建语义尺寸变量**：严禁创建 `间距/...`、`spacing/...`、`圆角/...`、`radius/...`、`描边/...`、`border/...`、`字号/...` 等任何语义尺寸引用。尺寸统一使用 `基础` collection 中的档位变量（如 `规范尺寸/sm`）。
2. **`语义` Collection 只允许颜色**：`collection: "语义"` 仅允许存放 `type: "PAINT"` 且 `name` 以 `颜色/...` 开头的颜色变量。其余类型一律归入 `基础` collection。
3. **两批提交顺序**：创建整套变量时必须分两批提交——**第 1 批：基础变量** ➜ **第 2 批：语义变量（仅颜色）**。严禁将基础变量与引用基础变量的语义变量同批提交。

## 2. Collection 与数据格式规范

只使用 `"基础"` 与 `"语义"` 两个 collection，通过 `name` 前缀与 `type` 区分：

| Collection | 适用类型 | 名称规范 (`name`)           | Mode & 引用要求                                                          | 典型示例                                                                                                                                                                     |
| :--------- | :------- | :-------------------------- | :----------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **基础**   | `COLOR`  | `基础色板/<颜色>/<阶梯>`    | 写 `value: "#hex"`（通常 10 个色阶）                                     | `{"collection":"基础","type":"COLOR","name":"基础色板/蓝色/600","mode":[{"name":"默认","value":"#2563eb"}]}`                                                                 |
| **基础**   | `NUMBER` | `规范尺寸/<档位>`           | 写 `value: 数字`，档位限 `xs`/`sm`/`md`/`lg`/`xl`/`2xl`/`3xl`/`4xl`      | `{"collection":"基础","type":"NUMBER","name":"规范尺寸/md","mode":[{"name":"默认","value":8}]}`                                                                              |
| **语义**   | `PAINT`  | `颜色/<分类>/<功能>/<状态>` | **必须用 `reference`** 引用已存在的基础色板名；建议配 `亮色`/`暗色` 模式 | `{"collection":"语义","type":"PAINT","name":"颜色/填充/操作/主要","mode":[{"name":"亮色","reference":"基础色板/蓝色/600"},{"name":"暗色","reference":"基础色板/蓝色/400"}]}` |

> ⚠️ **尺寸命名禁忌**：`规范尺寸/...` 的 `name` 严禁使用具体数值（如禁止 `规范尺寸/8`、`规范圆角/12`），数值只能写在 `mode[].value` 中。

## 3. 修改与删除规范

1. **修改已有变量**：必须保留原始 `id`（传 `id` + `name` 即可更新或重命名）。
2. **删除变量**：必须单独调用 `agent_remove_variable` 并显式传入 `id`（如 `{ "id": "7:07131" }`），严禁在更新接口中伪造删除。