note inc. 如何利用 Modern Web Guidance 将现代 Web 准则遵循率从 61% 提升至 94%

Syna Kim
Syna Kim
Takehiko Itabashi
Takehiko Itabashi VP of Technology, note inc.

发布时间:2026 年 11 月 10 日

背景:利用 Web 标准实现前端架构现代化

note inc. 是日本最大的创作者和媒体平台之一,每月服务超过 9, 000 万月活跃用户数。作为持续推进前端现代化改造工作的一部分,note 的 Web 应用是使用 Next.js 和 React 构建的。

前端工程团队已将 AI 编码助理纳入其开发工作流。为了帮助这些工具生成符合标准的现代代码,Google 推出了 Modern Web Guidance,这是一套将 Web 平台专业知识、最佳实践和浏览器兼容性数据直接嵌入到编码智能体中的技能。

为了评估 Modern Web Guidance 对其 Next.js 代码库中生成的代码有何影响,并确定如何将其与内部组件库 (note-ui) 集成,note 针对六个实际界面场景进行了结构化对比评估。

挑战:使内部组件与 Web 标准保持一致

note 维护着一个内部 React 组件库 note-ui,该库提供品牌一致、易于访问的元素,例如对话框、提示、折叠面板和表单字段。团队准则规定使用 note-ui,以在整个平台上保持视觉一致性和无障碍基准。

note 的前端团队希望确定 Modern Web Guidance 在哪些方面能带来最大的架构优势,以及如何最好地将 Web 标准与现有组件库进行协调。

评估设置

note 开展了一项对比研究,在六项实际界面任务中,对生产环境 Next.js 代码库的克隆版本进行了对比,比较了三种情况:

  1. 无指导:AI 工具在没有 Modern Web Guidance 的情况下运行。
  2. 有明确指导:AI 工具配备了 Modern Web Guidance,并被提示参考该指南。
  3. 隐式指导:Modern Web Guidance 存在于代码库中,但未在提示中明确提及。

这六项任务根据其与 Note 的内部组件库的关系进行了分类:

  • note-ui 涵盖的任务:删除确认对话框。
  • note-ui 范围之外的任务:滚动收缩标题、文章页面速度优化。
  • note-ui 部分涵盖的任务:常见问题解答折叠菜单(需要单开行为和页内搜索可查找性)、丰富的用户画像提示、会员注册表单。

我们不仅通过静态代码分析验证了实现,还通过在自动化 Chromium 和 WebKit 浏览器测试中检查渲染的 DOM 和 CSS 属性来验证实现。

以下是六种界面场景以及评估所依据的功能标准说明。

删除确认对话框
点击删除时打开;通过 Esc、点击背景或“取消”按钮关闭
滚动收缩标题
初始高度为 120px;滚动时收缩至 64px;保持固定在顶部
富用户提示
在鼠标悬停和键盘焦点时显示;在指针离开时关闭
常见问题解答折叠面板
点击即可展开;打开另一个项目会自动收起之前的项目
会员注册表单
在用户输入时隐藏错误;在字段失去焦点时显示验证错误
文章页面呈现
视口中最大的图片具有高优先级,且不会延迟加载;屏幕外卡片使用 content-visibility: auto;,屏幕外图片会延迟加载

关键发现:Modern Web Guidance 在哪些方面发挥的影响最大

为了衡量 Modern Web Guidance 的实际影响,note 在其生产 Next.js 代码库的克隆版本上执行了 180 次结构化评估。他们评估了两个商业前沿编码智能体在三种条件下的六种界面场景中的表现:无指导、无提示指导(提供代码库级技能)和显式提示。

自动化测试套件根据现代 Web 标准中定义的 19 项标准,在无头 Chromium 和 WebKit 浏览器运行时中验证了渲染的 DOM、布局和计算出的 CSS 属性。

Web 标准遵守情况(按评估条件)

编程智能体 基准 主动引导 明确指导 净升幅
智能体 A
主要模型
60.8%
无指导
76.5%
+15.7pt
94.0%
峰值性能
+33.2pt
p < 0.001
代理 B
次要模型
75.8%
无指导
86.2%
+10.3%
90.0%
高准确率
+14.2pt
p < 0.001
关于方法:该百分比表示 Chromium 和 WebKit 中 19 项自动化浏览器检查的平台合规率。测试验证了生成的代码采用的是原生 Web 功能,而不是旧版自定义 JavaScript。

1. 架构和性能改进

事实证明,Modern Web Guidance 是 note 现有架构的有力补充。虽然 note-ui 组件库为标准界面元素保持了品牌一致性,但 Modern Web Guidance 为 AI 工具提供了使用原生浏览器 API 处理复杂交互行为和性能优化的能力。

在没有指导的情况下,AI 工具经常会生成自定义 JavaScript 事件监听器、手动状态管理和临时资源加载。借助 Modern Web Guidance,工具始终采用声明式原生功能,并强化了关键性能最佳实践。

采用现代网络标准与无指导实现的影响

功能和原生 API 无指导 借助 Modern Web Guidance
滚动收缩标题
animation-timeline: scroll()
❌ 命令式 JS 监听器
在主线程上运行;会导致滚动卡顿
✅ 非主线程合成器
声明式 CSS 滚动动画;零 JS 监听器代码
互动式提示
Popover API
❌ 自定义 JS 坐标数学
脆弱的手动视口和大小调整计算
✅ 0 KB 软件包开销
原生顶层放置;零自定义数学或 DOM 封装容器
可搜索的常见问题解答折叠菜单
<details name="faq">
❌ 自定义 React 切换状态
内容在页内文本搜索 (Ctrl+F) 中隐藏,手动 ARIA
✅ 原生页内查找功能
浏览器在按下 Ctrl+F 时自动展开;零状态同步代码
候选 LCP 主打图片
fetchpriority="high"
❌ 冲突的反模式
将高优先级与主打图片上的延迟加载相结合
✅ 早期 HTML 解析发现
与延迟加载解耦;在 MWG 后的 PR 中,采用率提高了 28%
无障碍注册表单
autocomplete和语义化 HTML
❌ 缺少自动填充令牌
省略了无障碍错误通知
✅ 顺畅的浏览器自动填充
原生输入和 ARIA 提示;自动填充采用率提升 69%
方法说明:第 1-3 行反映了在 180 次无头浏览器测试运行中验证的架构结果。第 4-5 行包含在引入后 431 个 PR 中测量的生产采用率提升。

Modern Web Guidance 对代码库的影响因提示和所用功能而异。举个具体例子,下面展示了如何将标头的命令式 JavaScript 滚动监听器替换为原生 CSS 滚动驱动动画。

/* With Modern Web Guidance: CSS scroll-driven animation (excerpt, CSS Modules) */
.header {
  --shrink-progress: 0;
  --shrink-distance: calc(var(--header-max-height) - var(--header-min-height));

  position: fixed;
  inset: 0 0 auto;
  /* Without support, a JS fallback updates --shrink-progress */
  height: calc(var(--header-max-height) - var(--shrink-distance) * var(--shrink-progress));
}

/* The shadow fades in through opacity only */
.header::after {
  content: "";
  position: absolute;
  inset: 0;
  pointer-events: none;
  box-shadow: var(--elevation-4);
  opacity: var(--shrink-progress);
}

@supports ((animation-timeline: scroll()) and (animation-range: 0% 100%)) {
  .header,
  .header::after,
  .logo {
    animation-duration: auto;
    animation-timing-function: linear;
    animation-fill-mode: both;
    animation-timeline: scroll(block root);
    animation-range: 0px var(--shrink-distance);
  }

  .header { animation-name: header-shrink; }
  .header::after { animation-name: header-shadow; }
  .logo { animation-name: logo-shrink; }
}

@media (prefers-reduced-motion: reduce) {
  .header,
  .header::after,
  .logo {
    animation-timing-function: steps(1, end);
  }
}

@keyframes header-shrink { to { height: var(--header-min-height); } }
@keyframes header-shadow { to { opacity: 1; } }
@keyframes logo-shrink   { to { transform: scale(0.5); } }

2. 为内部设计体系建立正确的运营边界

评估还重点分析了 AI 编码工具如何解读指令。当工具收到明确、无条件的指令来遵循 Web 指南时,它们会自然地选择原生 HTML 元素(例如原生 <dialog> 或 <input>),即使已有 note-ui 组件可用也是如此。

note 发现,解决方案很简单:团队不应将网络指南视为非此即彼的开关,而是通过在代码库指令(例如 AGENTS.md)中建立清晰的规则层次结构,从而实现最佳结果。

决策:AGENTS.md 中的分层规则结构

根据评估结果,Note 在其代码库指南 (AGENTS.md) 中制定了一条系统性规则,以指导开发者和 AI 工具:

## UI Components and Modern Web Guidance

When building UI, follow this order of precedence. This applies even though the `modern-web-guidance` skill describes itself as mandatory for all HTML/CSS and client-side JavaScript tasks.

1. **Prioritize noteui**: For UI elements already provided by noteui (dialogs, toasts, buttons, form fields, popovers, etc.), use those components and follow existing conventions (such as `useDialogState` and react-hook-form). In apps, import them through `@/ui/noteui`. Do not replace an available component with a native HTML element (such as `<dialog>` or a plain `<input>`) simply because Modern Web Guidance recommends it.
2. **Use Modern Web Guidance where noteui falls short**: For capabilities that noteui does not cover or requirements it cannot meet, consult the `modern-web-guidance` skill before writing HTML, CSS, or client-side JavaScript. For example:
   - Scroll-linked effects: Use CSS scroll-driven animations instead of scroll event listeners.
   - Exclusive or page-searchable disclosure: Use `<details name="...">` and `hidden="until-found"`.
   - Core Web Vitals: Use `fetchpriority` for LCP images and `content-visibility` for off-screen content.
   - Form attributes: Pass attributes such as `autocomplete` and input `type` through the field component's props.
3. **Prioritize existing components when guidance conflicts**: Apply Modern Web Guidance only through the props and attributes supported by the component. For noteui form fields, display validation errors using the component's built-in mechanisms (`validationState` / `errorMessage`, or `HelpText` with `aria-describedby`) rather than custom alert elements.

通过定义以下层次结构:

  • 保留现有界面的一致性:标准对话框和表单继续使用 note-ui。
  • 消除了自定义 JavaScript:新的互动行为和动画利用了原生浏览器功能。
  • 代码质量标准化:开发者工具会自动遵循现代 Web 标准,尤其是在最关键的环节。

工程团队的要点

  • 在设计体系无法满足需求时,使用现代平台功能:组件库擅长处理品牌界面元素,但现代浏览器提供了强大的原生功能,可用于滚动、弹出式窗口和加载优先级。Modern Web Guidance 可帮助开发者工具采用这些原生功能,而不是编写自定义 JavaScript。
  • 定义清晰的优先级层次结构:在具有现有组件库的代码库中,在代码库文件(例如 AGENTS.md)中添加简洁的优先级顺序,可确保工具在采用现代 Web 标准的同时遵循您的设计体系。
  • 在真实浏览器运行时中进行验证:在自动化浏览器中测试渲染后的输出,可立即获得有关现代 CSS 和 HTML 如何与特定打包器和框架环境交互的反馈。

“note 的使命是‘开始创作,持续创作’,因此我们的平台必须保持快速、易用,让每位创作者和读者都能轻松访问。随着越来越多的代码由 AI 编码智能体编写,Modern Web Guidance 可帮助它们采用基于标准的现代解决方案,而不是退回到旧版 JavaScript 模式。它还指出了容易被忽略的细节,例如图片加载优先级和表单无障碍性。结合我们的设计体系,我们可以在不断改进 Note 的同时,保持界面的一致性。

- Takehiko Itabashi,note inc. 技术副总裁