danyang-match/前端组件库与 Design Token 规范.md

# 丹阳公益婚恋服务平台
# V1.0 前端组件库与 Design Token 规范

版本：V1.0  
适用范围：微信小程序用户端、公益红娘工作台、运营管理后台  
目标：统一视觉、降低研发成本、提高复用率、减少后期维护难度

---

# 第一章 规范目标

本规范用于统一整个V1.0前端设计与开发中的：

- 品牌颜色
- 中性色
- 字号
- 字重
- 行高
- 圆角
- 间距
- 阴影
- 图标
- 按钮
- 标签
- 表单
- 用户卡片
- 推荐卡片
- 活动卡片
- 状态组件
- 弹窗
- 空状态
- 错误状态
- 加载状态
- PC后台组件

后续所有页面原则上不得单独创造新的：

- 颜色
- 圆角
- 字号
- 按钮样式
- 卡片样式
- 状态颜色

如确需新增，应先进入组件库，再进入业务页面。

---

# 第二章 Token命名原则

统一采用语义化命名。

不要使用：

```text
red1
red2
gray3
bigFont
smallFont
```

建议使用：

```text
color-primary
color-text-primary
color-success
radius-card
spacing-page
font-title-lg
```

这样后期修改品牌风格时，不需要逐页面替换。

---

# 第三章 颜色 Design Token

## 3.1 品牌主色

```text
color-primary = #E96B6B
```

用途：

- 一级按钮
- 当前Tab
- 喜欢按钮
- 品牌强调
- 重点链接
- 部分进度状态

---

## 3.2 品牌主色按压态

```text
color-primary-active = #D95F5F
```

用于：

- 按钮按下
- 可点击组件按压反馈

---

## 3.3 品牌浅色

```text
color-primary-light = #FFF3F2
```

用途：

- 推荐理由背景
- 浅品牌卡片
- 已喜欢轻状态
- 婚恋相关轻提示

---

## 3.4 品牌极浅色

```text
color-primary-lighter = #FFF8F7
```

用于：

- 非核心区域背景
- 强调卡片底色

---

# 第四章 功能色

## 4.1 成功色

```text
color-success = #2E9B68
color-success-light = #ECF8F2
```

用于：

- 已实名
- 已审核
- 报名成功
- 已签到
- 操作完成

---

## 4.2 警告色

```text
color-warning = #E59A32
color-warning-light = #FFF7E9
```

用于：

- 审核中
- 需修改
- 风险提醒
- 待处理

---

## 4.3 错误/危险色

```text
color-danger = #D94A4A
color-danger-light = #FFF0F0
```

用于：

- 举报
- 拉黑
- 封禁
- 错误
- 极高风险

---

## 4.4 信息色

```text
color-info = #4A7CD4
color-info-light = #EEF4FF
```

用于：

- 系统说明
- 普通通知
- 辅助信息

---

# 第五章 中性色

```text
color-text-primary = #222222
color-text-secondary = #444444
color-text-tertiary = #777777
color-text-placeholder = #999999

color-border = #EEEEEE
color-divider = #F0F0F0

color-bg-page = #F7F8FA
color-bg-card = #FFFFFF
color-bg-disabled = #F3F3F3

color-disabled-text = #B5B5B5
```

---

# 第六章 深色文字使用规则

标题：

```text
color-text-primary
```

正文：

```text
color-text-secondary
```

辅助信息：

```text
color-text-tertiary
```

Placeholder：

```text
color-text-placeholder
```

不要随意使用：

```text
#000000
#333333
#666666
```

统一使用Token。

---

# 第七章 字体体系

用户端优先使用系统字体。

```text
font-family-cn = PingFang SC, Noto Sans SC, system-ui
```

PC后台：

```text
font-family-admin = Inter, PingFang SC, Noto Sans SC, system-ui
```

不额外引入装饰性品牌字体。

---

# 第八章 字号 Token

```text
font-size-xs = 12px
font-size-sm = 13px
font-size-md = 14px
font-size-base = 16px
font-size-lg = 18px
font-size-xl = 20px
font-size-2xl = 24px
font-size-3xl = 28px
```

---

# 第九章 字号使用规则

## 页面大标题

```text
24px
font-size-2xl
```

## 页面标题

```text
20px
font-size-xl
```

## 卡片标题

```text
18px
font-size-lg
```

## 正文

```text
16px
font-size-base
```

## 普通辅助文字

```text
14px
font-size-md
```

## 标签

```text
12～13px
font-size-xs / sm
```

---

# 第十章 字重

```text
font-weight-regular = 400
font-weight-medium = 500
font-weight-semibold = 600
font-weight-bold = 700
```

原则：

- 正文：400
- 按钮：500
- 卡片标题：600
- 页面大标题：600

极少使用700。

---

# 第十一章 行高

```text
line-height-tight = 1.25
line-height-normal = 1.5
line-height-relaxed = 1.7
```

使用：

标题：

```text
1.25
```

普通正文：

```text
1.5
```

长文本：

```text
1.7
```

---

# 第十二章 间距 Token

采用4px基础栅格。

```text
spacing-1 = 4px
spacing-2 = 8px
spacing-3 = 12px
spacing-4 = 16px
spacing-5 = 20px
spacing-6 = 24px
spacing-8 = 32px
spacing-10 = 40px
spacing-12 = 48px
```

---

# 第十三章 页面间距规范

用户端页面左右：

```text
spacing-page-x = 16px
```

区块间：

```text
20～24px
```

卡片内部：

```text
16px
```

紧密内容：

```text
8px
```

---

# 第十四章 圆角 Token

```text
radius-sm = 8px
radius-md = 12px
radius-lg = 16px
radius-xl = 20px
radius-full = 999px
```

使用：

- Input：12px
- Button：12px
- 普通卡片：16px
- 首页推荐卡片：20px
- Tag：999px

---

# 第十五章 阴影 Token

原则：

> 极轻阴影。

推荐：

```text
shadow-card =
0 4px 16px rgba(0,0,0,0.04)
```

浮层：

```text
shadow-popup =
0 8px 32px rgba(0,0,0,0.10)
```

不要使用明显深阴影。

---

# 第十六章 边框 Token

```text
border-width = 1px
border-color = #EEEEEE
```

Input Focus：

```text
border-color-focus = color-primary
```

错误：

```text
border-color-error = color-danger
```

---

# 第十七章 动效 Token

```text
motion-fast = 120ms
motion-normal = 200ms
motion-slow = 300ms
```

缓动：

```text
ease-standard = ease-out
```

不要超过500ms的常规UI动效。

---

# 第十八章 图标规范

建议统一线性图标。

基础尺寸：

```text
icon-xs = 16px
icon-sm = 20px
icon-md = 24px
icon-lg = 32px
```

图标库建议保持统一风格。

不要混用：

- 填充图标
- 卡通图标
- 3D图标
- 多套不同图标库

---

# 第十九章 Button组件

组件名：

```text
Button
```

支持Variant：

```text
primary
secondary
text
danger
ghost
```

支持Size：

```text
small
medium
large
```

---

# 第二十章 Primary Button

```text
height = 48px
radius = 12px
background = color-primary
text = white
font-size = 16px
font-weight = 500
```

Hover/Press：

```text
color-primary-active
```

Disabled：

```text
background = color-bg-disabled
text = color-disabled-text
```

---

# 第二十一章 Secondary Button

```text
height = 48px
background = #FFFFFF
border = color-primary
text = color-primary
```

典型场景：

- 查看资料
- 返回修改
- 稍后再聊
- 放宽条件

---

# 第二十二章 Text Button

没有背景。

用于：

- 编辑
- 查看更多
- 取消喜欢
- 解除拉黑

---

# 第二十三章 Danger Button

用于：

- 拉黑
- 封禁
- 注销
- 删除

背景方式建议：

普通用户端：

> 红色文字/描边优先。

后台严重操作：

> 可使用红色实心按钮。

---

# 第二十四章 Button状态

每个按钮必须支持：

```text
default
pressed
loading
disabled
```

Loading状态：

```text
加载图标 + 文案
```

例如：

> 提交中...

禁止用户重复点击。

---

# 第二十五章 Input组件

组件名：

```text
Input
```

高度：

```text
48px
```

支持：

```text
label
placeholder
prefix
suffix
helperText
errorText
disabled
```

---

# 第二十六章 Input状态

```text
default
focus
filled
error
disabled
```

错误状态：

```text
红色边框
+
字段下方错误文字
```

不要只用红框，不显示原因。

---

# 第二十七章 Textarea组件

用于：

- 自我介绍
- 举报说明
- 红娘服务说明
- 意见反馈

建议最小高度：

```text
120px
```

支持字数统计：

```text
128 / 500
```

---

# 第二十八章 Select组件

移动端优先：

> Picker / Bottom Sheet

PC后台：

> Dropdown Select

不要在微信小程序中强行模拟PC下拉菜单。

---

# 第二十九章 RadioGroup组件

整行可点击。

示例：

```text
○ 必须符合
● 最好符合
```

组件：

```text
RadioGroup
RadioItem
```

---

# 第三十章 Checkbox/TagSelect组件

婚恋标签选择建议使用：

```text
TagSelect
```

例如：

```text
[旅行] [运动] [阅读]
```

未选中：

```text
浅灰背景
深灰文字
```

选中：

```text
color-primary-light
color-primary
```

---

# 第三十一章 Switch组件

用于：

- 隐私设置
- 是否接收活动推荐
- 是否允许搜索
- 是否接受红娘推荐

建议使用系统化Switch。

---

# 第三十二章 SliderRange组件

用于：

- 年龄
- 身高

组件：

```text
RangeSlider
```

同时显示左右值：

```text
28岁 —— 35岁
```

不要只显示滑块而看不到当前数值。

---

# 第三十三章 ProgressBar组件

用于：

- 资料完善进度
- 注册流程

参数：

```text
value
max
showText
```

颜色：

```text
color-primary
```

---

# 第三十四章 StatusBadge组件

统一组件：

```text
StatusBadge
```

支持状态：

```text
verified
reviewed
reviewing
need_edit
success
pending
danger
disabled
service
```

---

# 第三十五章 StatusBadge视觉

## 已实名

```text
background = color-success-light
text = color-success
```

文案：

> 已实名

---

## 已审核

```text
background = color-success-light
text = color-success
```

---

## 审核中

```text
background = color-warning-light
text = color-warning
```

---

## 需修改

```text
background = color-warning-light
text = color-warning
```

---

## 高风险

```text
background = color-danger-light
text = color-danger
```

---

# 第三十六章 UserCard组件

UserCard是平台核心组件之一。

用于：

- 找对象
- 喜欢列表
- 红娘候选
- 活动意向名单

基础属性：

```text
avatar
displayName
age
height
region
education
occupation
maritalStatus
verified
reviewed
```

---

# 第三十七章 UserCard移动端结构

```text
┌────────────────────────┐
│ [照片] 王女士 · 32岁     │
│       165cm · 丹阳      │
│       本科 · 教师        │
│       未婚              │
│       ✓ 已实名          │
└────────────────────────┘
```

推荐：

```text
avatar：88×112px
```

比例约：

```text
4:5
```

---

# 第三十八章 UserCard交互

整卡：

> 可点击进入详情。

不要在普通列表里堆：

- 喜欢
- 举报
- 拉黑
- 红娘推荐

这些应进入详情或特定业务场景。

---

# 第三十九章 RecommendCard组件

用于：

> 首页每日推荐。

继承UserCard，并增加：

```text
photos
recommendReasons
likeStatus
actionMode
```

---

# 第四十章 RecommendCard结构

```text
照片区域
↓
用户核心资料
↓
认证状态
↓
推荐理由
↓
操作栏
```

---

# 第四十一章 RecommendReason组件

组件：

```text
RecommendReason
```

样式：

```text
background = color-primary-light
radius = 12px
padding = 12～16px
```

最多显示：

> 3～4条。

---

# 第四十二章 RecommendReason文案

每条使用：

```text
✓ 年龄符合双方要求
```

不要写：

```text
算法得分 +15
权重命中
```

---

# 第四十三章 ActivityCard组件

属性：

```text
cover
title
date
time
location
feeType
status
registrationCount
```

V1前台不要重点展示报名人数。

---

# 第四十四章 ActivityCard结构

```text
封面
活动名称
时间
地点
公益免费标签
状态
```

---

# 第四十五章 ActivityStatus

支持：

```text
报名中
审核中
报名成功
已满
已结束
已签到
```

---

# 第四十六章 ProfileSection组件

用于用户详情页。

结构：

```text
标题
内容
```

例如：

```text
关于TA
────────
婚姻状况  未婚
学历      本科
```

统一Padding：

```text
16px
```

统一Radius：

```text
16px
```

---

# 第四十七章 InfoRow组件

用于：

```text
左侧Label
右侧Value
```

例如：

```text
婚姻状况      未婚
```

属性：

```text
label
value
highlight
```

---

# 第四十八章 PhotoGrid组件

用于：

- 用户生活照片
- 举报证据
- 意见反馈

用户资料中：

```text
2～3列
```

照片比例：

```text
1:1
```

点击：

> Preview。

---

# 第四十九章 PhotoUploader组件

支持：

```text
single
multiple
maxCount
compress
preview
delete
```

主头像模式：

```text
single
```

生活照：

```text
multiple
```

---

# 第五十章 Avatar/ProfilePhoto规范

婚恋用户头像建议：

> 尽量使用真实照片矩形裁切。

列表：

```text
4:5
```

聊天：

```text
1:1
圆角
```

不要所有地方都裁成圆形。

---

# 第五十一章 NoticeBar组件

用于：

- 聊天安全提醒
- 审核提示
- 活动提示

Variant：

```text
info
warning
success
danger
```

聊天安全：

```text
warning
```

---

# 第五十二章 Toast组件

适用于即时轻反馈。

例如：

```text
已喜欢
保存成功
报名已提交
已解除拉黑
```

展示：

```text
1.5～2秒
```

不允许承载复杂信息。

---

# 第五十三章 Dialog组件

用于重要二次确认。

结构：

```text
title
description
primaryAction
secondaryAction
```

适用：

- 解除匹配
- 拉黑
- 暂停寻找
- 成功牵手
- 封禁
- 删除

---

# 第五十四章 BottomSheet组件

移动端优先用于：

- 选择操作
- 解除匹配原因
- 简单Picker
- 更多菜单

最大高度建议：

```text
80vh
```

---

# 第五十五章 MoreMenu组件

用户详情和聊天右上角：

```text
···
```

内容：

```text
查看资料
解除匹配
举报
拉黑
```

根据业务状态动态显示。

---

# 第五十六章 EmptyState组件

属性：

```text
icon
title
description
actionText
action
```

示例：

```text
暂无聊天

双方互相喜欢后，
就可以开始交流。

[ 去看看推荐 ]
```

---

# 第五十七章 ErrorState组件

示例：

```text
网络好像有点问题

请检查网络后重新加载。

[ 重新加载 ]
```

不要展示技术堆栈信息。

---

# 第五十八章 Loading组件

页面加载：

优先：

> Skeleton。

按钮：

> Spinner。

不要全屏长期显示大型Loading动画。

---

# 第五十九章 Skeleton组件

至少支持：

```text
UserCardSkeleton
RecommendCardSkeleton
ListSkeleton
ProfileSkeleton
```

避免页面加载时跳动过大。

---

# 第六十章 MatchSuccess组件

用于双向喜欢。

属性：

```text
userAvatar
targetAvatar
targetName
primaryAction
```

视觉：

> 简洁爱心+双头像。

不要做娱乐化动画。

---

# 第六十一章 ChatListItem组件

属性：

```text
avatar
name
lastMessage
time
unreadCount
```

样式接近用户熟悉的微信消息列表。

---

# 第六十二章 ChatBubble组件

支持：

```text
self
other
system
```

用户本人：

> 右侧。

对方：

> 左侧。

系统安全信息：

> 中间。

---

# 第六十三章 RiskNotice组件

用于聊天风险提示。

Variant：

```text
money
fraud
privacy
```

但V1视觉统一，不需要不同颜色体系。

默认警告色。

---

# 第六十四章 Tab组件

用户端：

```text
SegmentTabs
```

例如：

```text
互相喜欢 | 我喜欢的 | 喜欢我的
```

后台：

```text
PageTabs
```

例如：

```text
待审核 | 审核中 | 已通过
```

---

# 第六十五章 BottomTabBar组件

固定五项：

```text
首页
找对象
消息
活动
我的
```

必须使用统一图标和文案。

消息有未读时：

> 红点或数字Badge。

---

# 第六十六章 Navbar组件

小程序页面统一：

```text
title
back
rightAction
```

尽量使用微信原生导航行为。

---

# 第六十七章 SearchBar组件

后台和部分用户搜索使用。

用户端：

> 不作为主入口。

后台：

用于：

- 用户搜索
- 活动人员搜索
- 红娘用户搜索

---

# 第六十八章 FilterBar组件

后台列表统一使用。

结构：

```text
搜索
筛选项
查询
重置
```

避免每个后台页面重新布局。

---

# 第六十九章 DataTable组件

红娘端、后台核心组件。

支持：

```text
columns
pagination
sorting
selection
actions
loading
empty
```

---

# 第七十章 DataTable视觉规范

表头：

```text
14px
500
浅灰背景或白背景
```

表格正文：

```text
14px
```

行高：

```text
52～56px
```

---

# 第七十一章 TableRowAction组件

每行最多：

```text
2个直接操作 + 更多
```

例如：

```text
查看 | 审核 | 更多
```

---

# 第七十二章 AdminSidebar组件

宽度：

```text
220～240px
```

状态：

```text
default
active
collapsed
```

V1可不优先做折叠。

---

# 第七十三章 AdminHeader组件

包含：

```text
当前机构
通知
当前用户
退出
```

不加入无关信息。

---

# 第七十四章 StatCard组件

后台工作台统一组件。

属性：

```text
title
value
trend
status
action
```

示例：

```text
待审核资料
12
```

---

# 第七十五章 StatCard规则

待办类：

> 可点击。

普通统计：

> 不一定可点击。

不要用大量渐变背景。

---

# 第七十六章 RiskLevelTag组件

后台风险：

```text
正常
关注
高风险
封禁
```

颜色：

正常：

```text
success
```

关注：

```text
warning
```

高风险：

```text
danger
```

封禁：

```text
深灰/危险
```

---

# 第七十七章 ReviewStatus组件

用户审核：

```text
待审核
审核中
需修改
已通过
已拒绝
```

统一各端显示。

---

# 第七十八章 ServiceStatus组件

红娘：

```text
待分配
已接单
服务中
待跟进
已完成
```

---

# 第七十九章 ActivityManagementStatus组件

后台活动：

```text
草稿
报名中
报名结束
进行中
已结束
```

---

# 第八十章 FormSection组件

后台长表单使用。

例如：

```text
基本信息
活动时间
人数限制
报名设置
```

减少一个大表单堆几十个字段。

---

# 第八十一章 ConfirmDangerDialog组件

后台高风险操作统一使用。

例如封禁：

```text
确认封禁该用户？

封禁后用户将无法继续使用婚恋服务。

原因：
[请选择]

[确认封禁]
[取消]
```

必须要求原因。

---

# 第八十二章 Pagination组件

默认：

```text
20条/页
```

支持：

```text
20
50
100
```

V1默认建议只开放20/50。

---

# 第八十三章 DatePicker组件

移动端：

> 微信Picker。

后台：

> 日期时间组件。

统一存储时间格式由后端定义，前端负责本地化显示。

---

# 第八十四章 FormValidation规范

字段错误优先显示在字段下方。

例如：

```text
身份证号码
[32xxxxxxxxxxxx]

身份证号码格式不正确
```

不要提交后只顶部显示：

> 表单有错误。

---

# 第八十五章 必填标识

必填项：

```text
*
```

但首次资料填写中尽量通过产品流程减少大量星号。

可选项明确标注：

> 选填

---

# 第八十六章 Disabled状态

禁用组件必须：

- 视觉明显变淡
- 无点击响应
- 如用户可能疑惑，给说明

例如：

```text
资料审核中，暂不能修改婚姻状态。
```

---

# 第八十七章 图片占位组件

头像缺失：

不要默认用随机人物照片。

使用：

> 中性用户轮廓图标。

但正式进入匹配前：

> 必须上传真实头像。

---

# 第八十八章 内容超长规则

用户名称：

> 单行省略。

职业：

> 单行省略。

个人介绍：

详情页完整展示。

列表：

> 不显示或最多2行。

---

# 第八十九章 标签数量限制

UserCard：

最多：

```text
2～3个状态标签
```

详情页兴趣：

最多：

```text
8个
```

避免标签海洋。

---

# 第九十章 层级 Z-Index Token

建议统一：

```text
z-base = 1
z-sticky = 100
z-tabbar = 200
z-dropdown = 500
z-modal = 1000
z-toast = 2000
```

---

# 第九十一章 Safe Area规范

微信小程序底部：

必须考虑：

```text
env(safe-area-inset-bottom)
```

底部固定按钮和Tab不能被系统Home Indicator遮挡。

---

# 第九十二章 PC响应式断点

```text
breakpoint-md = 1024px
breakpoint-lg = 1280px
breakpoint-xl = 1440px
```

红娘端/后台：

V1优先优化：

```text
1280+
```

---

# 第九十三章 用户端组件命名建议

前端目录：

```text
components/
  button/
  input/
  status-badge/
  user-card/
  recommend-card/
  activity-card/
  profile-section/
  info-row/
  photo-grid/
  photo-uploader/
  notice-bar/
  empty-state/
  error-state/
  loading/
  match-success/
  chat-bubble/
  bottom-sheet/
```

---

# 第九十四章 后台组件命名建议

```text
admin-components/
  admin-sidebar/
  admin-header/
  stat-card/
  filter-bar/
  data-table/
  review-status/
  risk-level-tag/
  form-section/
  confirm-danger-dialog/
```

---

# 第九十五章 页面不得直接写死颜色

禁止：

```css
color: #E96B6B;
```

页面层应使用：

```css
color: var(--color-primary);
```

或框架对应的Token引用方式。

---

# 第九十六章 页面不得直接写死通用间距

避免：

```css
margin-top: 17px;
```

优先：

```text
spacing-4
spacing-5
spacing-6
```

只有特殊布局才允许例外。

---

# 第九十七章 微信小程序Token建议

可统一定义：

```text
--color-primary
--color-primary-light
--color-success
--color-warning
--color-danger
--color-info

--text-primary
--text-secondary
--text-tertiary

--bg-page
--bg-card

--radius-sm
--radius-md
--radius-lg

--spacing-1
--spacing-2
--spacing-3
--spacing-4
--spacing-5
--spacing-6
```

---

# 第九十八章 推荐Token代码结构示例

```text
theme/
  colors
  typography
  spacing
  radius
  shadow
  motion
```

不要把所有样式变量放在一个无法维护的大文件中。

---

# 第九十九章 组件状态统一原则

所有可交互组件至少考虑：

```text
默认
按下
加载
禁用
错误
空状态
```

需要网络数据的组件还要考虑：

```text
Loading
Error
Empty
Loaded
```

---

# 第一百章 组件复用红线

以下业务不能自行重新造组件：

- 用户卡片
- 推荐卡片
- 活动卡片
- 状态标签
- 空状态
- 弹窗
- Toast
- 审核状态
- 风险状态
- 表格
- 筛选栏

---

# 第一百零一章 组件文案原则

组件内部不要写死业务文案。

例如：

错误：

```text
Button组件内部默认文案：立即报名
```

正确：

```text
Button接受children/text参数
```

业务文案由页面传入。

---

# 第一百零二章 无障碍规范

Button：

> 必须有文字或accessible label。

纯图标：

> 必须提供说明。

颜色状态：

> 必须同时有文字。

例如：

不能只有红色点。

应该：

> 高风险

---

# 第一百零三章 点击热区

移动端交互元素最小：

```text
44×44px
```

文字“编辑”也应通过padding扩大可点击区域。

---

# 第一百零四章 用户端视觉密度

原则：

> 中低密度。

不追求一屏展示尽可能多数据。

尤其：

- 首页
- 详情
- 活动
- 红娘服务

都要有足够留白。

---

# 第一百零五章 后台视觉密度

原则：

> 中等密度。

可以比用户端紧凑，但避免传统ERP式高密度。

---

# 第一百零六章 头像审核状态显示

如果用户资料处于：

> 审核中

主头像仍然可以给本人看。

但在其他用户侧：

> 未审核用户不能进入正常推荐池。

因此不需要设计“别人看到审核中头像”的场景。

---

# 第一百零七章 敏感字段组件

后台建议：

```text
SensitiveField
```

默认：

```text
320***********1234
```

具备权限者点击：

> 查看完整信息

系统记录访问日志。

---

# 第一百零八章 MobileStickyAction组件

用于：

- 用户详情喜欢
- 活动报名
- 表单提交

固定底部。

必须：

- 避开TabBar
- 避开safe area
- 有白色背景
- 顶部轻分割线

---

# 第一百零九章 StepProgress组件

用于首次资料填写。

示例：

```text
完善资料 2/5

██████░░░░
```

不需要复杂Step图标。

---

# 第一百一十章 PageHeader组件

用户端简单：

```text
标题
可选说明
```

后台：

```text
页面标题
说明
主要操作
```

例如：

```text
活动管理                + 创建活动
管理公益婚恋线下活动
```

---

# 第一百一十一章 Alert组件

后台使用。

例如：

> 修改匹配权重会影响后续推荐，请谨慎操作。

Variant：

```text
info
warning
danger
```

---

# 第一百一十二章 Drawer组件

后台可用于：

- 快速查看用户
- 快速查看报名详情

不用于复杂审核。

复杂审核进入完整页面。

---

# 第一百一十三章 Tooltip组件

后台可以使用。

用户小程序：

> 尽量不用Tooltip。

移动端不适合依赖Hover。

---

# 第一百一十四章 Breadcrumb规范

后台页面层级较深时使用。

例如：

```text
活动管理 / 丹阳青年公益相亲会 / 报名管理
```

小程序不需要。

---

# 第一百一十五章 NotificationBadge组件

Tab消息：

```text
1～99
99+
```

系统通知：

可以只显示红点。

---

# 第一百一十六章 上传进度

照片上传必须有：

```text
上传中
失败
成功
```

上传失败：

显示：

> 重新上传。

不要让失败图片直接消失。

---

# 第一百一十七章 网络请求反馈

提交类操作：

Button Loading。

列表刷新：

Skeleton/局部Loading。

不使用：

> 点击后整个页面遮罩5秒。

---

# 第一百一十八章 防重复提交

以下操作必须前端防重复：

- 实名提交
- 资料提交审核
- 喜欢
- 活动报名
- 红娘申请
- 举报
- 反馈提交

同时后端也要保证幂等。

---

# 第一百一十九章 组件测试重点

每个组件必须验证：

- 普通状态
- 超长文字
- 无图片
- 弱网
- 禁用
- 加载
- 错误
- 不同屏幕宽度

---

# 第一百二十章 首批必须完成的组件

P0组件：

```text
Button
Input
Textarea
Picker
RadioGroup
TagSelect
Switch
RangeSlider
ProgressBar

StatusBadge
UserCard
RecommendCard
RecommendReason
ProfileSection
InfoRow
PhotoUploader

Toast
Dialog
BottomSheet
NoticeBar
EmptyState
ErrorState
Skeleton

BottomTabBar
Navbar
MobileStickyAction
```

---

# 第一百二十一章 第二批组件

P1：

```text
ActivityCard
MatchSuccess
ChatListItem
ChatBubble
RiskNotice
PhotoGrid
StepProgress
NotificationBadge
```

---

# 第一百二十二章 后台首批组件

```text
AdminSidebar
AdminHeader
PageHeader
StatCard
FilterBar
DataTable
TableRowAction
StatusBadge
ReviewStatus
RiskLevelTag
FormSection
Dialog
Drawer
Pagination
Alert
SensitiveField
```

---

# 第一百二十三章 组件验收标准

任何通用组件完成后必须回答：

### 能否在两个以上页面复用？

不能：

可能不应该进入公共组件库。

### 是否存在写死业务字段？

有：

需要重新抽象。

### 状态是否完整？

至少：

> 默认、加载、禁用、错误。

### 是否符合Token？

不能出现无规范颜色和间距。

---

# 第一百二十四章 Design Token验收标准

项目最终应达到：

> 修改一次主色，整个平台同步变化。

> 修改一次卡片圆角，所有卡片同步变化。

> 修改一次页面间距，所有标准页面遵循。

> 不需要人工逐页面搜索CSS修改。

---

# 第一百二十五章 最终开发原则

前端开发必须遵循：

> 页面由组件组成。

> 组件由Token控制。

> Token统一视觉。

> 业务逻辑不直接侵入基础组件。

最终目标不是做一套“漂亮页面”，而是建立一套：

> **可复用、可维护、可扩展、后期新增页面不容易跑偏的前端设计系统。**

V1.0所有页面都应尽可能从本规范中的组件组合产生，而不是每个页面重新设计一遍。