现代 Web 指南使用入门

“现代 Web 指南”是一种智能体技能，可将现代最佳实践应用于 AI 辅助的编码工作流程。它有助于引导您的编码代理避开针对常见 Web 开发问题的旧版解决方法，转而使用应采用的新版 Web 平台功能。

安装

现代 Web 指导技能可以安装在各种各样的代理中，让您能够保留自己喜欢的工作流程，同时还能受益于它们提供的指导。

建议通过 Chrome 团队构建的 modern-web-guidance CLI 进行安装。通过 modern-web-guidance CLI 安装技能会自动使技能保持最新状态。您可以从 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，并在安装流程中或从设置页面中的自定义 -> 使用 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

您可以在技能管理器中找到“现代 Web 指南”技能，该管理器位于设置 > AI 助理 > 技能下。选择一项技能，打开其详情页面。如需安装该技能，请点击安装按钮，将其应用到当前的 IDE 实例。

GitHub CLI

gh skill install GoogleChrome/modern-web-guidance

npx skills

npx skills add GoogleChrome/modern-web-guidance

Claude Code

安装“现代 Web 指南”以搭配 Claude Code 使用需要执行以下三个步骤：

1. 添加应用商店：

/plugin marketplace add GoogleChrome/modern-web-guidance

2. 从 Marketplace 安装插件：

/plugin install modern-web-guidance@googlechrome

3. 重新加载插件：

/reload-plugins

Copilot CLI

安装 Modern Web 指南以搭配 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

安装前探索

在安装之前，请先评估“现代 Web 指南”技能指南库，方法是使用查询进行搜索或按 ID 检索我们的指南。为此，请使用 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":"user-experience","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":"user-experience","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":"user-experience","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 指南？

与无辅助的 AI 模型相比，现代 Web 指南技能之所以能为 Web 开发者带来优势，有以下三个不同的原因：

  1. AI 编码代理往往会默认采用过时的旧解决方案来解决现代 Web 开发问题。这些解决方案通常包含 JavaScript，用于为通过现代 CSS 和 HTML API 能够更好地解决的问题提供功能。
  2. 从历史上看，AI 模型并不了解最新的 Web 平台功能，或者对这些功能的信息有误。
  3. 最后，AI 模型往往会提供过时的建议，而不会考虑项目要求或浏览器支持条件，也不会根据特定项目的 Baseline 要求量身定制指导。

现代 Web 指南技能可弥补这些不足，并确保 AI 辅助的编码工作流拥有可率先采用最新 Web 平台功能的工具，同时考虑到回退。

现代 Web 指南包含哪些内容？

现代 Web 指南包含 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...>

现代 Web 指南和功能回退

现代 Web 指南使用了各种现代 Web 功能。其中一些可能处于“Baseline 新近可用”或“Baseline 广泛可用”阶段，但另一些可能处于“存货有限”阶段。如果某项功能尚未广泛推出，用例指南会为客服人员提供具体说明，指导他们如何在不支持该功能的浏览器中确保更广泛的兼容性。在许多情况下，后备方案以渐进式增强功能的形式实现，可在支持现代功能的任何地方使用。如果不支持的浏览器需要 Polyfill，代理始终会指示有条件地加载它们，以便仅在必要时产生费用。

如何确保准确性？

现代 Web 指南中的每个用例都包含一个指南，并且大多数用例都会持续校准，以引导 AI 代理生成高质量的输出。

经过校准的用例使用自动化 QA 框架来测试正确的代理行为，其中 Playwright 起着核心作用：

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

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

后续步骤

现在，您已经大致了解了 Modern Web Guidance，以及它在简化 AI 编码工作流程中采用现代 Web 最佳实践方面的潜力。您现在可以探索现代 Web 指南提供的技能和使用场景。