frontend-excellence

前端卓越实践

一项全面的综合技能，助你打造令人难忘的 Web 界面：性能跻身 Lighthouse 前列，并能在各种设备和辅助技术上优雅降级。设计上与框架无关：每条规则都以原则加具体检查项的形式呈现，绝不依赖库的 API。

适用场景

只要工作会改变界面的外观、观感、动效、加载速度、排名或交互方式，就应用这项技能。例如：

• 构建或重构任何页面、表单、模态框、导航、表格、图表或组件
• 选择字体、颜色、间距、动效或视觉风格
• 审计或改善 Core Web Vitals（LCP、INP、CLS）、包体积或 hydration 开销
• 审计或改善无障碍体验（对比度、键盘操作、屏幕阅读器、焦点、动态字体）
• 审计或改善页面 SEO（标题、描述、标题层级、结构化数据、规范链接）
• 审查视觉精致度、层级、对比度、密度、深色／浅色模式的一致性
• 用鲜明独特的美学方向取代千篇一律、带有 AI 风格的设计
• 参照设计稿或生产环境基准，审计或润色现有的多页面网站

后端逻辑、基础设施、数据管道或非视觉脚本无需使用这项技能。

加载策略（读取参考资料前请先阅读）

references/ 下的每个文件平均有 400 到 600 行。一次加载超过三个文件，会消耗上下文来处理不需要的内容。请根据当前任务，阅读下方的路由表（依次为“按任务”“按症状”和“参考索引”），选出 2 到 3 个匹配的文件。如果无法根据表格确定，就先通过 head -20 查看候选文件顶部的 YAML frontmatter（每个文件约 15 行），再加载其余内容。如果当前任务已不再符合某份参考资料的用途，就将其移除。

北极星目标

每个界面在被视为“完成”前都应达到以下标准。任何未达标项都应视为阻塞性缺陷，而非待润色事项。

类别	移动端目标	桌面端目标	来源
Lighthouse 性能	>= 95	>= 99	Lighthouse
Lighthouse 无障碍	100	100	Lighthouse + axe
Lighthouse 最佳实践	100	100	Lighthouse
Lighthouse SEO	100	100	Lighthouse
最大内容绘制（LCP）	< 2.5s	< 2.0s	Core Web Vitals
下一次绘制交互（INP）	< 200ms	< 200ms	Core Web Vitals
累积布局偏移（CLS）	< 0.1	< 0.05	Core Web Vitals
首字节时间（TTFB）	< 800ms	< 600ms	Core Web Vitals
首次内容绘制（FCP）	< 1.8s	< 1.0s	Lighthouse
总阻塞时间（TBT）	< 200ms	< 100ms	Lighthouse
初始 JS 载荷（gzip 压缩后）	< 90 KB	< 130 KB	预算
初始 CSS 载荷（gzip 压缩后）	< 25 KB	< 35 KB	预算
Web 字体载荷（每个屏幕）	<= 2 种字体，<= 4 种字重	同左	预算

这些是通用标准。对于特定界面，项目可以有意放宽预算（例如，高度交互、客户端渲染的工具确实需要打包更多 JS），但放宽应作为有记录且有理由的例外，而不是默认做法。

优先级排序（评审时从上到下阅读）

1. 可抓取性和可索引性（页面是否存在于索引中，canonical 和 meta 是否正确？）
2. 无障碍正确性（语义化 HTML、对比度、键盘操作、焦点、屏幕阅读器）
3. 核心 Web 指标（LCP、INP、CLS、TTFB）
4. 布局和响应式完整性（没有水平滚动、没有内容裁切、尊重安全区域）
5. 视觉层级和有意为之的美感（排版、颜色、间距、动效、信息密度）
6. 交互质量（悬停、按下、焦点、加载、错误、空状态、成功状态）
7. 表单和反馈（验证、错误位置、恢复、自动填充、自动保存）
8. 动效和动画（目的明确、兼顾减少动态效果设置、仅使用 transform）
9. 数据和图表（清晰易读、无障碍、响应式）
10. 打磨和匠心（图标规范、深色／浅色模式一致性、品牌一致性）

高优先级项始终会阻断低优先级项。绝不能为了美感牺牲对比度，也不能为了动画牺牲 INP。

规则冲突时（决胜规则）

优先级排序涵盖常见情况。当两条具体规则相互冲突时，请使用下表：

冲突	决胜规则
动画打磨与 INP 预算	INP 优先。如果动画导致 INP 超过 200ms，这属于缺陷，而不是打磨项。
美学偏好与 WCAG 对比度	对比度优先。不能为了视觉品味而放宽大号文本 3:1 或正文 4.5:1 的最低标准。
LCP 预加载与初始 JS 预算	JS 预算优先。应寻找更小的 LCP 元素，或延迟预加载；不要超出预算。
SEO 的 SSR 与水合成本下的 INP	拆分处理：对外壳进行 SSR 以确保可索引性，将交互岛延后加载，使 INP 保持在 200ms 以下。
动效打磨与 prefers-reduced-motion	减少动态效果优先。动效是增强效果，而不是默认基准。
品牌色与深色模式文本对比度	在深色表面上的文本使用更亮的强调色；品牌色保留用于背景。参见 design.md。

决策：渲染策略

页面采用五种渲染策略之一。根据以下条件选择；详细说明见 performance.md 和 seo.md。

如果……	选择
需要被索引、内容大多静态、个性化程度低、能够应对流量高峰	SSG（静态站点生成）
需要被索引、按请求个性化、数据动态、服务器有计算预算	SSR（服务器端渲染），可选择流式传输
无需被索引、交互性强、采用应用外壳体验、对 INP 敏感	CSR（客户端渲染），并按路由拆分代码
需要被索引、部分个性化、希望对外壳使用 SSG 并进行重新验证	ISR（增量静态再生）
大多为静态内容，只有少数交互式组件，希望尽量减少 JS	静态页面加交互岛（部分水合／可恢复性）

经验法则：先考虑可索引性（对需要被索引的页面使用 SSG／SSR／ISR）；再考虑交互成本（如果 SSR 页面超出 JS 预算，就拆分成交互岛）；只有在无需被索引且产品本身就是应用外壳时，才退回使用 CSR。

路由：按任务

选择与你接到的任务相符的行。先加载指定文件；只有当这些文件指向其他文件时，才继续加载。

你需要……	加载这些文件
从头开始构建新页面	components.md、design.md、responsive.md、performance.md
根据参考内容审查现有网站	audit-workflow.md、defects.md、design.md
修复未通过的 Lighthouse 审查	lighthouse.md、performance.md、debug-recipes.md
提升现有页面的视觉效果	design.md、ui-ux.md、defects.md
添加表单或登录流程	forms.md、auth.md、accessibility.md
设置 CI 门禁和合并前检查	testing.md、lighthouse.md、observability.md
诊断生产环境问题	observability.md、debug-recipes.md、defects.md
在发布前确认页面已完成	pre-launch.md、quick-reference.md
对界面进行国际化或本地化	i18n.md、responsive.md、accessibility.md
加固安全性（CSP、标头、Trusted Types、SRI）	security.md、lighthouse.md、pre-launch.md
添加 PWA、离线功能或可安装性	pwa-offline.md、performance.md
嵌入第三方小组件或允许页面被嵌入	embed-patterns.md、security.md、auth.md
创建打印样式表或事务性电子邮件 HTML	print-email.md
添加图表、表格或数据展示	data-viz.md、ui-ux.md、accessibility.md
添加或优化动效和动画	motion.md、performance.md
对照已知反模式审查变更	anti-patterns.md、defects.md

路由：按症状

根据可观察到的问题信号，直接跳转到相关文件和章节。

症状	可能的根因、需要加载的文件和章节
LCP > 2.5s，LCP 回退	preload / fetchpriority / hydration 开销：performance.md: 核心网页指标
INP > 200ms，交互缓慢	长任务 / 处理程序 / hydration：performance.md: 核心网页指标，debug-recipes.md: INP 回退
CLS > 0.1，布局跳动	未为异步元素预留空间：performance.md: 核心网页指标，defects.md: 缺陷查询表
字体切换导致 CLS	后备字体缺少 size-adjust / metrics-override：debug-recipes.md: 字体切换导致 CLS，performance.md: 字体策略
Lighthouse SEO < 100	受评页面设置了 noindex、缺少 canonical：lighthouse.md: 审核失败到修复项映射，seo.md: 可索引性
Lighthouse Best Practices < 100	CSP 违规、控制台错误、弃用项：lighthouse.md: 审核失败到修复项映射，security.md: 深入了解 CSP
errors-in-console、SRI 信标过期	第三方信标 CORS / 固定哈希过期，或客户端拦截器误报：debug-recipes.md: Lighthouse 偶发问题分诊
开发环境假性失败（仅开发服务器上的分数较低）	评估的是开发服务器，而非生产构建：lighthouse.md: 正确运行 Lighthouse
图片在视网膜屏幕上太小（image-size-responsive）	最大的 srcset 候选图片小于 CSS 宽度乘以 DPR：responsive.md: 响应式图片，lighthouse.md: 审核失败到修复项映射
对比度不达标，尤其是在构建变更之后	比率过低，或 CSS 交付变更导致层叠顺序改变：accessibility.md: 颜色与对比度，lighthouse.md: 审核失败到修复项映射
id 重复	重复使用的组件带有硬编码 id：components.md: 漂移检测
滚动锁定导致侧向偏移	模态框缺少滚动条宽度补偿：ui-ux.md: 模态框与叠加层，defects.md: 缺陷查询表
hydration 不匹配	服务端与客户端不一致：debug-recipes.md: Hydration 不匹配，performance.md: JavaScript 策略
视口溢出、出现水平滚动	子元素溢出：responsive.md: 禁止水平滚动，defects.md: 缺陷查询表
焦点陷阱泄漏、焦点不可见	叠加层焦点管理：debug-recipes.md: 焦点陷阱泄漏，accessibility.md: 键盘
第三方脚本缓慢、分析脚本阻塞	第三方脚本规范 / async-defer 矩阵：performance.md: 第三方策略，build-hygiene.md: 依赖成本规范
仅在 Firefox / Safari 上出错	对功能支持的假设有误、缺少回退方案：responsive.md: 媒体偏好，motion.md: 减少动态效果
同意横幅导致 CLS、边界框跳动	未为叠加层预留空间：ui-ux.md: 模态框与叠加层，seo.md: 可索引性
aria-hidden 的背景仍被读出、inert 泄漏	叠加层应用到了错误的祖先元素：accessibility.md: 模态框与对话框，ui-ux.md: 模态框与叠加层
主视觉动画导致 LCP 或 TBT 回退	首屏以上的动态效果未受预算限制：motion.md: 主视觉动画

参考索引

详细指南位于 references/ 中。每行都说明文件的用途，并列出适用于检索该文件的关键词。

文件	使用场景（关键词）
lighthouse.md	Lighthouse、审计、评分、CI 门槛、csp-xss、duplicate-id、is-crawlable、评分差异、用户流程
performance.md	LCP、INP、CLS、TTFB、性能、水合、包、BFCache、Speculation Rules、Early Hints、fetchpriority、渲染策略、SSR、SSG、CSR、第三方脚本、列表虚拟化
accessibility.md	a11y、WCAG、ARIA、屏幕阅读器、键盘、焦点、对比度、强制颜色、减少动态效果、动态字体大小
seo.md	SEO、canonical、站点地图、robots、结构化数据、JSON-LD、AEO、GEO、llms.txt、hreflang、Open Graph
ui-ux.md	UI、UX、模态框、弹出层、对话框、抽屉、菜单、工具提示、面包屑、触控目标、点击目标、弹出层 API、inert
design.md	设计、字体排印、颜色、OKLCH、P3、深色模式、品牌、可变字体、@layer
responsive.md	响应式、断点、容器查询、视口、安全区域、dvh、srcset、subgrid、scrollbar-gutter
motion.md	动态效果、动画、过渡、缓动、View Transitions、滚动驱动、WAAPI、@starting-style
forms.md	表单、验证、输入、自动填充、自动完成、constraintValidation
data-viz.md	图表、数据可视化、坐标轴、图例、Canvas、SVG、WebGL、时区
pre-launch.md	发布前、清单、交付、门槛、验证、证据
audit-workflow.md	审计、路由、全面检查、基线、捕获、润色、多页面
components.md	组件、契约、提取、插槽、组合、令牌、Storybook
defects.md	缺陷、几何、全面检查、阈值、回归、查找
security.md	CSP、COOP、COEP、CORP、跨源隔离、Trusted Types、SRI、Permissions-Policy、Referrer-Policy、供应链
observability.md	RUM、可观测性、监控、源映射、错误捕获、INP 归因、Reporting API、CrUX、LoAF
testing.md	测试、视觉回归、axe-core、pa11y、size-limit、bundlesize、lighthouse-ci、契约测试
auth.md	身份验证、登录、通行密钥、WebAuthn、OAuth、魔法链接、会话、账户恢复、CAPTCHA、Storage Access API
debug-recipes.md	调试、配方、水合不匹配、布局溢出、焦点陷阱、字体切换导致的 CLS、Lighthouse 波动
anti-patterns.md	反模式、应避免的做法、错误
i18n.md	i18n、l10n、区域设置、翻译、Intl、复数规则、双向文本、RTL、镜像、hreflang
pwa-offline.md	PWA、离线、服务工作线程、安装提示、推送、后台同步、清单
build-hygiene.md	构建、tree-shaking、sideEffects、锁文件、死代码、代码拆分、依赖成本
embed-patterns.md	嵌入、iframe、sandbox、postMessage、宿主、访客、第三方小组件
print-email.md	打印、电子邮件、@page、分页、事务性电子邮件、Outlook
quick-reference.md	规则、快速参考、最高效益

工作流

1. 明确工作目标

编写代码前，记录以下内容：受众和意图；是否可被索引（可被搜索引擎索引的页面，还是需要身份验证才能访问）；美学方向（选定一种鲜明风格；拒绝“白底搭配 Inter 和紫色渐变”）；约束条件（采用上表中的哪种渲染策略、水合模型、最低浏览器支持版本、地区设置、书写方向）。

在每个阶段，渲染后的浏览器页面都是事实依据。不要只根据代码判断视觉质量；应截取屏幕截图，与参考进行比较，修复问题，然后重新截取。当工作内容是审查或打磨现有的多页面网站，而不是构建新网站时，改用下文的“多页面打磨循环”。

2. 规划结构

每页只设置一个 H1；标题层级依次递进。在首屏中呈现 LCP 元素（使用真实且已提供的资源，并声明其尺寸，不延迟加载，也不依赖水合）。为每个异步元素预留空间（aspect-ratio、固定高度、骨架屏）。确定哪些部分由服务器渲染、哪些采用流式传输、哪些延迟加载、哪些仅由客户端渲染；并说明每项仅由客户端渲染选择的理由。

3. 按预算构建

为每个页面区域声明并验证以下预算：JS 负载（初始路由，gzip 压缩后）；CSS 负载（初始路由，gzip 压缩后）；图像负载（首屏范围内）；字体预算（字体系列、字重、子集、总字节数）；第三方脚本预算（数量、主线程占用总时长）。若新增内容会超出预算，应予以拒绝，除非有明确记录的豁免。

4. 验证

宣布工作完成前，应完整通过 Lighthouse + axe + 视觉 + 响应式 + 深色模式 + 减少动态效果 + 键盘 + 屏幕阅读器检查。请参阅 pre-launch.md。

多页面打磨循环

如果工作内容是审查或打磨现有的多页面网站，请先阅读 audit-workflow.md，了解完整流程（操作规则、截图脚本、各阶段详情、最终验收关卡）。19 个阶段的索引：

1. 了解背景。 2. 清点路由。 3. 清点重复使用的小组件。 4. 截取基线。 5. 截取参考。 6. 审查每条路由。 7. 为修复排定优先级。 8. 遵循组件规范进行修复。 9. 遵循设计规范进行修复。 10. 每组修复后进行验证。 11. 以编程方式检查几何尺寸（并全面检查内容和标记）。 12. 检查组件差异。 13. 交互质量检查。 14. 无障碍验证。 15. Lighthouse 和性能打磨。 16. 参考级设计启发式检查。 17. 常见缺陷及修复方法。 18. 交付物。 19. 最终验收关卡。

组件提取规范见 components.md；缺陷查找和几何尺寸检查见 defects.md。

快速参考

涵盖性能、无障碍、SEO、UI/UX、设计和多页面一致性的高影响力规则汇总在 references/quick-reference.md 中。需要一个精简的总览来对照变更时，请打开该文件。

技能时效性

此技能记录的是某个时间点的 Web 平台行为。应用旧规则前，如遇到以下情况，请先确认该规则仍然适用：

• 规则引用了 Lighthouse 审计 ID、权重或类别阈值（Lighthouse 每隔几个版本就会重新调整类别权重）。
• 规则引用了浏览器支持的最低版本（Baseline 状态会变化；请查看 caniuse.com 或 MDN Baseline 小组件）。
• 规则引用了特定的 Core Web Vitals 阈值或指标名称（INP 于 2024 年取代了 FID；相关阈值也会定期调整）。
• 规则提到了 CSS 或 JS API（[@layer, View Transitions, Anchor Positioning, Popover, :has()] 在 2023 至 2026 年间的支持情况均有变化）。

关于新增内容和改进的日期记录，请参阅 CHANGELOG.md。

自我改进

应用此技能后，在宣布工作完成之前：

• 是否在真实生产构建（而非开发模式）上，使用限流的移动端和桌面端预设运行了 Lighthouse？
• 是否在每个已更改页面上运行了 axe（或同等工具），且违规数为零？
• 页面是否能在 320px、375px、768px、1024px、1280px 和 1920px 下正确渲染？
• 页面是否能分别在浅色和深色模式下正确渲染（而非通过 CSS 反转其中一种模式）？
• 页面是否能在 prefers-reduced-motion: reduce 下正确渲染？
• 页面是否能仅用键盘完成端到端操作？
• 页面是否通过了针对主要任务的屏幕阅读器测试（VoiceOver 或 NVDA）？
• LCP 元素是否使用了 fetchpriority="high"、声明了尺寸，并引用了实际提供的资源？
• 所有自定义字体是否都设置了 font-display，且字体系列数 <= 2、字重数 <= 4？
• 所有异步部分是否都预留了空间？
• 所有交互元素是否都有可见焦点样式，并符合对比度要求？
• 页面是否提供了唯一的标题、描述、canonical、OG、Twitter，以及（如适用）JSON-LD？
• 是否验证了已交付构建的输出（复制后的标头、静态文件、生成的图片），而不只是源配置？

对于多页面审计和润色工作，还需确认：

• 是否为每个共享组件系列（页眉、主视觉、内容区段、CTA、卡片、媒体、列表、交互元素、空状态、法律信息、404）建立了组件清单？
• 是否在任何修改之前，于 1440x900 和 375x812 下捕获了基线截图？
• 是否为每个已更改路由，在 1440x900 和 375x812 下捕获了修改后的截图？
• 几何检查是否在两种视口下的每个已审计路由上都没有发现问题？
• 是否在每个路由上都运行了两项程序化检查（几何检查以及内容与标记检查）？
• 漂移收集器是否未对任何共享组件系列报告无法解释的差异？
• 是否随变更提交了逐路由审计表（发现的问题、应用的修复、修改前、修改后）？

如果有任何一项答案是“否”或“未检查”，则工作尚未完成。