---
title: "主题与字体"
description: "默认主题采用编辑风：暖灰纸面、朱红强调色、衬线标题与等宽元信息。本页说明默认配色与字体、如何通过 app.config 切换颜色与标题字体、引入中文衬线字体，以及访客主题面板与动效偏好的行为。"
canonical_url: "https://docs.mhaibaraai.cn/docs/guide/theme"
---
# 主题与字体

> 默认主题采用编辑风：暖灰纸面、朱红强调色、衬线标题与等宽元信息。本页说明默认配色与字体、如何通过 app.config 切换颜色与标题字体、引入中文衬线字体，以及访客主题面板与动效偏好的行为。

::u-color-mode-image{alt="默认主题下的文档页" class="rounded-md border border-default" dark="/screenshots/theme-overview-dark.png" light="/screenshots/theme-overview-light.png"}
::

## 默认配色

Layer 内置两组自定义色阶，并设为 Nuxt UI 的默认颜色：

| 角色 | 色阶 | 说明 |
| --- | --- | --- |
| `primary` | `vermilion` | 朱红，`500` 为 `#d64b34`。亮色模式使用 `600`，暗色模式使用 `400` |
| `neutral` | `paper` | 低彩度暖灰，`50` 为 `#faf9f5`（亮色背景），`950` 为 `#141413`（暗色背景） |

背景、正文与边框颜色都由当前 `neutral` 色阶派生：亮色模式以 `50` 为背景、`900` 为正文，暗色模式以 `950` 为背景、`200` 为正文。因此改用任意 neutral 时，纸面与墨色的层次依然成立。

### 更换颜色

在 `app.config.ts` 中指定任意 Tailwind CSS 色名或自定义色阶：

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'emerald',
      neutral: 'zinc'
    }
  }
})
```

自定义色阶需要在 `app/assets/css/main.css` 中用 `@theme` 声明完整的 `50`–`950`：

```css [app/assets/css/main.css]
@theme static {
  --color-brand-50: #eef6ff;
  --color-brand-100: #d9eaff;
  /* ... */
  --color-brand-950: #0b1d3a;
}
```

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    colors: { primary: 'brand' }
  }
})
```

> [!WARNING]
> 
> app/assets/css/main.css
> 
>  会被 Layer 自动并入同一个 Tailwind 编译根，
> 
> 不要
> 
> 在其中再写 
> 
> @import "tailwindcss"
> 
> ，否则会生成第二份工具类并覆盖 Layer 的响应式样式，构建时会给出警告。

## 主题选项

`theme` 分组控制 Layer 自己的视觉选项：

```ts [app/app.config.ts]
export default defineAppConfig({
  theme: {
    radius: 0.25,
    blackAsPrimary: false,
    icons: 'lucide',
    font: 'editorial',
    grain: false
  }
})
```

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| `radius` | `0.25` | 全局圆角，单位 rem |
| `blackAsPrimary` | `false` | 以黑色（暗色模式为白色）作为主色 |
| `icons` | `'lucide'` | 界面图标集，主题面板中可切换 `lucide`、`phosphor`、`tabler` |
| `font` | `'editorial'` | `editorial` 使用衬线标题；`sans` 全站使用无衬线，标题改为 Inter |
| `grain` | `false` | 在页面背景叠加纸张颗粒质感，只作用于背景，不覆盖正文与代码块 |

## 字体

Layer 通过 Fontsource 自托管三款可变字体，只包含拉丁字符：

| 用途 | 字体 | CSS 变量 |
| --- | --- | --- |
| 正文 | Inter | `--font-sans` |
| 标题 | Fraunces | `--font-serif`、`--font-display` |
| 代码与元信息 | JetBrains Mono | `--font-mono` |

Layer 关闭了 Nuxt UI 的 `@nuxt/fonts` 集成，不会在构建期下载其他字体。中文字符按字体栈回退：

- 无衬线：Alibaba PuHuiTi（需使用方自行加载）→ PingFang SC → Hiragino Sans GB → Microsoft YaHei → Noto Sans CJK SC
- 衬线：Noto Serif SC → Source Han Serif SC → Noto Serif CJK SC，均未安装时回退到无衬线粗体

系统宋体常缺少粗体字重，因此没有列入衬线字体栈。

### 引入中文衬线字体

中文标题想要衬线效果，需要使用方加载 Noto Serif SC。推荐使用按 `unicode-range` 分片的 Fontsource 包，页面只下载实际用到的字：

```bash [pnpm]
pnpm add @fontsource/noto-serif-sc
```

```bash [npm]
npm install @fontsource/noto-serif-sc
```

```bash [yarn]
yarn add @fontsource/noto-serif-sc
```

```bash [bun]
bun add @fontsource/noto-serif-sc
```

```css [app/assets/css/main.css]
/* 标题只用到粗体，按需引入 700 字重即可 */
@import "@fontsource/noto-serif-sc/700.css";
```

如果希望中文正文使用阿里巴巴普惠体，可在 `nuxt.config.ts` 的 `app.head` 中引入托管该字体的样式表，字体名需为 `Alibaba PuHuiTi`：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  app: {
    head: {
      link: [
        { rel: 'preconnect', href: 'https://cdn.example.com', crossorigin: '' },
        { rel: 'stylesheet', href: 'https://cdn.example.com/fonts/alibaba-puhuiti.css' }
      ]
    }
  }
})
```

### 替换字体

覆盖 CSS 变量即可整体替换某一类字体：

```css [app/assets/css/main.css]
@import "@fontsource-variable/source-serif-4/index.css";

@theme {
  --font-serif: 'Source Serif 4 Variable', 'Noto Serif SC', serif;
}
```

## 代码高亮

代码块使用 Shiki 的 `github-light` 与 `github-dark` 主题，随颜色模式切换。需要更换主题时在 `nuxt.config.ts` 中覆盖：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  content: {
    build: {
      markdown: {
        highlight: {
          theme: { default: 'vitesse-light', light: 'vitesse-light', dark: 'vitesse-dark' }
        }
      }
    }
  }
})
```

## 主题面板

页头的调色盘按钮打开主题面板，访客可以即时调整主色、中性色、圆角、图标集与颜色模式。

::u-color-mode-image{alt="主题面板" class="rounded-md border border-default" dark="/screenshots/theme-picker-dark.png" light="/screenshots/theme-picker-light.png"}
::

- 选择结果保存在访客浏览器的 `localStorage` 中，只影响该访客
- 面板以 `app.config` 中的配置为基准判断是否已修改，「重置」恢复到站点配置而非 Layer 默认值
- 「导出」可复制对应的 CSS 变量或 `app.config.ts` 片段，方便把调好的配色写回站点配置

## 动效

页面切换使用 View Transitions：标题在页面之间形变，页头与侧栏保持静止。访客系统开启「减少动态效果」（`prefers-reduced-motion: reduce`）时，View Transitions、侧栏指示条滑动与其他过渡动画全部关闭。


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
