# Theming

Change arene's tokens, scope a theme and control the color scheme.

The theme files are source files in your project. Edit
`theme/tokens.stylex.ts` to change the design values your components read.
[Installation](https://www.arene.style/docs/installation) adds these files before the first component.

## Change tokens

`color` uses `stylex.defineVars()`, so each value becomes a CSS variable.
Keep theme-dependent colors as `light-dark()` pairs, with the light value
first. Semantic pairs such as `primary` and `primaryForeground` need enough
contrast in both schemes.

Fixed scales such as `space`, `width`, `radius` and `text` use
`stylex.defineConsts()`. The compiler substitutes them into styles. Edit the
source to change them; `createTheme` cannot override constants. Keep each
`text` size paired with its `leading` ratio when you change the type scale.

The `interop` group publishes flat custom properties that the reset reads.
Keep those mappings connected to the color tokens when you retheme, so plain
CSS and compiled styles use the same values. The font stacks live in
`styles/theme.css`, which also imports the fonts.

## Scope a theme

Use `stylex.createTheme(color, {…})` to override color variables for a subtree.
Apply the result with `stylex.props()` on a plain ancestor element. The
`xstyle` prop accepts styles, but does not accept the theme type. You can
override a subset of the group; other values keep their existing definitions.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { color } from "@/theme/tokens.stylex"

const theme = stylex.createTheme(color, {
  primary: "light-dark(oklch(0.45 0.15 260), oklch(0.8 0.1 260))",
  primaryForeground: "light-dark(oklch(0.99 0 0), oklch(0.15 0 0))",
})

export default function ThemingScope() {
  return (
    <div {...stylex.props(theme)}>
      <Button>Save changes</Button>
    </div>
  )
}
```

CSS variables inherit through DOM ancestry. A popup portalled outside this
subtree does not inherit its theme. Apply the theme to an ancestor containing
the portal destination too, or choose the destination through the part's
portal API.

## Dark mode

`color-scheme` controls dark mode. Every color token is a `light-dark()` pair,
and `theme.css` sets `color-scheme: light dark` on `:root`, so the page follows
the OS without JavaScript. A color that differs by theme is written once as a
pair, in `tokens.stylex.ts` or in the one component that uses it.

A theme toggle only has to force the scheme. The `.light` and `.dark` classes in
`theme.css` set `color-scheme`, and every token switches with it. Set the class
before first paint. Otherwise the page shows the OS theme for a moment first.

```html title="index.html"
<script>
  ;(function () {
    try {
      var t = localStorage.getItem("theme")
      if (t === "dark" || t === "light") document.documentElement.classList.add(t)
    } catch (e) {}
  })()
</script>
```

> **Note**
>
> Use any storage key, as long as your theme switcher writes the same one. If the
> keys differ, this script never finds the saved theme and the page loads in the
> OS theme.

`light-dark()` only works on colors. A non-color value that differs by theme,
such as a transform or a `font-style`, needs two rules: a `.dark` override for
the forced scheme, plus the same rule under
`@media (prefers-color-scheme: dark) { :root:not(.light) … }` for system mode.

## Keep local changes when updating

You own the component files and every theme file. The registry does not update
them automatically. Adding or overwriting a component updates that component
and its arene dependencies, including helpers, but never the theme files.

If a new component references a missing theme module, add the module. If it
references a new key in an existing module, merge that entry into your local
file. This includes `states.ts`, whose shared styles can gain keys as components
change. Declining a file replacement keeps the whole old file.

Follow [Updating](https://www.arene.style/docs/installation#updating) for the commands. Review theme
diffs before overwriting: `add @arene/theme --overwrite` replaces the theme
files, including your token edits, width styles and visibility styles.
