@arki/ui

React component library for ARKI apps: Base UI primitives styled with Tailwind v4 semantic tokens. Forms, overlays, navigation, data display and charts. One import per component.

Install

bun add @arki/ui @arki/design-systems @arki/theme react react-dom

react and react-dom 19 are peer dependencies. @arki/design-systems supplies the tokens the components read, and @arki/theme sets light and dark mode.

Quick start

Pick one design system and let Tailwind scan the component sources.

/* src/styles/global.css */
@import 'tailwindcss';
@import '@arki/design-systems/atelier/fonts.css';
@import '@arki/design-systems/atelier/tokens.css';
@import '@arki/design-systems/atelier/theme-bridge.css';
 
/* Adjust the path to where @arki/ui is installed. */
@source '../node_modules/@arki/ui/src';

Then import each component from its own subpath.

import { Button } from '@arki/ui/button';
import { Card, CardContent, CardHeader, CardTitle } from '@arki/ui/card';
import { cn } from '@arki/ui/cn';
 
export function Example() {
  return (
    <Card className={cn('max-w-md')}>
      <CardHeader>
        <CardTitle>Tidal Mug</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Add to cart</Button>
      </CardContent>
    </Card>
  );
}

When not to use this

• Your app does not use Tailwind v4. The components are styled with Tailwind classes and have no stylesheet of their own.
• You need a headless library to style yourself. Use @base-ui/react directly. This package is the styled layer on top of it.
• You mix design systems in one app. These components read one set of tokens (see @arki/design-systems).
• You build for React Native. Use @arki/native-ui.

Runtime support

Source-distributed: ships TypeScript/TSX, needs a bundler (Vite with the TanStack Start stack).

Public imports

There is no root import. Every component is its own subpath: @arki/ui/button, @arki/ui/dialog, @arki/ui/select, @arki/ui/table, @arki/ui/chart. llms.txt lists all of them with their names.

Failure behaviour

Components do not return failure values. Mistakes in how you compose them show up in three ways.

• Some compound parts need their parent. These hooks throw a plain Error when the parent is missing: useFormField (inside FormField), useSidebar (inside SidebarProvider), and the hooks for Chart, Carousel, ControlGroup and Timeline. Fix the tree; do not catch the error.
• A missing token gives a wrong colour, not an error. If a page looks unstyled, check the @source line and the token imports first.
• Toaster reads the theme from @arki/theme. Without a ThemeProvider it uses system.

Limits

• Tailwind only sees classes it can scan. If @source does not point at the installed @arki/ui/src, components render with no styling and no error.
• Pick one design system per app. Boundary: loading atelier tokens and workbench tokens in one stylesheet makes the later file win for every shared name, so components mix two palettes.
• katex does not load KaTeX's stylesheet. Import katex/dist/katex.min.css yourself, or maths renders unstyled.
• Imports must name a subpath. import { Button } from '@arki/ui' fails: the package has no root entry.
• Some components rely on browser APIs (matchMedia, ResizeObserver). Render them on the client; in tests use a DOM environment.

Design-system rules

1. Style with semantic classes: bg-background, bg-card, text-muted-foreground, border-border.
2. One design system per app: atelier, workbench or arena. Never mix them.
3. App-specific colours get new token names. Do not redefine a shared name.
4. If a component needs a token the contract does not have, propose the smallest extension and get confirmation before you change @arki/design-systems.

Benchmarks

Bundle size of the same components from @arki/ui and from popular React component libraries. Mantine, MUI and Radix Themes are the common full-featured choices.

Measured on Node 22.13.1 (Darwin 27.0.0 arm64, Apple M2 Max (12 cores)) · @arki/bench 0.0.1 (mitata 1.0.34) · publish, seed 1592639052 · commit 34146416b3 (uncommitted changes) · 2026-10-13.

Versions: @arki/bench 0.0.1 · @arki/ui 0.1.4 · @mantine/core 7.17.4 · @mui/material 9.5.0 · @radix-ui/themes 3.3.0 · mitata 1.0.34.

Button, JavaScript only

Rows marked different contract do other work: they are measured and shown, never ranked.

Dialog, JavaScript only

Rows marked different contract do other work: they are measured and shown, never ranked.

Form set (Button, Input, Select, Checkbox), JavaScript only

Rows marked different contract do other work: they are measured and shown, never ranked.

Button, complete styled

Dialog, complete styled

Form set (Button, Input, Select, Checkbox), complete styled

Notes

• Styling is not equal, so there are two kinds of group. JavaScript only counts the components without styles; a rival that needs a stylesheet or styles itself at runtime is measured but never ranked (differs). complete styled adds the CSS a user must also ship, and ranks everything.
• @arki/ui is Base UI primitives styled with Tailwind classes. Its CSS comes from your app Tailwind build. In the complete styled groups it is a Tailwind v4 build of the classes found in the measured component files (found by Tailwind’s own scanner), with preflight and the workbench tokens and theme bridge. Fonts are left out. A real app adds the classes of its own code on top.
• Mantine and Radix Themes ship one stylesheet for the whole library (styles.css), not a per-component one, so their complete rows include the CSS of every component. MUI styles components at runtime with Emotion, so its JavaScript includes the styling engine and it has no stylesheet.
• Mantine Modal and MUI/Radix Dialog are the nearest equivalents of the @arki/ui Dialog parts.

Reproduce: bunx arki-bench run --profile publish in the package directory.

Related packages

• @arki/design-systems: tokens, Tailwind bridge and fonts for atelier, workbench, arena.
• @arki/theme: light, dark and system provider and the no-flash script.
• @arki/icons: icon sets behind one React entry point.
• @arki/react-hooks: the hooks the components use, reusable on their own.

Documentation

• docs/agent-guide.md: the model, a task map, the rules that bite, and how to verify.
• llms.txt: the short form for agents.

Support

Report bugs and questions at https://github.com/arki-labs/arki/issues.

License

MIT. See LICENSE.