主题与字体

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

默认配色

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

角色色阶说明
primaryvermilion朱红,500 为 #d64b34。亮色模式使用 600,暗色模式使用 400
neutralpaper低彩度暖灰,50 为 #faf9f5(亮色背景),950 为 #141413(暗色背景)

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

更换颜色

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

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

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

app/assets/css/main.css
@theme static {
  --color-brand-50: #eef6ff;
  --color-brand-100: #d9eaff;
  /* ... */
  --color-brand-950: #0b1d3a;
}
app/app.config.ts
export default defineAppConfig({
  ui: {
    colors: { primary: 'brand' }
  }
})
app/assets/css/main.css 会被 Layer 自动并入同一个 Tailwind 编译根,不要在其中再写 @import "tailwindcss",否则会生成第二份工具类并覆盖 Layer 的响应式样式,构建时会给出警告。

主题选项

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

app/app.config.ts
export default defineAppConfig({
  theme: {
    radius: 0.25,
    blackAsPrimary: false,
    icons: 'lucide',
    font: 'editorial',
    grain: false
  }
})
字段默认值说明
radius0.25全局圆角,单位 rem
blackAsPrimaryfalse以黑色(暗色模式为白色)作为主色
icons'lucide'界面图标集,主题面板中可切换 lucide、phosphor、tabler
font'editorial'editorial 使用衬线标题;sans 全站使用无衬线,标题改为 Inter
grainfalse在页面背景叠加纸张颗粒质感,只作用于背景,不覆盖正文与代码块

字体

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 包,页面只下载实际用到的字:

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

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

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 变量即可整体替换某一类字体:

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 中覆盖:

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

主题面板

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

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

动效

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

Copyright © 2024 - 2026