[Github] Modern Web Guidance – Google Chrome 团队给 AI 编程代理的前端开发指南

Github发现2026-11-13发布 WarpEdit

让 AI 给网页弹窗加一段退场动画，它可能会写一个定时器，等动画结束再隐藏弹窗。浏览器其实已经能用 CSS 处理其中不少细节。难的是知道该用哪些属性，以及哪些旧浏览器还得另外照顾。Google Chrome 团队发布的 Modern Web Guidance 把这类判断整理成了 AI 编程代理能按需检索的指南。它也有独立的命令行工具，开发者自己就能查。

Modern Web Guidance 封面，透明浏览器窗口上悬着一块琥珀色弹窗面板

让代理带着具体问题查指南

2026 年 11 月 10 日发布的 1.0 稳定版包含两条工作路径：写新功能时按需求找指南，维护旧项目时先扫描已有代码。指南由 Chrome、Edge、Firefox、MDN 团队和 Web 开发社区共同维护。虽然项目放在 GoogleChrome 名下，它关心的是你的页面在不同浏览器里怎么工作。

本机有 Node.js 22 或更新版本就能试。下面两条命令固定为本文核对的 1.0.0，无需先给编辑器安装技能。第一条搜索的是一个具体需求，第二条用搜索结果里的 ID 取回指南：

npx modern-web-guidance@1.0.0 search "animate a dialog modal backdrop"
npx modern-web-guidance@1.0.0 retrieve animate-to-from-top-layer

在本次运行中，第一条结果就是 animate-to-from-top-layer。同一批结果里还有“点背景关闭弹窗”和“弹窗打开时阻止底层滚动”。描述看起来相近，解决的却是三件事。把搜索词写成用户能看到的行为，比只搜一个 dialog 更容易挑中需要的那份。

弹窗动画查询返回的前三项指南，分别处理顶层动画、点击外部关闭和阻止背景滚动 — 本次本地检索的前三项结果。ID 旁边的描述能帮助判断，哪一份指南回答了当前的问题。

取回的指南解释了一个很容易看漏的问题：弹窗刚出现时没有上一帧可供过渡，@starting-style 可以指定入场起点；关闭时还要考虑 display 和 overlay，否则弹窗可能在淡出结束前就消失。指南也讨论了用户偏好减少动态效果时怎么处理。本次 CLI 把较长的指南写进临时 Markdown 文件，并在终端打印路径，打开文件即可阅读全文。

用一个登录表单试试扫描

如果手头已经有一套网页，可以把 legacy-scan 指向前端目录。我们建了一个只有 login.html 的本地示例，密码框写成 <input type="password" name="password">，再运行：

npx modern-web-guidance@1.0.0 legacy-scan ./demo

扫描器报了 1 条，指向 login.html:6 和 autofill-sign-in-form 指南。它能认出密码输入框，却不能仅凭 type="password" 替开发者判断用户在填哪种秘密。这个示例是登录现有账号，所以给密码框加上 autocomplete="current-password"；注册新账号时应表达新密码的用途。如果组件已通过外层属性传入正确的值，就应忽略这条提示。

改好后对同一目录再扫一次，结果变成 0 条。这个数字的含义很窄：1.0.0 本次启用了 35 条确定性规则，覆盖 33 份指南；它们没有再命中示例代码。至于浏览器能否按预期填入账号、弹窗能否用键盘关闭，还得在目标浏览器里实际操作。

扫描器定位到 login.html 第 6 行的密码框；补上 current-password 后，复扫返回零条提示 — 同一份登录表单的两次扫描结果节选。修改的是第 6 行的自动填充用途，复扫后这条提示消失。

什么时候值得装进编辑器

偶尔查一次 CSS，直接用 CLI 就够了。如果团队经常让代理写前端，交互式安装向导 npx modern-web-guidance@latest install 可以把查指南这一步放进日常工作流。想自己挑选技能包，可加 --choose：普通网页选 modern-web-guidance，编写 Chrome 扩展时另有 chrome-extensions。仓库也列出了 Codex、Claude Code 和其他工具的专用安装入口。

项目用 Baseline 数据标明 Web 特性在主流浏览器中的支持情况。你的产品如果还支持旧设备，给代理布置任务时，最好写清浏览器范围，以及哪些操作必须保留。例如：“给设置弹窗加淡出效果，旧浏览器可以没有动画，但关闭按钮和 Esc 必须仍然可用。”这样，代理查到兼容性资料后，就能把视觉增强和必需功能分开处理。再用键盘走一遍开关流程，比把所有扫描建议一键采纳更有用。

搜索在本地完成，无需模型 API Key；首次通过 npx 获取工具仍需下载 npm 包。项目默认收集匿名使用数据，可能包含代理名称、检索词和取回的指南 ID，README 说明不收集原始用户提示词。团队如需关闭遥测，可在运行前设置环境变量 DISABLE_TELEMETRY=1。