Communitygithub.com

前端开发

用于构建、审查或修复浏览器用户界面,例如页面、组件、表单、客户端状态、图表、打印或PDF视图、无障碍性或Web性能(核心网页指标、打包体积、缓慢渲染)。不适用于视觉方向、布局批判或品牌(请使用 `designer` 或 `visual-design`)。不适用于原生或React Native应用(请使用 `mobile`)。

前端开发 是什么?

Frontend 技能定义了浏览器UI开发的核心标准,特别关注真实用户在使用键盘、屏幕阅读器、慢速手机和打印机等环境下的体验。它列出了UI“看起来已完成”时经常被忽略的规则,例如使用语义化HTML元素(按钮、链接、表格等)、处理每个异步视图的四种状态(加载、错误、空数据和数据)、不伪造数据、不单独使用颜色传递信息、将可共享状态放在URL中,以及从320 CSS像素宽度开始响应式设计。该技能还涵盖了图表、打印和简化视图的最佳实践,并提供了性能优化指南,重点关注请求瀑布流、JavaScript传输量和服务器响应时间等影响最大的领域,目标是LCP ≤ 2.5s、INP ≤ 200ms、CLS ≤ 0.1。此外,它还包含了许多开发中常见的“陷阱”和详细的验证清单,确保UI在可访问性、键盘导航、打印预览和控制台错误等方面均达到高标准。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/heliacon/claude-skills/tree/HEAD/skills/frontend

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

前端开发 是做什么的?

供真实用户使用键盘、屏幕阅读器、慢速手机和打印机的浏览器UI标准。 以下规则是UI“看起来已完成”时经常被忽略的部分。

最重要的规则

  1. 使用含义正确的元素。 <button> 用于操作,<a href> 用于导航,每个字段都需要 <label>,表格数据使用 <table>。带有点击处理器的 <div> 不可聚焦、没有角色,并且对辅助技术不可见。ARIA 仅用于填补原生元素无法满足的空白。
  2. 每个异步视图有四种状态: 加载、错误、空数据和数据。在认为视图完成之前,请编写所有四种状态。空白区域是一个bug。
  3. 绝不伪造数据。 缺失的数据点是间隙或“无数据”标签,绝不是零,也不是插值线。预测始终与实际情况明显不同。
  4. 绝不单独使用颜色传递信息。 每个颜色编码的状态还必须包含文本或带有可访问名称的图标。否则,灰度打印和色盲读者将无法获取任何信息。
  5. 可共享的状态存在于URL中。 过滤器、标签页、搜索词、选中的ID。返回、刷新和分享必须保留这些状态。临时状态(悬停、打开的提示框)不放入URL。
  6. 由多个状态片段推导出的值应放在一个函数中,在任何状态变化时调用。 绝不要将其计算在属于某个状态的回调函数内部。例如:基于截止日期和组过滤器构建的下载链接,仅在截止日期的获取回调中重建,因此在过滤器更改后,导出功能会静默地指向整个列表。
  7. 从320 CSS像素宽度开始适配。 没有水平页面滚动,没有内容被裁剪,文本可缩放至200%。在手机宽度和你设计的桌面宽度上都进行测试。
  8. 根据需求匹配工具。 在现有仓库中,遵循已有的框架和构建工具。对于小型新页面或内部工具,在添加构建流程之前,先考虑纯HTML、CSS和少量JavaScript;当状态确实需要时再使用框架。

何时不应使用

  • 选择视觉方向、排版或调色板:请使用 designer 和 visual-design 技能。
  • 原生 iOS、Android 或 React Native:请使用 mobile 技能(Swift 代码使用 swift)。
  • API 形状和服务器端点:请使用 api-design 和 backend-patterns 技能。
  • 测试技术深入:请使用 tdd 和 testing-strategy 技能。

状态的存储位置

在编写组件状态之前决定。从局部开始,仅在明确理由下升级。

状态存储位置示例
本地UI组件状态模态框打开、输入草稿、悬停
兄弟组件共享最近的共同父组件两个面板读取的活动标签页
服务器数据服务器缓存库(TanStack Query, SWR)或框架的加载器API响应、分页、重新获取
应用级客户端状态小型存储(仅在需要时)已登录用户、通知队列
可共享视图状态URL查询或路由过滤器、搜索、选中的ID
跨重新加载持久化,按设备localStorage偏好设置、未发送的草稿

仅在以下情况升级:两个无关组件需要相同状态(提升它,或使用服务器缓存);状态必须在重新加载后持久化(URL或存储);数据来自服务器(服务器缓存,而非全局存储)。复制到全局存储的服务器数据会变得过期,并且重复加载和错误逻辑。

图表、打印和简化视图

  • 图表:前后端共享一种颜色映射,明确的空状态,诚实的间隙,HTML图例。在构建或更改图表之前阅读 references/charts.md。
  • 打印或PDF:在构建可打印视图之前阅读 references/print.md。没有其中描述的捕获步骤,Canvas 无法可靠打印。
  • 面向非技术读者的简化或只读视图:无编辑控件,慷慨的文本和目标大小,使用颜色和文字表示状态,基于数据计算的通俗语言摘要,少量屏幕,以及用简短句子呈现的关键数字而非原始表格。

性能

按影响顺序优化:先处理请求瀑布流,然后是传输的JavaScript,接着是服务器响应时间,再是交互期间主线程的工作,最后是微优化。目标:在第75百分位的实际访问中,LCP ≤ 2.5秒,INP ≤ 200毫秒,CLS ≤ 0.1。当页面速度慢时,在添加重量级依赖项之前,或在进行有性能目标的发布之前,请阅读 references/performance.md。

陷阱

  • 渲染路径是热点循环。 组件体或计算的getter在每次悬停和每次无关状态更改时都会运行。那里的重量级推导会阻塞主线程,第一个症状可能是其他地方的测试不稳定。先去重,然后在上游输入上记忆化。
  • 未声明的CSS自定义属性会静默失败。 当 token 是 --font-mono 时,var(--mono) 在计算值时间使声明无效:属性继承,没有错误。在简写属性中(font: 400 10px/1 var(--mono)),字号和行高也会丢失。为 var() 提供回退值,或检查已声明的 token 与已构建样式表中被引用的 token 是否一致。
  • 图表的高度放在其包装器上。 canvas 上的高度会与库的调整大小逻辑冲突,导致图表在每次调整大小时变大。
  • 焦点管理是你自己的责任(在自定义小部件中)。 打开对话框将焦点移入其中;关闭对话框将焦点返回到触发器;Escape 关闭对话框。优先使用原生 <dialog> 元素。使用 innerHTML 重建标记会丢失焦点。
  • 没有替代方案的 outline: none 会移除键盘用户唯一的线索。请改用 :focus-visible 来设置样式。
  • 仅图标的按钮需要名称(aria-label 或视觉上隐藏的文本)。
  • 仅在客户端获取后才存在的内容 在弱设备上很慢,当 JavaScript 失败时显示为空白,对爬虫更不友好。在堆栈允许的情况下,在服务器上渲染有意义的内容。
  • 未设置尺寸的媒体会导致布局偏移。 在图片、视频和嵌入内容上设置 width 和 height(或 aspect-ratio)。永远不要延迟加载首屏上方最大的图片。
  • 手工制作的下拉菜单、标签页和滑块 需要来自 WAI-ARIA 创作实践的完整键盘模型。原生元素几乎总是更便宜。
  • 手工编写的伪造DOM会使测试失效。 如果伪造对象每次查找都返回一个新鲜对象,那么写入它的每个属性(href、disabled、value)都会丢失,并且任何关于它的断言都不会失败。回退该特性并要求测试在信任它之前失败。
  • 使用固定版本的CDN,绝不使用未固定版本。 未固定的脚本会在没有提交的情况下悄然改变。

验证

使用项目已有的工具(测试运行器、linter、类型检查器、无障碍性工具)进行验证,然后再添加新工具。

  • 测试、lint 和类型检查通过。任何新测试在回退该特性后应能观察到失败。
  • 在手机宽度和桌面宽度上渲染并查看了页面。尽可能给审查者提供运行的预览以及截图。
  • 纯键盘:每个控件可到达、可操作且可见焦点;顺序与视觉顺序匹配;无陷阱。
  • 自动化无障碍审核(axe、Lighthouse 或项目工具)没有新的违规。使用工具检查对比度:正文文本 4.5:1,大文本和UI组件边框 3:1(WCAG AA)。
  • 通过强制触发,分别显示加载、错误、空数据和数据状态。
  • 可共享状态在刷新和返回后仍然存在。
  • 加载时和使用过程中,控制台零错误和零警告。
  • 如果更改添加了依赖项或影响了重量级视图,则检查性能预算(包分析器、限速分析)。
  • 如果页面可打印,则检查打印预览。

对于审查,按文件报告发现的违规,指出违反的规则和修复方法,从最严重的开始。

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相关技能