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