Files
lpt-fe/roles/design-system.md

9.4 KiB
Raw Permalink Blame History

前端设计系统

  • 功能:一份人可读的设计系统说明,记录 LPT 前端的调性、颜色、间距、圆角、文字角色与组件语法,作为新增 UI 与评审的共同基准。
  • 何时用:新增页面/组件前;需要决定字号、间距、圆角、颜色取哪个值的时候;评审 UI 是否偏离现有规范时;与 roles/design-principles.md 配套使用。

调性

五个刻度上的取值(依据:个人长期使用的学习工具,中文界面,桌面为主兼顾手机,内容是学习记录):

刻度 取值 依据
能量 偏安静 每天多次打开的记录工具,不喧闹
完成度 偏精致(公差小) 长期使用,粗糙边缘会持续被看到
密度 中等偏密 复习总览要一次看全任务/残片/待归类
分量 中等 字重常规,色块面积克制
严肃度 中性偏稳重 学习记录,不玩梗、不用插画语言

一句话北极星:「像在看一本自己整理的笔记本」——安静、清楚、字先于装饰。

颜色

颜色字面量只允许出现在 src/assets/main.css,组件里一律用 var(--x)。

用途 变量 值
主色(实底、白字,满足 WCAG AA) --green-700 #237556
文字/链接用主色 --green-600 #2f8f68
悬停/描边强调 --green-500 #43a879
深色标题文字 --green-900 / --green-800 #123d2d / #1a5a42
浅色底(选中、标签底) --green-100 #eef9f3
页面底 / 卡片底 --surface / --surface-strong #f7fbf8 / #ffffff
主文字 / 次要文字 --text-primary / --text-secondary #1b2a23 / #4b6156
占位文字 --text-placeholder #69796f
实底强调色上的文字 --text-on-accent #ffffff
结构边框 --border-soft #d6e6dc
提醒语义 --accent-warning / --accent-warning-soft / --accent-warning-strong / --accent-warning-text #e6a23c / #fff8e1 / #b8860b / #856404
成功语义 --accent-success-soft / --accent-success-softer / --accent-success-strong / --accent-success-text #e8f5e9 / #f1f8e9 / #2e7d32 / #856404
阴影 --shadow-soft / --shadow-strong 见 main.css

规则:

  • 语义色同时提供浅底 + 深字一对,标签/状态块用它,不用纯色底压深字。
  • 浅色底上的正文字号颜色必须过 WCAG AA 4.5:1:提醒块内的文字用 --accent-warning-text(#856404,5.17:1,实测踩过的坑);--accent-warning-strong(3.06:1)只能用于描边等非文字场合。
  • Element Plus 的 primary 与 success 同源指向主题绿(src/assets/main.css 覆盖),组件不逐个改色。
  • 状态不只用颜色表达:配色之外配文字或图标。
  • Element Plus 默认灰阶不达标,已在 main.css 覆盖:EP 的 --el-text-color-secondary(#909399,白底 3.08:1)与 --el-text-color-placeholder(#a8abb2,2.30:1)都低于 AA,已分别改为 --text-secondary 与 --text-placeholder。不要在使用处再单独写灰色,也不要把 EP 默认灰放回来。
  • 深色模式暂未做;将来做时按「同色系降低饱和度 + 提高明度」派生,而不是把浅色值反相。

间距节奏

以 4px 为基数,只用下面这几档(当前代码里散布的 5px / 7px / 9px / 13px 属于漂移,改动到时收敛):

语义 值 用在哪
紧凑 4 / 6 / 8px 图标与文字之间、标签内边距、行内控件间距
组内 10 / 12px 卡片内相邻元素、列表条目之间
组间 14 / 16px 区块内子块之间、卡片之间
区块间 20 / 24px 页面主要区块之间
页面留白 32px 起 首屏与页脚
  • 组内紧、组间松;同一种关系用同一档。
  • 卡片内边距:常规 18px,紧凑列表行 12–14px。
  • 内容最大宽度:正文/表单页 960px 居中(如 TagReview)。

圆角、描边、阴影

  • 圆角档位(当前有 3/4/6/8/10/12/18 共 7 种,收敛为 4 档):
    • 4px 行内小控件(按钮、输入框、标签行)
    • 8px 块级容器(列表行、内嵌面板)
    • 18px 页面卡片(.surface-card)
    • 9999px 仅用于纯状态胶囊(.map-badge 这类)
  • 嵌套圆角:内层 ≤ 外层。
  • 描边统一 1px solid var(--border-soft);需要更重的分隔时靠间距与底色,不靠加粗边框。
  • 阴影只用 --shadow-soft(常态)与 --shadow-strong(悬停抬升),不为每个组件各自造值。

文字角色

固定 6 个角色,不新增中间档:

角色 字号 字重 颜色 用在哪
页面标题 clamp(24px, 3vw, 34px) 600 --text-primary .page-title,每页一个
页面区块标题 17px 600 --green-900 页面内的模块 h2(如「按任务复习」)
区块内标题 15px 600 --green-900 或 --text-primary 卡片/列表行内的 h3 与名称
正文 14px 400 --text-primary 内容、说明
辅助文字 12–13px 400 --text-secondary 提示、meta、时间
数据 13px 600 语义色 指标、覆盖率、条数;加 tabular-nums
  • 正文行高 1.6(body 已设);标题行高 1.2–1.35。
  • 中英混排时检查基线与字重观感;数字与单位不拆行。
  • 不靠加粗表达强调:优先用字号、颜色和位置差。
  • 正文对比度是硬门槛:正文与辅助文字都 ≥4.5:1;浅色底上的深字要用登记过的 token(如提醒块用 --accent-warning-text),不要拿只达到 3:1 的强调色去写文字。

组件语法

一套统一语法,跨按钮、输入、标签、状态、空态保持一致:

  • 按钮:主操作 type="success" size="large"(40px);次级 plain;编辑类 type="primary";危险 type="danger"。工具栏/页内操作用默认尺寸,列表行内用 size="small"(28px,不再调小)。同一功能不混用 success 与 primary。
  • 标签/状态胶囊:小字号、浅底 + 深字(--accent-success-soft + --green-700 等),不使用粗边框 + 重阴影。
  • 列表行:整行可点(role="link" + tabindex="0" + @keydown.enter/@keydown.space),行内附加动作 @click.stop;操作簇右对齐,不用 space-between 拉两端。
  • 列表超过一页就分页:页大小 20;列表顶部给轻量页码(「‹ 上一页 · 第 X / Y 页 · 下一页 ›」)+ 底部完整 el-pagination,避免「必须先滚到底才能再翻」。分页后滚回 Tab 头(保住「在哪个 Tab」,也让顶部页码留在视野)。
  • 列表接口用 pageNum/pageSize 并返回 PageResult<T>(records/total/size/current/pages);后端排序必须带唯一键兜底(如 id desc),否则翻页会重复或漏。
  • 汇总数字单独取全量口径(如 GET /review/summary):列表分页后把每页数字相加会得到「本页合计」而不是总数。
  • 筛选条件下推到服务端(如按标签筛任务),不在客户端筛当前页。
  • 选项类下拉(需要全部而不是一页):用专用轻量接口(如 /tasks/options),不复用带聚合的分页列表接口。
  • 需要可见的纤细分隔线与浅底胶囊要放在不透明底上:页面背景是渐变,--border-soft 纤细分隔线与 --accent-*-soft 浅底直接放上去对比只有 ~1.1:1,屏幕上等于不存在(Tab 条、胶囊都踩过)。
  • 容器语法分两级,同一页里同级条目必须用同一套:
    • 区块卡(.surface-card):18px 圆角 + 半透明底 + --shadow-soft,只用于页面级的独立区块(如待归类块),不用于列表条目。
    • 列表行:8px 圆角 + --surface-strong 纯白 + 1px var(--border-soft) + 无阴影;hover 只改边框色(可加 --shadow-soft),不做位移。同一页里任务行与导图行都走这一套。
  • 卡片:.surface-card 统一背景/圆角/阴影;hover 只做边框变色 + --shadow-soft,不做缩放、位移与发光。
  • 模块切换用 Tab:同一页里的两个并列模块(如按任务/按标签复习)用 el-tabs 同位置切换,URL 带 ?tab= 可深链;未访问过的 Tab 懒加载(lazy),Tab 标签上用胶囊显示条数并写清单位(45 个 / 3 张),让用户不进去也知道另一边有多少东西,也不会把「3 张导图」读成「3 条内容」。
  • 空状态:el-empty + 一句说明 + 一个主操作按钮(size="small" 或默认,视位置);页面级空态必须有下一步动作。
  • 等待文案:「正在 X…,已等待 N 秒」用 useElapsedSeconds(既有规则),不用固定延时。
  • 图标:当前未引入图标库;需要时按方向选一套(一产品只用一套),不混用 emoji 与 SVG。
  • 时间显示:统一用 src/utils/format.ts 的 formatDateTime(Intl),不写 replace("T"," ").substring(0,16)。

不要什么

(同 roles/design-principles.md 的禁用清单,这里只列与本设计系统直接冲突的)

  • 不新增第 6 档字号、第 5 档圆角、第 3 档阴影——需要时先改本文档,再改变量。
  • 不为单个页面另造一套色板;品牌感靠这套语义色与排版一致性,不靠换主色。
  • 不在组件里写颜色字面量或 #fff 之外的中性色(rgba(255,255,255,.85) 这类半透明卡片底除外,且应下沉为变量)。