# 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 `git@47.122.122.94:Mohan/SongUI.git`，默认分支 `main`（`master` 已删除）。提交前 `npm run build` 通过，单提交单意图，提交后立即 push。
- **接入路径**：`import { SongComponents } from './components/index'` → `app.use(SongComponents)`，或按需按名导入单个组件。