SongUI/Agent2-组件库更新说明.md

SongUI · 组件库更新说明（致前端 Agent2）

基于当前 main（e70712a）版本，面向接入组件库的前端 Agent 的增量变更清单。 组件库基线与设计契约见 SongUI研究报告.md 与 README.md。

---

0. 本次相比上一版的变更总览

类别	变更
新增组件	Message（提示框）、Loading（水墨晕染加载）、Seal（章印）
组件增强	Button 新增 loading 态；Scrim 新增 2 种纹样 + box 盒内模式
新增 Token	--song-btn-bg / --song-btn-text / --song-seal / --song-scrim-line（明暗双套）
行为修复	底纹确定性渲染（不再拖暗页面）；暗色模式提亮；主题切换按钮文字联动；提示框图标居中
响应式	全组件 ≤640px 小屏适配
工程	Vue3+Vite 脚手架、演示页、README、免责声明组件已就绪

---

1. 新增组件

1.1 Message — 提示框（组合函数式）

import { useMessage } from './composables/useMessage'
const message = useMessage()
message.success('纳签成功')   // success / warning / danger / info

• 顶层雾隐淡入，3.4s 自动消散；无需手动挂载容器（首调自动注入）。
• 层级 z-index: 1000（契约：弹层 900 < 加载遮罩 950 < 提示 1000）。

1.2 SongLoading — 加载（水墨晕染）

<SongLoading text="墨迹未干" />                      <!-- 行内 -->
<SongLoading mask :visible="loading" text="展卷 · 墨色氤氲" @click="loading=false" />  <!-- 全屏遮罩 -->

• Props：visible(默认 true)、mask(全屏遮罩)、text(默认 "墨迹未干")。
• 动效为纯 transform/opacity 合成层，遵循 prefers-reduced-motion。

1.3 SongSeal — 章印（自绘 SVG）

<SongSeal text="檐下" />            <!-- 方印田字格，≤4 字 -->
<SongSeal text="安" round :size="70" rotate="-3" />  <!-- 圆印连珠单字 -->

• Props：text、round(圆印)、size(默认 76)、rotate(默认 -2，模拟手钤微倾)。
• 颜色走 --song-seal（印泥砂红）。禁止将瘦金体字库字形放进章印（契约 §3.5）。

---

2. 组件增强

2.1 SongButton — 新增 loading

<SongButton :loading="busy" @click="submit">纳签</SongButton>

• loading 时显示墨点脉冲并禁用；其余 Props（type/size/disabled/block）不变。

2.2 SongScrim — 新增纹样与盒内模式

<SongScrim />                                          <!-- 全屏底纹，默认冰裂纹 -->
<SongScrim pattern="water" />                          <!-- 六选一：ice/blind/tortoise/vine/water/cloud -->
<SongScrim pattern="cloud" box />                      <!-- box：卡片/区块内局部底纹 -->

• opacity(默认 1) 可再调淡；纹样线条颜色由主题 Token --song-scrim-line 决定，已去除 blend/filter 技巧，确定性渲染，不会带暗页面。

---

3. 新增 Token（明暗双套）

Token	Light	Dark	用途
--song-btn-bg	#4f78b8	#48689e	实底主按钮底色（白字 ≥4.5:1）
--song-btn-text	#fff	#fff	实底按钮文字
--song-seal	#a84635	#c76a4f	章印印泥红
--song-scrim-line	rgba(90,107,116,.14)	rgba(230,236,239,.1)	底纹描边色

规则：实底填充控件用 --song-btn-bg，不要直接拿 --song-primary 上白字（暗色下对比度不足）。

---

4. 行为修复（重点）

1. 暗色模式不再被底纹拖暗：SongScrim 去掉 mix-blend-mode/filter/opacity 叠加，改为按主题描边色确定性渲染。
2. 暗色模式提亮：--song-bg-elevated→#20272b、--song-surface-3→#273036、--song-text-secondary→#b9c6cd，避免"整页发暗、字体不亮"。
3. 主题切换按钮文字联动：useSongTheme() 返回 reactive，theme.isDark 为布尔且响应式（模板中直接用 theme.isDark，勿取 .value）。
4. 提示框图标居中：SongMessageContainer 印章图标 line-height:1 + flex-shrink:0。

---

5. 响应式（≤640px）

• 演示页：Hero 字号收敛、操作按钮竖排、卡片单列、色卡 3 列。
• SongNav：小屏横向滚动、收紧间距。
• SongTable：display:block + overflow-x:auto，数据不撑破布局。
• 组件库各容器已用 minmax(min(300px,100%),1fr) 防溢出。

---

6. 注意事项

• 禁改项（契约 §0/§2.6）：瘦金体不得以字库文件形式入包；页脚须含 SongDisclaimer 免责声明；实底按钮须走 --song-btn-bg。
• 文件归属：src/composables/useSongTheme.js 由另一 Agent 维护，勿改动。
• 远程：origin 已切至 SSH [email protected]:Mohan/SongUI.git，默认分支 main（master 已删除）。提交前 npm run build 通过，单提交单意图，提交后立即 push。
• 接入路径：import { SongComponents } from './components/index' → app.use(SongComponents)，或按需按名导入单个组件。