# Theming

Theme axes, the accent color and its contrast rule, logo, banner, footer and the theme.css escape hatch.

A project changes its look through a fixed set of theme axes, its logo, banner and footer. Layout and components are
the same for every project. Set the axes under `theme` in `site.json` to give every project a default, and in
`project.json` to override them for one project.

```json title="project.json"
{
  "theme": {
    "accent": "#0F7B6C",
    "mode": "system",
    "grays": "cool",
    "radius": "soft",
    "header": "tinted",
    "headings": "instrument-serif",
    "code": "light"
  }
}
```

## Theme axes

| Axis | Values | Default | Effect |
|---|---|---|---|
| `accent` | `indigo`, `teal`, `orange`, `graphite` or a hex color like `#0F7B6C` | `indigo` | Project color: links, active rows, buttons, header. |
| `accentDark` | hex color | `accent` | Project color in dark mode. |
| `mode` | `light`, `dark`, `system` | `system` | Color mode a first visit opens in. Readers can switch; their choice is saved. |
| `grays` | `warm`, `cool`, `neutral` | `warm` | Gray scale of text, borders and surfaces. |
| `radius` | `sharp`, `standard`, `soft` | `standard` | Corner radius scale. |
| `header` | `neutral`, `tinted`, `solid` | `neutral` | Top bar: plain, the project color at 9% on the surface, or the project color with text on it. |
| `headings` | `geist`, `instrument-serif`, `space-grotesk` or a custom font | `geist` | Heading font. |
| `code` | `dark`, `light` | `dark` | Code block colors of the `docsp` code theme. Other code themes ignore it. |
| `css` | path to a CSS file | | Escape hatch for custom properties; see below. |

Code themes other than `docsp` are set with the top-level `code.theme` field; see [Code themes](./code-themes.md).

The color mode on first paint comes from, in order: the reader's saved choice, the project's `mode`, then the
system setting (`prefers-color-scheme`). A small script in the page head sets it before the page paints, so there is
no flash.

## Accent and contrast

For a hex accent, the build picks the text color that sits on it, white or `#1b1b1a`, whichever contrasts more,
separately for light and dark mode. Presets come with their own text colors. It then checks these pairs in both modes and fails below **4.5:1**:

- text on the accent (buttons, the solid header);
- accent text on the page surface (links);
- accent text on the active sidebar row;
- secondary header text on a `tinted` header;
- header text on the search field of a `solid` header.

The error names the project, the color, the pair and the ratio:

```text
rocket/project.json (project "rocket"): theme color #F5A623 gives 2.03:1 for accent: --accent-text (#F5A623) on --surface (light), below the required 4.5:1. Choose a darker or more saturated color.
```

`docsp check` prints the lowest ratio of each project, so you can see how much margin a color has. This site uses
`#AF3A03` with warm grays.

:::tip[Dark mode needs its own color sometimes.]
A dark accent that works on a white page can fail as link text on a dark page. Set `accentDark` to a lighter variant.
A project that sets `accent` without `accentDark` does not inherit the site's `accentDark`, since that one was chosen
for a different color.
:::

The four presets pass every check with the `neutral` and `solid` headers, in both modes and with every gray scale.
`graphite` with a `tinted` header fails with every gray scale (4.29:1 in light mode and 3.93:1 in dark mode with warm
grays): use another header with
`graphite`. `graphite` uses white text in light mode and dark text in dark mode.

## Custom heading font

```json title="project.json"
{
  "theme": {
    "headings": { "family": "Brand Sans", "src": "fonts/brand.woff2", "weight": 600 }
  }
}
```

`src` is relative to the file that declares it, may contain letters, digits, `.`, `_`, `-` and `/`, cannot contain
`..`, and must end in `.woff2`, `.woff`, `.ttf` or `.otf`. `family` may contain letters, digits, spaces, `_` and `-`.
`weight` defaults to 600. The build serves the file and writes the `@font-face` rule.

## Logo

Without a logo image, the mark is a square in the project color with one or two letters:

```json
{ "logo": { "mark": "R" } }
```

With images, `light` replaces the letters, and `dark`, when set, is shown in dark mode:

```json
{ "logo": { "light": "brand/logo.svg", "dark": "brand/logo-dark.svg" } }
```

Paths are relative to the configuration file. The logo of `site.json` is the square in the top bar of the portal; the
logo of `project.json` is used in the project selector, the portal card and the footer. A missing file fails the
build.

## Banner

A project can show one announcement above the top bar:

```json title="project.json"
{
  "banner": {
    "id": "rocket-2-4",
    "variant": "accent",
    "tag": "New",
    "text": "Rocket 2.4 is out.",
    "link": { "label": "See what's new", "href": "/rocket/changelog/2.4.0/" },
    "until": "2026-12-31"
  }
}
```

| Field | Effect |
|---|---|
| `id` | Required. A reader who closes the banner does not see it again for this id. Change the id to show a new banner. |
| `variant` | Required. `accent` for releases, `neutral` for events, `warning` for breaking changes. A `warning` banner cannot be closed. |
| `text` | Required. The announcement. |
| `link`, `tag` | Optional link after the text and a short label before it. |
| `dismissible` | `true` by default. `false` hides the close button. |
| `until` | Last day the banner shows, `YYYY-MM-DD`. |

`until` works twice: a build after that date leaves the banner out, and a page built earlier hides it in the browser
once the date has passed, using the `data-until` attribute on the banner. Closed banners are remembered in the
browser's local storage.

Pages of a deprecated version show a separate warning banner; see
[Versions and languages](./versions-and-languages.md).

## theme.css

`theme.css` is an escape hatch for values the axes do not cover. It may only redefine custom properties (`--*`) on
`:root` or `html` selectors, optionally with attribute conditions:

```css title="theme.css"
:root {
  --r-card: 10px;
}
html[data-mode="dark"] {
  --r-card: 6px;
}
```

```json title="project.json"
{ "theme": { "css": "theme.css" } }
```

The build fails, naming the selector or property, on:

- any selector other than `:root` or `html` with attribute conditions such as `[data-mode="dark"]`;
- any declaration that is not a custom property;
- at-rules such as `@media` or `@import`;
- the characters `<`, `>` and `\` anywhere in the file;
- attribute values with characters other than letters, digits, spaces and `_ . : -`.

:::warning[No contrast check here.]
Colors set in `theme.css` are not contrast-checked. The four accent properties set by the build,
`--accent-light`, `--accent-dark`, `--on-accent-light` and `--on-accent-dark`, cannot be overridden: set the color with
`accent` instead.
:::

The tokens you can redefine are in `packages/docsp/tokens/tokens.css`, and the
[token map](https://github.com/fabricatorsltd/docs-portal/blob/main/packages/docsp/docs/token-map.md) says which
design measure each one carries.

## How the theme reaches the page

The theme is applied with attributes on `<html>` (`data-mode`, `data-grays`, `data-radius`, `data-header`,
`data-code`, `data-headings`) and four inline custom properties for the accent. `tokens.css` derives every color from
them. The build gives the rules of `theme.css` an id-level selector, so they win over `tokens.css` whatever the order of the
stylesheets.
