frontend-patterns

前端模式

概述

用户界面旨在帮助用户完成任务。每一项 UI 决策都应让用户更轻松地完成任务，或让界面更易于访问。

核心原则： 为用户的成功而设计，而非迎合审美偏好。

此技能仅提供建议。明确的用户指示、CLAUDE.md、仓库规范和已批准的计划优先于此处的所有建议。

参考文件

仅阅读当前 UI 任务所需的参考资料：

• references/ui-state-and-feedback.md：加载、错误、空状态和成功状态的顺序，骨架屏与加载指示器的选择，以及变更反馈
• references/accessibility-and-forms.md：以 WCAG 为导向的检查、键盘与焦点、标签、表单模式和移动端可用性
• references/performance-and-layout.md：响应式检查、动效、溢出、URL 状态、性能守则以及浅色/深色模式检查
• references/design-md-authoring.md：根据截图、现有 UI、用户偏好或选定的灵感风格，创建或更新符合规范的项目本地 DESIGN.md
• 仅当用户要求提供风格参考、类似品牌的设计方向、情绪板或 DESIGN.md 风格示例时，才阅读 references/design-md-inspiration-index.md

重点领域（参考模式）

• React 组件架构（hooks、context、性能）
• 使用 Tailwind/CSS-in-JS 实现的响应式 CSS
• 状态管理（Redux、Zustand、Context API）
• 前端性能（延迟加载、代码拆分、记忆化）
• 无障碍访问（WCAG 合规性、ARIA 标签、键盘导航）

方法（参考模式）

1. 组件优先思维——构建可复用、可组合的 UI 部件
2. 移动端优先的响应式设计——从小屏开始，逐步扩展
3. 性能预算——力争在 3 秒内完成加载
4. 语义化 HTML 和恰当的 ARIA 属性
5. 类型安全——适用时使用 TypeScript

建议性守则

使用此技能补充以下内容：

• 无障碍访问检查
• 响应式/布局验证
• 性能和加载状态检查
• 仅在用户明确提出时提供可选的风格构想

不要使用此技能来覆盖明确的视觉方向、组件契约或已批准的工作流。

组件输出检查清单

每个前端交付物都应包含：

• 完整的 React 组件及其 props 接口
• 样式方案（Tailwind 类或 styled-components）
• 必要时提供状态管理实现
• 基本的单元测试结构
• 组件的无障碍访问检查清单
• 性能考量和优化

优先提供可运行的代码，而非解释。请在注释中加入用法示例。

铁律

NO UI DESIGN BEFORE USER FLOW IS UNDERSTOOD

如果尚未梳理清楚用户想要完成什么，就无法设计 UI。

设计思维（编写代码前）

编写任何 UI 代码前，先确定以下问题的答案：

1. 目的：此界面要解决什么具体问题？
2. 基调：选择一种审美方向，并贯彻到底：
   • 极简、极繁、复古未来主义、有机/自然
   • 奢华/精致、活泼/玩具感、编辑/杂志风、粗野/原始
   • 装饰艺术/几何、柔和/粉彩、工业/实用
3. 约束：框架要求、性能预算、无障碍访问级别
4. 差异化：这个 UI 有哪一处会让人印象深刻？

关键见解： 大胆的极繁主义和精致的极简主义都行之有效。真正的障碍是犹豫不决和千篇一律的默认设计。

编写 DESIGN.md

创建或更新符合规范的项目本地 DESIGN.md 前，请先阅读 references/design-md-authoring.md；尤其是在用户提供截图、现有 UI、视觉偏好，或要求 Agent 保留某种设计方向时。

需要灵感时，请阅读 references/design-md-inspiration-index.md，以选择一种风格类型。应将灵感视为项目自身设计规范的输入，而非照搬其他公司的 UI 的指令。

Mock 忠实度清单（不可悄无声息地遗漏）

构建可能通过所有测试，却悄悄漏掉主视觉、标志性元素，或设计要求的整个版块。将 VBC 的反占位实现原则——“不可悄无声息地遗漏”——应用到 UI：测试套件全部通过，并不能证明设计已经交付。

设计稿／模拟稿获批后、开始编码前，盘点其主要可见元素，并为每个元素确定实现路径：

元素	示例	实现路径
主视觉／视觉焦点	标题 + 主要 CTA、标志性视觉元素	立即实现／第二阶段（明确说明）／删减（已获批准）
标志性元素	颗粒质感、渐变、自定义光标、插画风格	立即实现／近似实现／删减（已获批准）
版块	模拟稿中的每个独立条带／区域	立即实现／第二阶段（明确说明）／删减（已获批准）
交互	悬停、滚动、动效、过渡效果	立即实现／静态回退方案／删减（已获批准）
状态	模拟稿中展示的空、加载、错误状态变体	立即实现（状态不可省略）

每个元素必须且只能对应一条路径。“删减”和“第二阶段”都是合理选项，但必须明确写出，绝不能因遗漏而默认如此。

验证——结合 VBC 的目标倒推法。 目标是获批的设计，而不是差异。沿着每个已盘点的元素反向核查，确认它已实现（或已明确延期／删减）。将任何悄悄被删掉的主要元素——在获批的模拟稿中存在，在构建结果中缺失，且从未明确延期——视为 P0 忠实度缺陷，严重程度与任务流程中断相同。请报告此问题；不要让通过的测试套件掩盖它。

UI 状态参考

在最终确定加载、错误、空、成功或变更状态前，请阅读 references/ui-state-and-feedback.md。明确保持状态顺序；不要临时自行创建 UI 状态。

动效与动画

规则	应该做	不应该做
减少动态效果	遵循 prefers-reduced-motion	忽略用户偏好
属性	仅对 transform/opacity 添加动画	对 width/height/top/left 添加动画
过渡效果	明确列出属性	使用 transition: all
时长	微交互持续 150-300ms	过快（<100ms）或过慢（>500ms）
可中断	允许取消动画	动画期间锁定 UI

/* CORRECT: Compositor-friendly, respects preferences */
@media (prefers-reduced-motion: no-preference) {
  .card { transition: transform 200ms ease-out, opacity 200ms ease-out; }
  .card:hover { transform: translateY(-2px); opacity: 0.95; }
}

无障碍与表单

当任务涉及键盘导航、表单、标签、焦点、对比度或触控操作时，请阅读 references/accessibility-and-forms.md。

成功标准框架

每个 UI 都必须有明确的成功标准：

1. 完成任务：用户能否完成目标？
2. 错误恢复：用户能否从错误中恢复？
3. 无障碍：所有用户都能使用吗？
4. 性能：响应速度是否令人满意？

布局与性能参考

请阅读 references/performance-and-layout.md，了解响应式检查、动效规则、溢出处理、URL 状态、触控／移动端和色彩模式验证。

通用问题（先回答）

设计／评审前务必先回答：

1. 用户想要完成什么？——具体任务，而非功能
2. 步骤有哪些？——逐次点击说明
3. 可能出什么问题？——所有错误状态
4. 哪些人可能遇到困难？——无障碍需求
5. 现有模式是什么？——项目约定

先梳理用户流程

开始任何 UI 工作前，先梳理流程：

User Flow: Create Account
1. User lands on signup page
2. User enters email
3. User enters password
4. User confirms password
5. System validates inputs (inline)
6. User clicks submit
7. System processes (loading state)
8. Success: User sees confirmation + redirect
9. Error: User sees error + can retry

针对每个步骤，明确：

• 用户看到什么
• 用户要做什么
• 用户会收到什么反馈
• 可能出什么问题

UX 评审清单

检查项	标准	问题示例
任务完成	用户能否达成目标？	按钮无法使用
可发现性	用户能否找到所需内容？	导航被隐藏
反馈	用户是否知道正在发生什么？	没有加载状态
错误处理	用户能否从错误中恢复？	没有错误消息
效率	用户能否快速完成任务？	步骤太多

严重级别：

• BLOCKS：用户无法完成任务
• IMPAIRS：用户能够完成任务，但有困难
• MINOR：轻微阻碍，不影响任务完成

视觉设计清单

检查项	好	差
层级	视觉优先级清晰	所有元素大小相同
间距	节奏一致	间距随意
对齐	元素与网格对齐	元素未对齐
交互状态	悬停／激活／焦点状态有明显区别	状态没有变化
反馈	对操作有明确响应	交互没有反馈

视觉创意（避免 AI 垃圾设计）

创建前端时，请避免泛泛的 AI 审美：

• 字体：选择有辨识度的字体，而非默认字体（避免 Inter、Roboto、Arial、系统字体）
• 颜色：采用协调统一的配色。鲜明的主色搭配醒目的强调色，胜过稳妥的渐变
• 避免：白底紫色渐变、可预见的布局、千篇一律的 Bootstrap/Tailwind 默认样式
• 图标：使用 SVG 图标（Heroicons、Lucide、Simple Icons）。绝不要使用表情符号作为 UI 图标
• 光标：为所有可点击元素添加 cursor-pointer
• 悬停：使用颜色／不透明度过渡效果。避免使用会导致布局偏移的 scale 变换
• 背景：通过微妙的纹理、渐变或颗粒效果增加层次感，而非使用纯色

做出贴合特定场景的创意选择。每个设计都应各不相同。

双层次本能检查

泛泛而谈不只是明显的默认选项，也包括那些可以预料到的刻意避开默认选项。确定视觉方向前，请进行以下两项测试：

• 一阶测试：仅凭类别就能猜出主题／配色吗？（“金融科技 → 蓝色 + 无衬线字体。”“AI 工具 → 紫色渐变 + 深色模式。”）如果能，那就很泛泛。拒绝。
• 二阶测试：凭类别 + 反向参考就能猜出来吗？当所有人都“避开紫色渐变”后，这种回避本身就成了本能反应——避开蓝色的金融科技产品会落到同一种近黑色 + 酸橙绿配色上，避开紫色的 AI 工具也会落到同一种暖米色 + 衬线字体上。如果结合人们如今趋之若鹜的方向，就能预料到这种选择，那它仍然很泛泛。拒绝。

第二项测试可以捕捉到从第 1 种本能反应直接跳到第 2 种的情况。解决两者的方法相同：根据具体产品、受众和内容来确定方向，而不是根据类别或该类别当前正在回避什么。

本能反应排除清单（持续维护，并在某类风格趋于饱和时精简）：

本能反应排除字体	本能反应排除美学路线
Inter、Roboto、Arial、system-ui 默认字体	白底紫／紫罗兰色渐变（AI 工具本能反应 #1）
Geist／Geist Mono（现已过度饱和）	近黑色 + 酸橙绿“反企业风”（本能反应 #2）
作为默认“现代”选择的 Space Grotesk	暖米色 + 衬线字体“反 AI”编辑风格（本能反应 #2）
当月热门的通用 Google Fonts 字体组合	渐变网格背景上的玻璃拟态卡片

当某条路线确实不再是本能反应时，就将其从清单中移除；随着新风格趋于饱和，再将其加入。这份清单有意保持动态；过时的屏蔽清单本身也会成为一种本能反应。

空间构图（打破网格）

跳出安全、居中的布局：

技巧	效果	适用场景
不对称	动态张力、视觉趣味	主视觉区、功能亮点
重叠	层次感、元素间的联系	卡片、图片、用户评价
对角线动线	活力、动感	着陆页、营销页面
打破网格	突出重点、带来惊喜	关键 CTA、视觉焦点
充足的负空间	奢华感、呼吸感	高端产品、编辑式设计
受控的密度	信息丰富、高效	仪表板、数据密集型界面

规则： 空间构图应与 Design Thinking 中选定的美学方向相匹配。极简主义 = 负空间。极繁主义 = 受控的密度。

设计系统偏差分类器

当某项功能偏离设计系统时，“看起来有点不对劲”并不是可执行的发现。对于每一处偏差，对其根本原因进行分类 —— 类别决定修复方式：

根本原因	含义	修复方式
缺少令牌	系统没有满足此需求的值（某种色调、间距级别、圆角）	补全该值 —— 将令牌添加到系统中，然后使用它
单次实现	令牌/组件已存在，但此功能在本地重新实现了它	改用共享组件/令牌；删除单次实现
概念不一致	此功能的交互模型与系统相悖	重新设计流程 —— 调整像素无法解决问题

流程形态匹配。 除了令牌，功能的流程形态也必须与相邻功能匹配。即使每个像素都符合系统规范，流程形态不一致也会显得像是坏掉了：

• 模态框与整页 —— 如果同类编辑器会打开模态框，就不要改为发布整页路由（反之亦然）。
• 失焦时保存与显式提交 —— 如果相邻表单会自动保存，单独出现一个带提交按钮的表单就属于概念不一致，而不是轻微的样式问题。

要求此功能的流程形态与相邻功能匹配，或提供明确且经过批准的偏离理由。将无法解释的流程形态不匹配视为概念不一致偏差，而非小问题。

组件模式

按钮

// Primary action button with all states
<button
  type="button"
  onClick={handleAction}
  disabled={isLoading || isDisabled}
  aria-busy={isLoading}
  aria-disabled={isDisabled}
  className={cn(
    'btn-primary',
    isLoading && 'btn-loading'
  )}
>
  {isLoading ? (
    <>
      <Spinner aria-hidden />
      <span>Processing...</span>
    </>
  ) : (
    'Submit'
  )}
</button>

带验证的表单

<form onSubmit={handleSubmit} noValidate>
  <div className="form-field">
    <label htmlFor="email">
      Email <span aria-hidden>*</span>
      <span className="sr-only">(required)</span>
    </label>
    <input
      id="email"
      type="email"
      value={email}
      onChange={handleChange}
      aria-invalid={errors.email ? 'true' : undefined}
      aria-describedby={errors.email ? 'email-error' : 'email-hint'}
      required
    />
    <span id="email-hint" className="hint">
      We'll never share your email
    </span>
    {errors.email && (
      <span id="email-error" role="alert" className="error">
        {errors.email}
      </span>
    )}
  </div>
</form>

加载状态

function DataList({ isLoading, data, error }) {
  if (isLoading) {
    return (
      <div aria-live="polite" aria-busy="true">
        <Spinner />
        <span>Loading items...</span>
      </div>
    );
  }

  if (error) {
    return (
      <div role="alert" className="error-state">
        <p>Failed to load items: {error.message}</p>
        <button onClick={retry}>Try again</button>
      </div>
    );
  }

  if (!data?.length) {
    return (
      <div className="empty-state">
        <p>No items found</p>
        <button onClick={createNew}>Create your first item</button>
      </div>
    );
  }

  return <ul>{data.map(item => <Item key={item.id} {...item} />)}</ul>;
}

错误消息

// Inline error with recovery action
<div role="alert" className="error-banner">
  <Icon name="error" aria-hidden />
  <div>
    <p className="error-title">Upload failed</p>
    <p className="error-detail">File too large. Maximum size is 10MB.</p>
  </div>
  <button onClick={selectFile}>Choose different file</button>
</div>

危险信号——停止并重新考虑

如果你发现自己正在：

• 绘制用户流程之前就设计 UI
• 在关注功能之前就关注美观
• 忽视无障碍设计（“以后再加”）
• 未处理错误状态
• 未提供加载反馈
• 仅用颜色传达信息
• 根据“看起来不错”来做决定

停止。回到用户流程。

防止自我辩解

借口	事实
“大多数用户不用键盘”	有些用户只用键盘。
“以后再加无障碍设计”	事后改造会难 10 倍。
“错误状态只是边缘情况”	错误总会发生。要妥善处理。
“加载很快，不需要状态”	网络状况各不相同。要显示状态。
“不加标签看起来更好”	没有标签的输入项不具备无障碍性。
“用户自己能弄明白”	如果让人困惑，就修复它。

反模式封禁列表（标记这些项）

反模式	错误原因	修复方法
user-scalable=no	阻止无障碍缩放	删除它
maximum-scale=1	阻止无障碍缩放	删除它
transition: all	影响性能并产生意外效果	明确列出属性
outline-none 未提供替代方案	移除了焦点指示器	添加 focus-visible:ring-*
<div onClick>	不支持键盘访问	使用 <button> 或 <a>
图片未设置 width/height	会导致布局偏移（CLS）	明确设置尺寸
表单输入框没有标签	无法无障碍访问	添加 <label> 或 aria-label
图标按钮没有 aria-label	屏幕阅读器无法识别其名称	添加 aria-label
Emoji 图标（🚀 ✨ 💫）	不够专业，且不一致	使用 SVG 图标
硬编码的日期/数字格式	破坏国际化	使用 Intl.DateTimeFormat
到处使用 autoFocus	会造成困扰，也会引发移动端问题	谨慎使用，仅限桌面端

输出格式

## Frontend Review: [Component/Feature]

### User Flow
[Step-by-step what user is trying to do]

### Success Criteria
- [ ] User can complete [task]
- [ ] User can recover from errors
- [ ] All users can access (keyboard, screen reader)
- [ ] Interface feels responsive

### UX Issues
| Severity | Issue | Location | Impact | Fix |
|----------|-------|----------|--------|-----|
| BLOCKS | [Issue] | `file:line` | [Impact] | [Fix] |

### Accessibility Issues
| WCAG | Issue | Location | Fix |
|------|-------|----------|-----|
| 1.4.3 | [Issue] | `file:line` | [Fix] |

### Visual Issues
| Issue | Location | Fix |
|-------|----------|-----|
| [Issue] | `file:line` | [Fix] |

### Recommendations
1. [Most critical fix]
2. [Second fix]

UI 状态检查清单（至关重要）

完成任何 UI 组件之前：

状态

• 处理错误状态并向用户显示
• 仅在没有数据时显示加载状态
• 为所有集合/列表提供空状态
• 提供成功状态及适当反馈
• 对非简单的状态顺序或骨架屏/加载指示器选择，参照 references/ui-state-and-feedback.md 进行检查

按钮和变更操作

• 异步操作期间禁用按钮
• 按钮显示加载指示器
• 变更操作有 onError 处理程序并向用户提供反馈
• 提交按钮不可能被双击

数据处理

• 状态顺序：错误 → 加载（无数据）→ 空 → 成功
• 所有用户操作都有反馈（toast/视觉反馈）

最终检查

完成前端工作之前：

• 已梳理并理解用户流程
• 已处理所有状态（加载、错误、空、成功）
• 键盘导航正常工作
• 已测试屏幕阅读器
• 已验证颜色对比度（最低 4.5:1）
• 移动端触控目标尺寸合适（44px+）
• 错误消息清晰且可操作
• 已满足成功标准
• 没有 Emoji 图标（仅使用 SVG）
• 遵循 prefers-reduced-motion 设置
• 已验证浅色/深色模式下的对比度
• 所有可点击元素都带有 cursor-pointer
• 代码库中没有 transition: all