Themes

A theme changes the dashboard's colours. Everything else stays the same: the pixel titles, the thick outlines, the layout and the fonts are Pepper's design, described in the brand book. That keeps every theme looking like Pepper, and it means a theme is one small file anyone can make.

Light, dark, or match your device

Open Settings: the gear at the foot of the left rail on a laptop, or at the top right on a phone. Under Appearance, each choice shows a small preview of Today, the dashboard's first tab:

Appearance	What you see
Match device (the default)	Follows your device, light or dark
Light	Always the light screen
Dark	Always the dark screen

Appearance is separate from the colours. Pepper ships one colour theme, One-bit: warm silver and ink. How to choose a theme in Settings is on Themes.

What a theme is

A theme is a JSON file in the themes/ folder. This is the default theme, themes/onebit.json:

{
  "$schema": "./theme.schema.json",
  "id": "onebit",
  "label": "Default",
  "author": "Pepper",
  "description": "Warm silver and ink. Follows your device: light by day, dark when it prefers dark.",
  "light": { "bg": "#B1AFA8", "fg": "#312F28", "red": "#A11F17", "redI": "#F05A4B", "green": "#2C6626", "greenI": "#7CC56C" },
  "dark":  { "bg": "#312F28", "fg": "#B1AFA8", "red": "#F05A4B", "redI": "#A11F17", "green": "#7CC56C", "greenI": "#2C6626" }
}

Field	What it is
`id`	2 to 32 lowercase letters, digits and dashes, starting with a letter. The file must be named `<id>.json`. Don't use `paper`, `workshop`, `pepper`, `pepper-navy`, `navy`, `onebit-cool` or `dark`: older versions used those names, and choosing one opens the default theme.
`label`	The name in Settings, up to 40 characters.
`author`	Your name or handle, up to 40 characters.
`description`	One sentence on how it looks, up to 160 characters.
`light`	The light palette. If there's no `dark`, it's used whichever appearance you choose.
`dark`	Optional, and recommended. Used for the Dark appearance, and for Match device when the device is in dark mode.

Each palette names the same six colours, as #rrggbb. The dashboard is ink on paper: bg is the paper, fg the ink, and an ink plate is a block filled solid with ink, with paper-coloured text on it. The chili is Pepper's logo.

Colour	Where it shows
`bg`	The paper: the page background, and text on filled ink plates
`fg`	The ink: text, outlines, filled plates and the dither patterns
`red`	Overdue and urgent, on the paper
`redI`	Overdue and urgent, on ink plates
`green`	The chili stem and pixel-icon accents, on the paper
`greenI`	The chili stem, on ink plates

Every shade on the dashboard is drawn with these six. There are no greys to set: a lighter shade is a dither pattern, a fine checkerboard of ink dots on paper.

The rules

A theme needs at least this much contrast between each pair, and npm run pepper -- theme check tells you which pairs fall short:

Pair	Minimum contrast
`fg` on `bg` (body text)	4.5 : 1
`red` on `bg`	3 : 1
`redI` on `fg`	3 : 1
`green` on `bg`	3 : 1
`greenI` on `fg`	3 : 1

These are contrast ratios as WCAG 2, the web accessibility standard, measures them: 1 : 1 is the same colour, 21 : 1 is black on white. A dark palette is checked the same way.

Some rules can't be checked by a script, so reviewers look for them when you share a theme in a pull request:

Two tones. bg and fg are the whole look. Use the accent colours only for the things they mark.
Red means urgent. It is also the chili and the accent on Pepper's avatar, so it has to read as red.
A dark palette makes a real dark screen. Swapping paper and ink is a fine start (the default does that), but check both previews in Settings: the accents have to read on the new paper too.

Make a theme

Start from the default theme:
```
npm run pepper -- theme new forest
```
This writes themes/forest.json. Set the label, your name, a description and the colours. Editors that read JSON Schema (VS Code and others) suggest the fields and flag bad colours as you type.
Check it:
```
npm run pepper -- theme check themes/forest.json
```
It prints every problem in plain words, with the ratio of any pair that falls short, so a near miss is easy to fix. Once the file passes, it prints every ratio.
See it: restart Pepper, open the dashboard and go to Settings > Colour theme. A file that fails the check is left off the page, and npm run pepper -- theme list says why. Keep themes/onebit.json as it is: without a valid default, the dashboard and the theme commands won't start.
Share it: open a pull request on Pepper's GitHub repository that adds themes/forest.json, with a screenshot of its previews in Settings. The tests check every file in themes/, so an invalid theme fails the checks.

With an AI assistant

An AI assistant can write a theme for you. Connect yours to these docs (how). As well as reading this page, it gets two theme tools:

Tool	What it does
`list_themes`	The JSON file of every theme that ships, plus the six colours and the contrast rules
`check_theme`	Checks a theme's JSON against the rules and returns each problem, and every contrast ratio once it passes

So you can ask for a theme in plain words, for example "make me a Pepper theme in forest greens, light and dark", and the assistant can write the file and check it before giving it to you.

How it works

themes/theme.mjs holds the rules and turns a theme into CSS. The dashboard and pepper theme import it, and the docs site's two tools use a copy made when the site is built, so the rules are the same everywhere. Only the dashboard and pepper theme check see the file's name; check_theme tells the assistant what to name it.

At startup the dashboard reads every file in themes/ and appends the accepted themes' colours to its stylesheet: on <html data-theme="<id>"> for the page, with the appearance set by data-mode (auto, light or dark), and on data-preview="<id> light|dark" for the previews in Settings. The choices are saved as the dashTheme and dashMode settings. A theme chosen in an older version opens as One-bit, and a dark theme chosen before carries over as the Dark appearance.