# Installation

Set up StyleX and the arene theme in a Vite + React project.

You don't install arene from npm. You add each component to your project as a
source file, with the shadcn CLI or by copying it from these docs, and then edit
it like any other file.

Before you add the first component, set up StyleX and add arene's theme files.
The arene setup is written and tested for Vite + React + TypeScript. Other
bundlers are not documented. File paths are relative to `src/`.

Follow every step, then render a component to check the setup. A successful
build does not prove that the styles are correct.

## Setup

**Command**

Run the setup item. It writes `components.json` with the `@arene` registry,
`theme.css`, `interop.css` and the theme modules, then installs the StyleX
runtime, the fonts and the compiler.

```bash
npx shadcn@latest add https://www.arene.style/r/init.json
```

> **Note**
>
> Don't run `shadcn init`. It requires Tailwind, and the setup item writes the
> same `components.json`.

**Manual**

1. Install the runtime packages, then the compiler as a dev dependency.

   ```bash
   npm install @stylexjs/stylex @base-ui/react clsx @fontsource/geist-sans @fontsource/geist-mono
   ```

   ```bash
   npm install -D @stylexjs/unplugin
   ```

2. Copy `theme.css`. It holds the element reset, the `color-scheme` switch that
   controls dark mode, and the font stacks.

   ```css title="styles/theme.css"
   @import "@fontsource/geist-sans/latin.css";
   @import "@fontsource/geist-mono/latin.css";

   @font-face {
     font-family: "Geist Sans Fallback";
     src: local("Arial");
     size-adjust: 107.11%;
     ascent-override: 85.9%;
     descent-override: 20.54%;
     line-gap-override: 9.34%;
   }

   :root {
     color-scheme: light dark;

     --font-sans: "Geist Sans", "Geist Sans Fallback", ui-sans-serif, system-ui, sans-serif;
     --font-mono: "Geist Mono", ui-monospace, monospace;
   }

   .light {
     color-scheme: light;
   }

   .dark {
     color-scheme: dark;
   }

   @layer arene.base {
     *,
     ::after,
     ::before,
     ::backdrop,
     ::file-selector-button {
       box-sizing: border-box;
       margin: 0;
       padding: 0;
       border: 0 solid var(--border);
       outline-color: var(--ring-50);
     }

     html {
       line-height: 1.5;
       tab-size: 4;
       -webkit-text-size-adjust: 100%;
       -webkit-tap-highlight-color: transparent;
       font-family: var(--font-sans);
     }

     body {
       background-color: var(--background);
       color: var(--foreground);
       -webkit-font-smoothing: antialiased;
       -moz-osx-font-smoothing: grayscale;
     }

     h1,
     h2,
     h3,
     h4,
     h5,
     h6 {
       font-size: inherit;
       font-weight: inherit;
     }

     a {
       color: inherit;
       text-decoration: inherit;
     }

     b,
     strong {
       font-weight: bolder;
     }

     code,
     kbd,
     samp,
     pre {
       font-family: var(--font-mono);
       font-size: 1em;
     }

     small {
       font-size: 80%;
     }

     sub,
     sup {
       font-size: 75%;
       line-height: 0;
       position: relative;
       vertical-align: baseline;
     }

     sub {
       bottom: -0.25em;
     }

     sup {
       top: -0.5em;
     }

     table {
       text-indent: 0;
       border-color: inherit;
       border-collapse: collapse;
     }

     hr {
       height: 0;
       color: inherit;
       border-top-width: 1px;
     }

     ol,
     ul,
     menu {
       list-style: none;
     }

     summary {
       display: list-item;
     }

     img,
     svg,
     video,
     canvas,
     audio,
     iframe,
     embed,
     object {
       display: block;
       vertical-align: middle;
     }

     img,
     video {
       max-width: 100%;
       height: auto;
     }

     button,
     input,
     select,
     optgroup,
     textarea,
     ::file-selector-button {
       font: inherit;
       letter-spacing: inherit;
       color: inherit;
       border-radius: 0;
       background-color: transparent;
       opacity: 1;
     }

     button,
     input:where([type="button"], [type="reset"], [type="submit"]),
     ::file-selector-button {
       appearance: button;
     }

     textarea {
       resize: vertical;
     }

     ::placeholder {
       opacity: 1;
       color: color-mix(in oklab, currentcolor 50%, transparent);
     }

     :-moz-focusring:where(:not(iframe)) {
       outline: auto;
     }

     [hidden]:where(:not([hidden="until-found"])) {
       display: none !important;
     }
   }

   ```

3. Copy the token module. Colors are `defineVars`, and each one is a
   `light-dark()` pair. The fixed scales, such as `space`, `radius`, `width`, `text` and
   `shadow`, are `defineConsts`. The `interop` group publishes the flat custom
   properties that `theme.css` reads. See [Theming](https://www.arene.style/docs/theming) before changing these values.

   ```ts title="theme/tokens.stylex.ts"
   import * as stylex from "@stylexjs/stylex"

   export const color = stylex.defineVars({
     background: "light-dark(oklch(1 0 0), oklch(0.145 0 0))",
     foreground: "light-dark(oklch(0.145 0 0), oklch(0.985 0 0))",
     card: "light-dark(oklch(1 0 0), oklch(0.205 0 0))",
     cardForeground: "light-dark(oklch(0.145 0 0), oklch(0.985 0 0))",
     popover: "light-dark(oklch(1 0 0), oklch(0.205 0 0))",
     popoverForeground: "light-dark(oklch(0.145 0 0), oklch(0.985 0 0))",
     primary: "light-dark(oklch(0.205 0 0), oklch(0.922 0 0))",
     primaryForeground: "light-dark(oklch(0.985 0 0), oklch(0.205 0 0))",
     secondary: "light-dark(oklch(0.97 0 0), oklch(0.269 0 0))",
     secondaryForeground: "light-dark(oklch(0.205 0 0), oklch(0.985 0 0))",
     muted: "light-dark(oklch(0.97 0 0), oklch(0.269 0 0))",
     mutedForeground: "light-dark(oklch(0.556 0 0), oklch(0.708 0 0))",
     destructive: "light-dark(oklch(0.577 0.245 27.325), oklch(0.704 0.191 22.216))",
     border: "light-dark(oklch(0.922 0 0), oklch(1 0 0 / 10%))",
     input: "light-dark(oklch(0.922 0 0), oklch(1 0 0 / 15%))",
     ring: "light-dark(oklch(0.708 0 0), oklch(0.556 0 0))",

     overlay: "light-dark(oklch(0 0 0 / 10%), oklch(0 0 0 / 40%))",
     sidebar: "light-dark(oklch(0.985 0 0), oklch(0.205 0 0))",

     buttonDestructiveBg: (): string =>
       `light-dark(color-mix(in oklab, ${color.destructive} 10%, transparent), color-mix(in oklab, ${color.destructive} 20%, transparent))`,

     buttonPrimaryEdge: "light-dark(oklch(0 0 0 / 40%), oklch(0 0 0 / 10%))",
     buttonPrimaryHighlight: "light-dark(oklch(1 0 0 / 16%), oklch(1 0 0 / 60%))",
     buttonPrimarySheen: "light-dark(oklch(1 0 0 / 14%), oklch(1 0 0 / 40%))",
     buttonDestructiveHighlight: "oklch(1 0 0 / 16%)",
     buttonDrop: "light-dark(oklch(0 0 0 / 20%), oklch(0 0 0 / 50%))",
     secondaryHoverBg: "light-dark(oklch(0.94 0 0), oklch(0.3 0 0))",
     keyBg: "light-dark(oklch(0.98 0 0), oklch(0.21 0 0))",
     keyTop: "light-dark(oklch(1 0 0), oklch(1 0 0 / 5%))",
     keyEdge: "light-dark(oklch(0 0 0 / 6%), oklch(0 0 0 / 36%))",
     keyHighlight: "light-dark(oklch(1 0 0 / 90%), oklch(1 0 0 / 7%))",
     keyDrop: "light-dark(oklch(0 0 0 / 4%), oklch(0 0 0 / 30%))",

     tray: "light-dark(oklch(0.985 0 0), oklch(0.17 0 0))",
     raisedHighlight: "light-dark(transparent, oklch(1 0 0 / 4%))",
     raisedShadow: "light-dark(oklch(0.2 0 0 / 6%), oklch(0 0 0 / 16%))",
     raisedRing: "light-dark(oklch(0 0 0 / 4%), oklch(0 0 0 / 40%))",
     popupRing: "light-dark(oklch(0 0 0 / 8%), oklch(0 0 0 / 50%))",
     popupShadowNear: "light-dark(oklch(0 0 0 / 6%), oklch(0 0 0 / 24%))",
     popupShadowFar: "light-dark(oklch(0 0 0 / 8%), oklch(0 0 0 / 40%))",
     itemHighlightBg: "light-dark(oklch(0 0 0 / 4%), oklch(1 0 0 / 7%))",
     itemHighlightRing: "light-dark(oklch(0 0 0 / 6%), oklch(1 0 0 / 6%))",
     invalidRing: (): string =>
       `light-dark(color-mix(in oklab, ${color.destructive} 20%, transparent), color-mix(in oklab, ${color.destructive} 40%, transparent))`,
     inputDisabledBg: (): string =>
       `light-dark(color-mix(in oklab, ${color.input} 50%, transparent), color-mix(in oklab, ${color.input} 80%, transparent))`,
     grooveShadow: "light-dark(oklch(0 0 0 / 3.5%), oklch(0 0 0 / 18%))",
     thumbShade: "oklch(0 0 0 / 3%)",
     thumbRing: "oklch(0 0 0 / 6%)",
     raisedEdge: "oklch(0 0 0 / 8%)",
     fieldHoverEdge: "light-dark(oklch(0 0 0 / 16%), oklch(1 0 0 / 14%))",
     fieldFocusEdge: "light-dark(oklch(0 0 0 / 20%), oklch(1 0 0 / 20%))",
     fieldHalo: "light-dark(oklch(0 0 0 / 6%), oklch(1 0 0 / 12%))",
     fieldDrop: "light-dark(oklch(0 0 0 / 6%), oklch(0 0 0 / 24%))",
     fieldBg: (): string =>
       `light-dark(${color.background}, color-mix(in oklab, ${color.input} 30%, transparent))`,
     well: "light-dark(oklch(0.965 0 0), oklch(0.205 0 0))",
     wellKey: "light-dark(oklch(1 0 0), oklch(0.3 0 0))",
     wellKeyEdge: "light-dark(transparent, oklch(0 0 0 / 60%))",

     infoBorder:
       "light-dark(color-mix(in oklab, oklch(68.5% 0.169 237.323) 25%, transparent), color-mix(in oklab, oklch(74.6% 0.16 232.661) 25%, transparent))",
     infoBg:
       "light-dark(color-mix(in oklab, oklch(68.5% 0.169 237.323) 6%, transparent), color-mix(in oklab, oklch(74.6% 0.16 232.661) 6%, transparent))",
     info: "light-dark(oklch(58.8% 0.158 241.966), oklch(74.6% 0.16 232.661))",
     tipBorder:
       "light-dark(color-mix(in oklab, oklch(60.6% 0.25 292.717) 25%, transparent), color-mix(in oklab, oklch(70.2% 0.183 293.541) 25%, transparent))",
     tipBg:
       "light-dark(color-mix(in oklab, oklch(60.6% 0.25 292.717) 6%, transparent), color-mix(in oklab, oklch(70.2% 0.183 293.541) 6%, transparent))",
     tip: "light-dark(oklch(54.1% 0.281 293.009), oklch(70.2% 0.183 293.541))",
     warningBorder:
       "light-dark(color-mix(in oklab, oklch(76.9% 0.188 70.08) 30%, transparent), color-mix(in oklab, oklch(82.8% 0.189 84.429) 25%, transparent))",
     warningBg:
       "light-dark(color-mix(in oklab, oklch(76.9% 0.188 70.08) 7%, transparent), color-mix(in oklab, oklch(82.8% 0.189 84.429) 6%, transparent))",
     warning: "light-dark(oklch(66.6% 0.179 58.318), oklch(82.8% 0.189 84.429))",
     successBorder:
       "light-dark(color-mix(in oklab, oklch(69.6% 0.17 162.48) 25%, transparent), color-mix(in oklab, oklch(76.5% 0.177 163.223) 25%, transparent))",
     successBg:
       "light-dark(color-mix(in oklab, oklch(69.6% 0.17 162.48) 6%, transparent), color-mix(in oklab, oklch(76.5% 0.177 163.223) 6%, transparent))",
     success: "light-dark(oklch(59.6% 0.145 163.225), oklch(76.5% 0.177 163.223))",

     transparent: "transparent",
     current: "currentColor",
   })

   export const interop = stylex.defineVars({
     "--background": color.background,
     "--foreground": color.foreground,
     "--border": color.border,
     "--card": color.card,
     "--muted": color.muted,
     "--muted-foreground": color.mutedForeground,
     "--primary": color.primary,
     "--ring": color.ring,
     "--ring-50": `color-mix(in oklab, ${color.ring} 50%, transparent)`,
   })

   export const radius = stylex.defineConsts({
     xs: "0.125rem",
     sm: "0.25rem",
     md: "0.375rem",
     lg: "0.5rem",
     xl: "0.75rem",
     xl2: "1rem",
     xl4: "1.5rem",
     full: "9999px",
   })

   export const shadow = stylex.defineConsts({
     ring: `0 0 0 2px color-mix(in oklab, ${color.ring} 30%, transparent)`,
     ringInvalid: `0 0 0 2px ${color.invalidRing}`,
     rowRing: `0 0 0 2px ${color.ring}`,

     buttonPrimary: `inset 0 1px 0 ${color.buttonPrimaryHighlight}, 0 1px 2px ${color.buttonDrop}`,
     buttonDestructive: `inset 0 1px 0 ${color.buttonDestructiveHighlight}, 0 1px 2px ${color.buttonDrop}`,
     key: `inset 0 1px 0 ${color.keyHighlight}, 0 1px 1px ${color.keyDrop}`,

     popup: `inset 0 0 1px 1px ${color.raisedHighlight}, 0 0 0 1px ${color.popupRing}, 0 1px 2px ${color.popupShadowNear}, 0 4px 12px -2px ${color.popupShadowFar}`,
     popupLifted: `inset 0 0 1px 1px ${color.raisedHighlight}, 0 0 0 1px ${color.popupRing}, 0 2px 4px ${color.popupShadowNear}, 0 16px 40px -8px ${color.popupShadowFar}`,

     tooltip: `inset 0 1px 0 ${color.buttonPrimaryHighlight}, 0 4px 12px -2px ${color.popupShadowFar}`,

     thumb: `0 0 0 0.5px ${color.thumbRing}, 0 1px 1px ${color.keyDrop}`,

     peekLeft: `4px 0 8px -4px ${color.popupShadowNear}, 12px 0 24px -12px ${color.popupShadowFar}`,
     peekRight: `-4px 0 8px -4px ${color.popupShadowNear}, -12px 0 24px -12px ${color.popupShadowFar}`,

     raised: `inset 0 0 1px 1px ${color.raisedHighlight}, 0 1px 2px ${color.raisedShadow}, 0 0 2px ${color.raisedEdge}, 0 0 0 1px ${color.raisedRing}`,

     field: `0 2px 2px -1px ${color.fieldDrop}`,
     fieldFocus: `0 0 0 3px ${color.fieldHalo}`,

     groove: `inset 0 1px 1px ${color.grooveShadow}`,
     well: "inset 0 1px 1.5px light-dark(oklch(0 0 0 / 6%), oklch(0 0 0 / 25%))",
     wellKey:
       "inset 0 1px 0 light-dark(transparent, oklch(1 0 0 / 8%)), 0 0 0 0.5px light-dark(oklch(0 0 0 / 10%), transparent), 0 1px 2px light-dark(oklch(0 0 0 / 8%), oklch(0 0 0 / 45%)), 0 2px 4px -1px light-dark(oklch(0 0 0 / 5%), transparent)",
   })

   export const ease = stylex.defineConsts({
     out: "cubic-bezier(0, 0, 0.2, 1)",
     standard: "cubic-bezier(0.4, 0, 0.2, 1)",
     decelerate: "cubic-bezier(0.32, 0.72, 0, 1)",
     tactile: "cubic-bezier(0.4, 0.36, 0, 1)",
     spring:
       "linear(0, 0.0575, 0.1802, 0.3206, 0.4549, 0.5727, 0.6709, 0.7499, 0.812, 0.86, 0.8965, 0.9239, 0.9444, 0.9596, 0.9707, 0.9789, 0.9848, 0.9891, 0.9922, 0.9944, 0.996, 0.9972, 0.998, 0.9986, 1)",
   })

   export const duration = stylex.defineConsts({
     fade: "100ms",
     color: "150ms",
     modal: "150ms",
     sheen: "300ms",
     move: "200ms",
     slide: "250ms",
     stackFade: "250ms",
     panel: "300ms",
     sheet: "400ms",
     drawer: "450ms",
     stack: "500ms",
   })

   export const layer = stylex.defineConsts({
     raised: 1,
     overlay: 10,
     sticky: 20,
     popup: 50,
   })

   export const font = stylex.defineConsts({
     sans: "var(--font-sans)",
     mono: "var(--font-mono)",
   })

   export const space = stylex.defineConsts({
     s0: "0",
     s0_5: "0.125rem",
     s1: "0.25rem",
     s1_5: "0.375rem",
     s2: "0.5rem",
     s2_5: "0.625rem",
     s3: "0.75rem",
     s3_5: "0.875rem",
     s4: "1rem",
     s5: "1.25rem",
     s6: "1.5rem",
     s7: "1.75rem",
     s8: "2rem",
     s9: "2.25rem",
     s10: "2.5rem",
     s12: "3rem",
     s16: "4rem",
     s24: "6rem",
   })

   export const width = stylex.defineConsts({
     narrow: "12rem",
     xs: "20rem",
     sm: "24rem",
     md: "28rem",
     lg: "32rem",
     xl3: "48rem",
   })

   export const text = stylex.defineConsts({
     xs: "0.75rem",
     compact: "0.8rem",
     code: "0.8125rem",
     sm: "0.875rem",
     base: "1rem",
     lg: "1.125rem",
     xl2: "1.5rem",
     xl3: "1.875rem",
     xl4: "2.25rem",
   })

   export const leading = stylex.defineConsts({
     xs: "calc(1 / 0.75)",
     compact: "calc(1.125 / 0.8)",
     code: "1.75",
     sm: "calc(1.25 / 0.875)",
     base: "1.5",
     lg: "calc(1.75 / 1.125)",
     xl2: "calc(2 / 1.5)",
     xl3: "calc(2.25 / 1.875)",
     xl4: "calc(2.5 / 2.25)",
   })

   export const tracking = stylex.defineConsts({
     tight: "-0.025em",
     widest: "0.1em",
   })
   ```

4. Copy the breakpoints. In StyleX a media query is a key inside a property's
   value, not a block around the rule, so a breakpoint is a constant you import.

   ```ts title="theme/breakpoints.stylex.ts"
   import * as stylex from "@stylexjs/stylex"

   export const breakpoints = stylex.defineConsts({
     sm: "@media (width >= 40rem)",
     md: "@media (width >= 48rem)",
     lg: "@media (width >= 64rem)",
     xl: "@media (width >= 80rem)",
     maxSm: "@media (width < 40rem)",
     maxMd: "@media (width < 48rem)",
     maxLg: "@media (width < 64rem)",
     maxXl: "@media (width < 80rem)",
   })
   ```

5. Copy the markers. A marker lets a part read an ancestor's state. An accordion's
   chevron uses one to change when its trigger is hovered. StyleX only compiles
   markers declared in a `.stylex.ts` file.

   ```ts title="theme/markers.stylex.ts"
   import * as stylex from "@stylexjs/stylex"

   export const codeBlock = stylex.defineMarker()

   export const drawerPopup = stylex.defineMarker()

   export const sidebarMenuItem = stylex.defineMarker()

   export const accordionTrigger = stylex.defineMarker()
   ```

6. Copy the shared state styles: the focus ring, the invalid ring, the disabled dim
   and the two popup surfaces. Every component merges these into its own styles
   instead of repeating them.

   ```ts title="theme/states.ts"
   import * as stylex from "@stylexjs/stylex"

   import { color, layer, radius, shadow, space } from "./tokens.stylex"

   const invalidBorder = `light-dark(${color.destructive}, color-mix(in oklab, ${color.destructive} 50%, transparent))`
   const inputBg = `light-dark(transparent, color-mix(in oklab, ${color.input} 30%, transparent))`
   const fieldEdge = "light-dark(oklch(0 0 0 / 10%), oklch(1 0 0 / 8%))"

   export const states = stylex.create({
     transparent: { opacity: 0 },
     popupTransparent: { opacity: 0, transform: "scale(0.95)" },
     popupSlideTop: { transform: `scale(0.95) translateY(${space.s2})` },
     popupSlideBottom: { transform: `scale(0.95) translateY(calc(-1 * ${space.s2}))` },
     popupSlideLeft: { transform: `scale(0.95) translateX(${space.s2})` },
     popupSlideRight: { transform: `scale(0.95) translateX(calc(-1 * ${space.s2}))` },
     instant: { transitionDuration: "0s" },

     focusRing: {
       borderColor: {
         default: `var(--arene-border-color, ${color.transparent})`,
         ":focus-visible": color.ring,
       },
       boxShadow: { default: null, ":focus-visible": shadow.ring },
       outlineStyle: "none",
     },

     focusWithinRing: {
       borderColor: {
         default: `var(--arene-border-color, ${color.transparent})`,
         ":focus-within": color.ring,
       },
       boxShadow: { default: null, ":focus-within": shadow.ring },
       outlineStyle: "none",
     },

     ring: { borderColor: color.ring, boxShadow: shadow.ring },

     rowFocusRing: {
       boxShadow: { default: null, ":focus-visible": shadow.rowRing },
       outlineStyle: "none",
     },

     invalidRing: {
       borderColor: invalidBorder,
       boxShadow: { default: shadow.ringInvalid, ":focus-visible": shadow.ringInvalid },
     },

     disabled: { opacity: 0.5, pointerEvents: "none" },

     popupSurface: {
       backgroundColor: color.popover,
       color: color.popoverForeground,
       boxShadow: shadow.popup,
       outlineStyle: "none",
     },

     itemHighlight: {
       backgroundColor: color.itemHighlightBg,
       boxShadow: `inset 0 0 0 1px ${color.itemHighlightRing}`,
     },

     itemHighlightDestructive: {
       backgroundColor: `color-mix(in oklab, ${color.destructive} 6%, transparent)`,
       boxShadow: `inset 0 0 0 1px color-mix(in oklab, ${color.destructive} 10%, transparent)`,
     },

     key: {
       "--arene-border-color": color.keyEdge,
       backgroundColor: color.keyBg,
       backgroundImage: `linear-gradient(to bottom, ${color.keyTop}, transparent)`,
       backgroundOrigin: "border-box",
       "--arene-key-surface": shadow.key,
     },

     choice: {
       "--arene-border-color": color.input,
       backgroundColor: inputBg,
     },

     choiceChecked: {
       "--arene-border-color": color.primary,
       backgroundColor: color.primary,
       color: color.primaryForeground,
     },

     keySurface: {
       boxShadow: {
         default: "var(--arene-key-surface)",
         ":focus-visible": `var(--arene-key-surface), ${shadow.ring}`,
       },
     },

     fieldSurface: {
       "--arene-border-color": fieldEdge,
       borderColor: {
         default: "var(--arene-border-color)",
         ":hover": color.fieldHoverEdge,
         ":focus-visible": color.fieldFocusEdge,
       },
       backgroundColor: { default: color.fieldBg, ":disabled": color.inputDisabledBg },
       backgroundClip: "padding-box",
       boxShadow: { default: shadow.field, ":focus-visible": `${shadow.field}, ${shadow.fieldFocus}` },
     },

     fieldFocused: {
       borderColor: color.fieldFocusEdge,
       boxShadow: `${shadow.field}, ${shadow.fieldFocus}`,
     },

     fieldFocusedInset: {
       "::after": {
         content: "''",
         position: "absolute",
         inset: 0,
         zIndex: layer.overlay,
         borderRadius: "inherit",
         boxShadow: `inset 0 0 0 1px ${color.fieldFocusEdge}, inset 0 0 0 3px ${color.fieldHalo}`,
         pointerEvents: "none",
       },
     },

     well: {
       backgroundColor: color.well,
       boxShadow: shadow.well,
     },

     wellKey: {
       "--arene-border-color": color.wellKeyEdge,
       backgroundColor: color.wellKey,
       backgroundImage: "none",
       "--arene-key-surface": shadow.wellKey,
     },

     popupItem: {
       borderRadius: `max(0px, calc(var(--arene-popup-radius, ${radius.lg}) - ${space.s1}))`,
     },

     iconTile: {
       display: "inline-flex",
       alignItems: "center",
       justifyContent: "center",
       flexShrink: 0,
       borderRadius: radius.lg,
       backgroundColor: color.card,
       boxShadow: `0 0 0 1px ${color.border}`,
       color: color.foreground,
     },

     trayFooter: {
       position: "relative",
       padding: `var(--arene-tray-spacing, ${space.s3})`,
       paddingBlockStart: `calc(${radius.xl} + var(--arene-tray-spacing, ${space.s3}))`,
       backgroundColor: color.tray,
       "::before": {
         content: "''",
         position: "absolute",
         insetInline: 0,
         insetBlockStart: `calc(-1 * ${space.s1})`,
         height: `calc(${radius.xl} + ${space.s1})`,
         borderEndStartRadius: radius.xl,
         borderEndEndRadius: radius.xl,
         backgroundColor: `var(--arene-tray-body-bg, ${color.popover})`,
         boxShadow: shadow.raised,
         clipPath: `inset(${space.s1} 0 calc(-1 * ${space.s2}) 0)`,
         pointerEvents: "none",
       },
     },

     srOnly: {
       position: "absolute",
       width: 1,
       height: 1,
       padding: 0,
       margin: -1,
       overflow: "hidden",
       clipPath: "inset(50%)",
       whiteSpace: "nowrap",
       borderWidth: 0,
     },

     positioner: { isolation: "isolate", zIndex: layer.popup, outlineStyle: "none" },
   })

   export const popupSlide = {
     top: states.popupSlideTop,
     bottom: states.popupSlideBottom,
     left: states.popupSlideLeft,
     right: states.popupSlideRight,
     "inline-start": states.popupSlideLeft,
     "inline-end": states.popupSlideRight,
   }
   ```

7. Copy the width and visibility styles. Pass `widths.xs` through `xstyle` for a
   full-width element capped at 20rem. The keys are `narrow` (12rem), `xs` (20rem),
   `sm` (24rem), `md` (28rem), `lg` (32rem) and `xl3` (48rem). These styles read
   the `width` constants in `tokens.stylex.ts`. In a mixed style entry, read a
   constant directly, such as `maxWidth: width.md`, to keep the entry cohesive.

   ```ts title="theme/widths.ts"
   import * as stylex from "@stylexjs/stylex"

   import { width } from "./tokens.stylex"

   export const widths = stylex.create({
     narrow: { width: "100%", maxWidth: width.narrow },
     xs: { width: "100%", maxWidth: width.xs },
     sm: { width: "100%", maxWidth: width.sm },
     md: { width: "100%", maxWidth: width.md },
     lg: { width: "100%", maxWidth: width.lg },
     xl3: { width: "100%", maxWidth: width.xl3 },
   })
   ```

   Choose a visibility style that names the element's visible display.
   `visibility.flexFromMd` is hidden below 48rem and flex from 48rem upward;
   `visibility.flexBelowMd` is flex below 48rem and hidden above it.
   The inline-flex pair uses `inlineFlexFromMd` and `inlineFlexBelowMd`.
   `flexFromSm`, `blockFromSm`, `blockFromMd` and `blockFromXl` show from 40rem,
   40rem, 48rem and 80rem respectively. Each style writes both display states,
   because StyleX replaces the whole display property when styles are merged.

   ```ts title="theme/visibility.ts"
   import * as stylex from "@stylexjs/stylex"

   import { breakpoints } from "./breakpoints.stylex"

   export const visibility = stylex.create({
     flexFromSm: { display: { default: "none", [breakpoints.sm]: "flex" } },
     blockFromSm: { display: { default: "none", [breakpoints.sm]: "block" } },
     flexBelowMd: { display: { default: "flex", [breakpoints.md]: "none" } },
     flexFromMd: { display: { default: "none", [breakpoints.md]: "flex" } },
     inlineFlexBelowMd: { display: { default: "inline-flex", [breakpoints.md]: "none" } },
     inlineFlexFromMd: { display: { default: "none", [breakpoints.md]: "inline-flex" } },
     blockFromMd: { display: { default: "none", [breakpoints.md]: "block" } },
     blockFromXl: { display: { default: "none", [breakpoints.xl]: "block" } },
   })
   ```

8. Copy the state-styles helper. Base UI passes a part's state to `className` and
   `style` callbacks, and `stylex.props()` returns both a class and a style. The
   helper builds both callbacks from one list of styles, so a dynamic style keeps
   its inline variable.

   ```ts title="lib/state-styles.ts"
   import type { CSSProperties } from "react"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"

   type VarStyles = StyleXStyles<{ [key: `--${string}`]: string | number }>

   type ExpressionStyles = StyleXStyles<{ zIndex: string }>

   type Marker = ReturnType<typeof stylex.defineMarker>

   type StyleList = ReadonlyArray<
     StyleXStyles | VarStyles | ExpressionStyles | Marker | false | null | undefined
   >

   type StateProps<State> = {
     className: (state: State) => string
     style: (state: State) => CSSProperties | undefined
   }

   type Overrides = {
     className?: string
     style?: CSSProperties
     hook?: string
   }

   export function stateStyles<State>(
     resolve: (state: State) => StyleList,
     { className, style, hook }: Overrides = {},
   ): StateProps<State> {
     return {
       className: (state) => clsx(hook, stylex.props(...resolve(state)).className, className),
       style: (state) => {
         const merged: CSSProperties = { ...stylex.props(...resolve(state)).style, ...style }
         return Object.keys(merged).length > 0 ? merged : undefined
       },
     }
   }
   ```

9. Copy `interop.css`. It holds the rules StyleX can't express: `@property`
   registrations, the scroll-driven edge masks, sizing for icons inside components
   and the drawer's gesture rules.

   ```css title="styles/interop.css"
   .no-scrollbar {
     -ms-overflow-style: none;
     scrollbar-width: none;
   }

   .no-scrollbar::-webkit-scrollbar {
     display: none;
   }

   @property --scroll-fade-t {
     syntax: "<length-percentage>";
     inherits: false;
     initial-value: 0px;
   }

   @property --scroll-fade-b {
     syntax: "<length-percentage>";
     inherits: false;
     initial-value: 0px;
   }

   @property --scroll-fade-s {
     syntax: "<length-percentage>";
     inherits: false;
     initial-value: 0px;
   }

   @property --scroll-fade-e {
     syntax: "<length-percentage>";
     inherits: false;
     initial-value: 0px;
   }

   @property --scroll-fade-mask {
     syntax: "*";
     inherits: false;
   }

   @keyframes scroll-fade-reveal-t {
     from {
       --scroll-fade-t: 0px;
     }
     to {
       --scroll-fade-t: var(--_scroll-fade-size-t, min(12%, 2.5rem));
     }
   }

   @keyframes scroll-fade-reveal-b {
     from {
       --scroll-fade-b: var(--_scroll-fade-size-b, min(12%, 2.5rem));
     }
     to {
       --scroll-fade-b: 0px;
     }
   }

   @keyframes scroll-fade-reveal-s {
     from {
       --scroll-fade-s: 0px;
     }
     to {
       --scroll-fade-s: var(--_scroll-fade-size-s, min(12%, 2.5rem));
     }
   }

   @keyframes scroll-fade-reveal-e {
     from {
       --scroll-fade-e: var(--_scroll-fade-size-e, min(12%, 2.5rem));
     }
     to {
       --scroll-fade-e: 0px;
     }
   }

   .scroll-fade-y {
     --_scroll-fade-size-t: var(--scroll-fade-t-size, var(--scroll-fade-size, min(12%, 2.5rem)));
     --_scroll-fade-size-b: var(--scroll-fade-b-size, var(--scroll-fade-size, min(12%, 2.5rem)));
     --scroll-fade-block: linear-gradient(
       to bottom,
       transparent 0,
       #000 var(--scroll-fade-t, 0px),
       #000 calc(100% - var(--scroll-fade-b, 0px)),
       transparent 100%
     );
     -webkit-mask-image: var(--scroll-fade-mask, var(--scroll-fade-block));
     mask-image: var(--scroll-fade-mask, var(--scroll-fade-block));
     -webkit-mask-composite: source-in;
     mask-composite: intersect;
     -webkit-mask-repeat: no-repeat;
     mask-repeat: no-repeat;
   }

   .scroll-fade-x {
     --_scroll-fade-size-s: var(--scroll-fade-s-size, var(--scroll-fade-size, min(12%, 2.5rem)));
     --_scroll-fade-size-e: var(--scroll-fade-e-size, var(--scroll-fade-size, min(12%, 2.5rem)));
     --scroll-fade-inline: linear-gradient(
       to right,
       transparent 0,
       #000 var(--scroll-fade-s, 0px),
       #000 calc(100% - var(--scroll-fade-e, 0px)),
       transparent 100%
     );
     -webkit-mask-image: var(--scroll-fade-mask, var(--scroll-fade-inline));
     mask-image: var(--scroll-fade-mask, var(--scroll-fade-inline));
     -webkit-mask-composite: source-in;
     mask-composite: intersect;
     -webkit-mask-repeat: no-repeat;
     mask-repeat: no-repeat;
   }

   .scroll-fade-x:where([dir="rtl"], [dir="rtl"] *) {
     --scroll-fade-inline: linear-gradient(
       to left,
       transparent 0,
       #000 var(--scroll-fade-s, 0px),
       #000 calc(100% - var(--scroll-fade-e, 0px)),
       transparent 100%
     );
   }

   @supports (animation-timeline: scroll()) {
     .scroll-fade-y {
       animation:
         scroll-fade-reveal-t 1ms ease-in-out,
         scroll-fade-reveal-b 1ms ease-in-out;
       animation-timeline: scroll(self y), scroll(self y);
       animation-range:
         0 var(--scroll-fade-reveal, 6rem),
         calc(100% - var(--scroll-fade-reveal, 6rem)) 100%;
       animation-fill-mode: both;
     }

     .scroll-fade-x {
       animation:
         scroll-fade-reveal-s 1ms ease-in-out,
         scroll-fade-reveal-e 1ms ease-in-out;
       animation-timeline: scroll(self inline), scroll(self inline);
       animation-range:
         0 var(--scroll-fade-reveal, 6rem),
         calc(100% - var(--scroll-fade-reveal, 6rem)) 100%;
       animation-fill-mode: both;
     }

     .scroll-fade-x.scroll-fade-y {
       animation:
         scroll-fade-reveal-t 1ms ease-in-out,
         scroll-fade-reveal-b 1ms ease-in-out,
         scroll-fade-reveal-s 1ms ease-in-out,
         scroll-fade-reveal-e 1ms ease-in-out;
       animation-timeline: scroll(self y), scroll(self y), scroll(self inline), scroll(self inline);
       animation-range:
         0 var(--scroll-fade-reveal, 6rem),
         calc(100% - var(--scroll-fade-reveal, 6rem)) 100%,
         0 var(--scroll-fade-reveal, 6rem),
         calc(100% - var(--scroll-fade-reveal, 6rem)) 100%;
       animation-fill-mode: both;
     }
   }

   @supports not (animation-timeline: scroll()) {
     .scroll-fade-y {
       --scroll-fade-t: var(--_scroll-fade-size-t);
       --scroll-fade-b: var(--_scroll-fade-size-b);
     }

     .scroll-fade-x {
       --scroll-fade-s: var(--_scroll-fade-size-s);
       --scroll-fade-e: var(--_scroll-fade-size-e);
     }
   }

   .scroll-fade-x.scroll-fade-y {
     -webkit-mask-image: var(--scroll-fade-block), var(--scroll-fade-inline);
     mask-image: var(--scroll-fade-block), var(--scroll-fade-inline);
   }

   [data-variant="outline"][aria-haspopup][aria-expanded="true"],
   [data-variant="ghost"][aria-haspopup][aria-expanded="true"],
   [data-variant="secondary"][aria-haspopup][aria-expanded="true"] {
     background-color: var(--arene-menu-open-bg);
     color: var(--arene-menu-open-fg);
   }

   [data-sidebar="menu-button"][aria-haspopup][aria-expanded="true"] {
     background-color: var(--arene-menu-open-bg);
     color: var(--arene-menu-open-fg);
   }

   [data-sidebar="menu-action"][aria-expanded="true"] {
     opacity: 1;
   }

   :where([data-slot="combobox-clear"] ~ [data-slot="combobox-trigger"]) {
     display: none;
   }

   [data-slot="drawer-overlay"][data-swiping] {
     transition-duration: 0s;
   }

   :is([data-slot="drawer-popup"], [data-slot="drawer-overlay"])[data-ending-style] {
     transition-duration: calc(var(--drawer-swipe-strength) * 400ms);
   }

   @media (prefers-reduced-motion: reduce) {
     :is([data-slot="drawer-popup"], [data-slot="drawer-overlay"])[data-ending-style] {
       transition-duration: 0s;
     }
   }

   :where([data-slot="alert"]) > svg {
     grid-column: 1;
     grid-row: 1 / span 2;
     margin-inline-end: 0.75rem;
     translate: 0 0.125rem;
     color: var(--arene-alert-accent);
   }

   :where([data-slot="alert-title"], [data-slot="alert-description"], [data-slot="marker-content"]) a {
     text-decoration-line: underline;
     text-underline-offset: 3px;
   }

   :where([data-slot="alert-title"], [data-slot="alert-description"], [data-slot="marker-content"])
     a:hover {
     color: var(--foreground);
   }

   :where([data-slot="alert-description"]) p:not(:last-child) {
     margin-block-end: 1rem;
   }

   :where([data-slot="card"]) > img:first-child {
     margin-block-start: calc(-1 * var(--arene-card-spacing));
   }

   :where(.arene-icons) svg {
     width: var(--arene-icon-size, 1rem);
     height: var(--arene-icon-size, 1rem);
     flex-shrink: 0;
     pointer-events: none;
   }

   :where([data-slot="field-description"]) a {
     text-decoration-line: underline;
     text-underline-offset: 4px;
   }

   :where([data-slot="field-description"]) a:hover {
     color: var(--primary);
   }

   :where([data-slot="resizable-handle"]:is([data-separator="hover"], [data-separator="active"])) {
     color: var(--ring);
   }

   :where([data-slot="attachment-media"][data-variant="image"]) > img {
     width: 100%;
     height: 100%;
     object-fit: cover;
   }

   ```

The remaining steps edit files your project already has. The CLI can't edit
them, so you do these steps on both paths.

1. Add the StyleX plugin to your Vite config. Put it first in the array, so it
   compiles your source before the React plugin transforms it.

   ```ts title="vite.config.ts"
   import path from "node:path"
   import { defineConfig } from "vite"
   import react from "@vitejs/plugin-react"
   import stylex from "@stylexjs/unplugin/vite"

   export default defineConfig({
     plugins: [
       stylex({
         aliases: { "@/*": [path.join(import.meta.dirname, "src/*")] },
         useCSSLayers: { before: ["arene.base"] },
       }),
       react(),
     ],
     resolve: { tsconfigPaths: true },
     build: { cssTarget: ["chrome123", "edge123", "firefox120", "safari17.5"] },
   })
   ```

   You need all four options:

   - `aliases` lets the compiler resolve `@/theme/tokens.stylex`. Without it the
     build fails with "Could not resolve the path to the imported file".
   - `useCSSLayers` puts the reset layer from `theme.css` under every StyleX class.
     Without it the reset's `* { margin: 0 }` overrides every StyleX declaration.
   - `resolve.tsconfigPaths` lets Vite resolve the same `@/` imports.
   - `build.cssTarget` stops Vite's CSS minifier from rewriting `light-dark()`,
     which every color token uses.

   The plugin appends the compiled CSS to your bundle. You don't need an `@import`
   or a virtual module.

2. Set `browserslist`. The StyleX compiler passes it to lightningcss as the target.
   With the default list, lightningcss replaces `light-dark()` with a polyfill that
   only works in a production bundle, so the color tokens stop working in dev. The
   list below is Baseline 2024, the same browser versions as `cssTarget` above.

   ```json title="package.json"
   {
     "browserslist": ["chrome >= 123", "edge >= 123", "firefox >= 120", "safari >= 17.5"]
   }
   ```

3. Point `@/*` at `src/` in both `tsconfig.json` and `tsconfig.app.json`. Vite and
   TypeScript read `tsconfig.app.json`. The shadcn CLI reads only the root file to
   decide where a component goes, and without the alias there it writes into a
   folder literally named `@`. If you copy by hand, nothing reads the root entry.

   ```json title="tsconfig.json"
   {
     "compilerOptions": {
       "paths": { "@/*": ["./src/*"] }
     }
   }
   ```

   ```json title="tsconfig.app.json"
   {
     "compilerOptions": {
       "paths": { "@/*": ["./src/*"] }
     }
   }
   ```

   In `tsconfig.node.json`, which type-checks `vite.config.ts`, set
   `"module": "esnext"` and `"moduleResolution": "bundler"`. Under the template's
   `nodenext`, TypeScript reads the StyleX plugin's default export as a namespace,
   and `tsc -b` fails with "This expression is not callable".

4. Delete the template's `src/index.css` and its import. It sets `--border` and
   `color-scheme` on `:root` outside any layer, which overrides arene's values.
   Then import both stylesheets at the top of your entry file, `theme.css` first.

   ```tsx title="main.tsx"
   import "./styles/theme.css"
   import "./styles/interop.css"
   ```

5. Add your first component. The CLI also adds the arene components and helpers
   it imports, and installs its npm dependencies.

   ```bash
   npx shadcn@latest add @arene/button
   ```

   Without the CLI, follow the **Manual** tab on the component's page.

   Then render it and check that it is styled. A missing compiler alias throws.
   An alias pointing at the wrong existing file leaves an undefined hashed `var()`
   in the CSS. Add the [lint and build checks](https://www.arene.style/docs/styling#lint-and-build-checks)
   to catch these mistakes in your project.

   > **Note**
   >
   > The first `vite` start after installing can show an "Invalid empty selector"
   > overlay from the StyleX plugin. Reload the page once. The production build is
   > not affected.

## Existing components.json

If the project already has a `components.json`, the setup item would ask to
overwrite it. Add the registry to your existing file instead, then add the
theme and the compiler:

```bash
npx shadcn@latest registry add @arene=https://www.arene.style/r/{name}.json
```

```bash
npx shadcn@latest add @arene/theme
```

```bash
npm install -D @stylexjs/unplugin
```

Then make the edits under [Setup](#setup), from the Vite config on.

Set `"rsc": true` in `components.json`. With `false`, the CLI strips
`"use client"` from about half the files it writes, and `--diff` reports changes
that aren't there. Vite ignores the directive. Leave `tailwind.cssVariables` at
its default, `true`.

> **Warning**
>
> Don't add arene to a project that uses shadcn/ui components. Both write
> `button.tsx`, `input.tsx`, `dialog.tsx`, `label.tsx`, `field.tsx` and more into
> the same `ui` alias, so arene's files overwrite shadcn/ui's. Both also define
> `--background`, `--foreground`, `--border`, `--card`, `--muted`, `--primary`,
> `--ring`, `--font-sans` and `--font-mono` on `:root`. This path is for a
> `components.json` that pulls from other registries.

## Updating

Nothing updates a component after you add it. To see what changed upstream, run
`add` with `--diff` and the file's path. Without a path, the CLI shows only the
first five files.

```bash
npx shadcn@latest add @arene/button --diff src/components/ui/button.tsx
```

To get new theme modules such as `widths.ts` and `visibility.ts`, add the theme
without `--overwrite` and decline replacement of files you have edited:

```bash
npx shadcn@latest add @arene/theme
```

For new entries in existing files, such as `states.ts` or `tokens.stylex.ts`,
compare the upstream source in [Setup](#setup) and merge the missing entries
into your local files before using the updated component. Declining replacement
keeps the old file, so it does not add those entries.

Or copy the missing modules from [Setup](#setup). Adding a component does not
bring new theme modules because theme imports are skipped as dependencies.

`--overwrite` rewrites the component, along with the arene components and
helpers it pulls in. It never writes the theme files, so it keeps your edits to
`tokens.stylex.ts`. To get theme updates, re-run the setup item or add the theme
with `--overwrite`. Both replace your edits to the token files.

```bash
npx shadcn@latest add @arene/theme --overwrite
```

## Writing UI

Read [Styling](https://www.arene.style/docs/styling) for overrides, tokens and checks, and
[Layout](https://www.arene.style/docs/layout) for composing a page. [Theming](https://www.arene.style/docs/theming) explains
changing tokens, scoping a theme and dark mode.

### Field state

`Field` shares its state with its layout parts through `field-state.ts`. The CLI
adds the file with any component that imports it. If you copy by hand, copy it
from here when a component's manual steps name it.

```ts title="lib/field-state.ts"
"use client"

import { createContext } from "react"
import type { Field } from "@base-ui/react/field"

export const FieldStateContext = createContext<Field.Root.State | null>(null)
```
