docs(contract): add changelog notice for agent2

Agent2-组件库更新说明.md

@@ -0,0 +1,114 @@
+# SongUI · 组件库更新说明（致前端 Agent2）
+
+> 基于当前 `main`（`e70712a`）版本，面向接入组件库的前端 Agent 的增量变更清单。
+> 组件库基线与设计契约见 [`SongUI研究报告.md`](./SongUI研究报告.md) 与 [`README.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 — 提示框（组合函数式）
+
+```js
+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 — 加载（水墨晕染）
+
+```vue
+<SongLoading text="墨迹未干" />                      <!-- 行内 -->
+<SongLoading mask :visible="loading" text="展卷 · 墨色氤氲" @click="loading=false" />  <!-- 全屏遮罩 -->
+```
+
+- Props：`visible`(默认 true)、`mask`(全屏遮罩)、`text`(默认 "墨迹未干")。
+- 动效为纯 `transform/opacity` 合成层，遵循 `prefers-reduced-motion`。
+
+### 1.3 SongSeal — 章印（自绘 SVG）
+
+```vue
+<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
+
+```vue
+<SongButton :loading="busy" @click="submit">纳签</SongButton>
+```
+
+- `loading` 时显示墨点脉冲并禁用；其余 Props（`type/size/disabled/block`）不变。
+
+### 2.2 SongScrim — 新增纹样与盒内模式
+
+```vue
+<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)`，或按需按名导入单个组件。