[@layout]: ../docs.layout.md

# 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](./styles.reference.md).
For a complete walkthrough, follow [Theme a site](./theme-a-site.guide.md).

---

## Choose a preset

Set frontmatter on a page:

```yaml
---
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](../../examples/theme-gallery.demo.md).

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](./theme-a-site.guide.md).

---

## Colors and schemes

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

```yaml
---
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:

```css
: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.

---

## Theme settings

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

| Key | Sets |
| --- | --- |
| `preset` | A preset, as with the `theme: paper` shorthand. |
| `hue` | The seed hue for presets that derive their palette from it. |
| `scheme` | `light` or `dark`, locking the scheme. |
| `color` | `bg`, `fg`, `muted`, `surface`, `link`, `accent`, `danger`, `border`, `border-strong`, `focus`, `success`, `warning`, `on-accent`, `hover`. |
| `font` | `body`, `heading`, `mono`; see [Typography](./typography.reference.md). |
| `prose` | `size`, `leading`, `flow`, `gutter`, `scale`, `h1`, `h2`, `h3`. |
| `measure` | The document reading width, `--pmx-document-measure`. |
| `shape` | `radius`. |
| `code` | `bg`, `fg`, `comment`, `keyword`, `string`, `punctuation`. |
| `light`, `dark` | Settings that apply only in that scheme. |

Unknown keys are reported and ignored.

---

## Color and shape tokens

| Token | Purpose |
| --- | --- |
| `--pmx-color-bg` | Page background. |
| `--pmx-color-fg` | Main text. |
| `--pmx-color-muted` | Secondary text. |
| `--pmx-color-accent` | Accents and highlighted controls. |
| `--pmx-color-link` | Text links. |
| `--pmx-color-surface` | Component surfaces. |
| `--pmx-color-border` | Borders and separators. |
| `--pmx-color-border-strong` | Field and outline-button edges, at least 3:1 against the page. |
| `--pmx-color-focus` | Focus rings. |
| `--pmx-radius` | Shared corner radius. |

Use `light-dark(light, dark)` for scheme-specific colors. Font and prose tokens are
listed in [Typography](./typography.reference.md); control tokens in
[Shared UI](./ui.reference.md#shared-controls).

## Related

- [Theme a site](./theme-a-site.guide.md)
- [Typography](./typography.reference.md)
- [Stylesheets](./styles.reference.md)