feat(contract): add song-ui design language contract

SongUI研究报告.md

@@ -0,0 +1,340 @@
+# 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 色彩配额（防止滥用）
+1. **主色额度**：天青系列覆盖 ≤ 35% 的彩色面积；大面积装饰底只用浅底（primary-bg）而非实色。
+2. **点睛额度**：赭石/缃/胭脂每屏合计 ≤ 5%——只用于图标、标签、进度、强调按钮。
+3. **中性主导**：其余一律用墨灰/月白/象牙白中性层次。
+4. **背景禁用**：禁止外发光、彩虹渐变、高饱和渐变背景。允许的是——极淡的釉质渐变（同色系 ±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` | — | — | 对齐统计数字 |
+
+```css
+--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% |
+
+**使用禁区**：
+1. 纹样仅作底纹/装饰层，**置于内容 Z 轴之下**，不得与文字/表格抢占对比度；
+2. 用 `--song-<role>` 中性色（透明度）+ 高对比时置灰；
+3. 避免大面积重复高纹样密度的"密集恐惧"效果——每屏最多 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）
+
+1. **Token 落地路径**：
+   - 定义 `styles/tokens/light.css`、`tokens/dark.css`（上述 `--song-*` 变量）；
+   - 通过 `:root[data-theme="dark"]` 切换，暗色跟随 `prefers-color-scheme` 与手动开关双源；
+   - 建议用 Vite + postcss 编译，或直接 CSS Variables 零编译成本。
+
+2. **组件库接入**：
+   - 本主题面向自研组件或组件库主题化。若是 Element Plus / Naive UI：
+     - 优先用各自主题的 **CSS Variables 覆盖**（如 EP 的 `--el-color-primary` 映射到 `var(--song-primary)`）；
+     - 组件库内部用 JS 生成主题色（如 `@element-plus/theme-chalk`）时用其 `ConfigProvider` 绑定 `--song-*`；
+     - 凡无法覆盖处（圆角、阴影、边框），在组件级 `scoped` 中抹平为契约值。
+
+3. **主题切换安全**：任何组件不得写死色值，一律消费 CSS 变量；对外暴露 `useSongTheme()` 组合函数（切换 `data-theme`、记忆 localStorage、监听系统偏好）。
+
+4. **字体引入**：标题 webfont 用 Vite 静态资源 + 分包；验证 `font-display` 与子集化，避免阻塞首屏。
+
+5. **验收钩子**：构建后执行一条检查，扫描打包产物中的色值硬编码与非法字体文件是否进入产物。
+
+---
+
+## 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. 交付清单
+
+1. `tokens/light.css`、`tokens/dark.css`（§2.2 全量语义 Token）
+2. 纹样 SVG 资源包（冰裂/直棂/龟背/缠枝/水纹/云纹，几何化）
+3. 字体栈与子集化配置建议（§3.4）
+4. 组件主题覆盖样式（按 §8.2 接入所选组件库）
+5. 免责声明组件（页脚可复用）
+
+**组件（已就绪，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 纹样禁区。其余可视场景灵活，但这四条款不可妥协。**