docs: add comprehensive design system (tokens, layout, components, dialog, implementation guide)

2026-06-09 01:50:30 +08:00 · 2026-05-19 10:11:17 +08:00
parent 3dc71de739
commit d3a646c325
1 changed files with 442 additions and 0 deletions
@@ -0,0 +1,442 @@
+# CraftLabs 前端设计体系 v1.0
+
+> 基于 Figma「安徽地质博物馆 v2.0」设计 Token 提取，适配 delivery-platform-ui  
+> 最后更新：2026-05-19
+
+---
+
+## 目录
+
+1. [设计 Token](#1-设计-token)
+2. [布局体系](#2-布局体系)
+3. [组件规范](#3-组件规范)
+4. [页面模板](#4-页面模板)
+5. [弹框体系](#5-弹框体系)
+6. [实施指南](#6-实施指南)
+
+---
+
+## 1. 设计 Token
+
+### 1.1 色彩
+
+| Token | 值 | 用途 |
+|-------|-----|------|
+| `--color-brand` | `#2C3E6B` | 主色：按钮、链接、选中态、表头文字 |
+| `--color-brand-hover` | `#3D5A99` | 主色悬停 |
+| `--color-brand-light` | `#F2F5FC` | 主色淡化：表头背景、选中背景 |
+| `--color-page-bg` | `#EAEFFA` | 页面底色 |
+| `--color-card-bg` | `#FFFFFF` | 卡片/面板/弹窗背景 |
+| `--color-text-primary` | `#303133` | 主要文字：标题、正文 |
+| `--color-text-secondary` | `#606266` | 次要文字：标签、说明 |
+| `--color-text-placeholder` | `#909399` | 占位/辅助文字 |
+| `--color-text-disabled` | `#C0C4CC` | 禁用/图标 |
+| `--color-border` | `#E8ECF1` | 通用边框：卡片、表格 |
+| `--color-border-input` | `#E0E3E8` | 输入框边框 |
+| `--color-success` | `#1A7A3A` | 成功文字 |
+| `--color-success-bg` | `#E6F7EE` | 成功背景 |
+| `--color-success-border` | `#A8E6C1` | 成功边框 |
+| `--color-danger` | `#F56C6C` | 危险/错误 |
+| `--color-danger-bg` | `#FEF0F0` | 危险背景 |
+| `--color-warning` | `#E6A23C` | 警告 |
+| `--color-warning-bg` | `#FDF6EC` | 警告背景 |
+| `--color-badge` | `#D54941` | 通知红点 |
+| `--color-search-bg` | `#F8F9FB` | 搜索框背景 |
+
+#### 色板速查
+
+```
+品牌色      #2C3E6B ████████  ████████  ████████
+页面底色    #EAEFFA ████████  ████████  
+卡片白      #FFFFFF ████████  ████████  ████████
+表头蓝      #F2F5FC ████████  
+成功绿      #E6F7EE ████████  
+危险红      #FEF0F0 ████████  
+警告橙      #FDF6EC ████████  
+Badge红     #D54941 ████████  
+```
+
+### 1.2 字体
+
+| 层级 | 字号 | 字重 | 颜色 | 场景 |
+|------|:--:|:--:|------|------|
+| H1 页面标题 | 22px | 700 | `--color-text-primary` | 页面主标题 |
+| H2 区块标题 | 20px | 700 | `--color-text-primary` | 卡片标题 |
+| H3 子标题 | 16px | 600 | `--color-text-primary` | 弹框标题 |
+| Body 正文 | 14px | 400 | `--color-text-primary` | 表格内容、菜单 |
+| Body-Secondary | 13px | 400 | `--color-text-secondary` | 标签、说明 |
+| Caption | 12px | 400 | `--color-text-placeholder` | 时间、统计小字 |
+| Code/Mono | 12px | 400 | `--color-text-primary` | 许可证ID、SN编码 |
+| Badge | 10-11px | 600 | `#FFFFFF` | 通知数字、标签 |
+
+**字体族**：`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif`
+
+### 1.3 间距
+
+| Token | 值 | 用途 |
+|-------|:--:|------|
+| `--space-xs` | 4px | 图标与文字间距 |
+| `--space-sm` | 8px | 按钮组间距、筛选条件间距 |
+| `--space-md` | 12px | 卡片间距、统计卡间距 |
+| `--space-lg` | 16px | 表单项间距、内容区上下内边距 |
+| `--space-xl` | 20px | 内容区左右内边距、弹框内边距 |
+| `--space-xxl` | 24px | 页面区块间距 |
+
+### 1.4 圆角
+
+| Token | 值 | 场景 |
+|-------|:--:|------|
+| `--radius-sm` | 4px | 输入框、按钮、标签 |
+| `--radius-md` | 6px | 卡片、搜索框、菜单项 |
+| `--radius-lg` | 8px | 弹框 |
+
+### 1.5 阴影
+
+| Token | 值 | 场景 |
+|-------|-----|------|
+| `--shadow-card` | `0 1px 2px rgba(0,0,0,.03)` | 卡片默认 |
+| `--shadow-card-hover` | `0 4px 12px rgba(0,0,0,.06)` | 卡片悬停 |
+| `--shadow-btn` | `0 2px 6px rgba(44,62,107,.2)` | CTA 主按钮 |
+| `--shadow-dialog` | `0 8px 40px rgba(0,0,0,.15)` | 弹框 |
+| `--overlay` | `rgba(0,0,0,.45)` | 弹框遮罩 |
+
+---
+
+## 2. 布局体系
+
+### 2.1 整体框架
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ Header 60px                                              │
+│ Logo  [导航1] [导航2]         🔍搜索  🔔³  ⚙️  👤用户名   │
+├────────┬─────────────────────────────────────────────────┤
+│Sidebar │ Breadcrumb 46px                                 │
+│232px   │ 授权运营 › 当前页面                               │
+│        ├─────────────────────────────────────────────────┤
+│ 菜单    │                    │                            │
+│ 分组    │  Tree Panel 280px  │  Main Content             │
+│        │  (可选)             │  (自适应)                  │
+│ 11项   │                    │                            │
+│        │                    │                            │
+│v0.1.0  │                    │                            │
+└────────┴────────────────────┴────────────────────────────┘
+```
+
+### 2.2 尺寸规范
+
+| 元素 | 尺寸 | 说明 |
+|------|:--:|------|
+| Header 高度 | 60px | 固定，含 Logo + 导航 + 搜索 + 通知 + 用户 |
+| Sidebar 宽度 | 232px | 白色底色，菜单项高 42-50px |
+| Sidebar 菜单项 | 42-88px | 主菜单 50px，子菜单 42px，分组标题 88px |
+| Breadcrumb 高度 | 46px | 内容区顶部，含当前路径 |
+| Tree Panel 宽度 | 280px | 许可证/客户页可选，含搜索框 |
+| Content 内边距 | 20px(左右) / 16px(上下) | 统一页面内边距 |
+| 卡片间距 | 12px | 统计卡 / 内容卡之间 |
+
+### 2.3 页面类型
+
+| 类型 | Tree Panel | 用途 | 示例页面 |
+|------|:--:|------|---------|
+| 标准列表页 | ❌ | 全宽卡片 + 筛选栏 + 表格 | 客户管理、合同管理、交付管理 |
+| Tree + 列表页 | ✅(280px) | 左侧层级导航 + 右侧列表 | 许可证管理 |
+| 工作台 | ❌ | 统计卡片 + 图表 + 待办 | 首页 Dashboard |
+| 详情页 | ❌ | 详情卡片 + 操作按钮 | 合同详情、交付详情 |
+| 只读列表 | ❌ | 简单表格 | 集成环境、产品线 |
+
+### 2.4 路由命名
+
+| 模块 | 路径 | 页面 |
+|------|------|------|
+| 工作台 | `/` | HomeView |
+| 客户管理 | `/customers` | CustomersView |
+| 合同管理 | `/contracts` | ContractsView |
+| 交付管理 | `/deliveries` | DeliveriesView |
+| 许可 SN | `/licenses/sn` | LicenseSnListView |
+| 许可证管理 | `/licenses` | LicenseList |
+| Callback | `/callbacks` | CallbackInboxView |
+| 集成环境 | `/integration/environments` | — |
+| 产品线 | `/integration/product-lines` | — |
+
+---
+
+## 3. 组件规范
+
+### 3.1 按钮
+
+```css
+/* 主按钮 */
+.btn-primary {
+  background: #2C3E6B; color: #fff; border: none;
+  border-radius: 4px; padding: 6px 14px;
+  font-size: 13px; font-weight: 500; cursor: pointer;
+}
+.btn-primary:hover { background: #3D5A99; }
+
+/* CTA 按钮（带阴影） */
+.btn-cta {
+  background: #2C3E6B; color: #fff; border: none;
+  border-radius: 4px; padding: 7px 16px;
+  box-shadow: 0 2px 6px rgba(44,62,107,.2);
+  font-size: 13px; font-weight: 500; cursor: pointer;
+}
+
+/* 取消/次要按钮 */
+.btn-cancel {
+  background: #fff; color: #606266;
+  border: 1px solid #E0E3E8; border-radius: 4px;
+  padding: 8px 20px; font-size: 14px;
+}
+
+/* 危险按钮 */
+.btn-danger {
+  background: #F56C6C; color: #fff; border: none;
+  border-radius: 4px; padding: 8px 20px; font-size: 14px;
+}
+```
+
+| 类型 | 背景 | 用途 |
+|------|------|------|
+| Primary | `#2C3E6B` | 查询、保存、签发 |
+| CTA | `#2C3E6B` + shadow | 创建/新建操作 |
+| Cancel | `#FFFFFF` + border | 取消、关闭 |
+| Danger | `#F56C6C` | 删除、吊销 |
+| Link | transparent + `#2C3E6B` | 详情、编辑 |
+
+### 3.2 输入框
+
+```css
+input, .input {
+  border: 1px solid #E0E3E8; border-radius: 4px;
+  padding: 7px 12px; font-size: 13px; color: #303133;
+}
+input:focus { border-color: #2C3E6B; }
+input::placeholder { color: #C0C4CC; }
+
+/* 搜索框 */
+.search-box {
+  border: 1px solid #E0E3E8; border-radius: 6px;
+  padding: 4px 10px; background: #F8F9FB;
+  display: flex; align-items: center; gap: 6px;
+}
+```
+
+### 3.3 表格
+
+```css
+table { width: 100%; border-collapse: collapse; font-size: 13px; }
+thead th {
+  padding: 10px 12px; text-align: left; font-weight: 600;
+  font-size: 12px; color: #2C3E6B; background: #F2F5FC;
+  border-bottom: 1px solid #E8ECF1; white-space: nowrap;
+}
+tbody td {
+  padding: 9px 12px; border-bottom: 1px solid #F2F5FC;
+}
+tr:hover td { background: #F8F9FB; }
+```
+
+### 3.4 状态标签
+
+```css
+.tag { display: inline-block; padding: 2px 8px; border-radius: 3px; font-size: 11px; font-weight: 500; }
+.tag-active   { background: #E6F7EE; color: #1A7A3A; border: 1px solid #A8E6C1; }
+.tag-revoked  { background: #FEF0F0; color: #F56C6C; border: 1px solid #FBC4C4; }
+.tag-pending  { background: #FDF6EC; color: #E6A23C; border: 1px solid #F5DAB1; }
+.tag-expired  { background: #f4f4f5; color: #909399; border: 1px solid #e9e9eb; }
+```
+
+### 3.5 通知 Badge
+
+```css
+.badge {
+  position: absolute; top: -2px; right: -5px;
+  width: 16px; height: 16px; background: #D54941;
+  border-radius: 50%; font-size: 10px; color: #fff;
+  line-height: 16px; text-align: center; font-weight: 600;
+}
+```
+
+### 3.6 侧边菜单
+
+```css
+.sidebar { width: 232px; background: #fff; border-right: 1px solid #E8ECF1; }
+.menu-item {
+  display: flex; align-items: center; gap: 10px;
+  padding: 9px 20px; font-size: 14px; color: #606266;
+  border-right: 3px solid transparent; cursor: pointer;
+}
+.menu-item:hover { background: #F2F5FC; color: #2C3E6B; }
+.menu-item.active {
+  background: #F2F5FC; color: #2C3E6B; font-weight: 600;
+  border-right-color: #2C3E6B;
+}
+.menu-section-label {
+  padding: 6px 20px; font-size: 11px; color: #C0C4CC;
+  text-transform: uppercase; font-weight: 600;
+}
+```
+
+### 3.7 面包屑
+
+```css
+.breadcrumb {
+  height: 46px; display: flex; align-items: center;
+  padding: 0 20px; gap: 6px; font-size: 13px;
+  background: #fff; border-bottom: 1px solid #E8ECF1;
+}
+.breadcrumb .sep { color: #C0C4CC; }
+.breadcrumb .current { color: #2C3E6B; font-weight: 600; }
+```
+
+---
+
+## 4. 页面模板
+
+### 4.1 标准列表页
+
+```
+┌─────────────────────────────────────────┐
+│ 统计卡片 (4列可选)                        │
+│ [总XX] [活跃] [已吊销] [已过期]           │
+├─────────────────────────────────────────┤
+│ [🔍搜索框] [状态下拉] [查询]  [+ 新建]    │
+├─────────────────────────────────────────┤
+│ 表格                                     │
+│ ID  │ 名称 │ 关联 │ 状态 │ 时间 │ 操作    │
+│ ...                                      │
+├─────────────────────────────────────────┤
+│                        共XX条  ‹ 1 2 ›   │
+└─────────────────────────────────────────┘
+```
+
+**对应文件**：`CustomersView.vue`、`ContractsView.vue`、`DeliveriesView.vue`
+
+### 4.2 Tree + 列表页（许可证管理）
+
+```
+┌──────────┬──────────────────────────────┐
+│ 🔍搜索   │ 统计卡片                       │
+│          │ [47] [38] [6] [3]            │
+│ ▸ 项目A  ├──────────────────────────────┤
+│ ▸ 项目B  │ [🔍] [类型▼] [状态▼] [查询]    │
+│ ▸ 项目C  │              [+ 签发许可证]    │
+│          ├──────────────────────────────┤
+│          │ 表格                          │
+│          │ 许可证ID │ 租户 │ 产品 │ ...   │
+│          │ ...                           │
+└──────────┴──────────────────────────────┘
+```
+
+**对应文件**：`LicenseList.vue`
+
+### 4.3 工作台
+
+```
+┌──────────────────────────────────────────┐
+│ [总许可证] [活跃终端] [待处理] [本月签发]   │
+├──────────────────────┬───────────────────┤
+│ 📊 许可证签发趋势      │  ⚠️ 待处理事项     │
+│ (柱状图)              │  · Callback 待处理 │
+│                      │  · 许可证将到期    │
+│                      │  · 终端额度满      │
+└──────────────────────┴───────────────────┘
+```
+
+**对应文件**：`HomeView.vue`（待完善为仪表盘）
+
+---
+
+## 5. 弹框体系
+
+### 5.1 基础规范
+
+```
+┌─────────────────────────────────┐
+│ 标题                     ✕ 关闭  │  ← Header: padding 16px/20px
+├─────────────────────────────────┤  ← 圆角: 8px
+│                                 │     阴影: 0 8px 40px rgba(0,0,0,.15)
+│  表单内容区                      │  ← Body: padding 20px
+│                                 │     表单项间距: 16px
+│  label: [______________]        │     标签色: #606266
+│                                 │
+├─────────────────────────────────┤
+│          [取消]    [确认/签发]    │  ← Footer: gap 10px, 右对齐
+└─────────────────────────────────┘
+
+遮罩: rgba(0,0,0,.45)
+动画: scale(.96→1) + opacity 200ms
+关闭按钮: 28×28, hover #F2F5FC
+```
+
+### 5.2 类型规格
+
+| 类型 | 宽度 | Header | 内容布局 | Footer |
+|------|:--:|--------|---------|--------|
+| 签发表单 | 560px | 标题+关闭 | 6+ 字段 + 特性复选框 | 取消+签发 |
+| 新建/编辑 | 480px | 标题+关闭 | 2-4 字段 | 取消+保存 |
+| 详情查看 | 480-520px | 标题+关闭 | KV 对(标签100px) | 关闭(+操作) |
+| 确认删除 | 420px | — | 居中图标+说明 | 取消+删除(红) |
+| 危险操作 | 420px | — | 红色危险提示区 | 取消+确认(红) |
+
+### 5.3 危险操作区分
+
+```css
+/* 普通确认：居中图标 + 文字 */
+/* 危险确认：额外红色背景提示区 */
+.danger-zone {
+  background: #FEF0F0; border: 1px solid #FBC4C4;
+  border-radius: 4px; padding: 10px 12px;
+  color: #F56C6C; font-size: 12px;
+}
+```
+
+---
+
+## 6. 实施指南
+
+### 6.1 Element Plus CSS 覆盖
+
+```css
+:root {
+  /* 核心 3 行 */
+  --el-color-primary: #2C3E6B;
+  --el-bg-color-page: #EAEFFA;
+  --el-border-radius-base: 6px;
+
+  /* 扩展 */
+  --el-color-primary-light-3: #3D5A99;
+  --el-color-primary-light-9: #D6DFF0;
+  --el-color-success: #1A7A3A;
+  --el-color-danger: #F56C6C;
+  --el-table-header-bg-color: #F2F5FC;
+  --el-table-header-text-color: #2C3E6B;
+  --el-dialog-border-radius: 8px;
+  --el-overlay-color-lighter: rgba(0,0,0,.45);
+}
+```
+
+### 6.2 文件对照
+
+| 设计 Token | 实现文件 |
+|-----------|---------|
+| 全局变量 | `src/theme.css` |
+| 整体布局 | `src/layout/MainLayout.vue` |
+| 路由+鉴权 | `src/router/index.js` |
+| 认证状态 | `src/stores/auth.js` |
+| API 封装 | `src/api/platform.js` |
+| 许可证页 | `src/views/LicenseList.vue` |
+| 设计对比 | `src/views/LayoutCompareView.vue` |
+| Demo | `public/design-demo.html` |
+
+### 6.3 新增页面检查清单
+
+- [ ] 使用 `<script setup>` + Composition API
+- [ ] 所有 API 调用有 try/catch + `apiErrorMessage`
+- [ ] 列表有 `v-loading` / 提交有 `:loading`
+- [ ] 路由 meta 包含 `roles` 鉴权
+- [ ] 表格表头使用 `#F2F5FC` 背景
+- [ ] 状态标签使用 `.tag-active` / `.tag-revoked` 等
+- [ ] CTA 按钮使用 `.btn-cta` 带阴影
+- [ ] 弹框使用 `<el-dialog>` 自动继承 `8px` 圆角