给 AI 前端补丁加上层级令牌约束
文章建议要求编码智能体复用仓库现有的 z-index 令牌,新增层级也应集中维护。遇到遮挡问题时,应先排查 transform、isolation 等形成的层叠上下文,避免用巨大数值掩盖根因。
AI 深度解读
弹窗被吸顶导航挡住,AI 把 z-index 改成 9999,顺手给 toast 加到 10000。眼前的遮挡消失了,项目的层级规则却被拆了。下一次修复,可能就得从 10001 开始。
作者提出的办法很直接:让 agent 遵守仓库现有的层级 token,并先检查层叠上下文。这篇短文没有性能数据,也没有对照实验,但给出了一套适合放进 AI 编程提示词和 PR 审查的具体规则。
为什么数字越大,问题反而越难修
作者描述的典型补丁是:dialog 用 9999,toast 用 10000,tooltip 用 1,结果 tooltip 又穿过了 drawer。某个 Storybook story 看起来正常,不代表整套界面的遮挡关系正确。
这里有两类问题。
第一类是规则失控。如果仓库已经定义了 --z-dropdown、--z-modal 和 --z-toast,组件却各自填写数字,后续开发者就得不断猜测谁应该更高。Portal、吸顶导航和第三方组件还会增加排查难度。下一轮 agent 未必知道此前用过 10000,于是继续加到 10001。
第二类是原因找错了。popover 被 header 挡住,可能与 isolation、transform、filter 或父元素的 z-index 有关。这些属性在相应条件下会形成层叠上下文(stacking context),让内部元素在自己的层级范围里排序。
子元素的数字再大,也不能直接越过所属层叠上下文的边界。
因此,给子元素加数字可能无效;给父元素加数字,又可能把整列内容一起抬到导航上方。局部修复会变成另一处遮挡。
给 agent 的应该是层级文件和排查规则
作者把层级刻度视为组件之间的契约,要求集中维护:
- 组件只使用已有 token,例如
var(--z-modal),或者主题中的 Sass、JS 等价定义。 - 新层级统一加到同一个文件,并用一行注释说明它位于哪些层之上、哪些层之下。
- 不通过给相邻组件的值加
1来争抢优先级。 - 用 modal、popover、toast、nav 等语义命名,避免并排出现却无法解释的
zIndex={50}和zIndex={40}。
Tailwind 也一样:使用项目配置过的 z-modal;只有当 z-10 属于现有刻度时才使用它。z-[9999] 并没有因为写成 utility class 就更合理。
下面这段提示词解决的是「agent 不知道应该遵守哪份规则」的问题,原文可以直接复用:
Use only the z-index tokens in src/theme/z-index.css.
Do not invent a new numeric z-index.
If a new layer is required, add a named token in that file and say what it sits above.
If the bug is a stacking context, fix the context — don’t raise the number.
最关键的是最后一行:允许 agent 修复产生错误的上下文,而不是只在数值上找答案。
作者还建议把 token 文件或约 10 行摘录贴进提示词。截图能说明哪里被挡住,却不能告诉 agent 项目允许哪些层级。
PR 则需要留下一行说明:用了哪个 token,或者为什么新增 token。遇到上下文问题,还应该指出具体元素。例如原文给出的 DevTools 说明是:header 存在 transform: translateZ(0),因此 popover 需要 portal 到 document.body。如果设计系统已经规定 overlay 的 portal target,就优先遵守该约定。
我的判断
我赞同把「层级归属」纳入 AI 补丁审查。它能让 reviewer 判断修复是否符合整个产品的遮挡关系,而不只是确认截图变好了。
但这是一套工程经验,作者没有提供误修率、返工次数或团队应用前后的对照数据。不能据此断言,这段提示词就能让 agent 稳定处理所有浮层问题。
「发现裸整数就退回」也有前提:仓库已经建立了可用的层级刻度。如果现有 token 不完整,应该允许补充命名层级;如果项目尚无刻度,需要先明确组件之间的上下关系。单纯禁用数字,不能自动形成设计规则。
另外,document.body 是原文示例中的处理方向,不应被当成所有遮挡问题的统一答案。选对 token 和选对渲染位置需要一起检查,真正要解释的是:哪个元素形成了上下文,浮层为什么应该放在那里。
能拿来做什么
- 让 AI 修复 React 弹窗、popover 或 toast 前,把项目的层级 token 文件和 overlay 的 portal 约定一起提供,明确要求复用现有定义。
- 审查补丁时,重点检查
z-index: 9999、z-[9999]、style={{ zIndex: 10000 }},要求说明对应的语义层级,而不是接受「设高一点就能赢」。 - 遮挡没有解决时,让 agent 先定位形成层叠上下文的元素,记录相关的
transform、filter、isolation或父级z-index,再决定修改上下文还是调整 portal 位置。 - 确实需要新层级时,把 token 加进统一文件,并写清它与 modal、popover、toast、nav 的顺序,让下一次 AI 编程也有规则可循。