现代 Web 指南使用入门

Modern Web Guidance 是一组技能，可将 Web 平台专业知识、最佳实践和浏览器兼容性数据直接嵌入到编码智能体中。这有助于引导编码智能体摆脱旧模式，转而采用能够充分利用现代 Web 平台强大功能和能力的解决方案。

安装

Modern Web Guidance 可与任何支持技能的编码智能体搭配安装和使用。

建议通过 Chrome 团队构建的 modern-web-guidance CLI 进行安装。通过 modern-web-guidance CLI 安装 Modern Web Guidance 将启用自动更新。您可以通过 modern-web-guidance CLI 进行安装，如下所示：

npx modern-web-guidance@latest install

（可选）如果您正在开发 Chrome 扩展程序，我们建议您使用以下命令：

npx modern-web-guidance@latest install --choose

这将运行交互式向导，以便根据您的偏好设置安装技能。

如果您不想使用 modern-web-guidance CLI 安装 Modern Web Guidance，请参阅以下特定于代理的说明。请注意，其中大多数选项都不支持自动更新。

Antigravity

下载 Antigravity，并在安装流程中或从设置页面（依次点击自定义和 Build with Google 插件）启用“modern-web-guidance”。

Antigravity CLI

agy plugin install https://github.com/GoogleChrome/modern-web-guidance

Gemini CLI

gemini extensions install https://github.com/GoogleChrome/modern-web-guidance --auto-update

JetBrains WebStorm

您可以在 Skill 管理器中找到 Modern Web Guidance，具体路径为设置 > AI 助理 > Skill。选择一项技能，打开其详情页面。如需安装技能，请点击安装按钮，将其应用于当前 IDE 实例。

GitHub CLI

gh skill install GoogleChrome/modern-web-guidance

npx skills

npx skills add GoogleChrome/modern-web-guidance

Claude Code

claude plugin install modern-web-guidance@claude-plugins-official

Claude Code CLI

安装 Modern Web Guidance 以便与 Claude Code CLI 搭配使用需要三个步骤：

1. 添加购物平台：

/plugin marketplace add GoogleChrome/modern-web-guidance

2. 从 Marketplace 安装插件：

/plugin install modern-web-guidance@googlechrome

3. 重新加载插件：

/reload-plugins

Codex

codex plugin marketplace add GoogleChrome/modern-web-guidance
codex plugin add modern-web-guidance@googlechrome

Copilot CLI

安装 Modern Web Guidance 以与 Copilot 搭配使用需要两个步骤：

1. 添加购物平台：

/plugin marketplace add GoogleChrome/modern-web-guidance

2. 从 Marketplace 安装插件：

/plugin install modern-web-guidance@googlechrome

鹅

goose plugin install https://github.com/GoogleChrome/modern-web-guidance --auto-update

Grok

grok plugin install https://github.com/GoogleChrome/modern-web-guidance --trust

Kimi Code

/plugins install https://github.com/GoogleChrome/modern-web-guidance

安装前先探索

在安装之前，您可以通过搜索查询或按 ID 检索指南来评估 Modern Web Guidance 指南库。为此，请使用 CLI 的 search 命令，通过提示找到用例 ID：

npx modern-web-guidance@latest search "animate a dialog modal backdrop"

这将在终端中输出一个 JSON 对象：

[{"id":"light-dismiss-a-dialog","description":"Create a modal dialog that can be closed via light dismiss (i.e. clicking or tapping outside of the dialog)","category":"ui-behaviors","featuresUsed":["<dialog closedby>"],"tokenCount":1085,"similarity":0.7076},
{"id":"animate-to-from-top-layer","description":"Animate elements such as dialogs, popovers, and tooltips as they're entering/exiting the top layer.","category":"ui-behaviors","featuresUsed":["::backdrop","<dialog>","overlay","Popover","@starting-style","transition-behavior"],"tokenCount":1541,"similarity":0.6842},
{"id":"declarative-dialog-popover-control","description":"Toggle the visibility of a dialog or popover from a button without writing JavaScript.","category":"ui-behaviors","featuresUsed":["Invoker commands","Popover","<dialog>"],"tokenCount":2684,"similarity":0.5685},
{"id":"html","description":"Action-oriented guidelines for modern HTML architecture, semantics, native interactive APIs (Dialog, Popover, Details), focus management, and resource prioritization. Use this guide when structuring web documents, implementing native overlays, or optimizing resource loading order.","category":"html","tokenCount":5484,"similarity":0.5471},
{"id":"accessibility","description":"Actionable coding guidelines for building accessible web applications, covering semantic HTML, focus management, forms, media, and testing. Use this skill when auditing or implementing accessibility features, keyboard navigation, or ARIA.","category":"accessibility","tokenCount":7129,"similarity":0.5102}]

通过读取 description 值，您可以选择最能反映您的目标的 id，并使用 retrieve 命令：

npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

在这种情况下，终端中会显示animate-to-from-top-layer 用例的 Markdown 指南。对于其他指南，请将 animate-to-from-top-layer 替换为任何有效的指南 ID。

为什么使用 Modern Web Guidance？

与无辅助 AI 模型相比，Modern Web Guidance 为 Web 开发者带来了三大优势：

  1. AI 编码智能体往往会默认使用过时的旧解决方案来解决现代 Web 开发问题。这些解决方案通常包含 JavaScript，用于提供可通过现代 CSS 和 HTML API 更好地解决的问题的功能。
  2. 过去，AI 模型并不了解最新的 Web 平台功能，或者掌握的信息不正确。
  3. 最后，AI 模型往往会给出过时的建议，这些建议没有考虑项目要求或浏览器支持标准，而不是根据给定项目的基准要求量身定制指导。

Modern Web Guidance 解决了这些不足，并确保您的 AI 辅助编码工作流拥有优先采用较新 Web 平台功能的工具，同时考虑到后备方案。

Modern Web Guidance 中包含哪些内容？

Modern Web Guidance 包含针对多个核心学科的 100 多个 Web 开发用例的最佳实践。在后台，这是一项智能体技能，可指示编码智能体如何调用 modern-web-guidance CLI，以便为您的用例查找和检索最佳指南。

  • 用户体验：视图过渡、CSS scrollbar-color 样式以及进入和退出动画。
  • CSS：容器查询、现代色彩空间（例如 oklch）、CSS 子网格布局、text-wrap和排版行高修剪。
  • 性能：Interaction to Next Paint (INP) 诊断、用于拆分长任务的 scheduler.yield、后台任务调度和图片加载优先级。
  • 表单：自动调整大小的输入字段 (field-sizing: content)，以及使用 :user-invalid 的准确验证样式。
  • 内置界面组件：直接控制对话框、用于提示信息的 CSS 锚点定位以及 popover。
  • 无障碍功能：无障碍错误提示和键盘焦点管理。
  • 内置 AI：使用本地设备端客户端模型（原生语言检测、摘要和翻译 API）。
  • 通行密钥：通行密钥注册、身份验证和管理。

以下是每个类别中的部分指南。如需查看所有指南，您可以查看指南的完整列表。

基准

Baseline 可让开发者清楚地了解哪些 Web 功能在主流浏览器引擎中具有互操作性。如果某项 Web 功能属于 Baseline，则说明浏览器的兼容性等级值得信赖。Web 功能分为 Baseline 定义的三类：

  • 可用性有限意味着该功能无法互操作。
  • 新近可用表示相应功能在过去 30 个月内才具备互操作性。
  • 广泛可用表示该功能已具备互操作性至少 30 个月。

虽然 Baseline 是 Web 功能互操作性的定义，但它也是项目的一个可配置方面。您可以选择一个基准目标，然后将该目标添加到 AGENTS.md 或 CLAUDE.md 文件中，以配置项目使用该目标，例如：

This project's Baseline target is Baseline 2024.

<other project info...>

Modern Web Guidance 和功能回退

Modern Web Guidance 使用了各种各样的现代 Web 功能。其中一些功能可能属于“Baseline 新近可用”或“Baseline 广泛可用”阶段，但有些可能属于“有限可用”阶段。如果某项功能尚未广泛普及，用例指南会为代理提供具体说明，指导他们如何在不支持该功能的浏览器中确保更广泛的兼容性。在许多情况下，后备方案会作为渐进增强功能来实现，以便在支持现代功能的地方使用。如果需要为不受支持的浏览器提供 polyfill，代理始终会收到有条件加载这些 polyfill 的指令，以便仅在必要时产生费用。

如何确保准确性？

Modern Web Guidance 中的每个用例都包含一组持续校准的评估，以确保输出质量。

应用场景评估会运行自动化质量保证 (QA) 框架来测试智能体行为是否正确，其中 Playwright 发挥着核心作用：

  1. 对于每个指南，我们都会开发一个 Playwright 脚本，用于测试是否遵循了指南的实现细节，例如，是否在需要的地方观察到了 @media (prefers-reduced-motion: reduce)。
  2. 这些 Playwright 脚本会根据“正确”的参考演示实现进行持续校准，以期达到 100% 的通过率。另一方面，这些脚本会针对故意存在缺陷的实现进行检查，预期通过率为 0%。
  3. 如果“正确”和故意设置缺陷的实现未能分别产生 100% 和 0% 的通过率，生成器会自动使用上下文重试，直到实现 100% 校准。
  4. 最后，对基础应用进行端到端评估。其中一项评估是无引导的，即对照组，使用默认训练数据，不调用 Modern Web Guidance 来完成任务。另一个评估（实验）使用 Modern Web Guidance 处理相同的任务。

我们每周都会使用前沿模型和编码智能体运行多次评估，从而清楚地了解智能体在有无我们指导的情况下表现如何。早期结果显示，平均而言，当客服人员配备 Modern Web Guidance 时，对现代最佳实践的遵循度提高了 37 个百分点。不过，实际结果可能会因项目要求、模型、您编写的提示以及您首选的智能体编码工具而异。

启用针对不稳定功能的指导

不稳定功能是指仅在一种浏览器引擎中实现的实验性 Web 功能，可能会发生破坏性更改。如需为这些功能启用指导，请在项目根目录中运行以下命令：

npx modern-web-guidance@latest set-allow-volatile-features

为源试用中的功能启用指导

实验性功能首次发布时，通常会隐藏在标志后面，或者仅通过源试用在生产网站上提供。部分 Modern Web Guidance 指南会使用这些功能，但默认情况下，您的编码智能体无法获取这些功能的指南。如需获取有关这些功能的指导，请在项目根目录中运行以下命令：

npx modern-web-guidance@latest set-allow-origin-trials

后续步骤

现在，您已经对 Modern Web Guidance 有了大致了解，并认识到它在 AI 编码工作流中简化现代 Web 最佳实践采用方面的潜力。您现在可以探索 Modern Web Guidance 提供的指南。