diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6802cf9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,81 @@
+# 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