# Cube UI Kit
[](https://www.npmjs.com/package/@cube-dev/ui-kit) [](https://github.com/cube-js/cube-ui-kit/blob/main/LICENSE)
An open-source React component library that powers [Cube Cloud](https://cubecloud.dev) and other [Cube Dev](https://cube.dev) products. While built for Cube's own interfaces, it is a general-purpose kit you can use freely in any application where it fits your needs.
**[Live Storybook](https://cube-ui-kit.vercel.app/)** ยท **[Tasty Docs](https://github.com/tenphi/tasty)**
## Highlights
- **100+ production-ready components** โ primitives (Button, Input), layout (Grid, Flex, Space), fields (Select, ComboBox, DatePicker), overlays (Dialog, Toast), and complex organisms (CommandMenu, FilterPicker, FileTabs).
- **Accessible by default** โ built on [React Aria](https://react-spectrum.adobe.com/react-aria/) with keyboard navigation, focus management, and screen reader support out of the box.
- **Tasty styling engine** โ declarative, token-aware styles with state-driven values, design tokens, responsive breakpoints, and zero specificity conflicts. See the [Tasty documentation](https://github.com/tenphi/tasty).
- **Integrated form system** โ async rule-based validation with field-level and form-level state management; fields plug in directly without extra wrapper components.
- **Runtime-tunable palette** โ the whole color system is generated by [Glaze](https://github.com/tenphi/glaze) from a brand hue, a saturation and one hue per status theme. Re-seed any of them at runtime and every token re-resolves for light, dark and high-contrast at once.
- **TypeScript-first** โ complete type definitions with autocomplete for tokens and style props.
- **Tree-shakeable** โ unbundled ESM output; import only what you use.
## Installation
```bash
pnpm add @cube-dev/ui-kit
```
Peer dependencies:
```bash
pnpm add react react-dom
```
React and React DOM 19.3 or newer are required (React 19). Upgrade both together before adopting this release. UI Kit ships compiled output using the native React compiler runtime; applications do not need to enable React Compiler.
## Quick Start
Wrap your application with `Root` to initialize the design system:
```tsx
import { Root, Button, TextInput, Space } from '@cube-dev/ui-kit';
function App() {
return (
<Root>
<Space flow="column" gap="2x" padding="4x">
<TextInput label="Name" placeholder="Enter your name" />
<Button type="primary" onPress={() => console.log('clicked')}>
Submit
</Button>
</Space>
</Root>
);
}
```
To ship your own brand color, tune the palette seeds โ every token, in every scheme, re-resolves from them:
```tsx
<Root palette={{ hue: 210, saturation: 72, themes: { danger: { hue: 12 } } }}>
<App />
</Root>
```
`setPaletteConfig()` does the same thing imperatively, from anywhere. It replaces rather than accumulates, like `useState` โ pass an updater to change one field:
```ts
setPaletteConfig((config) => ({ ...config, hue: 235 }));
```
## Components
| Category | Components |
| --- | --- |
| **Layout** | Flex, Grid, Space, Flow, Panel, ResizablePanel, Prefix, Suffix |
| **Actions** | Button, Button.Group, Button.Split, Link, Menu, CommandMenu |
| **Content** | Text, Title, Paragraph, Card, Badge, Tag, Avatar, Alert, Skeleton, Placeholder, Disclosure, Divider, CopySnippet, PrismCode |
| **Fields** | TextInput, NumberInput, PasswordInput, SearchInput, TextArea, Select, ComboBox, Checkbox, RadioGroup, Switch, Slider, DatePicker, FileInput, ListBox, FilterListBox, FilterPicker, Picker, TagInput |
| **Form** | Form, FieldWrapper, SubmitButton, ResetButton |
| **Overlays** | Dialog, AlertDialog, Modal, Tooltip, Toast, Notifications |
| **Navigation** | Tabs, FileTabs |
| **Status** | Spin, LoadingAnimation |
Browse all components with live examples in the [Storybook](https://cube-ui-kit.vercel.app/).
## Styling with Tasty
Cube UI Kit uses [Tasty](https://github.com/tenphi/tasty) โ a styling engine that generates conflict-free CSS using mutually exclusive selectors.
Create custom styled components:
```tsx
import { tasty } from '@cube-dev/ui-kit';
const Card = tasty({
styles: {
display: 'flex',
flow: 'column',
padding: '4x',
gap: '2x',
fill: '#surface',
border: '#border',
radius: '1r',
Title: { preset: 'h3', color: '#primary' },
Content: { preset: 't2', color: '#text' },
},
elements: { Title: 'h2', Content: 'div' },
});
```
Style properties support state-driven values:
```tsx
const StatusBadge = tasty({
styles: {
padding: '1x 2x',
radius: 'round',
fill: {
'': '#surface',
'type=success': '#success-bg',
'type=error': '#danger-bg',
},
},
});
```
## Development
### Prerequisites
- Node.js 24 (see `.nvmrc`)
- pnpm >= 10
### Scripts
```bash
pnpm storybook # Start Storybook dev server on port 6060
pnpm build # Build the library (tsdown, unbundled ESM)
pnpm test # Run all tests (Vitest)
pnpm test -- Button # Run tests matching "Button"
pnpm fix # Lint and format (Oxlint + Prettier)
pnpm size # Measure the bundle and check its dependencies
pnpm chromatic # Run visual regression tests
```
### Agent reviews
Local agent reviews follow the [UI Kit review rules](docs/rules/review.md), including [Entropy review](docs/rules/entropy.md#entropy-review). Use `$ui-review` in Codex or `/ui-review` in Claude for a full review, and `$entropy-review` or `/entropy-review` respectively for a focused complexity assessment.
### Project Structure
```
src/
โโโ components/
โ โโโ actions/ # Button, Link, Menu, CommandMenu, ...
โ โโโ content/ # Card, Badge, Tag, Alert, Skeleton, ...
โ โโโ fields/ # TextInput, Select, ComboBox, ...
โ โโโ form/ # Form, FieldWrapper, SubmitButton, ...
โ โโโ layout/ # Flex, Grid, Space, Flow, Panel, ...
โ โโโ navigation/ # Tabs
โ โโโ organisms/ # FileTabs, StatsCard
โ โโโ overlays/ # Dialog, Tooltip, Toast, ...
โ โโโ status/ # Spin, LoadingAnimation
โโโ icons/ # 130+ icon components (Tabler-based + custom)
โโโ stories/ # Storybook guides and documentation
โโโ tasty/ # Tasty integration utilities
โโโ tokens/ # Design tokens
โโโ index.ts # Public API barrel export
docs/
โโโ tasty/ # Tasty styling engine documentation
```
Each component follows a standard file layout:
```
ComponentName/
โโโ ComponentName.tsx # Implementation
โโโ ComponentName.stories.tsx # Storybook stories
โโโ ComponentName.docs.mdx # Documentation
โโโ ComponentName.test.tsx # Tests
โโโ index.tsx # Re-exports
```
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for commit conventions, branch naming, PR workflow, and changeset instructions.
## License
[MIT](./LICENSE) โ Cube Dev, Inc.