Components

46 components, each shown where it lives in a product.

No changes

Empty state

Labels and identity

Conversation

Ship it?

Merged and deployed.

Message

Ask Hazel about Fix smoke e2e

Mention pill

Containers

Appearance

Theme

Settings group

1 queued

Also: lerp should not clamp t.

Data

Daily bars

Pagination

Sign in

Auth surface

482913

Codes and secrets

Install

The kit isn't published to npm yet. Inside the Arcadia workspace, depend on it directly; React 19 is a peer dependency.

package.json

{
  "dependencies": {
    "@arcadia/ui": "workspace:*",
    "react": "^19",
    "react-dom": "^19"
  }
}

Set up the root

Boot the theme before the first paint, load the kit's CSS before your own, and mount the three hosts once.

server.ts

import { themeBootScript } from "@arcadia/ui";

// Inline in <head>, before any stylesheet, so a light theme never flashes dark.
const boot = themeBootScript({ themeKey: "myapp.theme", motionKey: "myapp.reduceMotion" });
const head = `<script>${boot}</script><link rel="stylesheet" href="/app.css" />`;

app.tsx

import "@arcadia/ui/styles.css"; // the kit first
import "./app.css";              // then yours, inside @layer features
import {
  Button, ConfirmHost, Toaster, TooltipProvider, useMotionPreference, useTheme,
} from "@arcadia/ui";

export function App() {
  // The same keys as the boot script: the choice persists, the OS is followed on "system".
  useTheme(undefined, { storageKey: "myapp.theme" });
  useMotionPreference(undefined, { storageKey: "myapp.reduceMotion" });
  return (
    <TooltipProvider>
      <Button variant="primary" icon="arrow-up">Send</Button>
      <Toaster />
      <ConfirmHost />
    </TooltipProvider>
  );
}

Things that silently break

No ConfirmHost: confirm() rejects with an error instead of asking, so the action behind it never runs.
No Toaster: toast() returns an id and nothing appears. There is no warning.
No boot script: The theme is applied after the first paint, so anyone on a light theme sees a dark flash on every load.
CSS outside a layer: Unlayered rules beat every layer, the kit's overrides included, so they quietly undo the reduced-motion contract and the legibility cut. Put product CSS in @layer features.

Layers: Every CSS file wraps its rules in exactly one layer, in the order reset, tokens, brand, base, ds, features, overrides. Kit components live in ds and product code in features, which wins at any specificity, so there is no !important and no specificity game.
Tokens: Three tiers, every value written once in tokens.ts. Per theme: one --ink, the rank alphas, five opaque surfaces, hues, shadows and the only literal colours. Derived ladders and scales come next (--text-1 to --text-4, --fill-*, --space-*), then component tokens on component roots (--button-bg).
Naming: Files are kebab-case, TSX and CSS in pairs. Components are PascalCase with flat compound exports (Menu, MenuItem). Kit classes are ui-component-part, the public slot hook, and booleans are present-or-absent attributes (data-open).
Product code: Imports only from @arcadia/ui, lays primitives out and sets their documented component tokens. Semantic and scale tokens only. When a need recurs, add a variant to the kit; one anatomy per concept, so every row is a ListRow and every disclosure a Collapsible.
Focus: One treatment: keyboard focus draws a 2px ring of neutral ink, never the accent. Components choose only its offset, and text fields show focus through their border instead.
Hierarchy: Hierarchy comes from rank and medium weight. Placeholders and key hints use --text-3; --text-4 is only for disabled labels and decoration.

Variant vocabulary

The same words mean the same thing on every component, and a variant only reassigns component tokens.

Prop	Values	Default
`variant`	`primarysecondaryoutlineghosttextdangerinverse`	`ghost`
`size`	`xssmmdlg`	`md` (IconButton `sm`)
`shape`	`roundedpill`	`rounded`
`tone`	`neutralmutedaccentsuccesswarningdangerplanaskdebug`	`neutral`
`render`	An element or a function: swap the element, keep the behaviour.	The part's own

Two documented exceptions: a Shimmer's tone is a text rank (secondary or tertiary), and a toast's tone is an outcome (info, success, warning or error).

Components

Actions

Fields

Overlays

Status