tomevault-io Frontend Design Skill
为本仓库 front 下的 Vue 管理后台提供统一的视觉和交互规范。目标不是做通用网页，而是做克制、清晰、可维护、适合桌面和移动端的后台界面。
1. 设计方向
- 风格：极简、亮色、黑白灰为主，避免花哨装饰。
- 场景：管理后台、CRUD 页面、统计页、配置页、弹窗表单。
- 原则：先保证信息层级、操作可达性、响应式可用性，再谈视觉细节。
- 响应式立场：移动端不是附加补丁，默认按 mobile-first 思考，再向上增强桌面布局。
2. 技术与组件约束
2.1 基础技术栈
- 框架：
vue3、vue-router、pinia - 样式：
tailwindcssv4、tailwind-merge、clsx - UI primitive：
reka-ui - 图标：
lucide-vue-next - 图表：
echarts、vue-echarts
2.2 组件目录
- 业务页面：
front/src/pages - 布局：
front/src/layouts - 全局组件：
front/src/components - UI 原子组件：
front/src/components/ui
不要绕过现有 UI 组件重复造轮子。优先复用：
ButtonInputSelectDialogTableCheckboxCardBadgePaginationPopoverToast
补充规则：
- 对附加说明、warning 详情、fallback 信息、帮助提示等次级信息，优先使用
Popover，不要默认直接展开。 - 不要优先依赖浏览器原生
title承载主要交互信息，除非只是极轻量的临时提示。
3. 视觉系统
3.1 色彩
默认只使用灰阶，强调色只用于交互态和选中态。
页面背景: bg-gray-50
卡片/表格/弹窗: bg-white
主要文字: text-gray-900
正文文字: text-gray-600
辅助文字: text-gray-500 / text-gray-400
边框: border-gray-200
弱分隔线: border-gray-100
表头背景: bg-gray-50/80
规则：
- 不要做大面积彩色背景。
- 不要引入渐变、发光、玻璃拟态、重阴影。
- 删除/危险态仅在按钮 hover、提示和错误态中使用红色。
3.2 阴影与边框
- 卡片、表格、表单区、弹窗优先用边框，不用阴影。
- 常用外框：
border border-gray-200 rounded-lg - 弱分隔：
border-t border-gray-100 - 避免把信息页拆成大量小卡片，这会削弱阅读连续性和聚焦。连续信息优先使用分组列表、
dl、带分隔线的网格或表格行；只有需要强调单个核心指标时才使用卡片。 - 避免反复使用
border border-gray-200包裹每个信息块，这会快速把页面做成一堆伪卡片。信息页优先依靠留白、对齐、border-b/divide-*分隔，而不是给每个区块单独画边框。
3.3 排版
- 页面标题：
text-lg font-semibold text-gray-900 tracking-tight sm:text-xl - 页面描述：
mt-1 text-sm text-gray-500 - 区块标题：
text-base font-semibold text-gray-900 - 表头：
text-xs font-medium text-gray-500 uppercase tracking-wider - 正文：
text-sm - 技术值：
font-mono text-xs text-gray-600 - 必填星号：
<span class="text-red-500 ml-0.5">*</span>
4. 移动端与响应式规范
这是当前技能必须覆盖的重点。已落地的全局基线在 front/src/style.css，新增页面或重构页面时应优先复用，不要自行发明另一套骨架。
4.1 全局基线
已存在的通用类：
.app-page.app-page-shell.app-page-shell--narrow.app-section.app-stack-sm.app-stack-md.app-scroll-x
含义：
app-page：页面外层，负责统一 padding 和 safe area。app-page-shell：页面内容壳层，负责统一最大宽度和纵向节奏。app-page-shell--narrow：编辑页等窄内容页面。app-scroll-x：需要横向滚动的局部容器。
规则：
- 页面不要再直接从
p-6起手，优先使用app-page和app-page-shell。 - 不要假定
100vh稳定，优先使用现有min-h-dvh/100dvh基线。 - 不要让
body或页面主容器出现无意义横向滚动。
4.2 页面头部
统一模式：
<div class="app-page">
<div class="app-page-shell">
<div class="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
<div class="min-w-0">
<h1 class="text-lg font-semibold text-gray-900 tracking-tight sm:text-xl">
标题
</h1>
<p class="mt-1 text-sm text-gray-500">描述</p>
</div>
<div class="flex w-full flex-col gap-2 sm:w-auto sm:flex-row sm:items-center">
<!-- actions -->
</div>
</div>
</div>
</div>
规则：
- 小屏下标题区和操作区默认纵向堆叠。
- 主操作按钮在小屏下允许独占一行，不要强行横排。
- 长标题或描述必须允许截断或换行，不要写死单行布局。
4.3 导航
当前布局基线：
- 桌面端：侧栏，可折叠。
- 移动端：顶部栏 + 抽屉导航 + 遮罩。
规则：
- 修改主布局时必须同时考虑桌面和移动端两套表现。
- 移动端顶部栏要保证页面标题、菜单按钮、语言切换可达。
- 抽屉打开时要考虑遮罩、路由切换自动关闭、
body滚动锁定。
4.4 表单响应式
- 单列优先，桌面再增强双列。
- 已有
grid grid-cols-2 gap-4的表单，响应式改造时优先改成grid grid-cols-1 sm:grid-cols-2 gap-4。 - Select 触发器在表单中显式加
class="w-full"。 - Checkbox / 开关项放入带边框容器：
flex items-center justify-between p-3.5 border border-gray-200 rounded-lg
4.5 表格与列表
- 桌面端可以保留表格。
- 移动端如果列很多，不要只依赖横向滚动，应优先考虑卡片化。
- 仍需保留表格时，用带边框容器包裹，并确保滚动只发生在局部。
基础样式：
- 外层：
border border-gray-200 rounded-lg overflow-hidden - 表头行：
bg-gray-50/80 hover:bg-gray-50/80 - 操作列：
text-right
4.6 弹窗
- 简单弹窗：
max-w-lg - 复杂弹窗：
max-w-4xl - 移动端弹窗必须考虑：
- 全宽边距
- 最大高度
- 内容区独立滚动
- 底部操作按钮稳定可见
4.7 安全区
项目已经引入 safe area 变量与 viewport-fit=cover。在移动端顶部栏、底部按钮区、全屏弹层中，优先复用现有基线，不要硬编码设备特例。
5. 组件使用规范
5.1 Button
- 页面主操作：
variant="outline"，通常配 Lucide 图标 - 保存：
variant="default" - 取消：
variant="ghost" class="text-gray-600" - 表格编辑：
variant="ghost" size="sm" - 表格删除：
variant="ghost" size="sm" class="text-gray-400 hover:text-red-600"
图标尺寸：
- 常规按钮：
h-4 w-4 mr-1.5 - 表格操作：
h-3.5 w-3.5 mr-1
5.2 Badge
- 状态/枚举：
variant="secondary"+font-mono text-xs - 次级标签：
variant="outline"+text-xs
5.3 Checkbox
- 禁止原生
<input type="checkbox"> - 统一使用
@/components/ui/checkbox
5.4 空状态
- 外层：
flex flex-col items-center justify-center py-20 - 图标：
h-10 w-10 stroke-1 text-gray-400 - 文案：
text-sm font-medium text-gray-500
5.5 加载状态
- 外层：
flex items-center justify-center py-16 - 图标：
<Loader2 class="h-5 w-5 animate-spin" />
6. 推荐页面模板
6.1 CRUD 页面
优先使用 CrudPageLayout.vue，不要重复实现页面外层、标题区和状态区。
6.2 自定义页面
当页面不适合 CrudPageLayout 时，至少复用：
app-pageapp-page-shell- 移动端优先的标题区布局
7. 当前仓库中的已知方向
在本仓库里设计或改页面时，优先遵守这几个方向：
- 已完成：
- 全局移动端 spacing / safe area /
dvh基线 - 默认布局的移动端顶部栏与抽屉导航
- 页面级统一骨架与标题区模式
- 全局移动端 spacing / safe area /
- 后续仍会继续加强：
- UI 原子组件的移动端触控尺寸
- 弹窗滚动与底部操作区
- 多列表格页的移动端卡片化
- 复杂编辑页的单列化与区块重排
这意味着：
- 新增页面应直接站在“移动端已是一级约束”的基础上设计。
- 不要再新增只适合桌面端的大宽度、固定高度、横向挤压布局。
8. 禁止事项
- 不要使用阴影作为主要层次手段。
- 不要硬编码中文文案，必须走 i18n。
- 不要引入新的高饱和品牌色体系。
- 不要绕过现有 UI primitive 直接写原生替代品。
- 不要默认写死
p-6、max-w-4xl mx-auto作为页面骨架，除非与app-page-shell--narrow等基线兼容。 - 不要把移动端适配理解为“桌面完成后补几个
sm:/md:”。 - 不要在复杂多列表格上只加
overflow-x-auto就算完成移动端支持；先评估是否应改成卡片列表。
Converted and distributed by TomeVault — claim your Tome and manage your conversions.