Theme — tidypress

Theme

# Theme

Configure typography scale, fonts, semantic color tokens, CSS variables, and code highlighting presets.

Theme config is optional. The default is a guarded baseline theme with the `claude` code highlighting preset.

## Typography

Scales:

| Value | Use for |
|-------|---------|
| `medium` | default reading size (used when `typography` is omitted) |
| `small` | compact documentation density |
| `large` | larger marketing or narrative pages |
| `extra` | extra-large display scale (alias for `large`) |

Omit `typography` to use `medium`.

Use a smaller scale explicitly:

```ts
typography: {
  scale: 'small',
}
```

`default` and `extra` are accepted aliases. `default` resolves to `medium`; `extra` resolves to `large`.

## Theme Mode

```ts
theme: {
  mode: 'guardrailed',
  preset: 'baseline',
}
```

`guardrailed` is the default. It keeps the baseline token set and lets TidyPress handle light and dark mode safely.

`preset` currently supports:

```ts
theme: {
  preset: 'baseline',
}
```

## Code Highlighting

```ts
theme: {
  code: {
    preset: 'claude',
  },
}
```

Code presets:

| Value | Style |
|-------|-------|
| `claude` | balanced dark code theme, default |
| `jetbrains` | vibrant JetBrains-like palette |
| `github` | conservative GitHub dark style |
| `dracula` | Dracula palette |
| `material` | Material theme palette |
| `nord` | Nord palette |

Omit `theme.code` to use `claude`.

## Custom Tokens

Custom tokens require the `themingCustom` capability:

```ts
capabilities: {
  enable: ['themingCustom'],
},
theme: {
  mode: 'custom',
  tokens: {
    light: {
      background: '#ffffff',
      foreground: '#111111',
      muted: '#71717a',
      border: '#e5e5e5',
      surface: '#f4f4f4',
      accent: '#f5a623',
      codeBg: '#f4f4f4',
      codeFg: '#111111',
    },
    dark: {
      background: '#0a0a0a',
      foreground: '#fafafa',
      muted: '#a1a1aa',
      border: '#27272a',
      surface: '#18181b',
      codeBg: '#18181b',
      codeFg: '#e4e4e7',
    },
  },
  variables: {
    '--status-ok': '#35c46a',
  },
}
```

Token names are open-ended. Each semantic key is emitted as `--tp-<kebab-case-name>`; for example `accentStrong` becomes `--tp-accent-strong`.

The built-in names `bg`/`background`, `fg`/`foreground`, `muted`, `border`, `surface`, `codeBg`, and `codeFg` also update the legacy variables consumed by the default theme. Use `theme.variables` when you need an exact CSS custom-property name; keys must begin with `--`.

Use custom tokens only when the baseline theme is not enough.

## Fonts

Body, heading, and monospace fonts are first-class:

```ts
theme: {
  fonts: {
    body: { family: 'Geist Mono', source: 'google' },
    heading: 'Geist Mono',
    mono: { family: 'JetBrains Mono', source: 'system' },
  },
}
```

A string selects a system family. Descriptors support `system`, `google`, `local`, and `external` sources plus `url`, `weight`, `style`, and `display`. Local files should live in `site/public/`.

## Project CSS

Compile project-local CSS or link public/external stylesheets:

```ts
theme: {
  css: ['./src/styles/brand.css'],
},
styles: ['/styles/print.css', 'https://cdn.example.com/widget.css'],
```

`theme.css` and top-level `styles` are combined. See [Presentation API](./presentation) for scripts, slots, component overrides, custom layouts, and plugins.

Theme config is optional. The default is a guarded baseline theme with the claude code highlighting preset.

Typography

Scales:

Value	Use for
`medium`	default reading size (used when `typography` is omitted)
`small`	compact documentation density
`large`	larger marketing or narrative pages
`extra`	extra-large display scale (alias for `large`)

Omit typography to use medium.

Use a smaller scale explicitly:

typography: {
  scale: 'small',
}

default and extra are accepted aliases. default resolves to medium; extra resolves to large.

Theme Mode

theme: {
  mode: 'guardrailed',
  preset: 'baseline',
}

guardrailed is the default. It keeps the baseline token set and lets TidyPress handle light and dark mode safely.

preset currently supports:

theme: {
  preset: 'baseline',
}

Code Highlighting

theme: {
  code: {
    preset: 'claude',
  },
}

Code presets:

Value	Style
`claude`	balanced dark code theme, default
`jetbrains`	vibrant JetBrains-like palette
`github`	conservative GitHub dark style
`dracula`	Dracula palette
`material`	Material theme palette
`nord`	Nord palette

Omit theme.code to use claude.

Custom Tokens

Custom tokens require the themingCustom capability:

capabilities: {
  enable: ['themingCustom'],
},
theme: {
  mode: 'custom',
  tokens: {
    light: {
      background: '#ffffff',
      foreground: '#111111',
      muted: '#71717a',
      border: '#e5e5e5',
      surface: '#f4f4f4',
      accent: '#f5a623',
      codeBg: '#f4f4f4',
      codeFg: '#111111',
    },
    dark: {
      background: '#0a0a0a',
      foreground: '#fafafa',
      muted: '#a1a1aa',
      border: '#27272a',
      surface: '#18181b',
      codeBg: '#18181b',
      codeFg: '#e4e4e7',
    },
  },
  variables: {
    '--status-ok': '#35c46a',
  },
}

Token names are open-ended. Each semantic key is emitted as --tp-<kebab-case-name>; for example accentStrong becomes --tp-accent-strong.

The built-in names bg/background, fg/foreground, muted, border, surface, codeBg, and codeFg also update the legacy variables consumed by the default theme. Use theme.variables when you need an exact CSS custom-property name; keys must begin with --.

Use custom tokens only when the baseline theme is not enough.

Fonts

Body, heading, and monospace fonts are first-class:

theme: {
  fonts: {
    body: { family: 'Geist Mono', source: 'google' },
    heading: 'Geist Mono',
    mono: { family: 'JetBrains Mono', source: 'system' },
  },
}

A string selects a system family. Descriptors support system, google, local, and external sources plus url, weight, style, and display. Local files should live in site/public/.

Project CSS

Compile project-local CSS or link public/external stylesheets:

theme: {
  css: ['./src/styles/brand.css'],
},
styles: ['/styles/print.css', 'https://cdn.example.com/widget.css'],

theme.css and top-level styles are combined. See Presentation API for scripts, slots, component overrides, custom layouts, and plugins.