企业官网建设流程全解析

Modern Web Guidance是由 Google Chrome 团队主导的开源指南库，它为 AI 编程代理提供现代 Web 平台最佳实践：涵盖 CSS 布局、表单组件、页面性能优化、Web 安全与无障碍（Accessibility）的 180 个真实开发场景用例，外加 212 个现代浏览器特性条目，帮助你的 AI 助手写出更现代、更少"祖传代码"的前端实现。

Modern Web Guidance 性能用例中的优化装饰图片示例，用于说明装饰图片的优化交付

它解决什么问题：为什么 AI 写出的网页代码常常"过时"

AI 编程代理（Coding Agent）的训练数据里包含海量旧代码，因此它们倾向于用陈旧的方案解决本可以原生搞定的问题，例如：

• 用几百行 JavaScript 实现一个浏览器原生就能完成的弹窗动画
• 加载重量级 polyfill，而现代 CSS 属性一行就能实现
• 忽略无障碍与性能基线，生成"能跑但不好"的代码

Modern Web Guidance 的思路很直接：把专家精选、经过实测校准的指南通过 CLI 检索后注入 AI 的上下文窗口，让它优先使用原生 API、合理的降级方案和轻量回退。

快速体验（无需安装）：npx modern-web-guidance@latest search "animate a dialog modal backdrop"

180 个真实用例是怎么组织的：按 17 个知识域分类

全部内容位于 guides/ 目录，每个用例一个独立文件夹，内含 guide.md（指导正文）、demo.html（黄金示例）与expectations.md（可测试断言）。按目录实测统计，各分类的用例数量如下：

每个用例文件夹长什么样

以"流体缩放"为例，一个完整用例包含：

• guide.md —— 给 AI 阅读的操作指南（DO / DO NOT 指令 + 代码片段 + 回退策略）
• demo.html—— 黄金标准实现，评分器要求 100% 通过
• negative-demo.html—— 反例页面，评分器要求 0% 通过
• expectations.md—— 自然语言断言清单，用于自动生成 Playwright 评分器

五大核心领域亮点速览

🎨 CSS 布局：容器查询、:has()、@scope

CSS 类是内容最密集的板块之一（20 个任务型用例 + 2 个领域总纲），覆盖从响应式排版到设计系统架构：

• fluid-scaling：字号、间距随容器宽度平滑缩放，替代固定断点
• style-parent-with-has：表单字段失焦后给父级加错误样式
• size-aware-styling：卡片根据"自身宽度"而非视口切换布局
• design-token-reactivity：密度模式/主题切换时，后代组件各自响应

⚡ 性能：从 LCP 到 INP 的全链路

性能类是数量最多的分类（32 个），围绕 Core Web Vitals 与加载调度展开：

• break-up-long-tasks：拆分长任务，让浏览器有机会响应用户输入
• optimize-image-priority：提升 LCP 候选图片的加载优先级
• schedule-tasks-by-priority：用 Scheduler API 按优先级排队
• identify-inp-causes：定位拖垮 INP 指标的具体脚本

📝 表单：让自动填充和验证"原生"工作

• autofill-address-form：正确的 autocomplete 取值，让地址栏一键填充
• branded-select-styling：品牌化定制 select 的下拉面板而不替换原生控件
• required-field-feedback：必填项错误提示只在用户交互后出现，避免"页面一打开就红一片"

🔐 安全：Passkey、Trusted Types 与加密

• passkeys：WebAuthn / Passkey 的总纲（注册、认证、管理、二次认证共 8 个子用例）
• trusted-types：封锁危险 DOM 出口，防 DOM 型 XSS
• client-side-encryption：浏览器内完成含后量子抗性的端到端加密

♿ 无障碍：屏幕阅读器与系统偏好

• accessible-error-announcement：aria-invalid与视觉:user-invalid状态同步
• respect-os-text-scale：尊重操作系统的文字缩放偏好

此外还有端侧 AI 用例（translator 本地翻译、summarizer 本地摘要），以及面向未来的 WebMCP——把标准 HTML 表单直接暴露为 AI 代理可调用的工具。

不只是文档：用评测证明指南真的有效

Modern Web Guidance 的独特之处在于：每条指南都有配套的自动化评测，不是拍脑袋的最佳实践。

• 基准应用：评测在 src/harness/base-apps/ 下两个真实站点（daily-grind博客应用、devtools-times新闻站）上进行
• 闭环校准：生成的 Playwright 评分器必须对黄金示例 100% 通过、对反例 0% 通过
• 对照实验：同一任务分别让 AI"无指南"与"有指南"完成，测量提升幅度（uplift）

README 中的最新评测快照显示，接入指南后各模型通过率普遍提升 19~28 个百分点，例如 claude_code 从 59% 提升到 87%。

如何快速上手：两条命令开始使用

1. 安装技能：npx modern-web-guidance@latest install（支持--choose挑选技能包）
2. 日常检索：在 AI 助手遇到前端任务时，它会先执行search找到最匹配的指南，再用retrieve <id>取回完整内容注入上下文

技术栈与内部机制可以进一步阅读 docs/CONTEXT.md（项目架构与gdCLI 流水线）、docs/EVALS.md（评测框架配置）以及 guides/AGENTS.md。

如果你正在评估 AI 生成代码的质量，这份覆盖 17 个领域、180 个真实场景的指南清单，是一个值得逐条对照的"现代 Web 开发体检表"。