前端 UI 工程

概述

构建具备可访问性、高性能与视觉精致度的生产级用户界面。目标是产出由顶尖公司中具备设计素养的工程师打造的 UI —— 而非由 AI 生成的界面。这意味着需严格遵循设计系统、正确实现无障碍支持、采用深思熟虑的交互模式，并杜绝泛化的“AI 审美”。

适用场景

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

组件架构

文件结构

将组件相关所有内容集中存放：

src/components/
  TaskList/
    TaskList.tsx          # 组件实现
    TaskList.test.tsx     # 测试文件
    TaskList.stories.tsx  # Storybook 示例（如使用）
    use-task-list.ts      # 自定义 Hook（如状态较复杂）
    types.ts              # 组件专属类型定义（如需要）

组件模式

优先采用组合而非配置：

// 推荐：可组合

  
    Tasks
  
  
    
  


// 避免：过度配置
}
/>

保持组件职责单一：

// 推荐：只做一件事
export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
  return (
    

       onToggle(task.id)} />
      {task.title}
       onDelete(task.id)}>
        
      
    
  );
}

分离数据获取与呈现逻辑：

// 容器组件：负责数据获取
export function TaskListContainer() {
  const { tasks, isLoading, error } = useTasks();

  if (isLoading) return ;
  if (error) return ;
  if (tasks.length === 0) return ;

  return ;
}

// 呈现组件：负责渲染
export function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    

      {tasks.map(task => )}
    
  );
}

状态管理

选择最简单且可行的方案：

本地状态（useState）           → 组件专属 UI 状态  
提升的状态（Lifted state）     → 在 2–3 个兄弟组件间共享  
Context                        → 主题、认证、本地化等（读多写少）  
URL 状态（searchParams）       → 过滤器、分页、可分享的 UI 状态  
服务端状态（React Query、SWR） → 带缓存的远程数据  
全局状态（Zustand、Redux）    → 复杂的、全应用共享的客户端状态  

避免 props 下钻超过 3 层。 若需将 props 穿透多个不使用它们的中间组件，请引入 Context 或重构组件树。

设计系统一致性

规避 AI 审美

AI 生成的 UI 具有明显可识别的模式。请全部规避：

间距与布局

使用一致的间距比例。禁止随意发明数值：

/* 使用既定比例：例如 0.25rem 增量（或项目所采用的比例） */
/* 推荐 */  padding: 1rem;      /* 16px */
/* 推荐 */  gap: 0.75rem;       /* 12px */
/* 不推荐 */ padding: 13px;      /* 不属于任何标准比例 */
/* 不推荐 */ margin-top: 2.3rem; /* 不属于任何标准比例 */

排版

尊重层级结构：

h1 → 页面标题（每页一个）  
h2 → 区块标题  
h3 → 子区块标题  
body → 正文默认文字  
small → 次要/辅助文字  

不可跳过标题层级。不可将标题样式用于非标题内容。

颜色

• 使用语义化颜色 Token：text-primary、bg-surface、border-default —— 禁止直接使用十六进制值
• 确保足够对比度（正文文字 ≥ 4.5:1；大号文字 ≥ 3:1）
• 不可仅依赖颜色传达信息（需同步使用图标、文字或图案）

无障碍支持（WCAG 2.1 AA）

每个组件必须满足以下标准：

键盘导航

// 所有可交互元素必须支持键盘访问
Click me        // ✓ 默认可聚焦
Click me
               // ✗ 不可聚焦

     onKeyDown={e => {
       if (e.key === 'Enter') handleClick();
       if (e.key === ' ') e.preventDefault();
     }}
     onKeyUp={e => {
       if (e.key === ' ') handleClick();
     }}>
  Click me

ARIA 标签

// 为缺少可见文本的可交互元素添加标签


// 为表单输入项添加 label
Email


// 或在无可见 label 时使用 aria-label

焦点管理

// 内容变更时主动移动焦点
function Dialog({ isOpen, onClose }: DialogProps) {
  const closeRef = useRef(null);

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

  // 对话框打开时限制焦点范围
  return (
    

      Close
      {/* 对话框内容 */}
    
  );
}

有意义的空状态与错误状态

// 禁止显示空白界面
function TaskList({ tasks }: { tasks: Task[] }) {
  if (tasks.length === 0) {
    return (
      

        
        
No tasks
        
Get started by creating a new task.
        Create Task
      
    );
  }

  return 
...
;
}

响应式设计

采用移动优先策略，再逐步扩展：

// Tailwind：移动优先响应式

需在以下断点进行测试：320px、768px、1024px、1440px。

加载与过渡效果

// 骨架屏加载（非旋转动画用于内容区域）
function TaskListSkeleton() {
  return (
    

      {Array.from({ length: 3 }).map((_, i) => (
        

      ))}
    
  );
}

// 乐观更新以提升感知速度
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);
    },
  });
}

参阅

关于详细的无障碍要求及测试工具，请查阅 references/accessibility-checklist.md。

常见借口

危险信号

• 单个组件超过 200 行（应拆分）
• 内联样式或任意像素值
• 缺失加载态、错误态或空态
• 未进行键盘导航测试
• 仅靠颜色表示状态（如红/绿色而无文字或图标）
• 泛化“AI 风格”（紫色渐变、超大卡片、模板化布局）

验证清单

完成 UI 开发后，请检查：

• 组件渲染无控制台报错
• 所有可交互元素支持键盘访问（Tab 键遍历页面）
• 屏幕阅读器可准确传达页面内容与结构
• 响应式适配：在 320px、768px、1024px、1440px 断点下均正常工作
• 加载态、错误态、空态均已覆盖
• 符合项目设计系统（间距、颜色、排版）
• 开发者工具或 axe-core 中无无障碍警告