Chrome、Edge、Firefox 联合推出编码 Agent 现代化 Web 指南

现代 Web 指南是一组技能，将 Web 平台专业知识、最佳实践和浏览器兼容性数据直接嵌入到你的编码智能体中。它帮助引导你的编码智能体远离遗留模式，转而采用能够发挥现代 Web 平台强大能力的解决方案。

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

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

npx modern-web-guidance@latest install

此命令会运行一个交互式向导来安装 Modern Web 指南。参见下方其他安装方式。

试用（无需安装）

#搜索相关指南
npx modern-web-guidance@latest search "为对话框模态背景添加动画"

#按 ID 获取指南
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

#扫描代码库以找出可现代化的遗留模式
npx modern-web-guidance@latest legacy-scan 。

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

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

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

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

我们覆盖了过去几年 Web 平台的新特性，直至最前沿。这些指南在设计上注重 token 效率；我们运行评估，以便剪除模型已经掌握的最低共同标准内容。

核心领域

查看示例： 该navigation-drawer指南。

完整列表

CSS 与布局（140 项特性）

HTML 与 DOM（36 项特性）

JavaScript 与 API（74 项特性）

无障碍

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

built-in-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: 当表单字段（例如标签或字段集）无效时，为其父元素设置样式。
• 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创建一个自定义选择组件，其选项可以包含复杂的 HTML 格式（例如图片、图标和其他富格式），而不仅仅是纯文本。
• select-menu-interaction仅在用户与控件交互之后，才校验选择菜单中是否已选中非默认选项。
• slider为原生范围滑块设置自定义轨道、滑块手柄、填充和聚焦状态的样式，同时保留原生功能和可访问性。
• sms-otp-form通过自动提取验证码和可访问的表单输入，验证用户手机号码以及通过短信发送的一次性验证码。
• 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，以及组件内部的级联层和容器查询，跨越 shadow 边界进行样式设置。
• web-components编写和使用 Web Components 的定位与横切原则，涵盖 Custom Elements、Shadow DOM、模板与插槽、Declarative Shadow DOM、跨 shadow 边界的样式设置、Form-Associated Custom Elements 以及无障碍要求。在构建可复用 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 事件进行防抖并批量合并到单个 beacon 中，以尽量减少网络争用并降低服务器负载，同时仍能提供实时更新。
• 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：通过保留单页应用（SPA）中先前访问过的视图的结构化 DOM 状态，而不是在每次导航时销毁并重建它们，从而实现更快地切换回这些视图。
• 无闪烁的客户端 A/B 测试：使用客户端 JavaScript 来修改或注入 HTML、CSS 和 JavaScript，以交付和渲染 A/B 测试、多变量测试或其他实验，同时避免原始内容先显示出来、再闪烁或闪动切换到实验内容。
• 全会话分析：在用户的整个页面访问过程中可靠地跟踪分析数据、Core Web Vitals、错误和遥测数据，并将数据的发送推迟到用户离开页面时。
• 识别高负载脚本：识别导致长动画帧的主要脚本
• 识别 INP 成因：识别运行缓慢的 JavaScript 以及其他导致 Interaction to Next Paint（INP）响应性不佳的原因。
• 提升下一页加载性能：通过预取或预渲染用户接下来可能访问的页面来提升页面加载性能。
• 交互绘制计时：测量用户交互和客户端导航在屏幕上渲染出新的内容更新所需的时间。
• 复杂布局中的交互：通过避免复杂布局（如数据密集型仪表盘或电子表格样式的网格）中的布局重新计算，使交互更迅捷、更灵敏（降低 Interaction to Next Paint（INP）分数）。
• 延迟加载视频和音频：推迟下载屏幕外的视频和音频资源（包括视频海报图片和预加载的媒体数据），直到媒体播放器接近视口，以节省带宽并减少初始页面加载期间的网络争用。
• 优化图片优先级：优化 Largest Contentful Paint（LCP）候选图片的加载优先级，并降低非关键图片的优先级，以减少关键资源的加载延迟。
• 优化预加载优先级：优化预加载内容的相对优先级，以减少关键资源的加载延迟。
• 优化脚本优先级：通过提升关键异步脚本的优先级、降低非必要或位于 body 后部的脚本的优先级来优化脚本的加载优先级，以改善加载顺序并减少延迟。
• 乱序 HTML 流式传输：以声明式方式用稍后流式传入同一 HTML 文档的内容更新页面，或通过命令式 JavaScript API 更新。
• 分辨率优化的伪元素：在 CSS 伪元素（例如::before和::after）中使用分辨率优化的图片，以减少 DOM 节点数量。
• 按优先级调度任务：按不同优先级调度任务，确保关键工作优先执行，同时推迟后台工作。

隐私

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

PWA

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

安全

• 客户端加密：使用公钥封装或密钥协商（包括混合及后量子保护）建立共享密钥，并在浏览器中使用认证加密加密敏感数据。
• 数字签名：在浏览器中使用经典或抗量子（后量子）非对称密钥对消息、令牌或产物进行签名和验证，以确保数据完整性和真实性。
• 本地网络访问：从公共 Web 应用访问用户本地网络或回环接口上的资源。
• 通行密钥认证：使用通行密钥对回访用户进行主登录认证。
• 通行密钥条件创建：在密码登录成功后，为现有用户静默注册通行密钥。
• 通行密钥管理：让用户查看和管理其账户已注册的通行密钥。
• 通行密钥重新认证：在敏感操作前，使用用户现有的通行密钥验证已登录用户的身份。
• 通行密钥注册：为现有用户账户注册通行密钥。
• 通行密钥：在 Web 应用中实现 WebAuthn 和通行密钥的全面入门指引与跨领域原则。在处理通行密钥注册、认证、管理或重新认证时使用本指南。
• 快捷登录在跳转到登录页面或打断用户工作流程之前，使用已保存的通行密钥或密码对回访用户进行就地身份验证。
• 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强制某些元素处于浅色模式或深色模式（例如代码块、媒体播放器等），独立于页面的配色方案。
• icons显示和管理图标，这些图标可通过 CSS 设置和参数化，加载速度快，在任何分辨率下都清晰，并正确暴露给（或隐藏于）辅助技术。
• position-aware-tooltips构建带有方向箭头（或其他视觉样式）的工具提示和弹出框，当元素翻转到回退位置时，箭头会自动指向正确的方向。
• pull-to-reveal构建下拉显示功能，使用户能够在屏幕上向下拉动以显示更多内容，例如搜索栏。
• responsive-table构建一个数据表格，以正确的表头语义呈现表格数据，并在小屏幕和辅助技术下保持可读性和可导航性。
• 滚动位置感知元素构建浮动按钮或小组件（返回顶部、滚动到底部、聊天启动器等），根据用户是否已滚动来显示和隐藏。
• 滚动进度指示器创建滚动进度条、分步进度跟踪器，或任何传达用户已滚动页面或区块多远的视觉提示。
• 可滚动性提示构建滚动阴影或渐隐边缘，仅当该方向上确实还有更多内容可滚动时才出现。
• 滚动时收缩的页头在滚动时平滑地为固定页头或整页封面添加动画，使其在预定义的滚动距离内动态收缩、获得阴影并变换布局。
• 单行溢出在可能放不下的空间中显示必须保持在一行内的文本，例如标签页标签、表格单元格、导航项或文件名，同时不破坏布局或丢失文本。
• 状态感知的粘性页头构建粘性区块页头或导航栏，当它们实际“粘”在顶部时进行视觉变换，改变配色方案或获得阴影。
• 视口感知的下拉菜单将下拉菜单、弹出层或上下文操作面板定位到触发按钮旁，使其在视口边缘自动翻转轴向，而不是被裁剪。

UI 行为

• 二维平移允许用户在二维表面上自由平移或滚动——例如地图、缩放图像、无限画布或大型数据网格——沿两个方向移动（无论是斜向还是手势中途改变方向），而不会让手势锁定到单一水平或垂直轴。
• 锚点定位的标签下划线在两个目标元素位置之间无缝过渡元素。例如，将选中的标签下划线从先前选中的标签移动到当前选中的标签。
• 元素进入/退出动画当元素被添加/移除到 DOM 或切换其 display 值时，平滑地隐藏/显示元素。
• 动画到/从顶层：在对话框、弹出框和工具提示进入/退出顶层时为其添加动画。
• 轮播吸附高亮：在滚动吸附轮播、画廊或整页滑动体验中，以视觉方式高亮当前吸附的非交互项。例如，在吸附时展开卡片，或显示隐藏内容。
• 一致的跨文档过渡：在启动跨文档视图过渡之前，确保关键页面状态已加载且稳定。这意味着关键 CSS 样式已加载并应用，关键 JavaScript 已加载并运行，并且用户初始视图可见的 HTML 已在过渡运行前完成解析。
• 跨文档过渡：在整页导航之间创建平滑、无缝的过渡，例如交叉淡入淡出、自定义揭示效果，或内容从一页到下一页的形变。
• 自定义按钮操作：使用声明式按钮命令、调用器命令、按钮命令、自定义命令或声明式切换操作，以声明方式将按钮连接到任意元素，以触发应用特定的自定义操作。
• 声明式对话框/弹出框控制：无需编写 JavaScript，即可通过按钮切换对话框或弹出框的可见性。
• 方向性导航过渡：为视觉状态变化添加动画，以反映用户导航流程的方向，例如前进时新内容从右侧滑入，返回上一屏幕时从左侧滑入。
• 拖拽：支持拖拽以在页面上移动浮动元素。
• 拖放：支持沿单一轴（水平或垂直）拖拽以重新排列容器的子元素，同时保留其状态和无障碍顺序。
• 动态同级动画：在兄弟元素之间错开动画或过渡时序，使每个元素根据其在兄弟列表中的位置，在计算出的延迟之后开始。
• 动态排序：处理用户触发的容器子元素动态重新排序（例如列表项、表格行或卡片网格）的最佳实践，包括可选的动画重排，该重排尊重用户偏好、提供良好的屏幕阅读器用户体验，并为大型列表提供最佳性能。
• 组元素过渡在添加、删除、打乱或重新排序时，将列表项、卡片或网格元素平滑地重新排列并同时动画到新位置——例如从购物车中移除商品。
• 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当其底层 DOM 节点在 DOM 中被移动或重新挂载时，保持模态对话框、全屏元素或原生弹出框在视觉上打开且功能上处于活动状态。
• physics-based-easing创建自定义的、基于物理的动画和过渡效果，例如弹跳和弹簧，比传统缓动曲线更自然、更具吸引力。
• platform-controls-dismiss-dialog创建一个可通过标准平台特定用户操作关闭的模态对话框，例如在桌面平台上按下Esc键，或在移动平台上执行“返回”或“关闭”手势
• prevent-page-scroll-under-modal-dialog在模态对话框打开时阻止底层页面滚动。
• 同文档过渡在单页应用（SPA）中，通过平滑地变形其尺寸、位置或其他样式属性，在不同页面状态或导航之间在视觉上连接持久存在的元素（例如将产品缩略图扩展为全出血主图）。
• 作用域组件过渡在单个组件（卡片、列表、面板或其他子树）内部为状态变化添加动画，同时页面其余部分保持可交互，并且其他过渡同时运行。
• 滚动完成效果仅在平滑的程序化滚动到目标元素完成后，才在该元素上触发视觉效果、动画或焦点变化。
• 滚动进入/退出效果在用户滚动时，为元素进入和退出滚动端口（或视口）创建淡入、放大或其他复杂的显现类效果。
• 滚动吸附实时反馈在用户滚动浏览吸附对齐的内容时，在滚动手势完成之前，在关联的 UI 元素中提供实时视觉反馈。
• 滚动吸附状态同步将导航指示器、关联内容面板和分析跟踪与可滚动容器中当前吸附的项目同步。
• 加载时滚动到目标构建一个可滚动的元素列表（例如图片轮播或聊天对话线程），在初始渲染时可以将特定元素滚动到视图中显示。
• 滚动叙事完全由另一个元素的滚动端口位置驱动，在目标元素上为视觉属性添加动画——例如淡化背景、改变背景颜色，或创建滚动叙事体验。
• 搜索隐藏内容使用手风琴、标签页和“阅读更多”部分等模式将内容从视图中隐藏，同时确保隐藏文本在原生“在页面中查找”搜索期间显示自身、允许搜索引擎索引、支持 URL 片段深度链接，并保持 ARIA 可访问性。
• 可排序表格通过允许用户点击列标题对行进行排序的行为，逐步增强数据表格。
• 空间导航：使用方向键实现无障碍的空间导航，在网格等不同布局模式下都能正确工作
• 滑动删除：让用户通过水平滑动手势对列表中的条目进行操作（删除、归档、标记为已读等），从而无需点击单独控件即可快速处理条目。
• 滑动显示：让用户在列表条目或内容面板上水平滑动，以显示上下文操作按钮或侧边菜单，而不会自动触发操作。

UI 组件

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

user-experience

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

visual-design

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

现代特性的安全采用

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

项目配置（.mwgrc）

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

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

npx skills add GoogleChrome/modern-web-guidance

gh skill install GoogleChrome/modern-web-guidance

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

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

/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
/plugin  #选择 GoogleChrome 市场，按回车，启用 AutoUpdate
/reload-plugins

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

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

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（约 205 tokens）：关于现代浏览器 API、布局和性能的全面指南。

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

• modern-web-guidance（约 175 tokens）：关于 Manifest V3、后台 worker、扩展 API 和 Chrome 应用商店发布的指南。
• chrome-extensions遥测与隐私

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

export DISABLE_TELEMETRY=1

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

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

衷心感谢每一位贡献者！

除非另有说明：

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

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