147 lines
3.3 KiB
Plaintext
147 lines
3.3 KiB
Plaintext
---
|
||
description: 前端工程师规范 - 元组件、苹果风格视觉标准
|
||
alwaysApply: false
|
||
---
|
||
|
||
# 前端工程师规范
|
||
|
||
## 一、元组件体系（必须使用）
|
||
|
||
| 元组件 | 路径 | 用途 |
|
||
|--------|------|------|
|
||
| `Button` | `@/components/ui/Button` | 所有按钮 |
|
||
| `Input` | `@/components/ui/Input` | 所有输入框 |
|
||
| `Textarea` | `@/components/ui/Input` | 多行输入 |
|
||
| `Modal` | `@/components/ui/Modal` | 所有弹窗 |
|
||
| `Card` | `@/components/ui/Card` | 所有卡片 |
|
||
| `Toast` | `@/components/ui/Toast` | 所有提示 |
|
||
| `Select` | `@/components/ui/Select` | 所有下拉框 |
|
||
| `Badge` | `@/components/ui/Badge` | 所有标签徽章 |
|
||
|
||
### Toast 使用
|
||
```tsx
|
||
import { useToast, ToastContainer } from '@/components/ui/Toast'
|
||
|
||
const toast = useToast()
|
||
toast.success('操作成功')
|
||
toast.error('操作失败')
|
||
|
||
// JSX 中添加容器
|
||
<ToastContainer toasts={toast.toasts} onClose={toast.removeToast} />
|
||
```
|
||
|
||
---
|
||
|
||
## 二、色彩系统
|
||
|
||
### 文本颜色
|
||
|
||
| 用途 | Tailwind 类 |
|
||
|------|-------------|
|
||
| 主文本 | `text-apple-label-primary` |
|
||
| 次文本 | `text-apple-label-secondary` |
|
||
| 辅助文本 | `text-apple-label-tertiary` |
|
||
|
||
### 背景颜色
|
||
|
||
| 用途 | Tailwind 类 |
|
||
|------|-------------|
|
||
| 主背景 | `bg-apple-bg-primary` |
|
||
| 次级背景 | `bg-apple-bg-secondary` |
|
||
| 三级背景 | `bg-apple-bg-tertiary` |
|
||
|
||
### 品牌色
|
||
|
||
| 模式 | 颜色 | Tailwind 类 |
|
||
|------|------|-------------|
|
||
| 浅色 | `#008D74` | `text-apple-brand` / `bg-apple-brand` |
|
||
| 深色 | `#00B896` | `text-apple-brand` / `bg-apple-brand` |
|
||
|
||
---
|
||
|
||
## 三、圆角规范
|
||
|
||
| 大小 | 像素 | Tailwind 类 |
|
||
|------|------|-------------|
|
||
| 中 | 10px | `rounded-apple-md` |
|
||
| 大 | 16px | `rounded-apple-lg` |
|
||
|
||
---
|
||
|
||
## 四、禁止事项
|
||
|
||
| 禁止 | 替代方案 |
|
||
|------|---------|
|
||
| `text-gray-*` | `text-apple-label-*` |
|
||
| `bg-gray-*` | `bg-apple-bg-*` |
|
||
| `shadow-*` | `shadow-apple-*` |
|
||
| `rounded-lg/xl` | `rounded-apple-md/lg` |
|
||
| `<button>` | `<Button>` |
|
||
| `<input>` | `<Input>` |
|
||
| 蓝色 focus ring | 品牌色 `#008D74` |
|
||
|
||
---
|
||
|
||
## 五、去 AI 味
|
||
|
||
| 禁止 | 推荐 |
|
||
|------|------|
|
||
| ❌ 均等分布（4个功能各占25%） | ✅ 非对称布局 |
|
||
| ❌ 默认实心图标 | ✅ 细线条 stroke-width 1.5 |
|
||
| ❌ 彩虹渐变背景 | ✅ 纯色/微妙渐变 |
|
||
| ❌ Lorem Ipsum 占位 | ✅ 真实场景数据 |
|
||
|
||
---
|
||
|
||
## 六、动画规范
|
||
|
||
| 场景 | 时长 | 缓动函数 |
|
||
|------|------|---------|
|
||
| 展开 | 500ms | `cubic-bezier(0.32, 0.72, 0, 1)` |
|
||
| 收起 | 350ms | `cubic-bezier(0.32, 0, 0.68, 0)` |
|
||
| 按钮按压 | 100ms | `scale(0.98)` |
|
||
| 悬停放大 | 200ms | `scale(1.02)` |
|
||
|
||
---
|
||
|
||
## 七、状态管理
|
||
|
||
### Zustand Stores
|
||
```
|
||
src/stores/
|
||
├── auth.store.ts # 认证状态
|
||
├── ui.store.ts # UI 状态
|
||
└── product.store.ts # 产品状态
|
||
```
|
||
|
||
### React Query Hooks
|
||
```
|
||
src/hooks/api/
|
||
├── useProducts.ts
|
||
├── useSKUs.ts
|
||
└── useUsers.ts
|
||
```
|
||
|
||
### 禁止
|
||
```typescript
|
||
// ❌ 禁止组件内直接 fetch
|
||
const [data, setData] = useState()
|
||
useEffect(() => { fetch('/api/xxx').then(...) }, [])
|
||
```
|
||
|
||
---
|
||
|
||
## 八、目录结构
|
||
|
||
```
|
||
src/components/
|
||
├── ui/ # 元组件（必须复用）
|
||
├── 3d/ # 3D 组件
|
||
└── [feature]/ # 功能组件
|
||
|
||
src/app/
|
||
├── (main)/ # 主布局页面
|
||
├── api/ # API 路由
|
||
└── share/ # 分享页面
|
||
```
|