---
title: 前端 UI 细则
description: 供 frontend-main 技能引用的 UI 设计与实现细则，涵盖目录结构、组件分类、Props 规范、视觉与组件示例、检查清单与禁止事项。
---

# 目录与分类
- 路由组：`frontend/src/app/(auth|core|engines|modules|workspace)`  
- 组件：`components/ui`（基础） / `components/common`（通用业务） / `components/layout`（布局） / 业务聚合组件置于 `components/`  
- 服务：`frontend/src/services/`；i18n：`frontend/src/locales/`

# 组件分类与示例
- UI 组件（ui/）：按钮、输入、对话框等（无业务耦合）  
- 通用业务组件（common/）：`BatchImportDialog`、`UserSelector` 等跨模块可复用  
- 布局组件（layout/）：`Sidebar` / `TopNavbar` / `LayoutWrapper`  

# Props 设计示例
```ts
interface ButtonProps {
  children: React.ReactNode;
  type?: 'button' | 'submit' | 'reset';
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  onClick?: () => void;
  className?: string;
}
```

# 视觉规范要点（Lark）
- 颜色/渐变/阴影/字体必须来自 Lark 设计系统；禁用自定义色与阴影。  
- 表格只用原生 `<table>`；每页主按钮 ≤ 1–2 个。  
- 动效以页面进入/分段揭示为主，控制数量与强度。

## Tailwind 映射
- 使用 Tailwind 预设类与 `cn` 合并 class。  
- 状态色示例：`text-green-600` / `text-yellow-600` / `text-red-600`；主操作 `bg-blue-500 hover:bg-blue-600 text-white`。  
- 禁止内联样式（除非动态计算），禁止自定义颜色。

# 核心组件示例
- 按钮：主按钮 `bg-blue-500 hover:bg-blue-600 text-white px-4 py-2 rounded-md shadow-sm`；次按钮白底蓝边；文本按钮用于表格操作。  
- 表格：`<table>`，表头 `bg-gray-50 text-gray-600`，行悬停 `hover:bg-gray-50`，`border-b`。  
- 卡片：标准卡片白底圆角+轻阴影；特色卡片用 Lark 渐变。  
- 徽章：浅底+边框+状态色文本。  
- 输入：边框灰、`focus:ring-2 focus:ring-blue-500`。

# 检查清单
- TS 严格模式，props 明确类型，禁 `any`。  
- Tailwind 预设类；不自定义颜色/阴影；表格用 `<table>`。  
- 文案全部 i18n（`next-intl`），键名稳定，动态值用插值；日期/数字用本地化格式。  
- 组件复用：先查 `ui/common/layout`，跨模块复用放 common。  
- 响应式：断点 `sm/md/lg`，触摸友好（≥44x44px），侧边栏移动端可隐藏。  
- 性能：长列表分页/虚拟滚动；避免无谓 re-render；用 `React.memo`/`useMemo`/`useCallback`。  
- 可访问性：语义化标签、表单有 label、焦点可见、支持键盘导航。  
- 遮罩/层级：使用固定层级（z-50 模态，z-100 toast），背景 `bg-black/50` 等。

# 禁止事项
- 使用 Lark 之外的颜色/自定义渐变或阴影/圆角体系。  
- 每页超过 2 个主按钮；硬编码文案；直接修改 shadcn/ui 源码。  
- 组件内直连 API（应经 hooks/services）；在 page/controller 写业务逻辑；跨层级直接访问数据。  
- 用 div 模拟表格；滥用嵌套三元或过度紧凑写法影响可读。

# 参考
- `./design-system-standards.md`
- `./frontend-standards.md`
- `docs/standards/03-frontend-architecture.md`