# BeitaBlog 主题样式文档

本文说明前台主题的 CSS 变量、命名、响应式和交互规范。目标是让主题好看、稳定、易维护，并且不影响后台页面。

## 样式来源

前台基础样式主要来自三部分：

- 后台配置生成的 CSS 变量，由 `generateThemeCSS($settings)` 输出。
- 当前主题的 `assets/css/theme.css`。
- 页面模板内必要的局部样式。

推荐把可复用样式放入主题 CSS，把单页特有样式放入页面模板或页面级 CSS 文件。

## 作用域规则

主题 CSS 必须加前台和主题作用域：

```css
body.front-shell.theme-my_theme .glass {
    border-color: rgba(var(--theme-primary-rgb), .24);
}

body.front-shell.theme-my_theme.route-home .hero-copy {
    max-width: 760px;
}
```

不要写这种全局规则：

```css
.card {
    margin: 20px;
}

button {
    border-radius: 999px;
}
```

原因是前后台、播放器、弹窗、付费卡片、小说阅读器都可能复用相同类名，全局覆盖会制造隐蔽 bug。

## body class

开发模板会自动注入：

- `theme-{theme_key}`，例如 `theme-my_theme`
- `route-{route}`，例如 `route-home`
- `body_class` 中自定义的类

路由类建议用于单页差异：

```css
body.front-shell.theme-my_theme.route-article .article-main {
    max-width: 860px;
}
```

## 核心 CSS 变量

颜色变量：

- `--theme-primary`
- `--theme-primary-rgb`
- `--theme-secondary`
- `--theme-secondary-rgb`
- `--theme-accent`
- `--theme-accent-rgb`
- `--theme-light`
- `--theme-dark`

背景变量：

- `--canvas`
- `--canvas-rgb`
- `--bg-1`
- `--bg-2`
- `--bg-3`
- `--bg-4`
- `--bg-light-1`
- `--bg-light-2`
- `--bg-light-3`
- `--bg-light-4`

文本变量：

- `--text-main`
- `--text-muted`
- `--text-soft`
- `--text-faint`
- `--hero-title`
- `--hero-subtitle`

卡片和边框变量：

- `--surface-base`
- `--surface-soft`
- `--surface-strong`
- `--surface-border`
- `--surface-elevated`
- `--card-radius`
- `--card-radius-sm`
- `--card-radius-lg`
- `--card-blur`

布局变量：

- `--max-width`
- `--hero-height`
- `--hero-min-height`
- `--card-thumb-height`
- `--navbar-blur`

状态变量：

- `--success`
- `--danger`
- `--tag-bg`
- `--tag-text`
- `--input-bg`
- `--input-text`

## 明暗模式

系统通过 `html[data-theme="light"]` 和 `html[data-theme="dark"]` 切换模式。

推荐写法：

```css
body.front-shell.theme-my_theme .article-panel {
    background: var(--surface-base);
    color: var(--text-main);
}

html[data-theme="light"] body.front-shell.theme-my_theme .article-panel {
    box-shadow: 0 24px 60px rgba(15, 23, 42, .08);
}
```

避免只适配暗色模式。后台设置可能让前台默认进入浅色模式。

## 间距规范

建议建立主题级 spacing token：

```css
body.front-shell.theme-my_theme {
    --space-page: clamp(18px, 3vw, 36px);
    --space-section: clamp(42px, 8vw, 96px);
    --space-card: clamp(18px, 2.4vw, 30px);
}
```

使用建议：

- 页面左右边距用 `--space-page`。
- 大区块上下间距用 `--space-section`。
- 卡片内边距用 `--space-card`。
- 不要在大量组件里散落固定 `margin: 23px` 这类魔法数字。

## 字体规范

默认主题通过后台配置输出 `--font-family`。自定义主题可以覆盖，但建议保留中文可读性：

```css
body.front-shell.theme-my_theme {
    font-family: var(--font-family);
}

body.front-shell.theme-my_theme .hero-title {
    font-family: "Noto Serif SC", "Songti SC", serif;
}
```

若引入远程字体，请在后台或 `partials/head.php` 中加载，并准备降级字体。

## 图片和媒体

文章缩略图、背景图、预览图建议：

- 使用 `object-fit: cover` 保持比例。
- 使用 `aspect-ratio` 控制卡片稳定高度。
- 图片容器加背景色，避免图片加载前布局跳动。
- 外链图失败时页面不应空白。

示例：

```css
body.front-shell.theme-my_theme .post-thumb {
    aspect-ratio: 16 / 10;
    background: rgba(var(--theme-primary-rgb), .08);
    overflow: hidden;
}

body.front-shell.theme-my_theme .post-thumb img {
    width: 100%;
    height: 100%;
    object-fit: cover;
}
```

## 动效规范

动效应短、明确、可关闭。系统会输出：

- `--anim-duration`
- `--anim-hover`

建议：

```css
body.front-shell.theme-my_theme .post-card {
    transition: transform var(--anim-duration) ease, box-shadow var(--anim-duration) ease;
}

body.front-shell.theme-my_theme .post-card:hover {
    transform: var(--anim-hover);
}
```

不要给正文、导航、弹窗持续播放大幅动画，阅读体验会变差。

## 响应式断点

推荐断点：

- `960px`：桌面到平板布局切换。
- `720px`：卡片、导航、文章正文移动端布局。
- `480px`：小屏按钮、标题字号、阅读边距。

示例：

```css
@media (max-width: 720px) {
    body.front-shell.theme-my_theme .article-main {
        padding-inline: 16px;
    }
}
```

## 文章正文

正文需要优先保证阅读：

- 行高建议 `1.85` 到 `2`。
- 中文正文宽度建议 `720px` 到 `860px`。
- 段落间距不要小于 `1em`。
- 代码块必须允许横向滚动。
- 表格必须放入可横向滚动容器。

示例：

```css
body.front-shell.theme-my_theme .article-content {
    max-width: 820px;
    line-height: 1.9;
    font-size: clamp(16px, 1.7vw, 18px);
}

body.front-shell.theme-my_theme .article-content pre {
    overflow-x: auto;
}
```

## 表单和评论

评论输入框、购买按钮、密码表单应保持明显可操作状态：

```css
body.front-shell.theme-my_theme input,
body.front-shell.theme-my_theme textarea {
    background: var(--input-bg);
    color: var(--input-text);
    border: 1px solid var(--surface-border);
}

body.front-shell.theme-my_theme input:focus,
body.front-shell.theme-my_theme textarea:focus {
    outline: 2px solid rgba(var(--theme-primary-rgb), .28);
    outline-offset: 2px;
}
```

不要隐藏评论提示、错误提示、付费状态和密码状态。

## 可访问性

- 文本和背景对比度要足够。
- 可点击元素至少 `40px` 高。
- hover 效果必须有 focus 对应样式。
- 不要只靠颜色表达状态。
- 图片按钮需要有文字、`aria-label` 或可见图标语义。

## 样式检查清单

- CSS 选择器已限制在 `body.front-shell.theme-my_theme` 下。
- 明暗模式都检查过。
- 手机端导航、文章页、小说阅读卡片不重叠。
- 文章正文、代码块、表格可读。
- 评论、密码、付费、下载按钮可操作。
- 没有覆盖后台 `.card`、`.btn`、`.alert` 等通用类。
- 图片加载失败时布局仍然稳定。
- 没有依赖不存在的字体或第三方资源。

