现代 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

您可以在技能管理器中找到“Modern Web Guidance”，具体路径为设置 > AI 助理 > 技能。选择一项技能，打开其详情页面。如需安装技能，请点击安装按钮，将其应用于当前 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 个百分点。不过，实际结果可能会因项目要求、模型、您编写的提示以及您首选的智能体编码工具而异。

后续步骤

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