# 帮道 Figma 视觉系统使用规范

## 目的

本文件规定员工端页面如何从通用视觉元素组合页面，再放置具体业务元素。

后续 LLM 打开 Figma 时，必须遵循：

```text
先识别页面结构
→ 选择通用视觉组件
→ 填入业务对象和字段
→ 映射业务状态
→ 补齐响应式与交互状态
```

不要把业务文案、业务状态或业务指标直接当成视觉组件。

## 一、四层模型

### 1. 业务元素

业务元素是产品要表达的对象、字段和动作，不属于视觉库。

员工端「我」页面示例：

- 用户身份：姓名、头像、工号、岗位、组织
- 成长数据：成长值、等级、训练次数、完成率
- 能力数据：能力维度、当前分数、趋势、短板
- 记录对象：训练记录、复盘记录、收藏内容
- 激励对象：积分、徽章、荣誉、排行榜名次
- 用户动作：查看详情、继续训练、查看荣誉、修改偏好

### 2. 业务状态

业务状态描述业务对象当前情况，也不属于视觉库。

示例：

- 训练：未开始、进行中、已完成、待复盘、已过期
- 审核：待审核、已通过、已驳回
- 任务：未完成、已完成、逾期
- 数据：加载中、暂无数据、加载失败

业务状态需要映射到通用组件，而不是创建同名视觉组件。

### 3. 通用视觉元素

通用视觉元素是可以跨业务复用的组件和布局结构。

基础元素：

- Color、Typography、Spacing、Radius、Shadow、Icon
- Avatar、Divider、Image、Grid

通用组件：

- PageHeader
- SectionHeader
- Card
- MetricCard
- ListItem
- Label
- Tag / Badge / StatusBadge
- Progress / Score
- Button / IconButton
- Tabs / BottomTabBar
- Modal / Drawer / Toast
- Loading / EmptyState / ErrorState

### 4. 页面组合

页面组合是业务元素使用通用视觉元素后的结果，不应反向污染视觉库。

示例：

```text
成长摘要卡 = Card + MetricCard + Progress + 业务成长数据
训练记录项 = ListItem + StatusBadge + Score + Button + 训练记录字段
个人资料区 = Card + Avatar + Label + 业务身份字段
荣誉墙 = SectionHeader + Grid + Badge + 业务荣誉数据
```

### 员工端首页并列入口的尺寸规则

「问老师傅」和「打字问」是同一问答卡中的并列入口，属于页面组合，不新增业务组件。两侧图片容器统一使用 `64×64`，横向内容行使用垂直居中；图形本身可按图标复杂度保持内部留白，但不能再出现一侧 `80×80`、另一侧 `40×40` 的视觉层级错位。

员工端「页面｜今日」对齐「参考稿｜今日」时，使用组件库提供的品牌头部、卡片、按钮、聊天气泡和底部 Tab 作为基础，再由页面组合承载「生活顾问 / 客服管家」、今日安排和我的地图等业务元素。参考稿中的师傅提示气泡属于通用沟通组件的页面实例，不应把“今天先处理投诉”等文案固化进组件；缺少图标时优先复用代码已有品牌资源或图标组件，只有确实没有可复用资产时才新增图形资源。

## 二、状态映射规则

业务状态只负责提供语义，视觉组件负责提供表现。

| 业务语义 | 推荐组件 | 视觉职责 |
|---|---|---|
| 未开始 | StatusBadge / Button | 中性状态、引导操作 |
| 进行中 | StatusBadge / Progress | 强调进行状态和完成比例 |
| 已完成 | StatusBadge / Score | 正向反馈、展示结果 |
| 待复盘 | StatusBadge / Button | 提示下一步动作 |
| 已过期 | StatusBadge | 警示和不可继续操作 |
| 暂无数据 | EmptyState | 解释原因和可执行动作 |
| 加载失败 | ErrorState / Button | 错误说明和重试 |

文案如“训练未开始”是业务 Label 的内容，不是新的视觉组件。

## 三、Figma 命名规则

### 组件命名

组件用通用结构命名，不用业务文案命名：

```text
正确：StatusBadge、MetricCard、ListItem
错误：训练未开始标签、成长值卡片、待复盘卡片
```

### 业务实例命名

实例可以带业务语义，但必须保留通用组件名：

```text
StatusBadge / training / not-started
MetricCard / growth-score
ListItem / practice-history
```

### 变体命名

优先使用结构化属性：

```text
size = sm | md | lg
tone = neutral | brand | success | warning | danger
state = default | loading | disabled | error
showIcon = true | false
```

不要为每个业务状态复制一套组件。

## 四、LLM 读取和生成页面的顺序

LLM 处理新页面时，按以下顺序工作：

1. 识别页面目标和用户任务。
2. 把页面内容拆成业务对象、字段、状态和动作。
3. 从 Figma 组件库选择页面骨架和通用组件。
4. 根据布局规则组合组件。
5. 将业务字段填入组件实例。
6. 将业务状态映射到 `tone`、`state`、`progress` 或操作按钮。
7. 检查加载、空、错误、禁用和完成状态。
8. 最后才调整页面级视觉，不新增业务专用组件。

## 五、「我」页面的推荐骨架

```text
Page
├── PageHeader
│   └── 业务元素：页面标题、设置入口
├── ProfileCard
│   └── Avatar + 业务身份字段
├── GrowthSummary
│   └── MetricCard + Progress + 业务成长数据
├── CapabilitySection
│   └── SectionHeader + Score / Progress + 业务能力数据
├── PracticeHistory
│   └── SectionHeader + ListItem + StatusBadge + 训练记录
├── HonorSection
│   └── SectionHeader + Badge / Grid + 荣誉数据
└── BottomTabBar
    └── 通用导航结构：今日 / 练 / 问 / 我
```

这里的 `ProfileCard`、`GrowthSummary` 等是页面组合名称；真正进入通用视觉库的仍是 `Card`、`MetricCard`、`Progress`、`ListItem`、`Badge` 等组件。

## 六、设计检查清单

- 是否能把业务文案替换成另一种业务，而不重画组件？
- 组件名称是否描述结构，而不是描述某个业务？
- 业务状态是否通过 `tone`、`state` 或内容字段表达？
- 是否复用了已有 Token 和组件？
- 是否覆盖加载、空、错误、禁用和完成状态？
- 页面是否由清晰的组件组合构成？
- 是否能让 LLM 根据名称判断组件用途和边界？

判断标准：如果一个元素离开当前业务仍然有意义，它才适合进入通用视觉库。