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 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.

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.

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

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 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.