# Code themes

Pick the colors of code blocks for a project, fix their mode, and let readers choose their own.

`code` sets the colors of code blocks. Put it in `site.json` for every project, or in `project.json` for one project;
each field of the project wins over the site.

```json title="site.json"
{ "code": { "theme": "gruvbox", "mode": "auto" } }
```

This site uses `gruvbox`. Use the palette button in the top bar to try the others on this page.

## Themes

| `code.theme` | Light mode | Dark mode |
|---|---|---|
| `docsp` (default) | The design's colors; `theme.code` picks a dark or light block | same |
| `catppuccin` | Catppuccin Latte | Catppuccin Mocha |
| `github` | GitHub Light | GitHub Dark |
| `one` | One Light | One Dark Pro |
| `solarized` | Solarized Light | Solarized Dark |
| `rose-pine` | Rose Pine Dawn | Rose Pine |
| `gruvbox` | Gruvbox Light Medium | Gruvbox Dark Medium |
| `dracula` | Dracula (dark only) | Dracula |
| `nord` | Nord (dark only) | Nord |
| `tokyo-night` | Tokyo Night (dark only) | Tokyo Night |

The families with two members follow the page mode. `dracula`, `nord` and `tokyo-night` stay dark in both modes.

## Code mode

`code.mode` fixes the mode of code blocks independently of the page:

| `code.mode` | Effect |
|---|---|
| `auto` (default) | Code follows the page: light code on a light page, dark code on a dark page. |
| `light` | Light code in both modes. Dark-only themes ignore it. |
| `dark` | Dark code in both modes, for example dark code on a light page. |

With the `docsp` theme, `theme.code` sets the block colors and `code.mode` can fix their mode the same way.

## The reader's choice

The palette button in the top bar opens a menu with "Project default", every theme and the code mode (Follow page,
Light, Dark). The choice is kept in the browser's local storage and applied by a script in the page head before the
page paints, so code does not flash in the default colors. For a dark-only theme, the Light choice is marked as not
available.

## Contrast correction

Every block is highlighted once with every theme at build time. Each combination of token colors becomes a class, and
`/_docsp/code-themes.css`, written at the end of the build, colors each class for each theme.

Some bundled themes have token colors, often comments, below 4.5:1 on their background. docsp lightens (on a dark
background) or darkens (on a light one) every such color in OKLab, toward white or black, which keeps its hue, until
it reaches 4.5:1 on the block background and on the highlighted line of a source excerpt. The code header, tabs, file
names and symbol links are derived from each theme the same way. The themes can therefore look slightly different
from their originals, and every one of them meets 4.5:1.
