# arene

> An opinionated React design system built on Base UI and StyleX. Every component is a source file you add to your project and own.

arene has no package. Its components are source files that the shadcn CLI writes into
the project from arene's registry, as `@arene/<name>`. Each component page also
lists its dependencies and carries its full source, for copying by hand. Either way the
imports point at `@/components/ui/*`, `@/theme/*` and `@/lib/*`. Do the quick setup below
first. It sets up the StyleX compiler and the token layer every component reads, which
`add` does not install. Skip it and a component renders unstyled, with no error or warning.

Every link below is Markdown. The same page as HTML is at the URL without `.md`.

## Quick setup

Written and tested for Vite + React + TypeScript. Other bundlers are not documented.
Paths are relative to `src/`. Each step is explained
on [Installation](https://www.arene.style/docs/installation.md).

1. Run `npx shadcn@latest add https://www.arene.style/r/init.json`. It writes `components.json` with the
   `@arene` registry, `styles/theme.css`, `styles/interop.css` and `theme/*`, and installs StyleX,
   the fonts and `@stylexjs/unplugin`. Do not run `shadcn init`: it requires Tailwind. Adding a
   component never writes the theme; this step does.
   If the project already has a `components.json`, run
   `npx shadcn@latest registry add @arene=https://www.arene.style/r/{name}.json`,
   `npx shadcn@latest add @arene/theme` and `npm install -D @stylexjs/unplugin` instead, and
   set `"rsc": true` in it. Never add arene to a project with shadcn/ui components: the file names
   and `:root` variables are the same, and arene's overwrite theirs.
2. In `vite.config.ts`, put `stylex()` from `@stylexjs/unplugin/vite` first in `plugins`, with
   `aliases: { "@/*": [path.join(import.meta.dirname, "src/*")] }` and
   `useCSSLayers: { before: ["arene.base"] }`. Add `resolve: { tsconfigPaths: true }` and
   `build: { cssTarget: ["chrome123", "edge123", "firefox120", "safari17.5"] }`.
3. In `package.json`, set `"browserslist": ["chrome >= 123", "edge >= 123", "firefox >= 120", "safari >= 17.5"]`.
4. In both `tsconfig.json` and `tsconfig.app.json`, set `"paths": { "@/*": ["./src/*"] }`. The
   CLI reads the root file; without it, components land in a literal `@/` folder. In
   `tsconfig.node.json`, set `"module": "esnext"` and `"moduleResolution": "bundler"`.
5. Delete `src/index.css` and its import. Import `"./styles/theme.css"`, then
   `"./styles/interop.css"`, at the top of `main.tsx`.
6. Add each component with `npx shadcn@latest add @arene/<name>`. The CLI adds the
   arene components and helpers it imports and installs its npm dependencies. To compare with
   upstream later, run `npx shadcn@latest add @arene/<name> --diff src/components/ui/<name>.tsx`.

Without the CLI, step 1 becomes
`npm install @stylexjs/stylex @base-ui/react clsx @fontsource/geist-sans @fontsource/geist-mono`,
`npm install -D @stylexjs/unplugin` and copies of `styles/theme.css`, `styles/interop.css`,
`theme/tokens.stylex.ts`, `theme/breakpoints.stylex.ts`, `theme/markers.stylex.ts`,
`theme/states.ts`, `lib/state-styles.ts` and `lib/field-state.ts` from Installation. Step 6
becomes: run the `npm install` line under **Manual** on the component's page and paste its
source into `components/ui/<name>.tsx`.

Check the result by rendering a component: an unresolved token drops its CSS without failing
the build. The first `vite` start can show an "Invalid empty selector" overlay; reload once.

## Guides

- [Installation](https://www.arene.style/docs/installation.md): Set up StyleX and the arene theme in a Vite + React project.
- [Styling](https://www.arene.style/docs/styling.md): Write StyleX styles with arene's tokens, overrides and shared states.
- [Layout](https://www.arene.style/docs/layout.md): Compose pages with Stack, Grid, Container and arene's type styles.
- [Theming](https://www.arene.style/docs/theming.md): Change arene's tokens, scope a theme and control the color scheme.
- [React Hook Form](https://www.arene.style/docs/forms/react-hook-form.md): Build forms with React Hook Form, Zod and the Field component.

## Components

- [Accordion](https://www.arene.style/docs/components/accordion.md): A stack of headings that each open and close a section of content.
- [Alert](https://www.arene.style/docs/components/alert.md): A notice that stands out from the page to tell the reader something important.
- [Alert Dialog](https://www.arene.style/docs/components/alert-dialog.md): A modal dialog that stops the user to confirm or cancel an important action.
- [Attachment](https://www.arene.style/docs/components/attachment.md): A file or image attachment with its media, metadata, upload state and actions.
- [Avatar](https://www.arene.style/docs/components/avatar.md): A person's picture, with initials shown while it loads or if it fails.
- [Badge](https://www.arene.style/docs/components/badge.md): A small label for a status, a count or a category.
- [Breadcrumb](https://www.arene.style/docs/components/breadcrumb.md): Displays the path to the current resource using a hierarchy of links.
- [Bubble](https://www.arene.style/docs/components/bubble.md): The surface for one piece of a conversation, with variants, alignment, groups, reactions and collapsible content.
- [Button](https://www.arene.style/docs/components/button.md): A button for actions, with styles that a link can reuse.
- [Button Group](https://www.arene.style/docs/components/button-group.md): A container that groups related buttons with shared borders and outer corners only.
- [Calendar](https://www.arene.style/docs/components/calendar.md): A month grid for picking a date, several dates or a range.
- [Card](https://www.arene.style/docs/components/card.md): A surface that groups a header, a body and a footer.
- [Carousel](https://www.arene.style/docs/components/carousel.md): A row of slides that scrolls by swipe, drag, arrow keys or buttons.
- [Checkbox](https://www.arene.style/docs/components/checkbox.md): A control that lets the user toggle between checked and not checked.
- [Checkbox Group](https://www.arene.style/docs/components/checkbox-group.md): Shares selection state across a set of checkboxes.
- [Code Block](https://www.arene.style/docs/components/code-block.md): Displays code, terminal output and tool results in a raised panel, with a title, copy and wrap.
- [Collapsible](https://www.arene.style/docs/components/collapsible.md): An interactive component that expands and collapses a panel.
- [Combobox](https://www.arene.style/docs/components/combobox.md): An input that filters a list of options as you type.
- [Command](https://www.arene.style/docs/components/command.md): A searchable list of actions, on the page or in a dialog.
- [Container](https://www.arene.style/docs/components/container.md): A padded and centred content column.
- [Context Menu](https://www.arene.style/docs/components/context-menu.md): A menu of actions for the thing under the pointer, opened by a right click or a long press.
- [Data Table](https://www.arene.style/docs/components/data-table.md): A table with sorting, filtering, pagination, row selection and column visibility, built on TanStack Table.
- [Date Picker](https://www.arene.style/docs/components/date-picker.md): A field that opens a calendar in a popover.
- [Dialog](https://www.arene.style/docs/components/dialog.md): A window that opens over the page and makes the content behind it inert.
- [Drawer](https://www.arene.style/docs/components/drawer.md): A panel that enters from an edge of the screen and is dismissed by swiping it back.
- [Dropdown Menu](https://www.arene.style/docs/components/dropdown-menu.md): A list of actions and options that opens from a button.
- [Empty](https://www.arene.style/docs/components/empty.md): Displays an empty state.
- [Field](https://www.arene.style/docs/components/field.md): Combine labels, controls, and help text to compose accessible form fields and grouped inputs.
- [Fieldset](https://www.arene.style/docs/components/fieldset.md): Groups related controls under a shared legend.
- [Form](https://www.arene.style/docs/components/form.md): Validates fields and displays server errors.
- [Grid](https://www.arene.style/docs/components/grid.md): Equal columns or a grid that fits its available width.
- [Heading](https://www.arene.style/docs/components/heading.md): A semantic heading with an independent visual size.
- [Hover Card](https://www.arene.style/docs/components/hover-card.md): A card that previews what is behind a link while the pointer rests on it.
- [Input](https://www.arene.style/docs/components/input.md): Displays a form input field for a single line of text.
- [Input Group](https://www.arene.style/docs/components/input-group.md): Puts icons, text and buttons inside a single input frame.
- [Input OTP](https://www.arene.style/docs/components/input-otp.md): Accepts a one-time password one character per slot, with paste and keyboard support.
- [Kbd](https://www.arene.style/docs/components/kbd.md): Displays a keyboard key or a combination of keys.
- [Label](https://www.arene.style/docs/components/label.md): Renders an accessible caption for a form control.
- [Marker](https://www.arene.style/docs/components/marker.md): A status line, system note, bordered row or labelled divider inside a conversation.
- [Menubar](https://www.arene.style/docs/components/menubar.md): A row of menus that stays on screen and holds an application's commands.
- [Message](https://www.arene.style/docs/components/message.md): Lays out one turn in a conversation, with an avatar, a header, the message content, a footer and alignment.
- [Message Scroller](https://www.arene.style/docs/components/message-scroller.md): The scroll container for a chat transcript. It anchors each turn, opens a saved thread where you choose, follows a streaming reply, keeps your place while history loads and scrolls to any message.
- [Meter](https://www.arene.style/docs/components/meter.md): Displays a numeric measurement within a range.
- [Middle Truncate](https://www.arene.style/docs/components/middle-truncate.md): Shortens a string in the middle, so a path, a hash or a URL keeps both its start and its end.
- [Navigation Menu](https://www.arene.style/docs/components/navigation-menu.md): A row of site links whose triggers open panels of further links.
- [Number Field](https://www.arene.style/docs/components/number-field.md): A numeric input with increment and decrement buttons and a draggable label.
- [Pagination](https://www.arene.style/docs/components/pagination.md): Page numbers with previous and next links.
- [Popover](https://www.arene.style/docs/components/popover.md): A floating panel that opens from a button and can hold any content.
- [Progress](https://www.arene.style/docs/components/progress.md): Displays an indicator showing the completion progress of a task.
- [Questionnaire](https://www.arene.style/docs/components/questionnaire.md): A multi-step form that asks one question at a time, with single-choice, multiple-choice, freeform and skippable questions.
- [Radio Group](https://www.arene.style/docs/components/radio-group.md): A set of radio buttons where no more than one can be checked at a time.
- [Resizable](https://www.arene.style/docs/components/resizable.md): Panels that resize when the handle between them is dragged or moved with the arrow keys.
- [Scroll Area](https://www.arene.style/docs/components/scroll-area.md): A scrolling region with scrollbars that look the same in every browser.
- [Select](https://www.arene.style/docs/components/select.md): Displays a list of options for the user to pick from, opened from a button.
- [Separator](https://www.arene.style/docs/components/separator.md): A horizontal or vertical line between pieces of content.
- [Sheet](https://www.arene.style/docs/components/sheet.md): A dialog that slides in from an edge of the screen and holds content related to the page.
- [Sidebar](https://www.arene.style/docs/components/sidebar.md): A collapsible app sidebar that renders as a sheet on small screens.
- [Skeleton](https://www.arene.style/docs/components/skeleton.md): Shows a placeholder while content is loading.
- [Slider](https://www.arene.style/docs/components/slider.md): An input where the user selects a value from within a given range.
- [Spinner](https://www.arene.style/docs/components/spinner.md): An indicator that shows a loading state.
- [Stack](https://www.arene.style/docs/components/stack.md): Flex layout as props, on a closed spacing scale.
- [Switch](https://www.arene.style/docs/components/switch.md): A control that lets the user toggle between checked and not checked.
- [Table](https://www.arene.style/docs/components/table.md): Rows and columns of data, with a header, a body and a footer.
- [Tabs](https://www.arene.style/docs/components/tabs.md): A set of layered sections of content, known as tab panels, that are displayed one at a time.
- [Text](https://www.arene.style/docs/components/text.md): Text with paired font sizes and line heights.
- [Textarea](https://www.arene.style/docs/components/textarea.md): Displays a form textarea for several lines of text.
- [Toast](https://www.arene.style/docs/components/toast.md): A short message that appears for a few seconds and then goes away.
- [Toggle](https://www.arene.style/docs/components/toggle.md): A button that stays pressed until it is clicked again.
- [Toggle Group](https://www.arene.style/docs/components/toggle-group.md): A row of toggles where one item, or several, can be pressed.
- [Toolbar](https://www.arene.style/docs/components/toolbar.md): Groups related controls into a single keyboard navigation region.
- [Tooltip](https://www.arene.style/docs/components/tooltip.md): A short label that appears beside an element on hover or keyboard focus.
- [Trace](https://www.arene.style/docs/components/trace.md): Displays the steps an agent takes, such as reasoning, tool calls and sources, as a list of lines.

## Utilities

- [Shimmer](https://www.arene.style/docs/utilities/shimmer.md): A style map that sweeps a highlight across text while it streams.

## Optional

- [All pages](https://www.arene.style/llms-full.txt): Every page above in one file, in this order
- [Source](https://github.com/arc1hq/arene): The repository, MIT-licensed
