# SongUI · 檐下

> 宋韵 · 至简 — 以宋代建筑、汝瓷、宋画留白为骨，现代极简为架的 Vue 3 UI 组件库与设计语言。
> 设计契约见 [`SongUI研究报告.md`](./SongUI研究报告.md)。

## 特性

- **双主题**：天青昼（Light）/ 黛墨夜（Dark），跟随系统偏好 + 手动切换，自动记忆（localStorage）。
- **16 个组件**：Button（含 loading 墨点）、Card、Tag、Input、Nav（直棂分隔）、Table、Badge、Progress（条/环）、Modal、Loading（水墨晕染 · 行内/遮罩）、Seal（章印）、Scrim（六种几何化底纹）、Logo、Disclaimer、Message（`useMessage()` 提示框）。
- **语义 Token**：`--song-*` CSS 变量贯穿明暗两套，无硬编码色值；数字统一 `tabular-nums`。
- **契约约束**：纹样几何化低占比、动效仅合成层、瘦金体版权免责声明、对比度达标。

## 快速开始

```bash
npm install
npm run dev        # 本地开发 http://localhost:5173
npm run build      # 生产构建（dist/）
npm run preview    # 预览构建产物
```

## 目录结构

```
src/
  components/         组件库（Song* 前缀，支持全局注册）
  composables/        useSongTheme（主题）、useMessage（提示）
  styles/
    tokens/           light.css / dark.css 语义 Token
    base.css          字阶、焦点态、动效基础
```

## 主题切换

```vue
<script setup>
import { useSongTheme } from './composables/useSongTheme'
const theme = useSongTheme() // { isDark, toggle }
</script>
```

`initSongTheme()` 在入口调用即可完成初始化（读 localStorage → 系统偏好兜底）。

## 使用提示框

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

## 组件示例

```vue
<SongButton :loading="busy" @click="submit">纳签</SongButton>
<SongTag type="success">成签</SongTag>
<SongTable :columns="columns" :data="rows" />
<SongLoading mask :visible="loading" text="展卷 · 墨色氤氲" />
<SongSeal text="檐下" :size="72" />
<SongScrim pattern="ice" />
```

## 全局注册

```js
import { SongComponents } from './components/index'
app.use(SongComponents)
```

## 版权声明

- 全部纹样为几何化 SVG；品牌字为自绘 SVG 图形，**非瘦金体字库文件**，禁止将任何未授权字库打包进产物。
- 字体遵循开源授权（霞鹜文楷 / 思源宋 / 思源黑体，OFL）并配置回退链。

## 提交规范

见仓库内约定：`type(scope): subject`（`feat` `fix` `refactor` `test` `docs` `chore` `style`），单提交单意图，提交前 `npm run build` 通过，提交后立即 push。

## License

MIT