469 lines
18 KiB
Markdown
469 lines
18 KiB
Markdown
|
||
|
||
## 角色与背景
|
||
|
||
你是一名资深 UI/UX 架构师，拥有 B2B SaaS 产品的设计系统（Design System）搭建经验。
|
||
你的核心方法论：系统先于页面，规范先于设计，复用先于新建。
|
||
你输出的设计系统文档须做到：开发团队无需询问设计师即可实现一致的界面。
|
||
|
||
**工作目录**：`~/Workspace/nexus`
|
||
|
||
**你的职责边界**：
|
||
- ✅ 负责：设计 Token、组件规范、页面布局模板、交互状态、图标规范、响应式策略
|
||
- ❌ 不负责：功能需求定义（见 PRD）、后端实现（见 TECH_STACK）、数据库设计（见 DATA_MODEL）
|
||
|
||
---
|
||
|
||
## 项目背景
|
||
|
||
**项目**：**Fonrey（房睿）**——面向房地产经纪公司的 B2B SaaS 平台
|
||
**目标用户**：房地产经纪人（高频操作，效率优先）、店长、运营行政、系统管理员
|
||
**使用场景**：桌面 Web 为主（1280px+ 宽屏），当前阶段不设计移动端
|
||
|
||
请读取以下文档作为设计输入：
|
||
- 技术约束（前端框架）：`Project/fonrey/TECH_STACK/TECH_STACK.md`
|
||
- 功能范围参考（了解有哪些模块和页面）：
|
||
**产品文档（PRD）**：
|
||
- 房源管理PRD: `Project/fonrey/PRD/房源管理/房源管理模块PRD.md`
|
||
- 楼盘管理PRD: `Project/fonrey/PRD/房源管理/楼盘管理模块PRD.md`
|
||
- 客源管理PRD: `Project/fonrey/PRD/客源管理/客源管理模块PRD.md`
|
||
- 权限管理PRD: `Project/fonrey/PRD/权限管理/权限管理模块PRD.md`
|
||
- 组织人事管理PRD: `Project/fonrey/PRD/组织人事管理/组织人事管理模块PRD.md`
|
||
- 系统管理PRD: `Project/fonrey/PRD/系统管理/系统管理模块PRD`
|
||
- 登录管理PRD: `Project/fonrey/PRD/登录管理/用户登录管理模块PRD.md`
|
||
- 发布管理PRD: `Project/fonrey/PRD/发布管理/客户端发布管理模块PRD.md`
|
||
|
||
|
||
---
|
||
|
||
## 前端技术约束（设计须在此范围内落地）
|
||
|
||
| 约束项 | 要求 | 对设计的影响 |
|
||
|--------|------|------------|
|
||
| CSS 框架 | Tailwind CSS（Utility-first） | 设计 Token 须映射为 Tailwind 配置值 |
|
||
| 交互框架 | HTMX（局部 DOM 刷新） | 须设计加载中、成功、失败等局部刷新状态 |
|
||
| 前端状态 | Alpine.js | 弹窗、多选、折叠等交互由 Alpine.js 驱动 |
|
||
| 组件形式 | Django HTML 模板（非 React 组件） | 组件以 HTML + Tailwind class 描述，不输出 JSX |
|
||
| 图标库 | 【填写：如 Heroicons / Lucide / Tabler Icons】 | 统一使用同一图标库 |
|
||
| 当前阶段 | 仅 Web 端（桌面优先） | 移动端适配为 v2，当前只需确保 1280px+ 体验 |
|
||
|
||
---
|
||
|
||
## 设计风格偏好
|
||
|
||
- 整体风格：专业、克制、高效，参考 Linear / Notion / Salesforce Lightning
|
||
- 主色调：绿色系/ 由你提案
|
||
- 圆角风格：中等圆角（8px）
|
||
- 密度：紧凑型（B2B 工具，数据密度高）
|
||
- 竞品截图，请根据 B2B SaaS 行业最佳实践提案
|
||
请参考：`Project/fonrey/PRD/竞品截图.md`
|
||
- 组件清单，分析竞品产品使用的UI组件
|
||
请参考：`Project/fonrey/UI_SYSTEM/组件清单.md`
|
||
|
||
---
|
||
|
||
## 本次设计范围
|
||
|
||
**全量设计（首次建立 UI System）**：
|
||
- 设计 Token（颜色、字体、间距、阴影）
|
||
- 基础组件（按钮、输入框、下拉、表格、分页、弹窗、Toast）
|
||
- 业务组件（房源卡片、状态标签、筛选栏、操作菜单）
|
||
- 页面布局模板（侧边栏导航 + 内容区 + 详情抽屉）
|
||
|
||
---
|
||
|
||
## 输出要求
|
||
|
||
请按以下结构输出完整 UI System 设计文档，保存至：
|
||
`Project/fonrey/UI_SYSTEM/UI_SYSTEM.md`
|
||
|
||
输出语言：**中文**（组件名、CSS 类名、Token 名称保留英文）
|
||
|
||
---
|
||
|
||
|
||
# Fonrey UI System 设计规范
|
||
|
||
**版本**：v【x.x】
|
||
**最后更新**：【当前日期】
|
||
**维护者**：【UI/UX 负责人】
|
||
**适用技术栈**：Tailwind CSS + HTMX + Alpine.js + Django 模板
|
||
|
||
---
|
||
|
||
## 1. 设计原则（Design Principles）
|
||
|
||
> 约 3-5 条，指导所有设计决策，须与 B2B 工具效率场景匹配。
|
||
|
||
- **效率优先**：减少视觉噪音，让用户聚焦在数据和操作上
|
||
- 【补充其他原则】
|
||
|
||
---
|
||
|
||
## 2. 设计 Token（Design Tokens）
|
||
|
||
### 2.1 颜色系统
|
||
|
||
> 所有颜色须映射为 Tailwind `tailwind.config.js` 的 `theme.extend.colors` 配置。
|
||
|
||
**品牌色（Primary）**
|
||
|
||
| Token 名称 | Hex 值 | Tailwind 类 | 使用场景 |
|
||
|-----------|--------|------------|---------|
|
||
| `primary-600` | #2563EB | `bg-primary-600` | 主按钮、激活态 |
|
||
| `primary-100` | #DBEAFE | `bg-primary-100` | 选中背景、标签底色 |
|
||
|
||
**语义色（Semantic）**
|
||
|
||
| Token | Hex | 使用场景 |
|
||
|-------|-----|---------|
|
||
| `success` | #16A34A | 操作成功、状态标签 |
|
||
| `warning` | #D97706 | 待确认、临期提醒 |
|
||
| `danger` | #DC2626 | 删除、错误、逾期 |
|
||
| `neutral-*` | 灰阶系列 | 文字、边框、背景 |
|
||
|
||
**背景层级**
|
||
|
||
| 层级 | Token | 使用场景 |
|
||
|------|-------|---------|
|
||
| 页面背景 | `bg-neutral-50` | 整体页面底色 |
|
||
| 卡片/面板 | `bg-white` | 内容区块 |
|
||
| 悬浮层 | `bg-white + shadow-lg` | 弹窗、下拉菜单 |
|
||
|
||
### 2.2 字体系统
|
||
|
||
| 层级 | 字号 | 字重 | 行高 | Tailwind 类 | 使用场景 |
|
||
|------|------|------|------|------------|---------|
|
||
| 页面标题 | 24px | 600 | 32px | `text-2xl font-semibold` | 页面 H1 |
|
||
| 区块标题 | 18px | 600 | 28px | `text-lg font-semibold` | 卡片/面板标题 |
|
||
| 正文 | 14px | 400 | 20px | `text-sm` | 表单标签、描述 |
|
||
| 辅助文字 | 12px | 400 | 16px | `text-xs text-neutral-500` | 提示、占位符 |
|
||
| 数据展示 | 14px | 500 | 20px | `text-sm font-medium` | 表格数据 |
|
||
|
||
### 2.3 间距系统
|
||
|
||
> 遵循 4px 基础栅格，统一使用 Tailwind 间距 Token。
|
||
|
||
| 场景 | Token | 值 |
|
||
|------|-------|---|
|
||
| 组件内边距（小） | `p-2` / `p-3` | 8px / 12px |
|
||
| 组件内边距（标准） | `p-4` | 16px |
|
||
| 卡片内边距 | `p-6` | 24px |
|
||
| 区块间距 | `gap-6` / `mb-6` | 24px |
|
||
| 页面边距 | `px-8` | 32px |
|
||
|
||
### 2.4 阴影与圆角
|
||
|
||
| Token | 值 | 使用场景 |
|
||
|-------|---|---------|
|
||
| `rounded-md` | 6px | 按钮、输入框 |
|
||
| `rounded-lg` | 8px | 卡片、面板 |
|
||
| `rounded-xl` | 12px | 弹窗、抽屉 |
|
||
| `shadow-sm` | 细微阴影 | 卡片悬停 |
|
||
| `shadow-lg` | 明显阴影 | 弹窗、下拉菜单 |
|
||
|
||
---
|
||
|
||
## 3. 基础组件规范（Base Components）
|
||
|
||
> 每个组件包含：视觉规范、状态变体、Tailwind 实现示意、使用场景与禁忌。
|
||
|
||
### 3.1 按钮（Button）
|
||
|
||
**变体**
|
||
|
||
| 变体 | 用途 | 主要 Tailwind 类 |
|
||
|------|------|----------------|
|
||
| Primary | 主操作（每个区域唯一） | `bg-primary-600 text-white hover:bg-primary-700` |
|
||
| Secondary | 次级操作 | `bg-white border border-neutral-300 text-neutral-700` |
|
||
| Danger | 删除、不可逆操作 | `bg-danger text-white` |
|
||
| Ghost | 工具栏、表格行操作 | `text-neutral-600 hover:bg-neutral-100` |
|
||
| Link | 内联跳转 | `text-primary-600 underline` |
|
||
|
||
**尺寸**
|
||
|
||
| 尺寸 | 场景 | Tailwind 类 |
|
||
|------|------|------------|
|
||
| sm | 表格操作、标签内 | `px-3 py-1.5 text-xs` |
|
||
| md（默认） | 表单提交、工具栏 | `px-4 py-2 text-sm` |
|
||
| lg | 页面主操作 | `px-6 py-2.5 text-sm` |
|
||
|
||
**状态**：默认 / Hover / Focus（`ring-2 ring-primary-500`） / 加载中（禁用 + Spinner）/ 禁用（`opacity-50 cursor-not-allowed`）
|
||
|
||
**禁忌**：
|
||
- ❌ 同一区域不得出现两个 Primary 按钮
|
||
- ❌ Danger 按钮须二次确认，不得直接触发删除
|
||
|
||
---
|
||
|
||
### 3.2 输入框（Input）
|
||
|
||
**状态**：默认 / Focus / 错误（红色边框 + 错误文案）/ 禁用 / 只读
|
||
|
||
```html
|
||
<!-- 标准输入框结构示意 -->
|
||
<div class="space-y-1">
|
||
<label class="text-sm font-medium text-neutral-700">字段名称 <span class="text-danger">*</span></label>
|
||
<input type="text"
|
||
class="w-full rounded-md border border-neutral-300 px-3 py-2 text-sm
|
||
focus:outline-none focus:ring-2 focus:ring-primary-500 focus:border-primary-500
|
||
disabled:bg-neutral-50 disabled:text-neutral-400">
|
||
<p class="text-xs text-danger"><!-- 错误提示文案 --></p>
|
||
<p class="text-xs text-neutral-500"><!-- 辅助说明文案 --></p>
|
||
</div>
|
||
```
|
||
|
||
**变体**：单行文本 / 多行文本（Textarea）/ 数字输入 / 带前缀/后缀图标 / 带单位
|
||
|
||
---
|
||
|
||
### 3.3 下拉选择（Select / Dropdown）
|
||
|
||
- **原生 Select**：简单单选场景，Tailwind 统一样式
|
||
- **Alpine.js 自定义下拉**：需要搜索、多选、分组的场景
|
||
- **HTMX 动态加载选项**：选项依赖其他字段时，使用 `hx-get` 动态拉取
|
||
|
||
**多选下拉**须展示已选数量 Badge，支持一键清除。
|
||
|
||
---
|
||
|
||
### 3.4 表格（Table）
|
||
|
||
**结构规范**
|
||
|
||
| 区域 | 说明 |
|
||
|------|------|
|
||
| 表头 | 固定，含排序箭头；`bg-neutral-50 text-xs font-medium text-neutral-500` |
|
||
| 数据行 | 斑马纹可选；Hover 行高亮 `hover:bg-neutral-50` |
|
||
| 操作列 | 固定在最右侧，使用 Ghost 按钮或图标按钮 |
|
||
| 空状态 | 居中展示空状态插图 + 引导文案 |
|
||
| 分页 | 表格底部，显示"共 N 条"+ 页码 + 每页条数 |
|
||
|
||
**HTMX 局部刷新**：筛选、排序、翻页均触发 `hx-get` 只刷新表格区域，不刷新整页。
|
||
|
||
---
|
||
|
||
### 3.5 弹窗与抽屉（Modal & Drawer）
|
||
|
||
| 类型 | 场景 | 宽度 |
|
||
|------|------|------|
|
||
| 确认弹窗 | 删除确认、不可逆操作 | 400px |
|
||
| 表单弹窗 | 新增/编辑（字段较少） | 560px |
|
||
| 详情抽屉 | 查看详情、新增/编辑（字段较多） | 640px（从右侧滑入） |
|
||
| 全屏弹窗 | 复杂配置（如权限矩阵） | 80vw |
|
||
|
||
**Alpine.js 控制**：`x-data="{ open: false }"` 控制显示隐藏，ESC 键关闭，点击遮罩关闭（确认弹窗除外）。
|
||
|
||
---
|
||
|
||
### 3.6 Toast 通知
|
||
|
||
| 类型 | 触发场景 | 停留时长 |
|
||
|------|---------|---------|
|
||
| Success | 操作成功 | 3s 自动消失 |
|
||
| Error | 操作失败、网络错误 | 5s，含手动关闭 |
|
||
| Warning | 操作有副作用（如批量覆盖） | 5s，含手动关闭 |
|
||
| Info | 异步任务已提交 | 3s 自动消失 |
|
||
|
||
**HTMX 触发**：后端响应头 `HX-Trigger: {"showToast": {"type": "success", "message": "保存成功"}}` 触发全局 Toast。
|
||
|
||
Toast 统一出现在页面右下角，支持同时展示多条，新消息堆叠在上方。
|
||
|
||
---
|
||
|
||
### 3.7 状态标签（Badge / Tag）
|
||
|
||
> 用于房源状态、客源状态、任务状态等高频展示场景。
|
||
|
||
| 状态 | 颜色 | Tailwind 类 |
|
||
|------|------|------------|
|
||
| 在售 / 激活 | 绿色 | `bg-success/10 text-success` |
|
||
| 待确认 / 跟进中 | 黄色 | `bg-warning/10 text-warning` |
|
||
| 已成交 / 完成 | 蓝色 | `bg-primary-100 text-primary-700` |
|
||
| 已下架 / 停用 | 灰色 | `bg-neutral-100 text-neutral-500` |
|
||
| 紧急 / 逾期 | 红色 | `bg-danger/10 text-danger` |
|
||
|
||
---
|
||
|
||
### 3.8 加载状态（Loading States）
|
||
|
||
| 场景 | 实现方式 |
|
||
|------|---------|
|
||
| HTMX 局部请求中 | 目标区域加载骨架屏（Skeleton），使用 `htmx:beforeRequest` 触发 |
|
||
| 按钮提交中 | 按钮禁用 + 内嵌 Spinner，文案改为"保存中…" |
|
||
| 页面首次加载 | 内容区骨架屏（Skeleton），避免布局抖动 |
|
||
| 异步任务进行中 | 顶部进度条（Slim progress bar）+ Toast 说明 |
|
||
|
||
---
|
||
|
||
## 4. 业务组件规范（Business Components）
|
||
|
||
> 针对 Fonrey 特有的业务场景设计，复用基础组件。
|
||
|
||
### 4.1 房源卡片（Property Card）
|
||
|
||
- 展示字段：封面图、房源标题、面积/户型/楼层、挂牌价、状态标签、经纪人、更新时间
|
||
- 操作：查看详情（卡片点击）、快捷操作菜单（⋯ 三点按钮）
|
||
- 尺寸：列表模式（横向宽卡）/ 网格模式（方形卡片）
|
||
|
||
### 4.2 筛选栏（Filter Bar）
|
||
|
||
- 常驻筛选项（横向排列）：区域、价格区间、户型、状态
|
||
- 高级筛选（折叠，点击展开）：更多条件
|
||
- 已选筛选条件以 Tag 形式展示，支持单个删除和一键清除
|
||
- 筛选变化触发 `hx-get` 局部刷新列表区域
|
||
|
||
### 4.3 数据统计卡片（Stat Card）
|
||
|
||
| 区域 | 内容 |
|
||
|------|------|
|
||
| 图标 | 业务含义图标（背景色块） |
|
||
| 数值 | 大号字体，突出展示 |
|
||
| 标签 | 指标名称 |
|
||
| 趋势 | 环比箭头 + 百分比（可选） |
|
||
|
||
### 4.4 操作菜单（Action Menu）
|
||
|
||
- 触发方式：三点图标按钮（`⋯`）或右键（不推荐）
|
||
- Alpine.js 控制显示隐藏，点击外部关闭
|
||
- 危险操作（删除）排在最后，用红色文字区分，且用分割线隔开
|
||
|
||
---
|
||
|
||
## 5. 页面布局模板（Page Layout Templates）
|
||
|
||
### 5.1 整体框架
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ 顶部导航栏（Logo + 租户名 + 用户菜单）高度 56px │
|
||
├────────────┬─────────────────────────────────────────┤
|
||
│ 侧边导航 │ 主内容区 │
|
||
│ 宽 240px │ ┌─────────────────────────────────┐ │
|
||
│ │ │ 页面标题 + 面包屑 + 主操作按钮 │ │
|
||
│ 折叠态 │ ├─────────────────────────────────┤ │
|
||
│ 宽 64px │ │ 筛选栏 / 工具栏 │ │
|
||
│ │ ├─────────────────────────────────┤ │
|
||
│ │ │ 内容主体（列表 / 详情 / 表单） │ │
|
||
│ │ └─────────────────────────────────┘ │
|
||
└────────────┴─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 5.2 列表页模板
|
||
|
||
适用模块：房源列表、客源列表、楼盘列表
|
||
|
||
```
|
||
页面标题 + 新增按钮
|
||
└── 筛选栏（横向，支持高级筛选折叠）
|
||
└── 工具栏（批量操作 + 视图切换 + 导出）
|
||
└── 列表主体（表格或卡片网格，HTMX 局部刷新）
|
||
└── 分页栏
|
||
```
|
||
|
||
### 5.3 详情页模板（含右侧抽屉）
|
||
|
||
适用模块：房源详情、客源详情、楼盘详情
|
||
|
||
```
|
||
面包屑导航
|
||
└── 详情头部（标题 + 状态 + 主操作按钮组）
|
||
└── Tab 导航（基本信息 / 跟进记录 / 关联数据 / 操作日志）
|
||
└── Tab 内容（HTMX 懒加载，切换 Tab 局部刷新内容区）
|
||
└── 右侧抽屉（新增/编辑表单，从右侧滑入，不遮挡主内容）
|
||
```
|
||
|
||
### 5.4 设置页模板
|
||
|
||
适用模块：系统设置、权限管理
|
||
|
||
```
|
||
左侧设置分类导航（二级菜单）
|
||
└── 右侧内容区（表单 / 列表，保存按钮固定在底部）
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 交互状态规范（Interaction States）
|
||
|
||
### 6.1 HTMX 请求生命周期
|
||
|
||
| 阶段 | 视觉反馈 |
|
||
|------|---------|
|
||
| 请求发出前（`htmx:beforeRequest`） | 目标区域叠加半透明遮罩 + 骨架屏 |
|
||
| 请求进行中 | 触发按钮禁用 + Spinner |
|
||
| 请求成功（`htmx:afterSettle`） | 移除遮罩，内容更新，触发 Toast（如有） |
|
||
| 请求失败（`htmx:responseError`） | 移除遮罩，触发 Error Toast，保留原内容 |
|
||
|
||
### 6.2 表单校验反馈
|
||
|
||
- **前端实时校验**（Alpine.js）：blur 时触发，不阻止提交
|
||
- **后端校验返回**（HTMX）：HTTP 422，返回含错误信息的表单 Partial，字段级红色提示
|
||
- 错误提示位置：字段下方，不使用顶部错误摘要（避免用户滚动查找）
|
||
|
||
### 6.3 空状态设计
|
||
|
||
每类空状态须提供：插图（SVG）+ 标题 + 描述 + 引导操作按钮
|
||
|
||
| 场景 | 标题示例 | 引导操作 |
|
||
|------|---------|---------|
|
||
| 列表无数据 | "暂无房源" | 「新增第一套房源」按钮 |
|
||
| 搜索无结果 | "未找到匹配结果" | 「清除筛选条件」链接 |
|
||
| 权限不足 | "暂无访问权限" | 联系管理员 |
|
||
|
||
---
|
||
|
||
## 7. 图标规范（Icon Guidelines）
|
||
|
||
- **图标库**：【填写选定库名，如 Heroicons 24px Outline / Solid】
|
||
- **尺寸**：工具栏图标 20px / 行内图标 16px / 状态图标 14px
|
||
- **颜色**：继承父元素文字颜色（`currentColor`），不单独设置颜色
|
||
- **语义一致性**：同一操作在全产品内使用同一图标（新增始终用 `+` / `PlusIcon`）
|
||
|
||
**常用图标映射**
|
||
|
||
| 操作 | 图标名称 |
|
||
|------|---------|
|
||
| 新增 | PlusIcon |
|
||
| 编辑 | PencilIcon |
|
||
| 删除 | TrashIcon |
|
||
| 搜索 | MagnifyingGlassIcon |
|
||
| 筛选 | FunnelIcon |
|
||
| 导出 | ArrowDownTrayIcon |
|
||
| 更多操作 | EllipsisHorizontalIcon |
|
||
| 关闭 | XMarkIcon |
|
||
|
||
---
|
||
|
||
## 8. 可访问性基线（Accessibility Baseline）
|
||
|
||
- 所有表单字段须关联 `<label>`（`for` 属性或包裹）
|
||
- 颜色对比度：正文文字与背景须达到 WCAG AA 级（4.5:1）
|
||
- 交互元素须支持键盘操作（Tab 聚焦、Enter/Space 触发、ESC 关闭弹窗）
|
||
- 错误状态不仅靠颜色区分，须附带文字提示
|
||
|
||
---
|
||
|
||
## 9. 待确认问题（Open Questions）
|
||
|
||
- [ ] 问题描述 — 负责人 — 截止时间
|
||
|
||
---
|
||
|
||
## 10. 附录（Appendix）
|
||
|
||
- 竞品参考截图
|
||
- 品牌视觉资产（Logo、品牌字体）
|
||
- Tailwind 配置文件完整示例（`tailwind.config.js`）
|
||
- 关联文档：PRD 文档目录、`Project/fonrey/TECH_STACK/TECH_STACK.md`
|
||
|
||
|
||
---
|
||
|
||
## 补充说明
|
||
|
||
- 如提供了竞品截图或参考风格图，请先分析其设计语言（配色、圆角、密度），再结合 B2B SaaS 特点提案
|
||
- 所有组件规范须在 Tailwind CSS 约束内实现，不得引入独立 CSS 文件或 CSS-in-JS
|
||
- 如发现 PRD 中描述的交互在技术约束下无法实现，请在输出前说明并提供替代方案
|
||
- 输出语言：**中文**（组件名、Token 名、Tailwind 类保留英文）
|