# Named themes

A named theme is a full set of tokens from `@recit/theme`: colors as HSL triplets, fonts and the
motion type scale. A story that names one keeps the **same theme as a deck and as a video**: the
slides read the tokens as CSS variables, the film reads the same tokens through the motion blocks.

| Theme            | Look                                              | Mode  |
| ---------------- | ------------------------------------------------- | ----- |
| `warm-editorial` | Yeseva One and Josefin Sans over cream, deep rose | light |
| `saas-product`   | Space Grotesk on grey and white, purple primary   | light |

## Switching theme

Name the theme in the front matter of a story, whatever its format:

```md
---
title: Lorem ipsum
theme: warm-editorial
---
```

or for every story of a project, in `recit.config.ts`:

```ts title="recit.config.ts"
export default defineConfig({
  theme: { name: "saas-product" },
});
```

- In a site, the `theme` of the site config styles the site: name the story's theme in its front
  matter, or in the `recit.config.ts` next to the story.
- The other `theme` keys still apply and override the named theme, one token at a time:
  `theme: { name: "saas-product", colors: { primary: "#e11d48" } }`.
- `theme:` names a theme. The display mode is `colorMode: light | dark | system`. `theme: light`
  still works and warns, because it used to mean the mode.
- A deck opens in the mode its theme is drawn for (both are light), unless `theme.defaultMode` is
  set. The named theme keeps its tokens in both modes.
- An unknown name is a warning, and the default tokens apply.

## The same story, two formats

This story names `warm-editorial`. It is played below as slides, then as a film paused at 3.5
seconds:

<StoryEmbed slug="named-theme" />

<StoryEmbed slug="named-theme" format="motion" time={3.5} />

## In a film

A film looks for its theme in this order: the front matter `theme`, the `theme` of a nested
`motion:` block, `motion.theme` in `recit.config.ts`, then `theme.name`. A deck reads only
`theme.name` and the front matter. Use `motion.theme` when the film must differ from the slides, or
for a brand theme imported into a `themes/` folder, which only the motion format knows.

The tokens map to the film like this:

| Deck token        | Film token |
| ----------------- | ---------- |
| `background`      | `bg`       |
| `card`            | `surface`  |
| `foreground`      | `text`     |
| `mutedForeground` | `muted`    |
| `primary`         | `accent`   |
| `fonts.heading`   | `display`  |
| `fonts.sans`      | `body`     |
| `fonts.mono`      | `mono`     |

The data palette (comparison bars) and the type scale of the motion blocks are part of the named
theme too. In code, `toMotionTheme` of `@recit/theme/motion` does the conversion, and `RECIT_THEMES`
of `@recit/theme` lists the themes.