prop-ai-hr/docs/FIGMA_DESIGN_SYSTEM_GUIDE.md

银城员工端 Figma 视觉系统使用规范

目的

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

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

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

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

一、四层模型

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. 页面组合

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

示例：

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

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

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

二、状态映射规则

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

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

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

三、Figma 命名规则

组件命名

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

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

业务实例命名

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

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

变体命名

优先使用结构化属性：

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. 最后才调整页面级视觉，不新增业务专用组件。

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

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 根据名称判断组件用途和边界？

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