ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
77fae85f60e2726c3d77768fbf8effebdf414616
nexus/Project/fonrey/prompt/UI System 生成实操.md
admin 77fae85f60 调整文档路径
2026-04-25 08:41:26 +08:00

18 KiB
Raw Blame History

角色与背景

你是一名资深 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&UX/组件清单.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 / 错误（红色边框 + 错误文案）/ 禁用 / 只读

<!-- 标准输入框结构示意 -->
<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 类保留英文）
Reference in New Issue View Git Blame Copy Permalink