agentcss 0.0.0-stage → 0.11.3

package/ai/motion-policy.json

@@ -0,0 +1,22 @@
+{
+  "_comment": "减少动效（prefers-reduced-motion）下的保留清单。默认一律关掉；只有列在 keep 里的组件允许保留动画，且必须写明为什么 —— 判定见 05-audit/motion.py --reduced-audit。⚠️ 不登记却私自保留 = 红：这正是本文件存在的意义。",
+  "version": "1.0.0",
+  "keep": {
+    "button": {
+      "file": "02-primitives/button/button.css",
+      "reason": "按钮里的 spinner 是「提交正在进行」的唯一证据。停掉它，用户会以为没点上，从而重复提交。"
+    },
+    "states": {
+      "file": "03-patterns/states/states.css",
+      "reason": "加载态停住 ⇒ 用户看到一个永远不动的界面，比有动画更糟。骨架屏的静态占位保留、扫光停止。"
+    },
+    "form-validation": {
+      "file": "03-patterns/form-validation/form-validation.css",
+      "reason": "校验中的小 spinner：没有它就没有「正在检查」的反馈，用户会重复提交表单。"
+    }
+  },
+  "shorten": {
+    "_comment": "颜色/透明度类允许保留但缩短到 --dur-fast。这一档**不强制**：本库没有为它逐文件改造（20 多个文件只为一个观感细节），所以不做机器判定 —— 写了却没判据的规则比没有规则更糟。",
+    "note": "组件若在 reduced 块里用 transition-duration: var(--dur-fast) 保留颜色过渡，审计不报错。"
+  }
+}

package/ai/patch.js

@@ -0,0 +1,323 @@
+/*
+ * patch.js — 补丁 API：作用对象是**语义 id**，不是 HTML
+ *
+ * ============================================================================
+ * 🔴 为什么是 id 而不是别的
+ * ----------------------------------------------------------------------------
+ * 三种"指向要改哪里"的方式：
+ *
+ *   ① HTML 路径  「第 3 个 div 的第 2 个子节点」
+ *      ⇒ 任何一次结构变动都会让它失效。改 A 的时候 B 的引用就悄悄变了。
+ *   ② CSS 选择器 「.page-3 h1」
+ *      ⇒ 作用域扩散到整个文档（INVARIANT I-1 / I-2）。这是事故的直接形态。
+ *   ③ 语义 id
+ *      ⇒ 稳定、可比、可 diff、可回放。**改别的地方不影响它。**
+ *
+ * ============================================================================
+ * 🔴 move 是**结构上不可能出错**的操作
+ * ----------------------------------------------------------------------------
+ * "改布局把内容弄没了" 这个故障，靠提醒 AI 小心是治不好的 ——
+ * 因为整篇重写时，"内容"和"位置"混在同一个字符串里。
+ *
+ * ⇒ 解法是把它们拆开：move 只改 children 数组，**一个字节的内容都不碰**。
+ *   这不是"小心一点"，是**让那类错误无法被表达出来**。
+ *
+ * ============================================================================
+ * 五种操作
+ * ----------------------------------------------------------------------------
+ *   create  { op, node, parent, index }   新建节点并挂到 parent
+ *   update  { op, id, set, unset }        改属性/文本（不动结构）
+ *   move    { op, id, parent, index }     只改挂载位置，内容保持不变
+ *   delete  { op, id }                    删除节点及其子树
+ *   replace { op, id, node }              整体替换（保留挂载位置与 id）
+ * ============================================================================
+ */
+'use strict';
+
+var OPS = ['create', 'update', 'move', 'delete', 'replace'];
+
+// 每种操作的必填字段。与 ai/patch.schema.json 的 opRequirements 保持一致。
+var REQUIRED = {
+  create: ['op', 'node'],
+  update: ['op', 'id'],
+  move: ['op', 'id', 'parent'],
+  delete: ['op', 'id'],
+  replace: ['op', 'id', 'node']
+};
+
+function clone(v) {
+  return v === undefined ? v : JSON.parse(JSON.stringify(v));
+}
+
+function fail(path, msg) {
+  return { path: path, msg: msg };
+}
+
+/**
+ * 校验补丁本身（不碰文档）。返回错误数组，空数组 = 合法。
+ */
+function validatePatch(patch) {
+  var errors = [];
+  if (!patch || typeof patch !== 'object') {
+    return [fail('', '补丁必须是一个对象')];
+  }
+  if (!Array.isArray(patch.ops)) {
+    return [fail('/ops', '补丁必须含 ops 数组')];
+  }
+  patch.ops.forEach(function (op, i) {
+    var p = '/ops/' + i;
+    if (!op || typeof op !== 'object') {
+      errors.push(fail(p, '操作必须是对象'));
+      return;
+    }
+    if (OPS.indexOf(op.op) < 0) {
+      errors.push(fail(p + '/op', '未知操作 ' + JSON.stringify(op.op) +
+        '（可用：' + OPS.join(' / ') + '）'));
+      return;
+    }
+    REQUIRED[op.op].forEach(function (k) {
+      if (op[k] === undefined) {
+        errors.push(fail(p, op.op + ' 操作缺少字段 ' + k));
+      }
+    });
+    if (op.op === 'create' && op.node && !op.node.id) {
+      errors.push(fail(p + '/node/id', 'create 的节点必须有 id'));
+    }
+    if (op.op === 'create' && op.node && !op.node.kind) {
+      errors.push(fail(p + '/node/kind', 'create 的节点必须有 kind'));
+    }
+    if (op.parent !== undefined && op.parent !== null &&
+        typeof op.parent !== 'string') {
+      errors.push(fail(p + '/parent', 'parent 必须是节点 id 或 null（表示顶层）'));
+    }
+  });
+  return errors;
+}
+
+function detachFromParent(nodes, id) {
+  Object.keys(nodes).forEach(function (pid) {
+    var ch = nodes[pid].children;
+    if (!Array.isArray(ch)) return;
+    var at = ch.indexOf(id);
+    while (at >= 0) {
+      ch.splice(at, 1);
+      at = ch.indexOf(id);
+    }
+  });
+  var root = nodes.__root || [];
+  var at2 = root.indexOf(id);
+  while (at2 >= 0) {
+    root.splice(at2, 1);
+    at2 = root.indexOf(id);
+  }
+}
+
+function subtree(nodes, id) {
+  var out = [id];
+  (nodes[id].children || []).forEach(function (c) {
+    if (nodes[c]) out = out.concat(subtree(nodes, c));
+  });
+  return out;
+}
+
+function attach(nodes, id, parent, index) {
+  if (parent === null || parent === undefined) {
+    if (!Array.isArray(nodes.__root)) nodes.__root = [];
+    if (index === undefined || index < 0 || index > nodes.__root.length) {
+      nodes.__root.push(id);
+    } else {
+      nodes.__root.splice(index, 0, id);
+    }
+    return null;
+  }
+  if (!nodes[parent]) {
+    return fail('', '父节点不存在：' + parent);
+  }
+  if (!Array.isArray(nodes[parent].children)) nodes[parent].children = [];
+  var ch = nodes[parent].children;
+  if (index === undefined || index < 0 || index > ch.length) ch.push(id);
+  else ch.splice(index, 0, id);
+  return null;
+}
+
+/**
+ * 应用补丁。**不修改传入的 doc** —— 成功才返回新文档，失败原文档不受影响。
+ * @returns {{ok:boolean, doc:object, errors:Array, applied:number}}
+ */
+function apply(doc, patch) {
+  var errs = validatePatch(patch);
+  if (errs.length) return { ok: false, doc: doc, errors: errs, applied: 0 };
+
+  var work = clone(doc);
+  work.nodes = work.nodes || {};
+  // root 用内部键承载，apply 结束时写回 doc.root
+  work.nodes.__root = Array.isArray(work.root) ? work.root.slice() : [];
+  delete work.root;
+
+  var applied = 0;
+  var errors = [];
+
+  for (var i = 0; i < patch.ops.length; i++) {
+    var op = patch.ops[i];
+    var p = '/ops/' + i;
+
+    if (op.op === 'create') {
+      if (work.nodes[op.node.id]) {
+        errors.push(fail(p, '节点 id 已存在：' + op.node.id +
+          '（create 不覆盖；要覆盖请用 replace）'));
+        continue;
+      }
+      work.nodes[op.node.id] = clone(op.node);
+      var e = attach(work.nodes, op.node.id, op.parent, op.index);
+      if (e) { errors.push({ path: p, msg: e.msg }); delete work.nodes[op.node.id]; continue; }
+      applied++;
+      continue;
+    }
+
+    if (op.op === 'update') {
+      var n = work.nodes[op.id];
+      if (!n) { errors.push(fail(p, '节点不存在：' + op.id)); continue; }
+      if (op.set) {
+        Object.keys(op.set).forEach(function (k) {
+          if (k === 'id') { errors.push(fail(p + '/set/id', '不允许改 id（等于换了一个节点）')); return; }
+          n[k] = clone(op.set[k]);
+        });
+      }
+      (op.unset || []).forEach(function (k) {
+        if (k === 'id') { errors.push(fail(p + '/unset/id', '不允许删除 id')); return; }
+        delete n[k];
+      });
+      applied++;
+      continue;
+    }
+
+    if (op.op === 'move') {
+      if (!work.nodes[op.id]) { errors.push(fail(p, '节点不存在：' + op.id)); continue; }
+      // 🔴 内容保持不变：只改挂载关系
+      detachFromParent(work.nodes, op.id);
+      var e2 = attach(work.nodes, op.id, op.parent, op.index);
+      if (e2) { errors.push({ path: p, msg: e2.msg }); continue; }
+      applied++;
+      continue;
+    }
+
+    if (op.op === 'delete') {
+      if (!work.nodes[op.id]) { errors.push(fail(p, '节点不存在：' + op.id)); continue; }
+      var doomed = subtree(work.nodes, op.id);
+      detachFromParent(work.nodes, op.id);
+      doomed.forEach(function (d) { delete work.nodes[d]; });
+      applied++;
+      continue;
+    }
+
+    if (op.op === 'replace') {
+      var old = work.nodes[op.id];
+      if (!old) { errors.push(fail(p, '节点不存在：' + op.id)); continue; }
+      var parentId = null, idx = -1;
+      Object.keys(work.nodes).forEach(function (pid) {
+        if (pid === '__root') return;
+        var at = (work.nodes[pid].children || []).indexOf(op.id);
+        if (at >= 0) { parentId = pid; idx = at; }
+      });
+      if (idx < 0) {
+        idx = (work.nodes.__root || []).indexOf(op.id);
+        parentId = null;
+      }
+      var kept = clone(op.node);
+      kept.id = op.id;                          // id 必须保持
+      subtree(work.nodes, op.id).forEach(function (d) {
+        if (d !== op.id) delete work.nodes[d];
+      });
+      work.nodes[op.id] = kept;
+      detachFromParent(work.nodes, op.id);
+      var e3 = attach(work.nodes, op.id, parentId, idx);
+      if (e3) { errors.push({ path: p, msg: e3.msg }); continue; }
+      applied++;
+      continue;
+    }
+  }
+
+  if (errors.length) {
+    return { ok: false, doc: doc, errors: errors, applied: applied };
+  }
+
+  var root = work.nodes.__root || [];
+  delete work.nodes.__root;
+  work.root = root;
+  return { ok: true, doc: work, errors: [], applied: applied };
+}
+
+/**
+ * 确定性检查：同一份文档 + 同一份补丁，跑两次结果必须逐字节相同。
+ * ⚠️ 这是"可回放"的可验证形式 —— 不是声称，是能跑出来的断言。
+ */
+function isDeterministic(doc, patch) {
+  var a = apply(doc, patch);
+  var b = apply(doc, patch);
+  if (a.ok !== b.ok) return false;
+  return JSON.stringify(a.doc) === JSON.stringify(b.doc);
+}
+
+/**
+ * 反向补丁（撤销用）。
+ * ⚠️ 只对**已成功应用**的补丁有意义；失败补丁无法求逆。
+ */
+function invert(doc, patch) {
+  var ops = [];
+  var errs = validatePatch(patch);
+  if (errs.length) return { ok: false, ops: [], errors: errs };
+
+  var nodes = doc.nodes || {};
+  for (var i = patch.ops.length - 1; i >= 0; i--) {
+    var op = patch.ops[i];
+    if (op.op === 'create') {
+      ops.push({ op: 'delete', id: op.node.id });
+    } else if (op.op === 'delete') {
+      var n = nodes[op.id];
+      if (!n) return { ok: false, ops: [], errors: [fail('/ops/' + i, '撤销失败：原节点已不存在')] };
+      var parentId = null, idx = 0;
+      Object.keys(nodes).forEach(function (pid) {
+        var at = (nodes[pid].children || []).indexOf(op.id);
+        if (at >= 0) { parentId = pid; idx = at; }
+      });
+      if (parentId === null) idx = (doc.root || []).indexOf(op.id);
+      ops.push({ op: 'create', node: clone(n), parent: parentId, index: idx });
+    } else if (op.op === 'move') {
+      var parent0 = null, idx0 = 0;
+      Object.keys(nodes).forEach(function (pid) {
+        var at = (nodes[pid].children || []).indexOf(op.id);
+        if (at >= 0) { parent0 = pid; idx0 = at; }
+      });
+      if (parent0 === null) idx0 = (doc.root || []).indexOf(op.id);
+      ops.push({ op: 'move', id: op.id, parent: parent0, index: idx0 });
+    } else if (op.op === 'update' || op.op === 'replace') {
+      var before = nodes[op.id];
+      if (!before) {
+        return { ok: false, ops: [], errors: [fail('/ops/' + i, '撤销失败：原节点已不存在')] };
+      }
+      if (op.op === 'update') {
+        var set = {}, unset = [];
+        (op.set ? Object.keys(op.set) : []).forEach(function (k) {
+          if (before[k] === undefined) unset.push(k);
+          else set[k] = clone(before[k]);
+        });
+        (op.unset || []).forEach(function (k) {
+          if (before[k] !== undefined) set[k] = clone(before[k]);
+        });
+        ops.push({ op: 'update', id: op.id, set: set, unset: unset });
+      } else {
+        ops.push({ op: 'replace', id: op.id, node: clone(before) });
+      }
+    }
+  }
+  return { ok: true, ops: ops, errors: [] };
+}
+
+module.exports = {
+  OPS: OPS,
+  REQUIRED: REQUIRED,
+  validatePatch: validatePatch,
+  apply: apply,
+  invert: invert,
+  isDeterministic: isDeterministic
+};

package/ai/patch.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://frontend-lib.dev/ai/patch.schema.json",
+  "title": "frontend-lib 补丁操作契约",
+  "$comment": [
+    "🔴 补丁的作用对象是【语义 id】，不是 HTML、也不是 CSS 选择器。",
+    "",
+    "为什么：",
+    "  · HTML 路径（第 3 个 div 的第 2 个子节点）—— 结构一变就失效",
+    "  · CSS 选择器（.page-3 h1）—— 会把作用域扩散到整个文档（I-1/I-2）",
+    "  · 语义 id —— 稳定、可比、可回放、可 diff",
+    "",
+    "五种操作：create / update / move / delete / replace",
+    "其中 **move 是内容保持操作**：只改挂载位置，一个字节的内容都不碰。",
+    "这是对『改布局把内容改没了』这个具体故障的直接回答 ——",
+    "把它做成一种**结构上不可能出错**的操作，而不是靠提醒 AI 小心。"
+  ],
+  "type": "object",
+  "required": ["schemaVersion", "ops"],
+  "properties": {
+    "schemaVersion": { "type": "string" },
+    "ops": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/op" }
+    }
+  },
+  "definitions": {
+    "op": {
+      "type": "object",
+      "required": ["op"],
+      "properties": {
+        "op": {
+          "type": "string",
+          "enum": ["create", "update", "move", "delete", "replace"]
+        },
+        "id": { "type": "string" },
+        "node": { "type": "object" },
+        "parent": { "type": ["string", "null"] },
+        "index": { "type": "number" },
+        "set": { "type": "object" },
+        "unset": { "type": "array", "items": { "type": "string" } },
+        "$comment": { "type": "string" }
+      },
+      "allOf": [
+        {
+          "$comment": "五种操作各自的必需字段（用 allOf 表达，便于校验器逐条给出原因）"
+        }
+      ]
+    }
+  },
+  "opRequirements": {
+    "$comment": [
+      "这张表不是 JSON Schema 标准键，是我们的**元信息**，",
+      "由 ai/validate.js 读取执行（表达力比 allOf/if-then 强，且报错可读）。",
+      "放在这里而不是写在代码里，是为了让『每种操作需要什么』这件事可被外部读取。"
+    ],
+    "create":  ["op", "node"],
+    "update":  ["op", "id"],
+    "move":    ["op", "id", "parent"],
+    "delete":  ["op", "id"],
+    "replace": ["op", "id", "node"]
+  }
+}

package/ai/profiles.json

@@ -0,0 +1,92 @@
+{
+  "$comment": [
+    "三档 Profile：约束的【松紧】是可以选的，但 Invariant 在任何档位下都必须成立。",
+    "",
+    "🔴 这为什么重要（架构悖论的解）",
+    "   恐惧是：今天为防 AI 犯错加的约束，明天变成更强 AI 的天花板。",
+    "   解法不是'以后再说'，是**把松紧做成可选项 + 把边界分层**：",
+    "     · Invariant（客观事实）   —— 任何档位都不能违反",
+    "     · Contract（版本化约定） —— 任何档位都不能违反，但可以升版本",
+    "     · Guidance（工作建议）   —— creative 档位下只是提示",
+    "     · 组件成熟度门槛          —— 三档不同，这是松紧的来源",
+    "   ⇒ 模型变强 ⇒ 用户切到 creative，而不是我们去删约束。",
+    "   ⇒ 约束永远留着给需要的人，不成为任何人的天花板。"
+  ],
+  "schemaVersion": "1.0.0",
+  "profiles": {
+    "creative": {
+      "label": "放开了做",
+      "allowedMaturity": ["alpha", "beta", "stable"],
+      "allowedUnknownComponent": true,
+      "allowedUnknownVariant": true,
+      "allowedUnknownState": true,
+      "allowedExtensions": true,
+      "guidanceLevel": "advisory",
+      "$comment": [
+        "适合：探索期、原型、模型很强且你能自己看结果。",
+        "未知组件/变体/状态都放行 —— 因为本库的组件集合本来就不完整，",
+        "不让用新东西等于让使用者为我们的缺口买单。"
+      ]
+    },
+    "standard": {
+      "label": "默认",
+      "allowedMaturity": ["beta", "stable"],
+      "allowedUnknownComponent": true,
+      "allowedUnknownVariant": true,
+      "allowedUnknownState": false,
+      "allowedExtensions": true,
+      "guidanceLevel": "warn",
+      "$comment": [
+        "适合：日常。不允许用**没在契约里登记过的状态取值**，",
+        "因为状态取值写错 = 组件静默停在错误状态（I-8/I-9），",
+        "这是最难靠肉眼发现的一类错误。",
+        "但允许没登记过的组件/变体 —— 我们的清单不全，不该卡住使用者。"
+      ]
+    },
+    "strict": {
+      "label": "只许用验证过的",
+      "allowedMaturity": ["stable"],
+      "allowedUnknownComponent": false,
+      "allowedUnknownVariant": false,
+      "allowedUnknownState": false,
+      "allowedExtensions": false,
+      "guidanceLevel": "error",
+      "$comment": [
+        "适合：交付物、要交给别人维护的东西、无人值守的自动化流水线。",
+        "只允许成熟度 = stable 的组件（名单/数量以 ai/components.json 的 maturity 字段为准，",
+        "不要信这里的数字 —— 数字会漂移，机器文件不会）。",
+        "",
+        "⚠️ 诚实说明：这一档位下 **beta 组件不可用**（0.7.6 实测 7 个 / 共 27 个）。",
+        "   这不是缺陷，是信息 —— 它告诉你这批组件还有**行为欠账**：",
+        "   行为矩阵里标着 manual（手写副本未收编）或 gap（该做没做），",
+        "   ⇒ 改一处不会全库跟着变（I-14 的病）。",
+        "   欠账清零后档位会自动升 stable（maturity 是算出来的，见 components.meta.json）。",
+        "",
+        "🔴 0.7.6（M8）之前这里写的是「11 个不可用、现已全部升完」—— 那时 27 个全 stable，",
+        "   ladder 等于没有鉴别力。补上第 4 条判据（行为欠账）后，7 个回到 beta。**这是**",
+        "   **判据变严了，不是组件变差了**：同一批组件，以前被算作 stable 只因为判据没问到点上。"
+      ]
+    }
+  },
+  "alwaysEnforced": {
+    "$comment": [
+      "无论哪一档都必须成立 —— 这些是 Invariant，不是偏好。",
+      "",
+      "🔴 适用范围：以下规则约束的是【采用本库契约】的场景",
+      "   （用本库组件，或明确按本库范式产出页面）。",
+      "   它们不是对所有 HTML / 网站任务的普遍禁令 ——",
+      "   改一个已有网站时，宿主项目原有的体系优先；",
+      "   本库组件不适用时，可以用别的实现方式。",
+      "",
+      "措辞与 docs/INVARIANT.md 保持同步：",
+      "   I-5 区分内容色与效果色；I-2 说明的是代价而非绝对禁止；",
+      "   I-8 说的是「状态的存在依赖 JS 执行过」，不是「class 不可读」。"
+    ],
+    "rules": [
+      "不得写裸标签选择器 —— 裸标签的作用域是整个文档，会改掉宿主页面（I-1）",
+      "本该跟随主题的内容色与间距不得绕过令牌；效果色（阴影等）不受此约束（I-5）",
+      "用页面级 override 表达局部改动时特异性只增不减 —— 这是代价，不是绝对禁止（I-2）",
+      "状态不得只存在于由 JS 维护的类名里 —— 否则其存在依赖 JS 执行过（I-8）"
+    ]
+  }
+}

package/ai/tokens.audience.json

@@ -0,0 +1,55 @@
+{
+  "schemaVersion": "1.0.0",
+  "source": "01-tokens/tokens.css",
+  "$comment": "手写，不是生成的。生成出来的『契约』只跟再生成一遍比，没有引入新信息（见 docs/INVARIANT.md I-10 实证 9）。这个文件回答的问题是：每个令牌是**给谁用的**。",
+
+  "audiences": {
+    "public": "契约的一部分：文档承诺使用者可以直接引用。改名/改值算破坏性变更。",
+    "internal": "库自己的实现细节：使用者不该依赖。可以改名改值，不必公告。",
+    "reference": "给人/脚本读的常量：CSS 里**物理上不可能**被 var() 引用（断点进不了 media query 条件），所以『没人引用』是它的本分，不是病。"
+  },
+
+  "families": {
+    "--accent":   { "audience": "public",    "why": "品牌色三档（--accent / -hover / -soft）：换主题色的第一入口" },
+    "--border":   { "audience": "public",    "why": "描边三档：控件 / 装饰 / 强装饰" },
+    "--bp-":      { "audience": "reference", "why": "断点：CSS media query 条件里用不了 var()，只能当锚点给流体计算和脚本查询" },
+    "--danger":   { "audience": "public",    "why": "危险色（--danger / -hover / -bg）" },
+    "--dur-":     { "audience": "public",    "why": "时长阶梯：快 / 基准 / 慢" },
+    "--ease-":    { "audience": "public",    "why": "缓动阶梯：默认 / 进出 / 滑入" },
+    "--fs-":      { "audience": "public",    "why": "字号阶梯：阶梯允许有暂未使用的档位（那是阶梯，不是死代码）" },
+    "--info":     { "audience": "public",    "why": "信息色（--info / -bg）" },
+    "--lh-":      { "audience": "public",    "why": "行高阶梯：紧 / 基准 / 松" },
+    "--lift-":    { "audience": "public",    "why": "动效的位移量（translate 的距离），不是阴影 —— 同样时长下幅度不统一就会感觉乱" },
+    "--measure-": { "audience": "public",    "why": "版心阶梯：正文 / 标题 / 导语 / 引言 / 边注 / 页面列宽" },
+    "--mono":     { "audience": "public",    "why": "等宽字族" },
+    "--paper":    { "audience": "public",    "why": "页面底色" },
+    "--popover-": { "audience": "internal",  "why": "气泡组件自己的尺寸与时长，是组件调参不是主题令牌" },
+    "--progress": { "audience": "internal",  "why": "进度条内部参数（--progress 是数值本身，不是族前缀）" },
+    "--r-":       { "audience": "public",    "why": "圆角阶梯" },
+    "--raw-":     { "audience": "internal",  "why": "L1 原始值层（D5 分层）：**当前配色的取值本身**，由语义令牌 var() 引用。组件只该用语义名；换一套品牌配色时这一层整体替换 ⇒ 使用者依赖它就是依赖实现细节。它不进 ai/tokens.tree.json（对外契约只承诺语义名）" },
+    "--ring-":    { "audience": "internal",  "why": "焦点环尺寸，只由 focus-ring.css 消费" },
+    "--sans":     { "audience": "public",    "why": "无衬线字族" },
+    "--scrim":    { "audience": "internal",  "why": "遮罩底色，overlay 用" },
+    "--scrollbar-": { "audience": "internal", "why": "滚动条外观，scrollbar.css 用" },
+    "--serif":    { "audience": "public",    "why": "衬线字族" },
+    "--shadow-":  { "audience": "public",    "why": "阴影阶梯 1 / 2" },
+    "--skeleton-":{ "audience": "internal",  "why": "骨架屏内部参数" },
+    "--sp-":      { "audience": "public",    "why": "间距阶梯 1–8" },
+    "--success":  { "audience": "public",    "why": "成功色（--success / -bg）" },
+    "--surface":  { "audience": "public",    "why": "表面色（--surface / -sunken / -raised）" },
+    "--switch-":  { "audience": "internal",  "why": "开关轨道色，只由 switch 消费" },
+    "--sz-":      { "audience": "public",    "why": "触控尺寸（--sz-touch / -sm）：点按目标最小边" },
+    "--text-":    { "audience": "public",    "why": "文字色五档（primary / secondary / tertiary / on-accent / on-solid）" },
+    "--tooltip-": { "audience": "internal",  "why": "气泡的一对反色面（bg / fg / border），只由 tooltip 消费。它替代了原先把 `prefers-color-scheme` 写进组件的那段分支（RFC-THEME-SCOPE D5）—— 是组件实现细节，不承诺改名" },
+    "--tracking-":{ "audience": "public",    "why": "字距阶梯（标题 / 常规）" },
+    "--warning":  { "audience": "public",    "why": "警告色（--warning / -bg）" },
+    "--z-":       { "audience": "internal",  "why": "层级栈：库内部层序，使用者不该依赖具体数值（依赖了就会和以后的层打架）" }
+  },
+
+  "tokens": {},
+
+  "budget": {
+    "orphan": 4,
+    "$comment": "棘轮：孤儿令牌总数只能降。降了就把这个数字一起改小，不许偷偷升。2026-10-10：--lh-loose / --fs-xl 被新增 recipe 引用，7→5；同日 04-recipes/report 改在自身层内重定义边注宽 ⇒ --measure-aside 由『被引用』回到『无引用』，5→5→再核为 4。"
+  }
+}

package/ai/tokens.audience.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://frontend-lib.dev/ai/tokens.audience.schema.json",
+  "title": "frontend-lib 令牌受众登记",
+  "$comment": [
+    "描述 ai/tokens.audience.json 的形状：**每个令牌是给谁用的**。",
+    "",
+    "🔴 为什么这份登记要存在：『声明了 108 个令牌、9 个从没被引用』早就量出来过，",
+    "   但它只是一句观察，不是判据 ⇒ 没人被它拦住过。而那 9 个根本不是同一种东西：",
+    "     · 断点          物理上不可能被 var() 引用（进不了 media query 条件）",
+    "     · 阶梯档位      没人用是本分（那是阶梯）",
+    "     · 为某组件造的  造它的人以为接上了，其实没有 ⇒ 真缺陷",
+    "     · 被取代的遗留  死重量 ⇒ 真缺陷",
+    "   在『只数孤儿个数』的视角下它们完全一样 ⇒ 必须先登记受众，判据才有鉴别力。",
+    "",
+    "🔴 三种受众：",
+    "   public    契约的一部分：文档承诺使用者可以直接引用；改名/改值算破坏性变更",
+    "   internal  库自己的实现细节：使用者不该依赖",
+    "   reference 给人/脚本读的常量：CSS 里物理上不可能被 var() 引用",
+    "",
+    "⚠️ 本文件是**手写**的，不是生成的。生成出来的『契约』只跟再生成一遍比，",
+    "   没有引入任何新信息（docs/INVARIANT.md I-10 实证 9）。",
+    "⚠️ 本 schema 只用了 ai/validate.js 白名单里的关键字（propertyNames 不在白名单）。"
+  ],
+  "type": "object",
+  "required": ["schemaVersion", "audiences", "families", "tokens", "budget"],
+  "properties": {
+    "schemaVersion": { "type": "string" },
+    "source": { "type": "string" },
+    "$comment": { "type": "string" },
+    "audiences": {
+      "type": "object",
+      "required": ["public", "internal", "reference"],
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "families": {
+      "type": "object",
+      "patternProperties": {
+        "^--[a-z][a-z0-9-]*$": {
+          "type": "object",
+          "required": ["audience", "why"],
+          "properties": {
+            "audience": { "enum": ["public", "internal", "reference"] },
+            "why": { "type": "string", "minLength": 1 }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "tokens": {
+      "type": "object",
+      "patternProperties": {
+        "^--[a-z][a-z0-9-]*$": {
+          "type": "object",
+          "required": ["audience", "why"],
+          "properties": {
+            "audience": { "enum": ["public", "internal", "reference"] },
+            "why": { "type": "string", "minLength": 1 }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "budget": {
+      "type": "object",
+      "required": ["orphan"],
+      "properties": {
+        "orphan": { "type": "integer", "minimum": 0 },
+        "$comment": { "type": "string" }
+      }
+    }
+  }
+}