Theme & Fonts

The default theme is editorial - a warm paper background, a vermilion accent, serif headings and monospaced metadata. This page covers the default colors and fonts, switching colors and heading fonts in app.config, adding a CJK serif font, the visitor theme picker and motion preferences.
View source
A docs page in the default theme

Default colors

The layer ships two custom color scales and sets them as the Nuxt UI defaults:

RoleScaleNotes
primaryvermilionVermilion red, 500 is #d64b34. Light mode uses 600, dark mode uses 400
neutralpaperLow-chroma warm gray, 50 is #faf9f5 (light background), 950 is #141413 (dark background)

Background, text and border colors are all derived from the current neutral scale: light mode uses 50 for the background and 900 for text, dark mode uses 950 and 200. Any neutral you pick keeps the same paper-and-ink contrast.

Changing colors

Set any Tailwind CSS color name or custom scale in app.config.ts:

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

A custom scale must declare all shades from 50 to 950 with @theme in app/assets/css/main.css:

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' }
  }
})
The layer merges app/assets/css/main.css into its own Tailwind root. Do not add @import "tailwindcss" there: it creates a second copy of the utilities that overrides the layer's responsive styles, and the build prints a warning.

Theme options

The theme group controls the layer's own visual options:

app/app.config.ts
export default defineAppConfig({
  theme: {
    radius: 0.25,
    blackAsPrimary: false,
    icons: 'lucide',
    font: 'editorial',
    grain: false
  }
})
FieldDefaultDescription
radius0.25Global border radius in rem
blackAsPrimaryfalseUse black (white in dark mode) as the primary color
icons'lucide'UI icon set; the theme picker can switch between lucide, phosphor and tabler
font'editorial'editorial uses serif headings; sans uses sans-serif everywhere, with Inter for headings
grainfalseOverlay a paper grain texture on the background only, never on text or code blocks

Fonts

The layer self-hosts three variable fonts through Fontsource, Latin subsets only:

UsageFontCSS variable
BodyInter--font-sans
HeadingsFraunces--font-serif, --font-display
Code and metadataJetBrains Mono--font-mono

The layer disables the @nuxt/fonts integration of Nuxt UI, so no other fonts are downloaded at build time. CJK characters follow the font stacks:

  • Sans-serif: Alibaba PuHuiTi (loaded by you) → PingFang SC → Hiragino Sans GB → Microsoft YaHei → Noto Sans CJK SC
  • Serif: Noto Serif SC → Source Han Serif SC → Noto Serif CJK SC, falling back to bold sans-serif when none is installed

System Song fonts often lack a bold weight, so they are not part of the serif stack.

Adding a Chinese serif font

For serif Chinese headings, load Noto Serif SC yourself. The Fontsource package is split by unicode-range, so pages only download the characters they use:

pnpm add @fontsource/noto-serif-sc
app/assets/css/main.css
/* Headings only use the bold weight */
@import "@fontsource/noto-serif-sc/700.css";

To use Alibaba PuHuiTi for Chinese body text, load a stylesheet that hosts it from app.head in nuxt.config.ts. The font family must be named 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' }
      ]
    }
  }
})

Replacing a font

Override the CSS variable to replace a whole font family:

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

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

Syntax highlighting

Code blocks use the Shiki themes github-light and github-dark, switching with the color mode. Override them in nuxt.config.ts:

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

Theme picker

The swatch button in the header opens the theme picker, where visitors can adjust the primary color, neutral color, radius, icon set and color mode.

The theme picker
  • Choices are stored in the visitor's localStorage and only affect that visitor
  • The picker compares against your app.config, so "Reset" restores your site configuration, not the layer defaults
  • "Export" copies the matching CSS variables or an app.config.ts snippet, so you can write a tuned palette back into your site config

Motion

Page navigation uses View Transitions: the title morphs between pages while the header and sidebar stay still. When the visitor's system enables reduced motion (prefers-reduced-motion: reduce), View Transitions, the sliding sidebar indicator and other transitions are all turned off.

Copyright © 2024 - 2026