Themes

A theme sets a site's shared colors, type and shapes through tokens. Start from a preset or the plain foundation, then adjust tokens in frontmatter or CSS.

Your own classes still style your own elements; see Stylesheets. For a complete walkthrough, follow Theme a site.

Set frontmatter on a page:

---
theme: paper
---

Core includes paper, studio, terminal, and synthwave. A theme on the root index supplies the site default. Folder indexes supply defaults for their subtrees, and a page supplies its own overrides. Settings layer from root through ancestor indexes to the page; more local values override only settings they supply. Preview a different preset with ?theme=paper, or use ?theme=default to preview the unthemed foundation. Remove the root index’s theme setting to remove the site default. Set theme: false on a page to clear inherited theme settings, or on an index to reset them for that subtree. Descendants can introduce new settings after a reset. This preserves authored CSS and layout selection.

Try the presets in the theme gallery.

A preset marks <html data-pmx-theme> and sets colors for both schemes, its typefaces and a type scale. Its fonts are served from your site with their licenses, so a preset needs no third-party requests. Object presets can supply a seed hue, for example theme: { preset: terminal, hue: 145 }. To build your own theme, start from the Glass and Bauhaus stylesheets in the gallery or follow Theme a site.

For a site designed for one scheme, set the lock and colors in the root index's frontmatter before adding layout CSS:

---
theme:
  scheme: light
  color:
    bg: "#f4f0e6"
    fg: "#282c23"
    surface: "#e5dfcf"
  code:
    bg: "#e5dfcf"
    fg: "#282c23"
---

A scheme lock is an authoring constraint and hides the scheme toggle. A preset without a lock leaves readers' saved preferences and system scheme available. Do not write a device preference merely to establish a site's design.

For a site supporting both schemes, pair each color in a stylesheet:

:root {
  --pmx-color-accent: light-dark(#6840c6, #bda2ff);
  --pmx-color-link: var(--pmx-color-accent);
  --pmx-radius: 0.75rem;
}

Check foreground and background together in both schemes, including hover and focus states.

Add <x-theme-scheme-toggle /> to a layout for a light/dark switch. Appearance applies automatically to every document, including layout-free pages, modals, and references. They share the site’s saved device preferences and follow the system color scheme when no override is selected. An authored scheme lock still applies to its Source and hides the toggle. Live updates and navigation preserve this behavior. Synthwave supports both light and dark schemes.

Check custom styles in reading, Focus, and Slides on desktop and narrow screens; every Source should present without a separate deck.

A theme: object accepts these keys. Each token key sets the matching CSS property, so color: { accent: tomato } sets --pmx-color-accent.

Unknown keys are reported and ignored.

Use light-dark(light, dark) for scheme-specific colors. Font and prose tokens are listed in Typography; control tokens in Shared UI.

• Theme a site
• Typography
• Stylesheets