用VUE3做的宋式风格UI库

19 KiB

Raw Blame History

SongUI 研究报告 — 宋韵·至简设计语言契约

本文档为设计语言交付契约，供前端 Agent 与其他美工 Agent 直接执行。每条规则均附「理由」与「取舍」，任何偏离需先与本文档对齐，禁止静默修改。

适用技术栈：Vue 3 + Vite 交付形态：设计系统 Token + 组件库主题 目标场景：展示型内容站与中后台（通过留白梯度级联兼容）

0. 主题定位

主题命名：SongUI · 檐下
一句话主张：安静、留白、玉质温润、书卷气。
对标说明：以现代极简（扁平、克制、少即是多）为骨架，注入宋代美学的三样东西——单一色钉锚（天青为魂）、材质温度（玉釉质感）、书卷气（版式与字体）。

设计三原则

原则	宋代来源	现代翻译
克制留白	马远"马一角"、夏圭"夏半边"，画面着墨不足十分之一	内容取边角聚拢，版面大量留白，信息密度受控
单一色钉锚	汝窑天青、龙泉粉青/梅子青，低饱和单色为主	全系统仅一个主色系，其余全靠明度/材质分层
结构即装饰	三清殿减柱造，"少即是多"，结构理性主义	去除装饰性元素，让间距、线条、栅格本身构成美感

禁区声明：本主题不是"复古穿越"或"新中式堆砌"。禁止龙凤、祥云、具象争纸等符号直用；一切纹样必须几何化、抽象化、低占比。

1. 美学溯源摘要

1.1 建筑（清雅柔逸 · 结构理性）

宋代建筑由唐之雄浑转向纤巧秀丽、清雅柔逸，屋脊起翘、出檐深远，尺度收小。
斗拱从装饰重归承重结构，"结构本身即最美的装饰"（三清殿"一斗六升"）。
减柱造 / 移柱造：以梁跨代柱，少即是多，营造"疏朗、空灵"的内部空间。
直棂窗：竖向木条疏朗排列，无横向干扰，极简单线构成。
翻译进 UI：① 控件/卡片不要加无意义的描边花纹；② 用 1px 墨线系统表达结构；③ 竖线分割（直棂意象）代替复杂分隔设计。

1.2 瓷器（天青为魂 · 素为至雅）

汝窑釉色青中透蓝、低饱和、内敛，宋徽宗"雨过天晴云破处，这般颜色做将来"。
造型极简（无纹圆器），"质"胜于"饰"；釉质如玉、光影温润，开片纹理天成。
翻译进 UI：① 主色天青，禁止高饱和跳色；② 层级靠材质质感（微渐变/半透明/光感），不靠花哨装饰；③ 背景可用极淡冰裂纹肌理模拟釉质。

1.3 绘画（留白 · 边角 · 墨分五色）

马夏边角构图：画面焦点集中、近景实、远景淡、中景舍去，大片空白造"辽阔无垠"之境。
墨分五色：焦、浓、重、淡、清，以明度而非色相组织空间。
翻译进 UI：① 列表/卡片排版取"边角聚拢、中央留白"；② 文字层级用墨色浓淡（近景=深墨正文，远景=淡墨弱化）；③ 加载/转场用淡墨晕染。

1.4 书法与印刷（瘦金体 · 宋版书）

瘦金体：宋徽宗独创，屈铁断金、瘦硬劲挺，装饰性极强——但版权敏感，见 §2.6 免责声明。
宋版书：版面疏朗、字大行疏、版心居中，雕版刀痕的呼吸感。
翻译进 UI：① 大标题可用带书法韵味的开源字体（霞鹜文楷）；② 正文靠网格系统与留白复刻"版心居中"的疏朗感。

1.5 色彩（青绿碾玉 · 丹粉刷饰）

宋式彩画《营造法式》有关：碾玉装冷青绿、五彩遍装华丽——取碾玉装的冷雅为底色原则，弃其繁缛。
城市/民居：青灰砖瓦为主，红白粉墙点缀，艳色小面积使用。
翻译进 UI：主冷色 + 小面积赭石/胭脂/缃色点睛（见 §2.3 色彩配额）。

2. 色彩系统 Token

2.1 宋韵色谱（基准色，初稿需以屏显感知校准）

色名	HEX	角色
天青	`#88ADED`	主色锚点（primary）
月白	`#D6ECF0`	浅底、呼吸空间
青白	`#C7DBD9`	浅底备选、冷色中性
竹青	`#789262`	成功/自然语义
缃色	`#C9A227`	警示（低饱和化）
墨灰	`#758A99`	中性层级、边框
茶褐	`#A8795B`	hover / 强调辅助
赭石	`#845A33`	小面积点睛、图标
胭脂	`#A8493A`	危险/错误语义
墨色	`#3A4A52`	正文文字
象牙白	`#F7F4EC`	暖白底、纸感背景
香灰	`#2C3236`	深色模式背景候选

说明：基准色谱的明度/色值在落地时需按 WCAG 感知校准，语义角色与色名绑定，色值可微调但不可换色相。天青视觉偏蓝紫，注意在暗底上调亮。

2.2 语义 Token（Light / Dark 双套）

命名规范 --song-<role>，供 CSS Variables 直接消费。

Light（浅色 / 天青昼）

Token	色值	用途	对比度(对底色)
`--song-bg`	`#F7F4EC`	页面底（暖象牙白纸感）	—
`--song-bg-elevated`	`#FFFDF8`	卡片/浮层底	—
`--song-text`	`#3A4A52`	正文（墨色）	≥ 9:1 ✅AAA
`--song-text-secondary`	`#5A6B74`	次级文字	≥ 5.5:1
`--song-text-disabled`	`#9AA7AD`	禁用	仅供装饰
`--song-primary`	`#4F78B8`	主品牌/主按钮文字底	≥ 4.6:1 ✅
`--song-primary-bg`	`#E7EEF9`	主色浅底（选中态）	—
`--song-success`	`#4E7A45`	成功	≥ 4.6:1
`--song-warning`	`#8F7A1E`	警告	≥ 4.6:1
`--song-danger`	`#A84635`	危险/错误	≥ 4.6:1
`--song-border`	`rgba(58,74,82,0.14)`	1px 墨线	—
`--song-border-strong`	`rgba(58,74,82,0.28)`	强调分割线	—
`--song-hover`	`rgba(79,120,184,0.08)`	行 hover	—
`--song-active`	`rgba(79,120,184,0.14)`	行/卡选中	—
`--song-surface-3`	`#ECE6D8`	次级底（缃调纸）	—
`--song-btn-bg`	`#4F78B8`	实底按钮底色（主钮）	—
`--song-btn-text`	`#FFFFFF`	实底按钮文字	≥ 4.5:1 ✅
`--song-seal`	`#A84635`	章印印泥砂红	—

Dark（深色 / 黛墨夜）

Token	色值	用途	对比度(对底色)
`--song-bg`	`#14181B`	页面底（深黛）	—
`--song-bg-elevated`	`#1D2326`	卡片/浮层底	—
`--song-text`	`#E6ECEF`	正文（月白墨）	≥ 12:1 ✅AAA
`--song-text-secondary`	`#A9B6BE`	次级文字	≥ 6:1
`--song-text-disabled`	`#5E6A71`	禁用	仅供装饰
`--song-primary`	`#9DBEEE`	主品牌/深底主文字	≥ 7:1 ✅
`--song-primary-bg`	`rgba(113,150,203,0.16)`	主色浅底（选中态）	—
`--song-success`	`#94B989`	成功	≥ 6:1
`--song-warning`	`#D3BC6A`	警告	≥ 6:1
`--song-danger`	`#D08A79`	危险/错误	≥ 6:1
`--song-border`	`rgba(230,236,239,0.12)`	1px 墨线	—
`--song-border-strong`	`rgba(230,236,239,0.26)`	强调分割线	—
`--song-hover`	`rgba(157,190,238,0.10)`	行 hover	—
`--song-active`	`rgba(157,190,238,0.16)`	行/卡选中	—
`--song-surface-3`	`#232B2F`	次级底	—
`--song-btn-bg`	`#48689E`	实底按钮底色（暗色压深，同色相）	—
`--song-btn-text`	`#FFFFFF`	实底按钮文字	≥ 4.5:1 ✅
`--song-seal`	`#C76A4F`	章印印泥砂红（暗色微提亮）	—

取舍说明（重要）：雅色（天青 #88ADED）作深底文字时对比度不足，故 Light 下 primary 压实至 #4F78B8、Dark 下调亮至 #9DBEEE。"雅"与"可读"冲突时，默认让位于可读性，但保持在同色相内调整明度。

按钮填充另立 Token（--song-btn-bg / --song-btn-text）：--song-primary 是"色相锚点"，用于文字/描边/选中态；实底按钮的填充底不使用它直接上白字——因为暗色下主色 #9DBEEE 偏亮，白字对比度仅约 1.8:1。故按钮底单独取深一档的同色相（Light #4F78B8 / Dark #48689E），保证白字 ≥ 4.5:1。未来若新增其他实底填充控件，一律用 --song-btn-bg 而非 --song-primary。

2.3 色彩配额（防止滥用）

主色额度：天青系列覆盖 ≤ 35% 的彩色面积；大面积装饰底只用浅底（primary-bg）而非实色。
点睛额度：赭石/缃/胭脂每屏合计 ≤ 5%——只用于图标、标签、进度、强调按钮。
中性主导：其余一律用墨灰/月白/象牙白中性层次。
背景禁用：禁止外发光、彩虹渐变、高饱和渐变背景。允许的是——极淡的釉质渐变（同色系 ±5% 明度）。

2.4 语义映射（组件主题用）

组件语义	色 token
primary / brand / nav 选中	`--song-primary`
success / 通过 / 正数	`--song-success`
warning / 待审 / 审核中	`--song-warning`
danger / 驳回 / 错误	`--song-danger`
neutral / 边框 / 分割	`--song-border*`
文字	`--song-text*`

3. 字体系统 Token

3.1 字体栈（含授权与回退）

用途	首选	授权	回退	说明
大标题/品牌	霞鹜文楷 LXGW WenKai	OFL 开源	Noto Serif SC → 系统衬线	书卷气、温润，屏显可读
展示型正文	Noto Serif SC（思源宋体）	OFL 开源	系统宋体	宋味正文，仅用于展示/大字号
中后台正文	Noto Sans SC（思源黑体）	OFL 开源	system-ui	小字号宋体屏显发虚（hinting 问题），12–14px 一律退黑体
数字	同正文栈 + `font-variant-numeric: tabular-nums`	—	—	对齐统计数字

--song-font-display: "LXGW WenKai", "Noto Serif SC", "Songti SC", serif;
--song-font-serif: "Noto Serif SC", "Songti SC", serif;
--song-font-sans: "Noto Sans SC", -apple-system, "PingFang SC", "Microsoft YaHei", system-ui, sans-serif;
--song-font-body: var(--song-font-sans);

取舍：正文用黑体不是妥协而是工程决策——宋体随字号缩小横细竖粗差异导致屏显发虚，反而不"雅"。标题用文楷/宋体保留韵味即可。

3.2 字阶（克制字阶，≥ 3–5 档）

层级	字号/行高	字体	用途
display	36 / 48	--font-display	落地页大标题
h1	28 / 38	--font-display	页签主标题
h2	22 / 30	--font-serif	区块标题（宋味）
h3	18 / 26	--font-serif	卡片标题
body	14 / 22	--font-body	正文/表单
caption	12 / 18	--font-body	辅助说明

3.3 楷体使用禁区

楷体（文楷）只用于标题与装饰文案，禁止用于正文/长文/数字表格。版式追求"版心居中、字大行疏"的宋版书呼吸感。

3.4 字体加载性能

国产 web font（文楷/思源 Serif）体积大：按需子集化（unicode-range 分片），只加载标题所需的常用字 ≥ 且设 font-display: swap。
中文 webfont 勿整体引入，优先只对 display 标题片断引入。

3.5 瘦金体版权声明（重要·强制）

瘦金体为宋徽宗赵佶所创书体，其字形不受现代著作权保护，但以"瘦金体"命名的既有字体文件/字库具有独立著作权，未获授权的字体文件严禁内嵌、下载分发或商用渲染。

允许：① 手工按瘦金体笔意绘制 Logo/装饰字作为 SVG 路径（图形作品）；② 引用具备合法商业授权的瘦金体字库。
禁止：将 web 字库、字体文件打包进项目任何环境中（含 assets 目录、CDN 缓存、npm 依赖）。
落地：页面若使用瘦金体风格的品牌字，必须在页面 Footer 展示免责声明：

免责声明（示例文案，可随页面调整，但不可删除） 「本页面中瘦金体风格标识为艺术字图形，参考自宋徽宗瘦金体书风自行绘制的 SVG 作品，所用字形获得公开授权 / 或为公开领域书风临摹，未被授权的瘦金体字库文件不得用于任何商业用途。如需商业使用宋徽宗瘦金体风格字体，请联系相应字库权利人获得授权。」

Token 约束：--song-font-shoujin 仅供图形断字/装饰字使用（如生僻装饰字符、印章、品牌符号），不允许作为段落排版字体。凡发现字体文件被导入，视为违反本契约。
章印（SongSeal）同规：章印为自绘 SVG 图形（印泥砂红 --song-seal），方印田字格 ≤ 4 字、圆印连珠单字，可微旋转(-3°~-1°)模拟手钤；禁止把瘦金体字库字形放进章印。

4. 间距 / 留白梯度 / 圆角 / 边框

4.1 间距刻度（8pt 网格，克制）

--song-space-1: 4px ... --song-space-8: 64px，一律 4 的倍数。组件内部默认 16px，区块默认 24px。

4.2 留白梯度（两场景级联，核心机制）

梯度	页面类型	留白占比	示例
G4 空灵	展示/官网/落地	≥ 60%	Hero、作品集、专题页
G3 疏朗	图文/内容	40–50%	文章、画廊、组件 demo
G2 紧凑	表单/引导	25–35%	设置、登录、向导
G1 密集	数据/表格	≤ 20%	Table、Dashboard

实现：留白幅度以 --song-density: G1..G4 一个变量的间距倍数（如 G4 对 --song-space × 2）控制，页面级动态切换，组件内由主题级联继承。表格/表单页不得强行压缩到空灵档，尊重 G1 的信息密度。

4.3 圆角（温润不圆滑）

Token	值	用途
`--song-radius-s`	2px	标签、输入
`--song-radius-m`	4px	按钮、卡片
`--song-radius-l`	6px	大悬浮窗、图容器

禁全圆（24px+ pill）——宋韵是"含蓄的弧度"，非现代圆润。卡片圆角小、留白大、行距松。

4.4 边框（1px 墨线系统）

所有边界 = 1px 实线 rgba(墨, <alpha>)，不许 2px+ 粗边。
三层透明度：--song-border(12–14%) → --song-border-strong(26–28%) → 实色仅用于关键焦点。

5. 纹理与图案 Token（几何化 · 低占比）

一切纹样以 SVG 几何化矢量 交付，禁止具象图案。

纹样	几何化 SVG	应用	占比上限
冰裂纹	细碎裂网格	大面积背景底纹（釉质肌理）	≤ 6% 视觉噪声
直棂窗	竖向细条	列表左侧竖分割、栅格 hover 分隔	结构内嵌
龟背纹	正六边形	图表底纹、统计卡角饰	≤ 4%
缠枝纹	简化波浪/环形卷草	环形图装饰、页脚分节	≤ 2%
水纹	波浪同心回环	水景、数据流底纹、深色氛围	≤ 4%
云纹	卷云 S 形勾勒	边缘留白角饰、Hero 氛围	≤ 3%

使用禁区：

纹样仅作底纹/装饰层，置于内容 Z 轴之下，不得与文字/表格抢占对比度；
用 --song-<role> 中性色（透明度）+ 高对比时置灰；
避免大面积重复高纹样密度的"密集恐惧"效果——每屏最多 1 种主纹样。

6. 阴影层级（平面温润，非重阴影）

禁用：大阴影、玻璃拟态（backdrop-blur 大面积）、外发光、浮雕投影。

层级	阴影 Token	说明
地面	`--song-shadow-1: 0 1px 2px rgba(20,24,27,0.06)`	悬浮态
抬升	`--song-shadow-2: 0 2px 8px rgba(20,24,27,0.08)`	卡片浮层
遮蔽	`--song-shadow-3: 0 8px 24px rgba(20,24,27,0.12)`	Modal / Dropdown

层级表达按顺序靠：墨线 → 轻微阴影 → 底色纯度差，三者叠加而非单靠阴影。

7. 动效语言

场景	动效	时长/缓动
页面转场	雾隐淡入（内容边缘渐入 `opacity + translateY(8px)`）	320ms, ease-out
加载	水墨晕染（低饱和不透明渐变遮罩 + 淡墨扩散）	400ms+，循环
卡片/行 hover	极轻抬升 + 主色 line 右滑	200ms, ease
弹层	平缓浮起 + 淡入	240ms, ease-out
数据更新	数字 tabular-nums 淡变，禁用组件抖动	—
提示框	雾隐淡入（顶部滑落 + 渐隐），墨线左批注 + 小章意象，3.4s 自散	320ms, ease-out
加载	水墨晕染（墨点如滴入宣纸扩散敛去，多墨点错峰 0.8s，合成层），支持行内/全屏遮罩两态	2.4s 循环, ease

性能约束（硬性）：仅使用 transform/opacity 合成层属性；禁止动画 background/box-shadow/filter 大范围重绘；背景渐变一动不补。动效统一走 prefers-reduced-motion 关闭。 图层级契约：弹层(Modal) 900 < 全屏加载遮罩 950 < 提示框 1000，三者不可同屏抢占。

8. Vue3 & Vite 落地建议（写给前端 Agent）

Token 落地路径：
- 定义 styles/tokens/light.css、tokens/dark.css（上述 --song-* 变量）；
- 通过 :root[data-theme="dark"] 切换，暗色跟随 prefers-color-scheme 与手动开关双源；
- 建议用 Vite + postcss 编译，或直接 CSS Variables 零编译成本。
组件库接入：
- 本主题面向自研组件或组件库主题化。若是 Element Plus / Naive UI：
  - 优先用各自主题的 CSS Variables 覆盖（如 EP 的 --el-color-primary 映射到 var(--song-primary)）；
  - 组件库内部用 JS 生成主题色（如 @element-plus/theme-chalk）时用其 ConfigProvider 绑定 --song-*；
  - 凡无法覆盖处（圆角、阴影、边框），在组件级 scoped 中抹平为契约值。
主题切换安全：任何组件不得写死色值，一律消费 CSS 变量；对外暴露 useSongTheme() 组合函数（切换 data-theme、记忆 localStorage、监听系统偏好）。
字体引入：标题 webfont 用 Vite 静态资源 + 分包；验证 font-display 与子集化，避免阻塞首屏。
验收钩子：构建后执行一条检查，扫描打包产物中的色值硬编码与非法字体文件是否进入产物。

9. 无障碍与验收清单（可测项）

#	校验项	通过标准
1	文本对比度	正文 ≥ 7:1，次级 ≥ 4.6:1（见 §2.2 实测值）
2	焦点态	键盘 `:focus-visible` 清晰可见（主色 2px 轮廓）
3	深色切换	所有页面双模式下无高光溢出、色块不刺眼
4	字体回退	禁用 webfont 后页面仍可读（回退链完整）
5	动效可关	`prefers-reduced-motion` 生效
6	Token 覆盖	任意组件无硬编码颜色/圆角/阴影
7	纹样占比	每屏 ≤ 1 种主纹样，占比达标
8	瘦金体合规	产物中无未授权字库文件；涉及页含免责声明

10. 交付清单

tokens/light.css、tokens/dark.css（§2.2 全量语义 Token）
纹样 SVG 资源包（冰裂/直棂/龟背/缠枝/水纹/云纹，几何化）
字体栈与子集化配置建议（§3.4）
组件主题覆盖样式（按 §8.2 接入所选组件库）
免责声明组件（页脚可复用）

组件（已就绪，Vue3 + Vite）：Button（含 loading 墨点）、Card、Tag、Input、Nav（直棂分隔）、Table、Badge、Progress（条/环）、Modal、Loading（水墨晕染 · 行内/遮罩）、Seal（章印）、Scrim（六种底纹）、Logo、Disclaimer、Message（提示框，useMessage() 组合函数）。

本契约的强制约束 = §2.6 瘦金体版权、§7 动效性能、§2.3 色彩配额、§5 纹样禁区。其余可视场景灵活，但这四条款不可妥协。

19 KiB Raw Blame History

SongUI 研究报告 — 宋韵·至简 设计语言契约