update README.md

docs/customize/css-variables.md

@@ -0,0 +1,244 @@
+# CSS 变量
+
+WarmIsland 主题使用 CSS 自定义属性（CSS Variables）构建完整的样式系统，方便用户通过覆盖变量来自定义主题外观。
+
+## 颜色变量
+
+### 浅色模式
+
+```css
+:root {
+  --bg: #faf7f2;
+  --bg-raised: #f3ede5;
+  --bg-overlay: rgba(250, 247, 242, 0.85);
+  --ink: #2c2420;
+  --ink-2: #7a6e64;
+  --ink-3: #b5a99e;
+  --rule: #e8e0d6;
+  --accent: #d4764e;
+  --accent-hover: #c4613a;
+  --accent-bg: #fdf0e8;
+  --mist-pink: #f0e4de;
+  --sea-salt: #e8e0d6;
+  --caramel: #8b6f5e;
+  --glass-bg: rgba(250, 247, 242, 0.72);
+  --glass-border: rgba(232, 224, 214, 0.5);
+  --shadow-sm: 0 1px 3px rgba(44, 36, 32, 0.06);
+  --shadow-md: 0 4px 16px rgba(44, 36, 32, 0.08);
+  --shadow-lg: 0 8px 32px rgba(44, 36, 32, 0.12);
+  --shadow-glow: 0 0 40px rgba(212, 118, 78, 0.15);
+}
+```
+
+### 深色模式
+
+```css
+html.dark {
+  --bg: #1a1614;
+  --bg-raised: #242018;
+  --bg-overlay: rgba(26, 22, 20, 0.85);
+  --ink: #ede6de;
+  --ink-2: #9a8e84;
+  --ink-3: #5e544a;
+  --rule: #2e2822;
+  --accent: #e8955f;
+  --accent-hover: #f0a872;
+  --accent-bg: #2a1e16;
+  --mist-pink: #2e2420;
+  --sea-salt: #2e2822;
+  --caramel: #a08878;
+  --glass-bg: rgba(26, 22, 20, 0.72);
+  --glass-border: rgba(46, 40, 34, 0.5);
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.2);
+  --shadow-md: 0 4px 16px rgba(0, 0, 0, 0.25);
+  --shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.35);
+  --shadow-glow: 0 0 40px rgba(232, 149, 95, 0.12);
+}
+```
+
+## 字体变量
+
+```css
+:root {
+  --font-sans: 'Noto Serif SC', 'Source Han Serif SC', Georgia, serif;
+  --font-body: 'Noto Sans SC', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
+}
+```
+
+| 变量 | 用途 |
+|------|------|
+| `--font-sans` | 标题、强调文字（衬线体） |
+| `--font-body` | 正文、UI 文字（无衬线体） |
+| `--font-mono` | 代码（等宽体） |
+
+## 字号变量
+
+使用 `clamp()` 实现响应式字号：
+
+```css
+:root {
+  --text-xs: clamp(0.7rem, 0.66rem + 0.2vw, 0.75rem);
+  --text-sm: clamp(0.8rem, 0.76rem + 0.2vw, 0.875rem);
+  --text-base: clamp(0.938rem, 0.89rem + 0.24vw, 1rem);
+  --text-md: clamp(1.05rem, 0.99rem + 0.3vw, 1.125rem);
+  --text-lg: clamp(1.15rem, 1.06rem + 0.45vw, 1.25rem);
+  --text-xl: clamp(1.3rem, 1.16rem + 0.7vw, 1.5rem);
+  --text-2xl: clamp(1.55rem, 1.34rem + 1.05vw, 1.875rem);
+  --text-3xl: clamp(1.85rem, 1.52rem + 1.65vw, 2.25rem);
+  --text-4xl: clamp(2.15rem, 1.7rem + 2.25vw, 3rem);
+  --text-5xl: clamp(2.6rem, 1.9rem + 3.5vw, 3.75rem);
+}
+```
+
+| 变量 | 最小值 | 最大值 | 典型用途 |
+|------|--------|--------|----------|
+| `--text-xs` | 0.7rem | 0.75rem | 辅助标签、日期 |
+| `--text-sm` | 0.8rem | 0.875rem | 次要文字、描述 |
+| `--text-base` | 0.938rem | 1rem | 正文 |
+| `--text-md` | 1.05rem | 1.125rem | 页面正文 |
+| `--text-lg` | 1.15rem | 1.25rem | 卡片标题 |
+| `--text-xl` | 1.3rem | 1.5rem | 小节标题 |
+| `--text-2xl` | 1.55rem | 1.875rem | 区块标题 |
+| `--text-3xl` | 1.85rem | 2.25rem | 页面标题 |
+| `--text-4xl` | 2.15rem | 3rem | 大标题 |
+| `--text-5xl` | 2.6rem | 3.75rem | Hero 标题 |
+
+## 间距变量
+
+```css
+:root {
+  --space-xs: 0.25rem;
+  --space-sm: 0.5rem;
+  --space-md: 1rem;
+  --space-lg: 1.5rem;
+  --space-xl: 2rem;
+  --space-2xl: 3rem;
+  --space-3xl: 4rem;
+  --space-4xl: 6rem;
+  --container-sm: 640px;
+  --container-md: 768px;
+  --container-lg: 1024px;
+  --container-xl: 1200px;
+  --content-max: 800px;
+  --section-spacing: clamp(3rem, 2rem + 3vw, 6rem);
+}
+```
+
+## 圆角变量
+
+圆角使用 SCSS 变量定义，不在运行时作为 CSS 变量暴露：
+
+```scss
+$border-radius-sm: 8px;
+$border-radius-md: 12px;
+$border-radius-lg: 16px;
+$border-radius-xl: 24px;
+$border-radius-full: 9999px;
+```
+
+## 阴影变量
+
+```css
+:root {
+  --shadow-sm: 0 1px 3px rgba(44, 36, 32, 0.06);
+  --shadow-md: 0 4px 16px rgba(44, 36, 32, 0.08);
+  --shadow-lg: 0 8px 32px rgba(44, 36, 32, 0.12);
+  --shadow-glow: 0 0 40px rgba(212, 118, 78, 0.15);
+}
+
+html.dark {
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.2);
+  --shadow-md: 0 4px 16px rgba(0, 0, 0, 0.25);
+  --shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.35);
+  --shadow-glow: 0 0 40px rgba(232, 149, 95, 0.12);
+}
+```
+
+## 动画变量
+
+```css
+:root {
+  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);
+  --ease-in-out-cubic: cubic-bezier(0.65, 0, 0.35, 1);
+  --duration-fast: 150ms;
+  --duration-normal: 300ms;
+  --duration-slow: 500ms;
+  --duration-breath: 3s;
+}
+```
+
+## 行高变量
+
+```css
+:root {
+  --leading-none: 1;
+  --leading-tight: 1.2;
+  --leading-snug: 1.35;
+  --leading-normal: 1.6;
+  --leading-relaxed: 1.75;
+  --leading-loose: 2;
+}
+```
+
+| 变量 | 值 | 用途 |
+|------|-----|------|
+| `--leading-none` | 1 | 紧凑元素 |
+| `--leading-tight` | 1.2 | 标题 |
+| `--leading-snug` | 1.35 | 小标题 |
+| `--leading-normal` | 1.6 | 正文 |
+| `--leading-relaxed` | 1.75 | 长文阅读 |
+| `--leading-loose` | 2 | 宽松排版 |
+
+## 字间距变量
+
+```css
+:root {
+  --tracking-tight: -0.02em;
+  --tracking-normal: 0;
+  --tracking-wide: 0.04em;
+  --tracking-wider: 0.08em;
+  --tracking-widest: 0.12em;
+}
+```
+
+| 变量 | 值 | 用途 |
+|------|-----|------|
+| `--tracking-tight` | -0.02em | 大标题 |
+| `--tracking-normal` | 0 | 正文 |
+| `--tracking-wide` | 0.04em | 辅助文字 |
+| `--tracking-wider` | 0.08em | 标签、日期 |
+| `--tracking-widest` | 0.12em | 大写标签 |
+
+## 如何覆盖变量
+
+### 方法一：主题设置
+
+在 Halo 后台 → **外观** → **主题** → **样式设置** 中的「自定义 CSS」字段添加覆盖规则：
+
+```css
+:root {
+  --accent: #e85d75;
+  --accent-hover: #d44a64;
+  --accent-bg: #fdf0f3;
+}
+
+html.dark {
+  --accent: #f07090;
+  --accent-hover: #f5889f;
+  --accent-bg: #2a1a1e;
+}
+```
+
+### 方法二：外部 CSS
+
+在 Halo 后台 → **外观** → **主题** → **页脚设置** 中的「自定义 HTML」字段引入外部 CSS：
+
+```html
+<link rel="stylesheet" href="https://your-cdn.com/custom.css" />
+```
+
+::: warning
+覆盖变量时，务必同时覆盖深色模式的对应变量（`html.dark` 选择器下），否则深色模式下可能出现颜色不协调的问题。
+:::

docs/customize/custom-css.md

@@ -0,0 +1,300 @@
+# 自定义 CSS
+
+WarmIsland 主题提供了灵活的自定义 CSS 能力，让你无需修改源码即可调整主题外观。
+
+## 两种方法
+
+### 方法一：主题设置（推荐）
+
+在 Halo 后台 → **外观** → **主题** → **样式设置** 中找到「自定义 CSS」字段，直接输入 CSS 代码。
+
+**优点**：
+- 随主题数据保存，升级主题不丢失
+- 无需额外的网络请求
+- 实时生效
+
+**缺点**：
+- 不适合大量 CSS 代码
+- 没有语法高亮和自动补全
+
+### 方法二：外部 CSS 文件
+
+在 Halo 后台 → **外观** → **主题** → **页脚设置** 中的「自定义 HTML」字段引入外部 CSS：
+
+```html
+<link rel="stylesheet" href="https://your-cdn.com/custom.css" />
+```
+
+**优点**：
+- 可以使用代码编辑器编写，有完整的开发体验
+- 适合大量自定义样式
+- 可以版本控制
+
+**缺点**：
+- 需要额外的网络请求
+- 需要自己托管 CSS 文件
+- 主题升级后需要检查兼容性
+
+## 实用示例
+
+### 更改强调色
+
+将默认的赤陶橙改为玫瑰粉：
+
+```css
+:root {
+  --accent: #e85d75;
+  --accent-hover: #d44a64;
+  --accent-bg: #fdf0f3;
+}
+
+html.dark {
+  --accent: #f07090;
+  --accent-hover: #f5889f;
+  --accent-bg: #2a1a1e;
+}
+```
+
+改为薄荷绿：
+
+```css
+:root {
+  --accent: #3d9970;
+  --accent-hover: #2d8060;
+  --accent-bg: #edf7f2;
+}
+
+html.dark {
+  --accent: #5cb895;
+  --accent-hover: #72c8a8;
+  --accent-bg: #1a2a22;
+}
+```
+
+改为靛蓝：
+
+```css
+:root {
+  --accent: #5b6abf;
+  --accent-hover: #4a59ae;
+  --accent-bg: #eef0f8;
+}
+
+html.dark {
+  --accent: #7b8ad0;
+  --accent-hover: #95a0dd;
+  --accent-bg: #1e1e2a;
+}
+```
+
+::: tip
+更改强调色时，需要同时修改 `--accent`、`--accent-hover` 和 `--accent-bg` 三个变量，并分别为浅色和深色模式设置。
+:::
+
+### 更改字体
+
+#### 使用 Google Fonts CDN 引入字体
+
+在「自定义 HTML」中添加：
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=LXGW+WenKai:wght@400;700&display=swap" rel="stylesheet" />
+```
+
+在「自定义 CSS」中覆盖字体变量：
+
+```css
+:root {
+  --font-sans: 'LXGW WenKai', serif;
+  --font-body: 'LXGW WenKai', sans-serif;
+}
+```
+
+#### 使用国内 CDN 镜像
+
+如果 Google Fonts 访问不稳定，可以使用国内镜像：
+
+```html
+<link href="https://fonts.loli.net/css2?family=LXGW+WenKai:wght@400;700&display=swap" rel="stylesheet" />
+```
+
+其他可用的国内镜像：
+
+| 镜像 | 地址 |
+|------|------|
+| loli.net | `https://fonts.loli.net` |
+| fonts.font.im | `https://fonts.font.im` |
+
+#### 仅更改标题字体
+
+```css
+:root {
+  --font-sans: 'LXGW WenKai', serif;
+}
+```
+
+#### 仅更改正文字体
+
+```css
+:root {
+  --font-body: 'LXGW WenKai', sans-serif;
+}
+```
+
+### 增加行高
+
+如果觉得正文行高偏小，可以增加：
+
+```css
+:root {
+  --leading-relaxed: 2;
+}
+```
+
+或直接针对文章正文：
+
+```css
+.wi-post__content {
+  line-height: 2;
+}
+```
+
+### 隐藏元素
+
+#### 隐藏阅读进度条
+
+```css
+.wi-reading-progress {
+  display: none !important;
+}
+```
+
+#### 隐藏文章点赞按钮
+
+```css
+.wi-post__like {
+  display: none !important;
+}
+```
+
+#### 隐藏文章上下篇导航
+
+```css
+.wi-post__nav {
+  display: none !important;
+}
+```
+
+#### 隐藏 Hero 区域
+
+```css
+.wi-hero {
+  display: none !important;
+}
+```
+
+#### 隐藏页脚
+
+```css
+.wi-footer {
+  display: none !important;
+}
+```
+
+### 自定义卡片样式
+
+#### 增加卡片圆角
+
+```css
+.wi-card {
+  border-radius: 20px !important;
+}
+```
+
+#### 卡片添加边框
+
+```css
+.wi-card {
+  border: 1px solid var(--rule) !important;
+}
+```
+
+#### 卡片悬停变色
+
+```css
+.wi-card:hover {
+  background: var(--accent-bg) !important;
+}
+```
+
+### 自定义 Hero 区域
+
+#### 更改 Hero 背景渐变
+
+```css
+.wi-hero {
+  background: linear-gradient(135deg, #faf7f2 0%, #e8d5c4 50%, #d4a98e 100%) !important;
+}
+
+html.dark .wi-hero {
+  background: linear-gradient(135deg, #1a1614 0%, #2a2018 50%, #3a2e22 100%) !important;
+}
+```
+
+#### 隐藏 Hero 光球动画
+
+```css
+.wi-hero__orb {
+  display: none !important;
+}
+```
+
+#### 调整 Hero 标题大小
+
+```css
+.wi-hero__title {
+  font-size: clamp(2.5rem, 2rem + 4vw, 4.5rem) !important;
+}
+```
+
+## 注意事项
+
+### 特异性问题
+
+主题的 CSS 经过构建后具有较高的特异性。如果你的自定义样式不生效，可以：
+
+1. **使用 `!important`**：简单粗暴但有效
+2. **增加选择器特异性**：如 `body .wi-card` 代替 `.wi-card`
+3. **使用 `:where()` 降权**：如果主题使用了 `:where()`，你可以直接覆盖
+
+### 深色模式兼容
+
+::: warning 重要
+自定义 CSS 时务必同时考虑深色模式！使用 `html.dark` 选择器为深色模式提供对应的样式。
+:::
+
+```css
+.wi-card {
+  background: #ffffff;
+  border: 1px solid #e0e0e0;
+}
+
+html.dark .wi-card {
+  background: #242018;
+  border: 1px solid #2e2822;
+}
+```
+
+### 主题升级兼容
+
+- 优先使用 CSS 变量覆盖而非直接修改元素样式
+- 避免依赖主题内部的类名结构（可能随版本变化）
+- 使用 `!important` 时添加注释说明原因
+
+### 性能考虑
+
+- 避免使用过多的 `!important`
+- 外部 CSS 文件建议压缩后部署
+- 避免使用 `*` 通配符选择器

docs/customize/development.md

@@ -0,0 +1,323 @@
+# 开发指南
+
+本文档面向 WarmIsland 主题的开发者，介绍如何搭建开发环境、构建主题以及参与贡献。
+
+## 环境要求
+
+| 工具 | 最低版本 | 推荐版本 |
+|------|----------|----------|
+| Node.js | 18.x | 20.x LTS |
+| pnpm | 8.x | 9.x |
+| Git | 2.x | 最新 |
+
+### 安装 pnpm
+
+```bash
+npm install -g pnpm
+```
+
+### 验证环境
+
+```bash
+node -v    # v20.x.x
+pnpm -v    # 9.x.x
+git --version  # git version 2.x.x
+```
+
+## 克隆与安装
+
+```bash
+git clone https://github.com/your-username/WarmIsland.git
+cd WarmIsland
+pnpm install
+```
+
+## 开发模式
+
+### 启动开发服务器
+
+```bash
+pnpm dev
+```
+
+启动后，Astro 开发服务器会在 `http://localhost:4321` 运行，支持热更新。
+
+### 使用 Halo DevTools
+
+WarmIsland 使用 `vite-plugin-halo-theme` 插件，可以与 Halo 实例联动开发：
+
+1. 确保本地 Halo 实例正在运行
+2. 在 Halo 后台安装主题的开发版本
+3. 修改源码后，主题会自动重新构建并推送到 Halo
+
+```bash
+pnpm dev:halo
+```
+
+## 构建
+
+### 生产构建
+
+```bash
+pnpm build
+```
+
+构建产物位于 `dist/` 目录，包含所有模板文件和静态资源。
+
+### 打包主题
+
+```bash
+pnpm package
+```
+
+生成 `.zip` 主题包，可直接在 Halo 后台上传安装。
+
+## 项目结构
+
+```
+WarmIsland/
+├── src/                          # 源代码
+│   ├── components/               # Astro 组件
+│   │   ├── HeroSection.astro     # Hero 首屏
+│   │   ├── PostCard.astro        # 文章卡片
+│   │   ├── Pagination.astro      # 分页组件
+│   │   ├── TableOfContents.astro # 目录组件
+│   │   ├── ReadingProgress.astro # 阅读进度条
+│   │   ├── LikeButton.astro      # 点赞按钮
+│   │   ├── CommentSection.astro  # 评论区
+│   │   ├── Footer.astro          # 页脚
+│   │   └── ...
+│   ├── layouts/                  # 布局组件
+│   │   ├── BaseLayout.astro      # 基础布局
+│   │   └── PostLayout.astro      # 文章布局
+│   ├── lib/                      # 工具库
+│   │   ├── pages.ts              # 页面路由定义
+│   │   └── utils.ts              # 工具函数
+│   ├── pages/                    # 页面入口
+│   │   ├── index.astro           # 首页
+│   │   ├── post.astro            # 文章详情
+│   │   ├── archives.astro        # 归档
+│   │   ├── categories.astro      # 分类
+│   │   ├── tags.astro            # 标签
+│   │   ├── moments.astro         # 瞬间
+│   │   ├── photos.astro          # 图库
+│   │   ├── links.astro           # 友情链接
+│   │   ├── friends.astro         # 朋友圈
+│   │   ├── page.astro            # 自定义页面
+│   │   ├── page_messageboard.astro # 留言板
+│   │   ├── douban.astro          # 豆瓣
+│   │   ├── equipments.astro      # 装备
+│   │   ├── footprints.astro      # 足迹
+│   │   └── steam.astro           # Steam
+│   └── styles/                   # 样式文件
+│       ├── main.scss             # 主样式入口
+│       ├── _variables.scss       # SCSS 变量
+│       ├── _colors.scss          # 颜色定义
+│       ├── _typography.scss      # 排版
+│       ├── _spacing.scss         # 间距
+│       ├── _animations.scss      # 动画
+│       ├── _mixins.scss          # 混入
+│       └── components/           # 组件样式
+├── templates/                    # Thymeleaf 模板（构建输出）
+├── public/                       # 静态资源
+│   └── assets/                   # 编译后的 CSS/JS
+├── docs/                         # 文档
+├── theme.yaml                    # 主题元信息
+├── settings.yaml                 # 主题设置定义
+├── astro.config.mjs              # Astro 配置
+├── package.json                  # 项目依赖
+├── tsconfig.json                 # TypeScript 配置
+└── vite.config.ts                # Vite 配置
+```
+
+## 技术栈
+
+### 核心框架
+
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| [Astro](https://astro.build) | 5.x | 静态站点生成，组件开发 |
+| [vite-plugin-halo-theme](https://github.com/halo-sigs/vite-plugin-halo-theme) | - | Halo 主题开发集成 |
+| [Thymeleaf](https://www.thymeleaf.org/) | - | Halo 服务端模板引擎 |
+
+### 前端技术
+
+| 技术 | 用途 |
+|------|------|
+| [Vue 3](https://vuejs.org/) | 交互组件（目录、点赞、无限滚动等） |
+| [SCSS](https://sass-lang.com/) | 样式预处理 |
+| [Prism.js](https://prismjs.com/) | 代码高亮 |
+| [LightGallery](https://www.lightgalleryjs.com/) | 图片灯箱 |
+
+### 构建工具
+
+| 技术 | 用途 |
+|------|------|
+| [Vite](https://vitejs.dev/) | 构建打包 |
+| [pnpm](https://pnpm.io/) | 包管理 |
+| [TypeScript](https://www.typescriptlang.org/) | 类型安全 |
+
+## 模板语法
+
+WarmIsland 使用 Astro 编写组件，构建后输出为 Thymeleaf 模板供 Halo 使用。
+
+### Astro 组件 → Thymeleaf 模板
+
+Astro 组件中的前端代码会被 `vite-plugin-halo-theme` 转换为 Thymeleaf 模板：
+
+```astro
+---
+// Astro 前置脚本
+const title = "Hello";
+---
+<h1>{title}</h1>
+```
+
+转换为 Thymeleaf：
+
+```html
+<h1 th:text="${title}">Hello</h1>
+```
+
+### Halo Finder API
+
+在模板中使用 Halo 的 Finder API 获取数据：
+
+```html
+<!-- 获取文章列表 -->
+<th:block th:each="post : ${postFinder.list(1, 10)}">
+  <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
+</th:block>
+
+<!-- 获取分类 -->
+<th:block th:each="category : ${categoryFinder.listAll()}">
+  <span th:text="${category.spec.displayName}"></span>
+</th:block>
+
+<!-- 获取标签 -->
+<th:block th:each="tag : ${tagFinder.listAll()}">
+  <span th:text="${tag.spec.displayName}"></span>
+</th:block>
+```
+
+### Vue 3 交互组件
+
+需要客户端交互的组件使用 Vue 3 编写，通过 `<script>` 标签引入：
+
+```html
+<div id="toc-app"></div>
+<script type="module" src="/assets/js/toc.js"></script>
+```
+
+## Docker 部署
+
+### 构建镜像
+
+```bash
+docker build -t warmisland-theme .
+```
+
+### 运行
+
+```bash
+docker run -d \
+  --name warmisland \
+  -p 8090:8090 \
+  -v ~/.halo2:/root/.halo2 \
+  warmisland-theme
+```
+
+### Docker Compose
+
+```yaml
+version: '3'
+services:
+  halo:
+    image: warmisland-theme
+    ports:
+      - "8090:8090"
+    volumes:
+      - ./halo2:/root/.halo2
+    restart: unless-stopped
+```
+
+## 贡献指南
+
+### 提交 Issue
+
+- 使用 GitHub Issues 提交 Bug 报告或功能建议
+- 请提供详细的复现步骤和环境信息
+- 附上截图或错误日志
+
+### 提交 Pull Request
+
+1. Fork 本仓库
+2. 创建特性分支：`git checkout -b feature/your-feature`
+3. 提交更改：`git commit -m 'feat: add your feature'`
+4. 推送分支：`git push origin feature/your-feature`
+5. 提交 Pull Request
+
+### Commit 规范
+
+使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+
+| 类型 | 说明 |
+|------|------|
+| `feat` | 新功能 |
+| `fix` | 修复 Bug |
+| `docs` | 文档更新 |
+| `style` | 样式调整（不影响功能） |
+| `refactor` | 代码重构 |
+| `perf` | 性能优化 |
+| `test` | 测试相关 |
+| `chore` | 构建/工具变更 |
+
+## 代码规范
+
+### BEM 命名
+
+WarmIsland 使用 BEM（Block Element Modifier）命名规范，前缀为 `wi-`：
+
+```
+.wi-block
+.wi-block__element
+.wi-block__element--modifier
+```
+
+**示例**：
+
+```css
+.wi-post { }                    /* Block */
+.wi-post__title { }             /* Element */
+.wi-post__title--large { }      /* Modifier */
+.wi-post__content { }           /* Element */
+.wi-post__meta { }              /* Element */
+.wi-post__meta-item { }         /* Element */
+.wi-post__like { }              /* Element */
+.wi-post__like--active { }      /* Modifier */
+```
+
+### SCSS 规范
+
+- 使用 SCSS 变量（`$variable`）定义设计 token
+- 使用 CSS 变量（`--variable`）暴露可覆盖的值
+- 嵌套不超过 3 层
+- 使用 `@mixin` 封装复用样式
+- 使用 `@include` 引入混入
+
+### Vue 组件规范
+
+- 使用 Composition API
+- 使用 `<script setup>` 语法
+- Props 使用 TypeScript 类型定义
+- 事件使用 `defineEmits`
+
+### 文件命名
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| Astro 组件 | PascalCase | `PostCard.astro` |
+| Vue 组件 | PascalCase | `TableOfContents.vue` |
+| SCSS 文件 | kebab-case | `_variables.scss` |
+| 页面文件 | kebab-case | `page_messageboard.astro` |
+| 工具文件 | camelCase | `utils.ts` |

docs/customize/style.md

@@ -0,0 +1,207 @@
+# 样式与配色
+
+WarmIsland 主题的视觉设计围绕「暖夜中的小岛」这一意象展开，追求温暖、宁静、有质感的阅读体验。
+
+## 设计哲学
+
+### 暖夜小岛
+
+想象一座深夜里温暖的小岛——远处是深邃的夜空，近处是篝火般的暖光。这就是 WarmIsland 的设计基调：
+
+- **温暖**：以暖色调为基础，避免冷硬的科技感
+- **宁静**：克制的动效和留白，不喧宾夺主
+- **质感**：毛玻璃、渐变光晕、细腻的阴影层次
+- **呼吸**：元素有节奏地律动，如岛上的微风
+
+### 设计原则
+
+1. **内容优先**：所有视觉设计服务于内容阅读
+2. **克制装饰**：每个装饰元素都有其存在的理由
+3. **层次分明**：通过颜色、字号、间距建立清晰的信息层级
+4. **温暖一致**：从配色到动效，保持统一的温暖气质
+
+## 色彩系统
+
+### 浅色模式
+
+| 变量 | 色值 | 用途 |
+|------|------|------|
+| `--bg` | `#faf7f2` | 页面背景，温暖的米白色 |
+| `--bg-raised` | `#f3ede5` | 卡片背景，略深的暖色 |
+| `--bg-overlay` | `rgba(250, 247, 242, 0.85)` | 遮罩层背景 |
+| `--ink` | `#2c2420` | 主文字色，深棕黑 |
+| `--ink-2` | `#7a6e64` | 次要文字，中灰棕 |
+| `--ink-3` | `#b5a99e` | 辅助文字，浅灰棕 |
+| `--rule` | `#e8e0d6` | 分隔线、边框 |
+| `--accent` | `#d4764e` | 强调色，温暖的赤陶橙 |
+| `--accent-hover` | `#c4613a` | 强调色悬停态，更深的赤陶 |
+| `--accent-bg` | `#fdf0e8` | 强调色浅底，用于标签背景 |
+| `--mist-pink` | `#f0e4de` | 薄雾粉，Hero 渐变用 |
+| `--sea-salt` | `#e8e0d6` | 海盐色，与 rule 相同 |
+| `--caramel` | `#8b6f5e` | 焦糖色，滚动条用 |
+| `--glass-bg` | `rgba(250, 247, 242, 0.72)` | 毛玻璃背景 |
+| `--glass-border` | `rgba(232, 224, 214, 0.5)` | 毛玻璃边框 |
+
+### 深色模式
+
+通过 `html.dark` 选择器切换，所有颜色变量重新定义：
+
+| 变量 | 色值 | 说明 |
+|------|------|------|
+| `--bg` | `#1a1614` | 深棕黑背景 |
+| `--bg-raised` | `#242018` | 略浅的卡片背景 |
+| `--ink` | `#ede6de` | 浅色主文字 |
+| `--ink-2` | `#9a8e84` | 次要文字 |
+| `--ink-3` | `#5e544a` | 辅助文字 |
+| `--accent` | `#e8955f` | 更亮的强调色（保证对比度） |
+| `--accent-hover` | `#f0a872` | 更亮的悬停态 |
+| `--accent-bg` | `#2a1e16` | 深色强调底 |
+
+### 阴影系统
+
+| 变量 | 浅色模式 | 深色模式 | 用途 |
+|------|----------|----------|------|
+| `--shadow-sm` | `0 1px 3px rgba(44, 36, 32, 0.06)` | `0 1px 3px rgba(0, 0, 0, 0.2)` | 轻微阴影 |
+| `--shadow-md` | `0 4px 16px rgba(44, 36, 32, 0.08)` | `0 4px 16px rgba(0, 0, 0, 0.25)` | 中等阴影 |
+| `--shadow-lg` | `0 8px 32px rgba(44, 36, 32, 0.12)` | `0 8px 32px rgba(0, 0, 0, 0.35)` | 大阴影 |
+| `--shadow-glow` | `0 0 40px rgba(212, 118, 78, 0.15)` | `0 0 40px rgba(232, 149, 95, 0.12)` | 强调色光晕 |
+
+## 深色模式
+
+### 切换机制
+
+深色模式通过 `html.dark` 类名控制：
+
+1. **跟随系统**（默认）：根据 `prefers-color-scheme` 媒体查询
+2. **手动切换**：通过导航栏的主题切换按钮
+3. **配置指定**：通过 `color_scheme` 配置项强制指定
+
+### 切换逻辑
+
+```javascript
+// 优先级：localStorage > 配置项 > 系统偏好
+var stored = localStorage.getItem("wi-theme");
+var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+var scheme = document.currentScript.getAttribute("data-scheme");
+
+if (stored === "dark") { isDark = true; }
+else if (stored === "light") { isDark = false; }
+else if (scheme === "dark") { isDark = true; }
+else if (scheme === "light") { isDark = false; }
+else if (!stored && prefersDark) { isDark = true; }
+```
+
+### 设计要点
+
+- 深色模式不是简单的反色，而是重新定义了所有颜色变量
+- 强调色在深色模式下更亮，保证足够的对比度
+- 阴影在深色模式下使用纯黑，更自然
+- 文字颜色保持温暖色调，不是纯白
+
+## 字体系统
+
+### 字体栈
+
+| 变量 | 字体栈 | 用途 |
+|------|--------|------|
+| `--font-sans` | `'Noto Serif SC', 'Source Han Serif SC', Georgia, serif` | 标题、强调文字 |
+| `--font-body` | `'Noto Sans SC', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif` | 正文、UI 文字 |
+| `--font-mono` | `'JetBrains Mono', 'Fira Code', monospace` | 代码 |
+
+### 设计思路
+
+- **标题用衬线体**：Noto Serif SC 赋予标题优雅的文艺气质
+- **正文用无衬线体**：Noto Sans SC 保证长文阅读的舒适度
+- **代码用等宽体**：JetBrains Mono 专为代码设计
+
+::: tip
+这些字体不会自动加载，需要在 Halo 后台或 HTML 中引入对应的字体 CSS。推荐使用 Google Fonts 或国内 CDN 镜像。
+:::
+
+## 间距系统
+
+| 变量 | 值 | 用途 |
+|------|-----|------|
+| `--space-xs` | `0.25rem` | 极小间距 |
+| `--space-sm` | `0.5rem` | 小间距 |
+| `--space-md` | `1rem` | 标准间距 |
+| `--space-lg` | `1.5rem` | 大间距 |
+| `--space-xl` | `2rem` | 超大间距 |
+| `--space-2xl` | `3rem` | 区块间距 |
+| `--space-3xl` | `4rem` | 大区块间距 |
+| `--space-4xl` | `6rem` | 页面级间距 |
+
+### 容器宽度
+
+| 变量 | 值 | 用途 |
+|------|-----|------|
+| `--container-sm` | `640px` | 小容器 |
+| `--container-md` | `768px` | 中容器 |
+| `--container-lg` | `1024px` | 大容器 |
+| `--container-xl` | `1200px` | 最大容器 |
+| `--content-max` | `800px` | 内容最大宽度 |
+
+### 区块间距
+
+`--section-spacing: clamp(3rem, 2rem + 3vw, 6rem)` — 响应式区块间距，在小屏幕上更紧凑。
+
+## 圆角系统
+
+| SCSS 变量 | 值 | 用途 |
+|-----------|-----|------|
+| `$border-radius-sm` | `8px` | 小元素（标签、代码块） |
+| `$border-radius-md` | `12px` | 中等元素（卡片、图片） |
+| `$border-radius-lg` | `16px` | 大元素（卡片、面板） |
+| `$border-radius-xl` | `24px` | 超大元素 |
+| `$border-radius-full` | `9999px` | 胶囊按钮、头像 |
+
+### 配置项
+
+通过 `border_radius` 配置项可全局调整圆角风格：
+
+| 选项 | 效果 |
+|------|------|
+| `small` | 较小的圆角 |
+| `medium` | 中等圆角（默认） |
+| `large` | 较大的圆角 |
+
+## 动画系统
+
+### 时间曲线
+
+| 变量 | 值 | 用途 |
+|------|-----|------|
+| `--ease-out-expo` | `cubic-bezier(0.16, 1, 0.3, 1)` | 弹性出场，用于悬停和展开 |
+| `--ease-out-quart` | `cubic-bezier(0.25, 1, 0.5, 1)` | 平滑出场，用于颜色过渡 |
+| `--ease-in-out-cubic` | `cubic-bezier(0.65, 0, 0.35, 1)` | 对称缓动，用于循环动画 |
+
+### 时长
+
+| 变量 | 值 | 用途 |
+|------|-----|------|
+| `--duration-fast` | `150ms` | 快速反馈（颜色变化） |
+| `--duration-normal` | `300ms` | 标准过渡（悬停效果） |
+| `--duration-slow` | `500ms` | 慢速过渡（大位移） |
+| `--duration-breath` | `3s` | 呼吸动画周期 |
+
+### 关键帧动画
+
+| 动画名 | 效果 | 用途 |
+|--------|------|------|
+| `breathe` | 透明度 0.4→0.7 + 缩放 1→1.08 | Hero 光球呼吸 |
+| `fadeInUp` | 透明度 0→1 + 上移 20px | 元素入场 |
+| `float` | 上下浮动 6px | 装饰元素 |
+| `shimmer` | 背景位置平移 | 加载占位 |
+| `scrollHint` | 透明度 + 下移 8px | 滚动指示器 |
+| `likeHeartbeat` | 缩放 1→1.3→0.9→1 | 点赞心跳 |
+
+### 动画开关
+
+| 配置 | 说明 | 默认值 |
+|------|------|--------|
+| `animation_enabled` | 启用动效 | `true` |
+| `animation_breath` | 呼吸动画 | `true` |
+| `animation_scroll_reveal` | 滚动渐入 | `true` |
+| `animation_cursor_glow` | 光感跟随 | `false` |
+
+关闭动效时，`html` 元素添加 `wi-no-animations` 类名。