Modern Web Guidance：让编码代理摆脱2019年的JavaScript，拥抱现代Web原语

Modern Web Guidance

Modern Web Guidance 是一组技能，可将 Web 平台专业知识、最佳实践和浏览器兼容性数据直接嵌入你的编码代理中。它帮助引导你的编码代理远离旧有模式，转而采用能够发挥现代 Web 平台能力与特性的解决方案。

由 Google Chrome、Microsoft Edge、Mozilla Firefox 和 MDN 团队以及 Web 开发社区共同维护。

文档 · 评估仪表板 · 源代码 · 报告问题

快速开始

npx modern-web-guidance@latest install

此命令会运行一个交互式向导来安装 Modern Web Guidance。请参阅下方的其他安装方法。

试用（无需安装）

# Search for relevant guides
npx modern-web-guidance@latest search "animate a dialog modal backdrop"

# Retrieve a guide by ID
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

# Scan a codebase for legacy patterns to modernize
npx modern-web-guidance@latest legacy-scan .

为什么？

编码代理常常默认采用较旧的模式，因为 LLM 训练数据中包含大量遗留代码。这往往导致它们为那些如今已有原生、高性能 Web 平台解决方案的任务生成臃肿的 JavaScript。

即使模型知道某个 API 存在，它通常也缺乏生产级代码所需的密集的真实世界现代实现模式。

Modern Web Guidance 弥合了这一差距。我们技能的 CLI 会将有针对性的、由专家精心策划的指南直接返回到你的代理上下文窗口中，重点关注：

• 现代浏览器 API：帮助模型正确构建它们经常误用的 API。
• 性能与无障碍：优先使用可由浏览器优化并内置无障碍能力的平台级 API。
• 负责任的回退方案：引导模型使用合理、轻量的回退方案，而不是沉重的 polyfill 或遗留库。

包含哪些内容？

我们覆盖了过去几年 Web 平台的新特性，直至最前沿。这些指南设计为令牌高效；我们运行评估，以便剪除模型已经知道的最低共同标准内容。

核心领域

查看示例：navigation-drawer 指南。

完整列表

250 项现代 Web 特性

CSS 与布局（140 项特性）

HTML & DOM（36 项特性）

JavaScript 与 API（74 项特性）

203 个真实开发者用例

无障碍

• accessible-error-announcement：将程序化无障碍状态（如 aria-invalid）与视觉上的 :user-invalid 状态同步，确保屏幕阅读器用户仅在交互后收到错误反馈，与视觉体验保持一致。
• accessible-generated-content：以保持无障碍的方式使用 CSS 生成内容（::before/::after），包括为装饰性内容提供替代文本。
• respect-os-text-scale：遵循操作系统对页面的文本缩放偏好，使字体大小、布局和基于 rem 的度量跟随用户的无障碍设置。

内置 AI

• language-detection：检测用户生成内容或站点已有内容的语言。
• language-model：使用 Prompt API 在浏览器中运行设备端自然语言推理，支持流式输出、结构化 JSON 响应和多轮会话管理。
• summarizer：使用设备端 Summarizer API 对文本内容进行摘要。
• translator：使用设备端 Translator API 在语言之间翻译文本。

css

• animate-to-intrinsic-sizes：将交互式组件（如手风琴、菜单和可展开卡片）平滑地动画到其自然尺寸并从中恢复。
• atrule-support-conditionals：仅当浏览器支持某个 at-rule 时，才条件性地应用某些 CSS 规则或声明。
• calculate-with-intrinsic-sizes：基于元素的内在尺寸计算其大小，同时确保其符合给定的设计约束。
• child-state-based-styling：构建一个根据其某个子元素的状态改变样式的组件。例如，根据主题切换开关是否被选中（或未选中）以浅色或深色模式渲染的组件。
• content-based-styling：构建一个根据是否包含特定子元素（或不包含）改变布局的组件。例如，如果组件包含图片，则使用多列布局，否则默认使用单列布局。
• css：面向现代 CSS 架构的实践导向指南，包括层叠、选择器、作用域、嵌套和设计令牌。在编写样式或管理设计系统时使用本指南。
• css-layout：现代 CSS 布局，如 flexbox、grid、subgrid、容器查询、锚点定位和内在尺寸。在架构响应式 UI 组件或页面布局时使用本技能。
• design-token-reactivity：定义高阶设计令牌，如密度模式（紧凑、舒适、宽松）或主题，并让后代组件以适合组件的方式直接响应变化。
• dynamic-sibling-styling：创建动态视觉谱系或布局排列，自动适应一组元素的数量。
• fluid-scaling：根据父容器尺寸平滑缩放字号、间距和媒体尺寸等项目，而不是使用固定断点
• individual-transform-properties：在单个元素上独立于其他 transform 属性，对各个 CSS transform 属性（如 translate、rotate、scale）进行动画或覆盖。
• overflow-clipping-control：调整元素可见的裁剪边界，使其与内容边缘、内边距边缘或边框边缘对齐——或与其中任一者保持指定偏移——从而对内容的裁剪方式提供更细粒度的控制。
• reduce-style-repetition：通过将复杂或动态的样式逻辑封装为可复用函数（例如根据一组输入参数计算渐变的函数），减少过度的样式重复。
• responsive-design：构建适应容器和视口尺寸的 UI，包括容器查询、动态视口单位、宽高比和响应式排版。
• selector-atrule-combinations：基于选择器与条件 @ 规则的交叉或并集来定位元素，同时尽量减少重复。
• size-aware-styling：构建一个组件，其样式可以有条件地取决于自身的宽度或高度，而不是视口的宽度或高度。例如，一个卡片组件可以根据自身大小改变布局，或者一个行动号召按钮可以根据自身宽度有条件地显示辅助文本。
• style-parent-with-has：当表单字段无效时，为其父元素（例如 label 或 fieldset）设置样式。
• usage-aware-component-variations：使用 CSS 容器样式查询，构建基于语义上下文调整视觉逻辑的组件。

forms

• animated-select-picker：创建一个自定义 select 组件，其下拉菜单带有动画。例如，菜单淡入或滑入视图，或者选项在被选中时播放动画。
• autofill-address-form：构建一个具有正确 autocomplete 属性和自动填充支持的地址表单。
• autofill-highlight-inputs：自定义已被自动填充且用户尚未编辑的表单字段的样式
• autofill-payment-form：构建一个收集卡片详情的支付表单，具有正确的 autocomplete 值和自动填充支持。
• autofill-sign-in-form：构建一个具有正确 autocomplete 值和自动填充支持的登录表单。
• autofill-sign-up-form：构建一个具有正确 autocomplete 值和自动填充支持的注册表单。
• brand-consistent-forms：让复选框、单选按钮、范围滑块和进度条匹配你网站的配色方案，而无需用自定义组件替换它们。
• branded-select-styling：创建自定义 select 元素，其按钮、选择器、箭头图标和勾选标记都无缝匹配你的品牌或设计系统的排版、颜色、间距和边框处理。
• custom-select-picker-layouts：创建自定义 select 选择器，其选项以独特或有趣的方式定位，而不是传统的堆叠选项列表。
• form-fields-automatically-fit-contents：允许表单字段增长和收缩以适应用户输入，例如当用户输入或选择不同选项时。应用最大和最小尺寸限制，创建符合页面设计的动态响应式表单字段。
• ime-safe-enter-submit：在文本域和单行输入框（聊天、搜索、内联重命名）中实现回车提交，对 IME（输入法编辑器）用户安全，防止提交不完整的文本。
• required-field-feedback：仅在用户交互之后，为被跳过或留空的必填表单字段提供错误消息，以避免先发制人的错误，并确保反馈及时且与用户流程在上下文中相关。
• rich-media-picker：创建一个自定义 select 组件，其选项可以包含复杂的 HTML 格式（例如图片、图标和其他富格式），而不仅仅是纯文本。
• select-menu-interaction：仅在用户与该控件交互之后，才验证 select 菜单中已选择了非默认选项。
• slider：为原生范围滑块设置自定义轨道、滑块头、填充和聚焦状态的样式，同时保留原生功能和可访问性。
• sms-otp-form：验证用户电话号码和通过 SMS 发送的一次性密码，支持自动提取验证码和可访问的表单输入。
• switch：使用原生 HTML switch 属性构建可访问的开关，在不支持时回退到带样式的复选框。
• validate-input-after-interaction：仅在用户完成初始交互之后显示表单字段验证反馈（例如密码复杂度或电子邮件格式要求），避免在页面加载时或用户输入时过早报错。

html

• accessible-web-components：让自定义元素默认可访问：通过 ElementInternals ARIA mixin 设置角色和 ARIA 状态，使用 delegatesFocus 管理焦点，并将 ARIA 关系保持在单个 shadow root 内。
• custom-elements：定义、注册和管理自主自定义元素的生命周期，涵盖构造函数规则、生命周期回调、升级时机、属性/特性反射和命名约定。
• form-associated-custom-elements：通过 formAssociated 和 ElementInternals 让自定义控件原生参与表单，提交自身的值，与约束验证集成，并对重置、禁用和状态恢复做出反应。
• prerendering-custom-elements：在服务器端渲染自定义元素，然后就地水合，而无需重新渲染或出现无样式内容闪烁。
• shadow-dom：使用 Shadow DOM 封装组件的 DOM 和样式，使用 HTML 模板高效构建树，并使用插槽投影使用方内容。
• styling-web-components：使用 :host 选择器、用于主题化的继承属性和自定义属性、::slotted 和 ::part，以及组件内部的级联层和容器查询，跨越影子边界进行样式设置。
• web-components：编写和使用 Web Components 的入门指南与横切原则，涵盖 Custom Elements、Shadow DOM、模板与插槽、声明式 Shadow DOM、跨影子边界的样式设置、表单关联自定义元素以及无障碍要求。在构建可复用 UI 组件、设计系统或服务器渲染的自定义元素时使用本指南。

js

• calculate-event-differentials：计算日期和时间之间已流逝或剩余的时间，平衡时长单位，并使用 Temporal.Duration 和 Intl.DurationFormat 格式化人类可读的本地化时长。
• capture-location-agnostic-data：使用 Temporal Plain 类型对与位置无关的日历日期、挂钟时间、部分日期（循环生日、信用卡到期日）以及循环月度间隔进行建模，而不会产生时区漂移。
• coordinate-global-events：通过将未来的会议或事件显式绑定到地理 IANA 时区来安排它们，使事件时间无论夏令时（DST）转换、时钟变更期间的“跳过”或“重复”小时如何都保持准确。
• sort-high-precision-timestamps：使用 Temporal.Instant 解析、排序和测量亚毫秒或纳秒级 ISO 8601 时间戳之间的间隔，而不会出现 Date 截断冲突。
• support-global-calendar-systems：为非公历日历系统（例如伊斯兰历、希伯来历或中国历）准确显示和计算日期，以服务国际用户。

performance

• batch-analytics-events：对多个分析、遥测和 Core Web Vitals 事件进行防抖并批量合并到单个信标中，以尽量减少网络争用并降低服务器负载，同时仍提供实时更新。
• break-up-long-tasks：拆分繁重的同步处理（复杂计算和/或长循环）或 DOM 更新，以改善 Interaction to Next Paint（INP）响应性，并让浏览器处理用户输入和重绘屏幕。
• calculate-total-foreground-time：计算用户实际查看页面的总时间，排除标签页处于后台的时段。
• conditional-async-dependencies：有条件地加载或初始化异步依赖（例如为缺失的 Web 特性导入 polyfill），而无需在页面的所有脚本依赖之间进行复杂的编排。
• defer-rendering-heavy-content：通过推迟渲染任何用户不能立即看到的内容，减少内容繁重的网页（例如具有长信息流、大量文章或复杂仪表板的页面）的渲染时间。
• defer-work-until-scroll-ends：将 DOM 更新、数据获取、分析跟踪或布局重计算等昂贵操作推迟到滚动完成后，以保持流畅的滚动性能。
• deliver-optimized-decorative-images：通过同时提供下一代图像格式（如 AVIF 或 WebP）以及多种像素密度（如 1x 和 2x），交付优化的装饰性图像（如背景、UI 图标或复杂遮罩），以便浏览器能够根据用户设备能力动态协商文件大小和视觉质量的最佳组合。
• deprioritize-background-fetches：降低使用 Fetch API 进行的后台数据获取的优先级，以防止与用户发起的请求发生网络争用。
• detect-initial-visibility-state：可靠地确定页面最初是否在后台加载，即使在脚本于用户将页面切到前台后异步加载的情况下也是如此。
• efficient-background-processing：当组件在屏幕外时暂停后台 JavaScript 执行（例如 <canvas> 动画、WebGL 渲染或高频 WebSocket 数据轮询），并在其滚动回视图时及时恢复，以节省系统资源和电池寿命。
• faster-spa-view-transitions：通过保留之前访问过的视图的结构化 DOM 状态，而不是在每次导航时销毁并重建它们，在单页应用（SPA）中实现更快速地返回之前访问过的视图。
• flicker-free-client-side-ab-testing：使用客户端 JavaScript 交付并渲染 A/B 测试、多变量测试或其他实验，以更改或注入 HTML、CSS 和 JavaScript，而不会先显示原始内容再闪烁或闪动以显示实验内容。
• full-session-analytics：可靠地跟踪用户整个页面访问期间的分析、Core Web Vitals、错误和遥测数据，并将数据发送推迟到用户离开页面时。
• identify-heavy-scripts：识别对长动画帧负主要责任的脚本
• identify-inp-causes：识别运行缓慢的 JavaScript 以及其他导致 Interaction to Next Paint（INP）响应性不佳的原因。
• improve-next-page-load-performance：通过预取或预渲染用户接下来可能访问的页面来改善页面加载性能。
• interaction-paint-timing：测量用户交互和客户端导航在屏幕上渲染新的有内容更新所需的时间。
• interactions-in-complex-layouts：通过避免复杂布局（如数据繁重的仪表板或电子表格式网格）中的布局重计算，使交互更迅捷、更响应（降低 Interaction to Next Paint（INP）分数）。
• lazy-load-video-and-audio：延迟下载屏幕外的视频和音频资源（包括视频海报图像和预加载的媒体数据），直到媒体播放器接近视口，以节省带宽并减少初始页面加载期间的网络争用。
• optimize-image-priority：优化 Largest Contentful Paint（LCP）候选图像的加载优先级，并降低非关键图像的优先级，以减少关键资源的加载延迟。
• optimize-preload-priority：优化预加载内容的相对优先级，以减少关键资源的加载延迟。
• optimize-script-priority：优化脚本的加载优先级，提升关键异步脚本的优先级并降低非必要或位于 body 后段的脚本的优先级，以改善加载顺序并减少延迟。
• out-of-order-html-streaming：以声明式方式用稍后流式传输到同一 HTML 文档中的内容更新页面，或通过命令式 JavaScript API 更新页面。
• resolution-optimized-pseudo-elements：在 CSS 伪元素（如 ::before 和 ::after）中使用分辨率优化的图像，以减少 DOM 节点数量。
• schedule-tasks-by-priority：按不同优先级调度任务，确保关键工作优先运行，同时推迟后台工作。

隐私

• privacy：面向 Web 开发者的行动导向指南，用于实施隐私设计、数据最小化、第三方审计和安全数据处理。在设计应用、集成第三方服务、处理用户数据或配置安全标头时使用此技能。

pwa

• install-web-app：通过浏览器控制的同意界面从页面安装 Web 应用。
• migrate-web-app-origin：将已安装的 Web 应用迁移到新的源，同时保留用户配置和操作系统级快捷方式。

安全

• client-side-encryption：使用公钥封装或密钥协商（包括混合和后量子保护）建立共享密钥，并在浏览器中使用认证加密对敏感数据进行加密。
• digital-signatures：在浏览器中使用经典或抗量子（后量子）非对称密钥对消息、令牌或工件进行签名和验证，以确保数据完整性和真实性。
• local-network-access：从公共 Web 应用访问用户本地网络或回环接口上的资源。
• passkey-authentication：使用通行密钥对回访用户进行身份验证，作为主要登录方式。
• passkey-conditional-create：在密码登录成功后，为现有用户静默注册通行密钥。
• passkey-management：让用户查看和管理注册到其账户的通行密钥。
• passkey-reauthentication：在敏感操作前，使用已登录用户现有的通行密钥验证其身份。
• passkey-registration：为现有用户账户注册通行密钥。
• passkeys：在 Web 应用中实施 WebAuthn 和 Passkeys 的全面入门指南与跨领域原则。在处理通行密钥注册、身份验证、管理或重新验证时使用本指南。
• quick-sign-ins：在导航到登录页面或打断用户工作流之前，使用已保存的通行密钥或密码就地验证回访用户。
• restrict-outbound-connections：限制页面或 worker 仅与显式的网络端点允许列表通信，以防止未经授权的第三方请求和客户端数据外泄。
• sanitize-untrusted-html：通过移除不安全的元素和属性，安全地解析并显示来自用户输入的不可信 HTML 内容。
• secure-external-subresources：验证从第三方源加载的外部脚本、样式表、字体和图像的加密完整性，并控制这些请求是否发送凭据或引用 URL。
• trusted-types：通过定义 Trusted Types 策略来清理不可信 HTML、在写入 innerHTML 等 DOM 接收点时使用该策略，并通过内容安全策略强制执行 Trusted Types，以防止基于 DOM 的 XSS 攻击。
• validate-origins：在跨文档消息和 URL 之间安全地比较和验证 Web 源与站点，无需容易出错的字符串解析。
• verify-email-ownership：在账户创建、登录或恢复期间验证用户拥有某个电子邮件地址，而无需发送一次性验证码或魔法链接邮件。

ui-atoms

• carousel-slide-effects：创建包含图像或其他视觉元素的幻灯片轮播，其中每张幻灯片在进入/居中/离开其滚动容器时播放动画。例如，幻灯片可以淡入/淡出、旋转、变大或变小等。
• component-specific-light-dark-theme：强制某些元素处于浅色模式或深色模式（例如代码块、媒体播放器等），独立于页面的 color-scheme。
• icons：显示和管理图标，这些图标可从 CSS 设置和参数化，加载快速、在任何分辨率下都清晰，并正确暴露给（或隐藏于）辅助技术。
• position-aware-tooltips：构建带有方向箭头（或其他视觉样式）的工具提示和弹出框，当元素翻转到回退位置时，箭头会自动指向正确方向。
• pull-to-reveal：构建下拉显示功能，使用户能够在屏幕上向下拉动以显示更多内容，例如搜索栏。
• responsive-table：构建数据表格，以正确的表头语义呈现表格数据，并在小屏幕和辅助技术下保持可读性和可导航性。
• scroll-position-aware-elements：构建浮动按钮或小组件（返回顶部、滚动到底部、聊天启动器等），根据用户是否已滚动来显示和隐藏。
• scroll-progress-indicator：创建滚动进度条、分步进度跟踪器，或任何传达用户已滚动页面或区块多远的视觉提示。
• scrollability-affordance-hints：构建滚动阴影或渐隐边缘，仅当该方向上确实还有更多内容可滚动时才出现。
• shrinking-header-on-scroll：在滚动时平滑地为固定页眉或整页封面添加动画，使其在预定义的滚动距离内动态缩小、获得阴影并变换布局。
• single-line-overflow：在可能放不下的空间中显示必须保持在一行内的文本，例如标签页标签、表格单元格、导航项或文件名，同时不破坏布局或丢失文本。
• state-aware-sticky-headers：构建粘性区块标题或导航栏，当它们真正“粘”在顶部时进行视觉变换，改变配色方案或获得阴影。
• viewport-aware-dropdowns：将下拉菜单、飞出菜单或上下文操作面板定位为附着在触发按钮上，使其在视口边缘自动翻转轴向，而不是被裁剪。

ui-behaviors

• 2d-panning：允许用户在两个方向上自由平移或滚动二维表面——例如地图、缩放图像、无限画布或大型数据网格——（无论是沿对角线还是手势中途改变方向），而不会让手势锁定到单一水平或垂直轴。
• anchor-positioning-tab-underline：在两个目标元素位置之间无缝过渡元素。例如，在先前选中的标签页和当前选中的标签页之间移动选中标签页的下划线。
• animate-element-entry-exit：当元素被添加/移除到 DOM 或切换其 display 值时，平滑地隐藏/显示元素。
• animate-to-from-top-layer：为对话框、弹出框和工具提示等元素进入/退出顶层（top layer）时添加动画。
• carousel-snap-highlights：在滚动吸附轮播、画廊或整页滑动体验中，视觉上高亮当前吸附的非交互项。例如，在吸附时展开卡片，或显示隐藏内容。
• consistent-cross-document-transitions：在启动跨文档视图过渡之前，确保关键页面状态已加载且稳定。这意味着关键 CSS 样式已加载并应用，关键 JavaScript 已加载并运行，并且用户初始视图可见的 HTML 已在过渡运行前解析完成。
• cross-document-transitions：在整页导航之间创建平滑、无缝的过渡，例如交叉淡入淡出、自定义显示效果，或内容从一页到下一页的变形。
• custom-button-actions：使用声明式按钮命令、调用器命令、按钮命令、自定义命令或声明式切换操作，以声明方式将按钮连接到任意元素，以触发自定义的、应用特定的操作。
• declarative-dialog-popover-control：无需编写 JavaScript，即可从按钮切换对话框或弹出框的可见性。
• directional-navigation-transitions：为视觉状态变化添加动画，以反映用户导航流的方向，例如前进时从右侧滑入新内容，或返回上一屏幕时从左侧滑入。
• drag：支持拖动以在页面上移动浮动元素。
• drag-and-drop：支持拖动以沿一个轴（水平或垂直）重新排列容器的子元素，同时保留其状态和可访问顺序。
• dynamic-sibling-animations：在兄弟元素之间错开动画或过渡时序，使每个元素根据其在兄弟列表中的位置在计算出的延迟后开始。
• dynamic-sort：处理用户触发的容器子元素动态重新排序（例如列表项、表格行或卡片网格）的最佳实践，可选地提供尊重用户偏好、良好的屏幕阅读器用户体验以及大型列表最佳性能的动画重新排序。
• group-element-transitions：在添加、移除、打乱或重新排序时，平滑地重新排列列表项、卡片或网格元素并同时为其新位置添加动画——例如从购物车中移除商品。
• highlight-text-ranges：高亮页面上的任意文本范围，例如搜索结果、拼写错误或协作编辑光标。
• interactive-content-reveal：创建交互式显示效果，例如跟随用户指针的聚光灯，以揭示图像或 UI 区块内的细节。
• interest-triggered-action-previews：当用户表示兴趣（例如悬停、聚焦或长按）但尚未点击时，显示按钮效果的实时预览。
• interest-triggered-tooltips：当用户悬停、聚焦或长按交互元素时，显示工具提示或补充信息，而无需点击。
• light-dismiss-a-dialog：创建可通过轻触关闭（即点击或轻触对话框外部）的模态对话框。
• motion：使用 CSS 过渡、动画、滚动驱动动画和视图过渡为 UI 添加动画，同时将动画保持在合成器上并尊重减少动态效果偏好。
• move-dom-element-without-losing-state：移动或重新挂载 DOM 元素而不丢失重要的元素状态，例如交互状态（:focus/:active）、<iframe> 加载状态、动画/过渡状态等。
• parallax-scroll-effects：创建基于滚动的效果（如视差），让前景层和背景层以不同速率移动，在用户滚动时营造出纵深感。
• persistent-top-layer-ui：当模态对话框、全屏元素或原生 popover 的底层 DOM 节点在 DOM 中被移动或重新挂载时，使其保持可见打开且功能正常。
• physics-based-easing：创建自定义的、基于物理的动画和过渡效果，如弹跳和弹簧，比传统缓动曲线更自然、更有吸引力。
• platform-controls-dismiss-dialog：创建可通过标准平台特定用户操作关闭的模态对话框，例如在桌面平台按 Esc 键，或在移动平台使用“返回”或“关闭”手势。
• prevent-page-scroll-under-modal-dialog：在模态对话框打开时，阻止底层页面滚动。
• same-document-transitions：在单页应用（SPA）中，通过平滑变形持久元素的大小、位置或其他样式属性，在不同页面状态或导航之间在视觉上连接这些元素（例如将产品缩略图扩展为全出血主图）。
• scoped-component-transitions：在单个组件（卡片、列表、面板或其他子树）内部为状态变化添加动画，同时页面其余部分保持可交互，其他过渡并发运行。
• scroll-completion-effects：仅在平滑的程序化滚动到目标元素完成后，才在该目标元素上触发视觉效果、动画或焦点变化。
• scroll-entry-exit-effects：在用户滚动时，为元素进入和退出滚动视口（或视口）创建淡入、放大或其他复杂的显现类效果。
• scroll-snap-realtime-feedback：在用户滚动浏览对齐到吸附点的内容时，在滚动手势完成之前，在关联的 UI 元素中提供实时视觉反馈。
• scroll-snap-state-sync：将导航指示器、关联内容面板和分析跟踪与可滚动容器中当前吸附的项目同步。
• scroll-target-on-load：构建一个可滚动的元素列表（例如图片轮播或聊天会话线程），在初始渲染时可将特定元素滚动到视图中显示。
• scrollytelling：完全由另一个元素的滚动视口位置驱动，为目标元素上的视觉属性添加动画——例如淡化背景、改变背景颜色，或创建滚动叙事体验。
• search-hidden-content：使用手风琴、标签页和“阅读更多”区块等模式将内容隐藏起来，同时确保隐藏文本在原生“在页面中查找”搜索时能够显示、允许搜索引擎索引、支持 URL 片段深链接，并保持 ARIA 无障碍性。
• sortable-table：通过渐进增强为数据表格添加行为，允许用户点击列标题对行进行排序。
• spatial-navigation：使用方向键实现无障碍的空间导航，并在不同布局模式（网格等）下正确工作。
• swipe-to-remove：让用户通过水平滑动手势对列表中的项目执行操作（移除、归档、标记为已读等），从而无需点击单独控件即可快速处理条目。
• swipe-to-reveal：让用户在列表项或内容窗格上水平滑动，以显示上下文操作按钮或侧边菜单，而不会自动触发操作。

UI 组件

• accordion：构建一个带有动画、可选互斥（一次只打开一个）行为和品牌一致样式的折叠面板组件。
• app-menus：构建一个应用程序菜单栏，其中多个顶级菜单（如文件、编辑和视图）作为一个键盘停靠点，并在悬停或按方向键时相互切换。
• breadcrumbs：构建面包屑导航，显示用户在站点层级中的位置，并允许他们导航到祖先页面。
• card：构建一个卡片组件，使其呈现方式能适应自身可用空间和内容。
• carousel：构建一个轮播组件，以水平或垂直布局显示一组项目。
• checkbox：为复选框设置样式，包括自定义图标、布局、颜色、勾选/取消勾选动画，同时保留原生功能和可访问性。
• copy-button：构建一个复制按钮，将任意元素中的文本复制到剪贴板。
• dark-mode-toggle：构建一个深色模式切换组件，允许用户覆盖当前站点的系统配色方案偏好。
• dialog：构建一个模态或非模态对话框组件，具备可访问性、能恰当管理焦点，并可按各平台上用户预期的方式关闭。
• hovercard：构建一个悬停卡片组件，在悬停时显示某类链接（例如用户个人资料）将要导航到的页面的可交互结构化预览。
• menu：构建一个菜单组件，显示选项或操作列表，并支持嵌套子菜单。
• navbar：构建一个站点导航栏，能适应不同屏幕尺寸并指示当前页面。
• navigation-drawer：创建一个导航抽屉组件，当从菜单按钮触发时，从侧边滑入并覆盖在现有页面内容之上；当被关闭时（通过滑动移开、点击外部或按 Escape 键），滑出。
• persistent-app-tours：使用在用户交互期间保持打开状态的绑定原生覆盖层，创建持久的入门引导流程。
• persistent-toast-notifications：创建非侵入式的 toast 和覆盖层通知，用于持久、可堆叠的消息传递和状态传达。
• progress：构建一个带样式的进度条，用于传达任务或流程的完成情况，同时支持确定和不确定两种状态。
• progress-ring：构建一个进度环组件，以视觉方式呈现任务或流程的完成状态，支持在中心放置内容，并保持与品牌一致的样式。
• scrollspy：在导航菜单中高亮当前可见的页面区块
• spinner：构建一个加载旋转指示器，向所有用户传达忙碌状态，遵循减少动态效果偏好，并高效地播放动画。
• stack-drill-down：构建全屏层级导航，让用户可以逐层深入嵌套视图，并通过滑动或导航返回，同时保持浏览器历史记录同步。
• tabs：构建响应式标签页界面，当所有标签无法在屏幕上容纳时仍能提供良好的用户体验。
• toolbar：构建一个工具栏组件，显示一组用于执行操作的控件。

用户体验

• content-first-noise-reduction：通过移除阻塞式弹窗、保持持久导航紧凑，并将次要内容置于按需展开之后，最大化内容并减少干扰。
• form-factor-adaptation：让布局、控件和文本适应任何设备或容器，使触摸目标保持可用、内容适配其空间，且不与系统 UI 发生碰撞。
• natural-interactions：实现自然的交互，具备清晰的悬停、聚焦和按下反馈，从触发元素展开的动效，可滑动的内容，以及可通过键盘触达的操作。

视觉设计

• adapt-scrollbar-to-contrast-preferences：为偏好高对比度界面的用户增强滚动条可见性
• apply-webgl-shaders：使用 WebGL 着色器为 HTML 内容应用自定义视觉效果。
• browser-ui-theming：使用 CSS 为浏览器生成的 UI（如文本选区、滚动条、表单控件和选择器）设置主题，而不是用自定义元素重新创建它们。
• color：面向 Web 的颜色指南，包括对比度要求、浅色与深色配色方案、强制颜色模式，以及从基础色生成色调和阴影。
• complex-shapes：将元素及其内容裁剪为任意自由形状，例如符号、笔触或有机纹理，以实现更具表现力的设计。
• contrast-color：在动态背景色上选择具有足够对比度的可读文本颜色。
• custom-text-decorations：添加文本装饰，如下划线、上划线、删除线或完全自定义的形状，支持显现动画、自定义偏移和末端内缩，以及灵活的墨迹跳过。
• customize-scrollbar-color-and-thickness：自定义滚动条的颜色或粗细
• dark-mode：以尊重用户浅色/深色主题偏好的方式实现深色模式支持，并适配浏览器 UI（例如滚动条、表单控件等）
• equal-width-text-lines：让多行标题或组合文字的每一行都占据相同宽度，如同海报风格或堆叠标题排版。与两端对齐文本不同，这里调整的是文本本身的尺寸以匹配宽度，而不是拉伸间距
• export-html-media-from-canvas：在 canvas 内捕获动态 HTML 内容并将其导出为图像或视频帧。
• expose-canvas-content-to-browser-features：将 canvas 中渲染的内容暴露给浏览器功能，如辅助技术、翻译或阅读模式。
• improve-text-layout-and-legibility：通过让浏览器在文本换行时应用均匀平衡的换行，改善简短独立文本内容（例如不超过几行的标题）的布局和可读性。
• interactive-content-in-3d-scenes：将交互式 HTML 元素集成到 3D 场景中。
• precise-text-alignment：与任意字体的文本实现精确的垂直对齐。例如，文本上方和下方具有完全相等的视觉内边距，或使文本与相邻图标或图像完美齐平对齐。
• shaped-cutouts：组合多个形状，在元素中创建复杂的镂空或“挖空”效果，例如为元素添加缺口。
• soft-edge-content-fade：对内容边缘应用透明度渐变，以指示还有可滚动区域，或遮蔽付费墙后的文本。
• typography：面向 Web 的排版最佳实践，包括字号单位、行高、文本换行与平衡，以及随视口缩放的流式字体。
• visual-effects：使用 CSS 实现视觉效果，例如分层阴影、混合模式、具有可预测颜色插值的渐变，以及仅用渐变构建的条纹、棋盘格、圆点和饼图等图案。
• visually-stable-font-fallbacks：定义字体样式，使得在首选字体与某个回退字体之间发生切换（或反向切换）时，文本仍保持可读且视觉一致。
• visually-stable-mixed-fonts：定义字体样式，使得在使用多种字体渲染同一段文本的情况下，文本仍保持可读且视觉一致。
• visually-texture-content：为元素应用逼真的风化和纹理图案，使其呈现有机、陈旧或实体材质的观感。

wasm

• cpp-on-the-web：使用 Emscripten 将 C/C++ 编译为 WebAssembly

webmcp

• agentic-forms：通过使用 WebMCP 属性标注标准 HTML 表单，将客户端功能作为工具暴露给 AI 智能体。
• agentic-javascript-tools：使用 WebMCP 命令式 API 以编程方式将客户端 JavaScript 函数注册为 AI 智能体的工具。
• webmcp：使用本指南在浏览器应用中实现 WebMCP，通过声明式或命令式 API 将客户端功能作为工具暴露给 AI 智能体。

安全采用现代特性

• 渐进增强与细致回退：我们区分纯增量增强（如推测性预加载），这类特性可安全地让旧浏览器静默忽略；以及关键行为（如对话框控件或网络信标），对这类行为我们编写经过深思熟虑、低开销的回退方案。
• 负责任的回退：我们优先采用轻量、针对具体场景的自定义回退（<50 行代码）或按条件加载的 polyfill，而非沉重的第三方打包产物。
• 陷阱与怪癖：我们记录隐藏的平台限制，例如 fetchLater() 的 64KB 载荷配额或 macOS 特有的滚动条行为。
• 感知 Baseline 的集成：我们利用 Baseline 项目的实时兼容性数据，使智能体能够动态适应当前浏览器支持情况。
• Origin Trial 与易变特性门控：涵盖实验性 Origin Trial API 或易变特性（过去 3 个月内发布的单引擎特性或仍在稳定中的特性）的指南仍可通过 search 发现，但受 retrieve 门控，因此智能体不会在未获得开发者明确同意的情况下采用不稳定的 API。

项目配置（.mwgrc）

通过项目根目录下可选的 .mwgrc JSON 文件（或以 ~/.mwgrc 作为用户级回退）为仓库配置 Origin Trial 和易变特性的选择加入，你可以提交该文件以便在团队中共享：

工作原理

1. 激活：编码智能体因相关任务而激活 modern-web-guidance 技能。智能体被指示使用 modern-web-guidance CLI 进行 Web 平台查询。
2. 本地语义搜索：智能体运行 modern-web-guidance search "<query>"。该工具使用离线、零依赖的嵌入模型和 BM25 搜索引擎将查询匹配到最佳指南（无网络调用，无 API 密钥）。
3. 指南获取：智能体通过 modern-web-guidance retrieve <guide-id> 检索指南，将针对性的代码模式、陷阱和回退方案直接插入其上下文窗口。

提示

注意：我们使用 npx 以确保内容不会过时，但该 CLI 可离线运行，完全私密且本地化。npm 包是自包含的，没有额外依赖，以确保低延迟和供应链安全。

其他安装方式

Vercel Skills CLI（又名 npx skills）

npx skills add GoogleChrome/modern-web-guidance

GitHub CLI

gh skill install GoogleChrome/modern-web-guidance

Google Antigravity

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

GitHub Copilot CLI

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

Claude Code 插件

/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
/plugin  # Select GoogleChrome marketplace, press enter, enable AutoUpdate
/reload-plugins

Grok Build CLI

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

Kimi Code

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

OpenAI Codex

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

更新

如果你使用 npx modern-web-guidance@latest install 安装了该技能，可以通过以下命令更新：npx modern-web-guidance@latest update。

否则，请查阅你的智能体文档以更新插件和技能。

证明其效果良好的评估

我们开发了一套稳健的评估框架，确保内容经过实证验证并持续校准，从而使 AI 智能体编写出更好的代码。我们使用闭环验证流水线运行自动化评估：

  [ Expert-authored guidance and demo ]
            │
            ▼
  [ Target generation ] ──> Tasks on real webapps, Golden solutions, Playwright graders
            │
            ▼
  [ Calibration loop ] ───> Runs Grader on Golden Solutions (Must Pass 100%)
            │               Runs Grader on Unmodified Base App (Must Fail 100%)
            ▼
  [ E2E agent evals ] ────> Runs coding agents in guided vs. unguided modes
                            Compares pass rates and accessibility w/ and w/o the skill

1. 模拟开发者任务：我们针对完整的基座应用（daily-grind、devtools-times）定义贴近真实的开发者提示词，模拟真实世界的请求（例如“让我的图片加载得更快”）。提示词避免提及 API 或特性名称，以测试智能体能否自然发现并应用正确的指南。
2. 静态与基于浏览器的断言：Playwright 评分器验证每项实现要求是否得到遵循——检查源码模式、计算样式、运行时 DOM 行为和可访问性状态。
3. 自愈校准：评分器以多智能体（Claude/Codex/AGY）黄金解决方案（100% 通过目标）和未修改的基线应用（0% 通过目标）为基准进行校准。
4. 端到端测试：我们衡量编码智能体在有指导和无指导下完成真实任务的性能。机会（100% - 无指导通过率）和提升（有指导通过率 - 无指导通过率）是关键：如果模型在无指导下已经成功，我们就删减冗余建议；在智能体表现吃力的地方，我们改进指南以最大化提升。

近期评估结果快照

在评估仪表盘上查看完整的按智能体和按指南细分结果。

可用的技能包

你可以使用 --choose 标志自定义安装哪些技能包：

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

• modern-web-guidance（约 205 个 token）：关于现代浏览器 API、布局和性能的全面指导。
• chrome-extensions（约 175 个 token）：关于 Manifest V3、后台 worker、扩展 API 和 Chrome Web Store 发布的指导。

遥测与隐私

Google 会收集匿名使用信息，以提升工具的可靠性、相关性和性能。收集的信息包括安装次数、调用方 agent 名称、指南检索 ID，以及 agent 生成的 CLI 工具搜索查询（例如“dark mode scrollbar color-scheme”）。不会收集用户的原始提示词。你可以在 modern-web.ts 中查看所收集的内容。

提示

如需退出：在你的 shell 配置文件中设置 DISABLE_TELEMETRY=1 环境变量（例如 .bashrc 或 .zshrc）：

export DISABLE_TELEMETRY=1

Google 依据 Google 隐私权政策处理这些数据。

贡献者

发现了 bug、过时的模式或缺失的 Web 平台特性？提交 issue，或在源代码仓库（GoogleChrome/modern-web-guidance-src）中查看 CONTRIBUTING.md。

衷心感谢每一位贡献者！

许可证

除非另有说明：

• 本项目中的软件代码依据 Apache License 2.0 授权。
• guides/ 下的文档和指南内容依据 Creative Commons Attribution 4.0 International (CC-BY 4.0) 授权。

本项目中的部分文档内容源自 Mozilla 贡献者编写的 MDN Web Docs，以及 W3C、WHATWG 和 IETF 规范。