Styling
Write StyleX styles with arene's tokens, overrides and shared states.
Write your app's styles with stylex.create(). Use arene's tokens for design
values and pass styles to components through xstyle.
Override props
xstyle takes StyleX styles. Each component merges it last, so your declarations
win over its own. It can take an array of styles, including conditional entries.
className is a hook for plain CSS. Components concatenate it without resolving
conflicts. Use xstyle when a declaration must override the component's style.
style is ordinary inline CSS. Use it for values you only know at runtime,
such as a measured width. Keep design values in compiled styles.
Tokens
Import tokens from theme/tokens.stylex.ts. The groups have different jobs:
| Group | Use |
|---|---|
color | Semantic colors and control materials, with light and dark values. |
interop | Flat custom properties for CSS, including the reset's border and ring colors. |
space | Gaps, padding and control dimensions. |
width | Named content widths. |
radius | Corner radii. |
shadow | Focus rings, control shadows and raised surfaces. |
font | Sans and mono font stacks. |
text | Font sizes. |
leading | The line height paired with each font size. |
tracking | Letter spacing. |
duration | Transition durations. |
ease | Transition timing functions. |
layer | Stacking levels for raised, overlay, sticky and popup elements. |
Always write fontSize and lineHeight together. text.sm is only a size.
Without leading.sm, it inherits the ancestor's line height and changes the
spacing of the type scale. The leading tokens are unitless ratios, so their
line boxes scale with the font size.
Keep entries whole
A shared style replaces a whole entry or carries shared behaviour. Do not turn each CSS property into a named style and assemble a component from those names. A reader should see what an entry does without following a list of fragments.
This fragments a caption into utilities:
Keep the caption together instead:
Both versions use text, leading, color and width from
theme/tokens.stylex.ts. Repeating a token in two cohesive entries is fine.
Extract a style when the entries have the same job, or when they share behaviour
such as a focus ring. StyleX deduplicates atomic declarations in the output;
you do not need a utility for each declaration to reduce CSS.
Merge once per element
Pass every style for an element to one stylex.props() call. Later styles win
for properties they define, including all conditions on that property.
Concatenating the classes from two calls leaves competing atomic declarations
in the element's class list. Stylesheet order then decides which wins.
Spread the complete result onto your element. It can include style as well
as className, because dynamic StyleX styles use inline variables. If you add
a plain CSS hook, combine it with sx.className and keep sx.style. A separate
className attribute beside the spread overwrites the spread's class.
Reuse exported styles
Components export style maps for use on other elements. buttonStyles has
base, variants and sizes; textStyles has sizes, tones and weights.
On your own element, merge the exported styles in that element's
stylex.props() call. A style map supplies appearance, not keyboard behaviour
or semantics.
On a arene component, pass a style through xstyle so the receiving component
merges it correctly. This applies one whole tone entry:
Breakpoints
Import breakpoints from theme/breakpoints.stylex.ts. A media query is a key
inside a property's value. Write default alongside the breakpoint so the
property has a value on both sides. The scale is sm at 40rem, md at 48rem,
lg at 64rem and xl at 80rem, with maxSm through maxXl for below each one.
The Layout guide shows this on a Stack.
Shared states
Import states from theme/states.ts for shared behaviour and materials.
It includes focus and invalid rings, disabled dimming, row highlights, popup
surfaces, field surfaces, keys and wells. It also provides srOnly, popup
positioning and transition states. transparent sets opacity to zero;
popupTransparent also scales down. popupSlide maps popup sides to slide
styles. instant sets the transition duration to zero.
Merge a state only when it applies. states.disabled changes appearance and
pointer events; it does not set the native disabled attribute. On Base UI
parts, use their state callbacks. The stateStyles helper from
lib/state-styles.ts returns both callbacks, preserving the inline variables
from stylex.props().
For your own control, merge its entry before states.focusRing so the shared
state owns the border color and focus shadow, including their focus conditions.
It reads --arene-border-color for the resting border. Set that variable in
the control entry instead of a flat borderColor, which would replace the
focus condition if merged after the state. These two entries do not compete
for properties, so reversing them currently gives the same result.
Ancestor state
For state your component knows, merge a conditional style. For an ancestor's
state, use stylex.when.ancestor() with a marker. Declare your own marker in a
.stylex.ts file, which is required for the compiler to recognize it:
Import stylex from @stylexjs/stylex in that file. Add the marker to the
ancestor's stylex.props() call, then use it in the child's property value:
Use context when children need an ancestor's data, such as orientation, rather than a CSS state. Keep selectors for DOM you do not render in plain CSS.
Focus, motion and color schemes
Keep keyboard focus visible. Reuse states.focusRing or states.rowFocusRing
when you style a control. Do not remove the outline without a replacement.
Name the properties you transition. For motion, put
"@media (prefers-reduced-motion: reduce)": "0s" inside transitionDuration.
The control example above does this for color changes. Progress indicators
that must communicate activity can keep an opacity pulse under reduced motion.
Color tokens already use light-dark(). Read the same token in either scheme;
you do not need a dark selector. See Theming for the
scheme switch and local themes.
Lint and build checks
The component registry does not install these checks. Add them to your app alongside the compiler so mistakes in your own styles fail before release.
Lint styles
Install oxlint and the StyleX ESLint plugin. Oxlint's JavaScript plugins require Node 22.18 or newer.
Copy the lint plugin to scripts/stylex-lint.mjs at your project root. It
rejects a fontSize without lineHeight in the same StyleX style object.
Copy this config to the root, or merge its jsPlugins and rules into your
existing oxlint config. These are the rules arene runs: valid-styles checks
style values, no-unused checks unused styles, valid-shorthands rejects
unsupported shorthands, and enforce-extension checks token module filenames.
Check compiled tokens
Copy this Vite plugin to plugins/stylex-token-check.ts at your project root.
It checks all emitted CSS together and rejects hashed StyleX variables without
a definition. It runs at build time, not in dev, and does not check arbitrary
custom properties or whether a token has the intended value.
Add it after your StyleX and React plugins in vite.config.ts:
A missing compiler alias throws during compilation. An alias pointing at the
wrong existing file can instead leave an undefined hashed var() in the CSS.
This check catches that second case. Keep the alias and browser targets from
Installation, then run your production build.