# Frontend UI Engineering

> 构建生产级 UI。适用于构建或修改面向用户的界面，也适用于创建组件、实现布局、管理状态，或输出必须看起来像生产产品而不是 AI 生成原型的时候。

- Skill: `233i/frontend-ui-engineering` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 233i/frontend-ui-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/233i/frontend-ui-engineering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: 233i (https://skillmd.com/u/233i)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/233i/frontend-ui-engineering

---


# 前端 UI 工程

## 概览

构建既可访问、又高性能、而且视觉完成度高的生产级用户界面。目标是让 UI 看起来像出自一家优秀公司的设计感工程师之手，而不是像 AI 随手拼出来的东西。这意味着要真正遵守设计系统、认真处理可访问性、设计合理的交互模式，并彻底避免通用的 “AI 审美”。

## 何时使用

- 构建新的 UI 组件或页面
- 修改现有用户界面
- 实现响应式布局
- 添加交互或状态管理
- 修复视觉或 UX 问题

## 组件架构

### 文件结构

把与组件相关的内容就近放在一起：

```
src/components/
  TaskList/
    TaskList.tsx          # Component implementation
    TaskList.test.tsx     # Tests
    TaskList.stories.tsx  # Storybook stories (if using)
    use-task-list.ts      # Custom hook (if complex state)
    types.ts              # Component-specific types (if needed)
```

### 组件模式

**优先组合，而不是堆配置：**

```tsx
// Good: Composable
<Card>
  <CardHeader>
    <CardTitle>Tasks</CardTitle>
  </CardHeader>
  <CardBody>
    <TaskList tasks={tasks} />
  </CardBody>
</Card>

// Avoid: Over-configured
<Card
  title="Tasks"
  headerVariant="large"
  bodyPadding="md"
  content={<TaskList tasks={tasks} />}
/>
```

**让组件保持聚焦：**

```tsx
// Good: Does one thing
export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
  return (
    <li className="flex items-center gap-3 p-3">
      <Checkbox checked={task.done} onChange={() => onToggle(task.id)} />
      <span className={task.done ? 'line-through text-muted' : ''}>{task.title}</span>
      <Button variant="ghost" size="sm" onClick={() => onDelete(task.id)}>
        <TrashIcon />
      </Button>
    </li>
  );
}
```

**把数据获取和展示分开：**

```tsx
// Container: handles data
export function TaskListContainer() {
  const { tasks, isLoading, error } = useTasks();

  if (isLoading) return <TaskListSkeleton />;
  if (error) return <ErrorState message="Failed to load tasks" retry={refetch} />;
  if (tasks.length === 0) return <EmptyState message="No tasks yet" />;

  return <TaskList tasks={tasks} />;
}

// Presentation: handles rendering
export function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    <ul role="list" className="divide-y">
      {tasks.map(task => <TaskItem key={task.id} task={task} />)}
    </ul>
  );
}
```

## 状态管理

**选择刚好够用的最简单方案：**

```
Local state (useState)           → 组件内部 UI 状态
Lifted state                     → 2-3 个兄弟组件共享的状态
Context                          → 主题、认证、语言环境这类读多写少状态
URL state (searchParams)         → 筛选、分页、可分享的 UI 状态
Server state (React Query, SWR)  → 带缓存的远程数据
Global store (Zustand, Redux)    → 跨应用共享的复杂客户端状态
```

**不要让 prop drilling 深过 3 层。** 如果 props 穿过很多并不消费它们的组件，就该考虑 context 或重新调整组件树。

## 遵守设计系统

### 避免 AI 审美

AI 生成的 UI 往往有很明显的默认套路，要主动避开：

| AI 默认套路 | 为什么有问题 | 生产级替代 |
|---|---|---|
| 全是紫色 / 靛蓝色 | 模型偏爱“安全审美”，结果所有应用都长得一样 | 使用项目真实配色体系 |
| 滥用大面积渐变 | 渐变容易制造噪音，还经常和设计系统冲突 | 使用设计系统定义的纯色或轻微渐变 |
| 所有元素都超圆角 | `rounded-2xl` 到处用，会破坏真实设计里的层级感 | 用设计系统规定的统一圆角体系 |
| 通用 Hero 区块 | 模板化布局与真实内容和用户需求无关 | 以内容优先的布局 |
| 假文案占位 | 假文案会掩盖真实内容长度、换行和溢出问题 | 使用尽可能真实的占位内容 |
| 所有地方都超大留白 | 一样大的充裕 padding 会毁掉视觉层级 | 使用稳定的 spacing scale |
| 通用卡片网格 | 这是布局捷径，不考虑信息优先级和扫描路径 | 根据内容优先级设计布局 |
| 重阴影设计 | 复杂阴影会和内容抢注意力，还影响低端设备渲染 | 除非设计系统明确要求，否则少用或不用 |

### 间距与布局

使用统一的 spacing scale，不要发明新数值：

```css
/* Use the scale: 0.25rem increments (or whatever the project uses) */
/* Good */  padding: 1rem;      /* 16px */
/* Good */  gap: 0.75rem;       /* 12px */
/* Bad */   padding: 13px;      /* Not on any scale */
/* Bad */   margin-top: 2.3rem; /* Not on any scale */
```

### 排版

尊重文字层级：

```
h1 → 页面标题，每页一个
h2 → 区块标题
h3 → 子区块标题
body → 正文
small → 次级 / 辅助文本
```

不要跳 heading 层级，也不要把 heading 样式拿去装非标题内容。

### 颜色

- 使用语义化颜色 token，例如 `text-primary`、`bg-surface`、`border-default`，不要直接写 hex
- 确保对比度足够，正文至少 4.5:1，大字号至少 3:1
- 不要只靠颜色表达信息，还要辅以图标、文本或图案

## 可访问性（WCAG 2.1 AA）

每个组件都必须满足这些要求：

### 键盘导航

```tsx
// Every interactive element must be keyboard accessible
<button onClick={handleClick}>Click me</button>        // ✓ Focusable by default
<div onClick={handleClick}>Click me</div>               // ✗ Not focusable
<div role="button" tabIndex={0} onClick={handleClick}    // ✓ But prefer <button>
     onKeyDown={e => e.key === 'Enter' && handleClick()}>
  Click me
</div>
```

### ARIA 标签

```tsx
// Label interactive elements that lack visible text
<button aria-label="Close dialog"><XIcon /></button>

// Label form inputs
<label htmlFor="email">Email</label>
<input id="email" type="email" />

// Or use aria-label when no visible label exists
<input aria-label="Search tasks" type="search" />
```

### 焦点管理

```tsx
// Move focus when content changes
function Dialog({ isOpen, onClose }: DialogProps) {
  const closeRef = useRef<HTMLButtonElement>(null);

  useEffect(() => {
    if (isOpen) closeRef.current?.focus();
  }, [isOpen]);

  // Trap focus inside dialog when open
  return (
    <dialog open={isOpen}>
      <button ref={closeRef} onClick={onClose}>Close</button>
      {/* dialog content */}
    </dialog>
  );
}
```

### 有意义的空状态和错误状态

```tsx
// Don't show blank screens
function TaskList({ tasks }: { tasks: Task[] }) {
  if (tasks.length === 0) {
    return (
      <div role="status" className="text-center py-12">
        <TasksEmptyIcon className="mx-auto h-12 w-12 text-muted" />
        <h3 className="mt-2 text-sm font-medium">No tasks</h3>
        <p className="mt-1 text-sm text-muted">Get started by creating a new task.</p>
        <Button className="mt-4" onClick={onCreateTask}>Create Task</Button>
      </div>
    );
  }

  return <ul role="list">...</ul>;
}
```

## 响应式设计

先为移动端设计，再往上扩展：

```tsx
// Tailwind: mobile-first responsive
<div className="
  grid grid-cols-1      /* Mobile: single column */
  sm:grid-cols-2        /* Small: 2 columns */
  lg:grid-cols-3        /* Large: 3 columns */
  gap-4
">
```

至少测试这些断点：320px、768px、1024px、1440px。

## Loading 与过渡

```tsx
// Skeleton loading (not spinners for content)
function TaskListSkeleton() {
  return (
    <div className="space-y-3" aria-busy="true" aria-label="Loading tasks">
      {Array.from({ length: 3 }).map((_, i) => (
        <div key={i} className="h-12 bg-muted animate-pulse rounded" />
      ))}
    </div>
  );
}

// Optimistic updates for perceived speed
function useToggleTask() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: toggleTask,
    onMutate: async (taskId) => {
      await queryClient.cancelQueries({ queryKey: ['tasks'] });
      const previous = queryClient.getQueryData(['tasks']);

      queryClient.setQueryData(['tasks'], (old: Task[]) =>
        old.map(t => t.id === taskId ? { ...t, done: !t.done } : t)
      );

      return { previous };
    },
    onError: (_err, _taskId, context) => {
      queryClient.setQueryData(['tasks'], context?.previous);
    },
  });
}
```

## 常见自我安慰

| 自我安慰 | 现实 |
|---|---|
| “可访问性只是加分项” | 在很多地区它是法律要求，同时也是工程质量标准。 |
| “响应式以后再补” | 事后补响应式，难度通常是从一开始就做好它的 3 倍。 |
| “设计还没定，我先不管样式” | 先按设计系统默认值做。完全没样式的 UI 会让 reviewer 第一眼就觉得是坏的。 |
| “这只是原型” | 原型经常会直接流入生产。基础要从一开始就打对。 |
| “先用 AI 默认审美也没关系” | 它会直接传达出低质量信号。应该从一开始就使用项目真正的设计系统。 |

## 危险信号

- 单个组件超过 200 行，应拆分
- 出现大量内联样式或随意像素值
- 缺少 loading、error 或 empty 状态
- 从未做过键盘导航测试
- 只靠颜色表达状态，例如纯红绿没有图标或文字
- 充满通用 AI 风格，例如紫色渐变、超大卡片、库存式布局

## 验证

完成 UI 后，确认：

- [ ] 组件渲染时没有控制台错误
- [ ] 所有交互元素都可键盘访问，可以 Tab 一遍页面验证
- [ ] 屏幕阅读器可以传达页面内容和结构
- [ ] 在 320px、768px、1024px、1440px 下都正常工作
- [ ] Loading、error、empty 状态都已处理
- [ ] 遵守项目设计系统，包括间距、颜色和排版
- [ ] 在 dev tools 或 axe-core 中没有可访问性警告