Theme

import { resolveThemeCss } from "pzzadocs";
import { ThemeStyles } from "pzzadocs/ui";
import type {
  ThemeConfig,
  ResolvedThemeConfig,
  ThemeColors,
  CodeTokenColors,
  CodeThemePair,
  ThemePreset,
  ThemeDensity,
  ThemeFonts,
  ThemeLayout,
} from "pzzadocs";

ThemeConfig#

The theme section of DocsConfig. defineConfig fills in defaultTheme, hotKey, preset, codeTheme and density and returns a ResolvedThemeConfig; the override sections stay partial.

interface ThemeConfig {
  defaultTheme?: "light" | "dark" | "system";
  hotKey?: boolean;
  preset?: ThemePreset;
  colors?: { light?: Partial<ThemeColors>; dark?: Partial<ThemeColors> };
  code?: { light?: Partial<CodeTokenColors>; dark?: Partial<CodeTokenColors> };
  codeTheme?: "pzza" | CodeThemePair;
  radius?: number | string;
  fonts?: ThemeFonts;
  layout?: ThemeLayout;
  density?: ThemeDensity;
}

ResolvedThemeConfig#

interface ResolvedThemeConfig extends ThemeConfig {
  defaultTheme: "light" | "dark" | "system";
  hotKey: boolean;
  preset: ThemePreset;
  codeTheme: "pzza" | CodeThemePair;
  density: ThemeDensity;
}

ThemeColors#

One key per colour token. Any CSS colour string is accepted and used as written.

Preset values for each key are listed on the Presets page.

CodeTokenColors#

Token groups of the bundled pzza-light and pzza-dark themes. Each key maps to a set of TextMate scopes; the defaults below are what codeTheme: "pzza" ships with.

CodeThemePair#

interface CodeThemePair {
  light: ThemeRegistration;
  dark: ThemeRegistration;
}

ThemeRegistration is the shiki theme object type. Both themes are loaded into the highlighter and every token carries both colours as CSS variables, so switching schemes does not re-highlight anything.

ThemeFonts#

ThemeLayout#

Numbers are pixels; strings are used verbatim.

Design tokens#

Every custom property the stylesheet reads. Colour defaults are the mono preset.

Colour tokens#

Shape, size and motion tokens#

Density tokens#

Emitted only for density: "compact"; the comfortable values are the stylesheet defaults.

ThemeStyles#

import { ThemeStyles } from "pzzadocs/ui";

function ThemeStyles({ theme }: { theme: ResolvedThemeConfig }): JSX.Element | null;

A server component that renders a <style> element with the output of resolveThemeCss(theme). RootProvider renders it for you; include it yourself only when you build a custom provider. Pass config.theme from your defineConfig result.

import { ThemeStyles } from "pzzadocs/ui";
import config from "@/docs.config";

<ThemeStyles theme={config.theme} />

resolveThemeCss#

import { resolveThemeCss } from "pzzadocs";

function resolveThemeCss(theme: ResolvedThemeConfig): string;

Returns the CSS text ThemeStyles emits: a :root { ... } block followed by a .dark, [data-theme="dark"] { ... } block, each omitted when empty. The empty string means the config changes nothing. Resolution order:

1. The preset expands to all thirteen colour tokens for both schemes, unless it is mono.
2. colors.light and colors.dark are layered on top, key by key.
3. radius writes --pd-radius and the derived --pd-radius-sm.
4. fonts and layout write their tokens; numbers become px.
5. density: "compact" appends the compact density tokens.

String values have ;, { and } stripped so a value cannot break out of its declaration. This is a server entry; use it to inline the CSS somewhere other than ThemeStyles, for example in a static export or an email-safe preview.