现代 Web 指南（Modern Web Guidance，源码仓库）#

本仓库是 GoogleChrome/modern-web-guidance 的源码仓库，包含用于编写、校准和评估其内容的代码与文档。

Modern Web Guidance 是一组技能（skills），将 Web 平台专业知识、最佳实践和浏览器兼容性数据直接嵌入你的编程智能体。它帮助引导编程智能体远离遗留模式，转而采用能够利用现代 Web 平台能力与性能的解决方案。

工作方式与代码库导览见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [GOVERNANCE.md](GOVERNANCE.md)。

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

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

快速开始#

npx modern-web-guidance@latest install

该命令会运行一个交互式向导来安装 Modern Web Guidance。其他安装方式见下文。

试用（无需安装）#

# 搜索相关指南
npx modern-web-guidance@latest search "animate a dialog modal backdrop"

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

# 扫描代码库中的遗留模式并进行现代化
npx modern-web-guidance@latest legacy-scan .

为什么需要它？#

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

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

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

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

包含什么？#

我们覆盖 Web 平台过去几年的新特性，一直延伸到最前沿。这些指南设计得词元高效；我们运行评估，以删减模型已经知道的「最低共同标准」内容。

核心领域#

🎨 用户体验

流畅的视觉状态（View Transitions、进入/退出动画、视差滚动、CSS scrollbar-color）。

📐 CSS 布局

现代布局系统（容器查询、subgrid、oklch 等现代色彩空间、text-wrap 调优、行高裁剪）。

⚡ 性能

速度优化（即时预加载、Interaction to Next Paint（INP）诊断、通过 scheduler.yield 调度任务）。

📝 表单与 UI

原生组件（用于工具提示的 Anchor Positioning、Popover API、对话框、:user-invalid 验证、自动调整大小的字段）。

♿ 可访问性

重要考量（屏幕阅读器和键盘可操作性、内容导航与可发现性）。

🤖 内置 AI

本地客户端模型（原生翻译、摘要和语言检测 API）。

查看示例：navigation-drawer 指南。

完整列表#

250 项现代 Web 特性

CSS 与布局（140 项）#

::backdrop、content-visibility、progress()、::details-content、contrast-color()、reading-flow、::file-selector-button、跨文档视图过渡、相对颜色、::placeholder、currentColor、rem、::selection、自定义高亮、resize（CSS 属性）、:dir()、自定义属性、revert、:focus-visible、display 动画、revert-rule、:focus-within、元素作用域视图过渡、安全区域 inset 环境变量、:has()、em 单位、滚动标记目标伪类、:host-context()、field-sizing、滚动方法 Promise、:is()、filter、滚动吸附、:modal、flex-wrap: balance、滚动吸附事件、:not()、Flexbox、scroll-axis-lock、:nth-child() of <selector>、font-size、scroll-behavior、:placeholder-shown、font-size-adjust、滚动驱动动画、:user-valid 与 :user-invalid、强制颜色、scroll-initial-target、:where()、渐变插值、scroll-target-group、@function、渐变、scrollbar-color、@scope、Grid、scrollbar-gutter、@starting-style、Grid lanes、scrollbar-width、@supports、断字、scrollend、abs() 与 sign()、image-set()、scrollIntoView()、accent-color、独立 transform 属性、Shadow parts、活动视图过渡、inherit、sibling-count() 与 sibling-index()、生成内容的替代文本、initial、粘性定位、锚点位置容器查询、交互媒体查询、Subgrid、锚点定位、interpolate-size、系统颜色、动画（CSS）、isolation、文本溢出、appearance、Lab 与 LCH、文本描边与填充（兼容前缀）、aspect-ratio、light-dark()、text-box、at-rule()、line-clamp、text-decoration、attr()、line-height、text-decoration-skip-ink、background-blend-mode、linear() 缓动、text-decoration-skip-ink: all、background-clip: border-area、逻辑属性、text-decoration-skip-spaces、border-radius、遮罩、text-wrap、box-shadow、min()/max()/clamp()、text-wrap: balance、calc-size()、mix-blend-mode、text-wrap: pretty、级联层、嵌套、transition-behavior、ch 单位、Oklab 与 OkLCh、过渡（CSS）、clip-path、overflow-clip-margin、三角函数（CSS）、color-mix()、overflow-wrap、unset、color-scheme、overflow: clip、user-select、锥形渐变、overlay、视图过渡、容器查询（尺寸）、overscroll-behavior、view-transition-class、容器滚动状态查询、prefers-color-scheme 媒体查询、视口单位、容器样式查询、prefers-contrast 媒体查询、Web 动画、content、prefers-reduced-motion 媒体查询。

HTML 与 DOM（36 项）#

:autofill、<slot>、HTML 流式 setter、:indeterminate、<video>、HTML-in-canvas、<audio>、自主自定义元素、inert、<details>、blocking="render"、Interest invokers、<dialog closedby>、可定制 <select>、Invoker commands、<dialog>、声明式 Shadow DOM、媒体懒加载、<input type="checkbox" switch>、电子邮件/电话/URL <input> 类型、moveBefore()、<input type="range">、Fetch priority、MutationObserver、<input>、focusgroup、互斥 <details> 元素、<link rel="expect">、表单关联自定义元素、Popover、<link rel="preload">、hidden="until-found"、popover="hint"、<progress>、HTML setter 方法、Shadow DOM。

JavaScript 与 API（74 项）#

<install>、url() 的 integrity()、Sanitizer API、<meta name="text-scale">、Interaction contentful paint 性能条目、Scheduler API、<template for>、Intersection observer、小/大/动态视口单位、AbortController 与 AbortSignal、Intl.DurationFormat、软导航性能条目、ARIA 属性反射、键盘事件、Speculation rules、ariaNotify()、语言检测器、子资源完整性、异步剪贴板、LanguageModel、Summarizer、autocorrect、图像和 iframe 懒加载、SVG、beforeinstallprompt、light-dark() 图像值、Temporal、border-shape、本地网络访问、text-decoration-inset、连接允许列表、长动画帧性能条目、text-fit、corner-shape、long-animation-frames-style-layout、顶层 await、凭证管理、Navigation API、touch-action、url() 的 cross-origin()、navigator.install()、Translator、document.modelContext、Origin、Trusted Types、email-verification、页面可见性、用户代理客户端提示、enterkeyhint、页面可见性状态性能条目、Web 应用清单、Event timing 性能条目、分区 Cookie、Web 应用源迁移、联邦凭证管理、密码凭证、Web 认证、Fetch、权限策略、Web 认证信号方法、fetchLater、Pointer Events、Web 加密、表单关联 WebMCP 属性、Referrer 策略、WebAssembly、HTML 处理指令、url() 的 referrer-policy()、webcrypto-modern-algos、image()、注册自定义属性、WebOTP、inputmode、Resize observer。

203 个真实开发者用例#

可访问性（accessibility）#

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

内置 AI（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：基于选择器与条件 @-rule 的交集或并集定位元素，同时尽量减少重复。
• size-aware-styling：构建样式可条件性依赖自身宽度或高度（而非视口宽高）的组件。例如，可根据自身大小改变布局的卡片组件，或可根据宽度条件性显示辅助文本的行动号召按钮。
• style-parent-with-has：当表单字段无效时，使用 :has() 为其父元素（例如标签或 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：创建选项可包含复杂 HTML 格式（例如图像、图标和其他富格式）而非纯文本的自定义 select 组件。
• select-menu-interaction：仅在用户与 select 菜单交互后，才验证是否选择了非默认选项。
• 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 模板高效构建树，并通过 slot 投射使用方内容。
• styling-web-components：使用 :host 选择器、继承和自定义属性进行主题化、::slotted 与 ::part，以及组件内部的级联层和容器查询，跨越 shadow 边界设置样式。
• web-components：编写和使用 Web Components 的导览与横切原则，涵盖 Custom Elements、Shadow DOM、模板和 slot、声明式 Shadow DOM、跨 shadow 边界的样式、表单关联自定义元素以及可访问性要求。在构建可复用 UI 组件、设计系统或服务端渲染自定义元素时使用本指南。

JavaScript#

• 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：通过保留之前访问视图的结构化 DOM 状态，而不是在每次导航时销毁并重建，实现单页应用（SPA）中更快的返回过渡。
• flicker-free-client-side-ab-testing：使用客户端 JavaScript 修改或注入 HTML、CSS 和 JavaScript 来交付和渲染 A/B 测试、多变量测试或其他实验，避免原始内容先显示、随后闪烁切换到实验内容。
• 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：通过避免复杂布局（如数据密集型仪表盘或电子表格式网格）中的布局重计算，使交互更迅捷、更响应（降低 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：通过浏览器控制的同意 UI，从页面安装 Web 应用。
• migrate-web-app-origin：将已安装的 Web 应用迁移到新源，同时保留用户配置和操作系统级快捷方式。

安全（security）#

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

UI 原子组件（ui-atoms）#

• carousel-slide-effects：创建图像或其他视觉元素的轮播，每张幻灯片在进入/居中/离开滚动容器时播放动画。例如，幻灯片可以淡入淡出、旋转、变大或变小等。
• component-specific-light-dark-theme：强制某些元素处于浅色或深色模式（例如代码块、媒体播放器），不受页面配色方案影响。
• 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 行为（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：使用声明式按钮命令、invoker 命令、按钮命令、自定义命令或声明式切换操作，以声明方式将按钮连接到任何元素，触发应用特定的自定义操作。
• 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：当模态对话框、全屏元素或原生弹出框的底层 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 组件（ui-components）#

• accordion：构建带手风琴组件，支持动画、可选的互斥（一次只开一个）行为和品牌一致的样式。
• app-menus：构建应用菜单栏，让多个顶级菜单（如文件、编辑和视图）作为单个键盘停留点，并在悬停或方向键操作时相互切换。
• breadcrumbs：构建面包屑导航，显示用户在站点层级中的位置，并允许导航到祖先页面。
• card：构建卡片组件，使其呈现方式适应自身可用空间和内容。
• carousel：构建以水平或垂直布局显示一组项目的轮播组件。
• checkbox：为复选框设置样式，包括自定义图标、布局、颜色、勾选/取消勾选动画，同时保留原生功能和可访问性。
• copy-button：构建复制按钮，将任意元素的文本复制到剪贴板。
• dark-mode-toggle：构建深色模式切换组件，允许用户为当前站点覆盖系统配色方案偏好。
• dialog：构建可访问的模态或非模态对话框组件，适当管理焦点，并可按各平台用户预期的方式关闭。
• hovercard：构建悬停卡片组件，当鼠标悬停在某种链接（例如用户资料）上时，显示该链接将导航到的页面的交互式结构化预览。
• menu：构建显示选项或操作列表的菜单组件，支持嵌套子菜单。
• navbar：构建站点导航栏，可跨屏幕尺寸自适应并指示当前页面。
• navigation-drawer：创建导航抽屉组件，由菜单按钮触发时从侧边滑入并覆盖在现有页面内容之上，关闭时（滑动移开、点击外部或按 Esc）滑出。
• persistent-app-tours：使用绑定的原生覆盖层创建持久的新手引导流程，在用户交互期间保持打开。
• persistent-toast-notifications：创建非侵入式的 toast 和覆盖层通知，用于持久、可堆叠的消息传递和状态传达。
• progress：构建带样式的进度条，以确定和不确定状态传达任务或流程的完成情况。
• progress-ring：构建可视化表示任务或流程完成状态的进度环组件，支持中心内容和品牌一致样式。
• scrollspy：在导航菜单中高亮当前可见的页面区块。
• 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：为元素应用逼真的风化和纹理图案，使其具有有机、老化或物理材质的外观。

WebAssembly（wasm）#

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

WebMCP#

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

安全采用现代特性#

• 渐进增强与细致回退：我们区分纯增量增强（如推测性预加载），这类特性可以让旧浏览器静默忽略；以及关键行为（如对话框控件或网络 beacon），对后者我们会编写经过深思熟虑、低开销的回退方案。
• 负责任的回退：我们优先使用轻量、针对具体场景的自定义回退（少于 50 行代码）或条件加载的 polyfill，而不是沉重的第三方包。
• 陷阱与怪癖：我们记录隐藏的平台限制，例如 fetchLater() 的 64KB 负载配额，或 macOS 特有的滚动条行为。
• 基线感知集成：我们利用 Baseline 项目的实时兼容性数据，让智能体动态适应当前浏览器支持情况。
• Origin Trial 与易变特性门控：涵盖实验性 Origin Trial API 或易变特性（最近 3 个月内发布的单引擎特性，或仍在稳定中的特性）的指南仍可通过搜索发现，但在 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 # 选择 GoogleChrome marketplace，按回车，启用 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 智能体写出更好的代码。我们使用闭环验证流水线运行自动化评估：

[ 专家编写的指南和演示 ]
        │
        ▼
[ 目标生成 ] ──> 在真实 Web 应用上的任务、黄金解决方案、Playwright 评分器
        │
        ▼
[ 校准循环 ] ───> 对黄金解决方案运行评分器（必须 100% 通过）
        │          对未修改的基础应用运行评分器（必须 100% 失败）
        ▼
[ 端到端智能体评估 ] ────> 在引导与非引导模式下运行编程智能体
                           比较有无该技能时的通过率和可访问性

• 模拟开发者任务：我们针对完整的真实基础应用（daily-grind、devtools-times）定义逼真的开发者提示，模拟真实请求（例如「让我的图像加载更快」）。提示避免点名 API 或特性，以测试智能体能否自然发现并应用正确的指南。
• 静态与浏览器断言：Playwright 评分器验证每个实现要求是否被遵循——检查源代码模式、计算样式、运行时 DOM 行为和可访问性状态。
• 自愈校准：评分器针对多智能体（Claude/Codex/AGY）黄金解决方案（目标 100% 通过）和未修改的基线应用（目标 0% 通过）进行校准。
• 端到端测试：我们衡量编程智能体在真实任务上使用和不使用指南时的表现。「机会」（100% 减去非引导通过率）和「提升」（引导通过率减去非引导通过率）是关键指标：如果模型在没有指南时已经成功，我们会删减冗余建议；如果智能体表现困难，我们会改进指南以最大化提升。

近期评估结果快照#

完整的按智能体和按指南细分请见评估仪表盘。

可用的技能包#

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

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

• modern-web-guidance（约 205 词元）：关于现代浏览器 API、布局和性能的全面指南。
• chrome-extensions（约 175 词元）：关于 Manifest V3、后台 worker、扩展 API 和 Chrome 网上应用店发布的指南。

遥测与隐私#

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

提示 退出方式：在 shell 配置文件（例如 .bashrc 或 .zshrc）中设置 DISABLE_TELEMETRY=1 环境变量： ``bash 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 规范。

关于#

goo.gle/modern-web-guidance

资源：Readme、Apache-2.0 license、行为准则、贡献指南

活动：1.7k stars、32 watching、138 forks