# Kobra

A React component library for shadcn, installed through the shadcn CLI. 100+ components counting the variants inside them, indexed below under 84 names. 10 of those install free.

This page is written for coding agents and lives at https://kobra.systems/install.md, also served at https://kobra.systems/design.md and https://kobra.systems/llms.txt. Everything below is the whole interface — setup, the rules, the house style and every component: there is no separate documentation site to fetch.

## Setup

The 10 free components install with no account. The rest need a registry token, minted at https://kobra.systems/dashboard and read from `KOBRA_TOKEN` in the environment.

Add to `components.json`:

```json
"registries": {
  "@kobra": {
    "url": "https://kobra.systems/r/{name}.json",
    "headers": {
      "Authorization": "Bearer ${KOBRA_TOKEN}"
    }
  }
}
```

Then install by name:

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

## Rules

1. Read the index below before writing any UI. If a component here does the job, install it. Do not hand-roll a dropdown, a dialog, a toast or a combobox that already exists.
2. Restyle through variants and props, never `className`. If no variant fits, add one inside the component's own file rather than overriding it from the outside.
3. Use theme tokens — `bg-muted`, `text-foreground`, `border` — never raw palette colors like `bg-zinc-800`. Colors, radius and type are CSS variables, so retheming is editing those variables.
4. Use the spacing and type scale. Reach for an arbitrary value only when the scale has no step for it.
5. No inline styles. Style through classes, and pass dynamic values as CSS custom properties.
6. Write class names out in full. Anything assembled at runtime is a class Tailwind never generates.

## Style

The look is quiet by default. Follow these and new work sits beside the components rather than on top of them.

1. **Color is information.** The palette is gray — every neutral token is pure achromatic. Color arrives through content, and through the four status hues (`--error`, `--warning`, `--success`, `--info`), which share one lightness so no state shouts louder than another. A colored surface should mean something.
2. **Two weights, not five.** 400 for everything, 700 for emphasis. `font-medium` and `font-semibold` resolve to those two on purpose. Size and color carry hierarchy; weight is the last resort.
3. **Interface text is small and dense.** 14px is the body size, 13px for secondary labels, and headings rarely pass 20px. Line length caps around 60 characters.
4. **One radius family.** `--radius` is 0.625rem, with `sm`/`md`/`lg`/`xl` stepping 4px either side. Nest concentrically: a child's radius is its parent's less the padding between them.
5. **One hairline, then depth.** A surface gets a single border or a ring at about 10% opacity, and separation past that comes from a shadow, not a second heavier line.
6. **Motion is short and asymmetric.** Entrances 150–250ms on `--ease-out` (`cubic-bezier(0.23, 1, 0.32, 1)`); exits shorter, on `--ease-exit` (`cubic-bezier(0.4, 0, 0.6, 1)`), because an arrival is worth watching and a departure is only worth not snapping. Animate transform, opacity and filter. Everything answers `motion-reduce`.
7. **Press gives, it does not jump.** The surface under a pressed control scales to about 0.99 while the label stays where it is.
8. **Focus is one ring.** `focus-visible:ring-3 ring-ring/50`, never an outline removed and not replaced. `--ring` clears 3:1 against the page on its own.
9. **A busy button keeps its word.** The label turns out and a spinner turns in; never swap it for "Saving…", and never disable it, which dims the spinner that is the state.
10. **Numbers that change get `tabular-nums`,** so a counter does not shuffle the layout under itself.
11. **Empty and loading states are designed,** not left blank: a skeleton the size of what is coming, and an empty state that says what to do next.

## Right to left

Every component supports Arabic and the other right-to-left scripts, with nothing to set per component. Set the direction once, at the root:

```tsx
import { DirectionProvider } from '@base-ui/react/direction-provider'

<html lang="ar" dir="rtl">
  <body>
    <DirectionProvider direction="rtl">{children}</DirectionProvider>
  </body>
</html>
```

`dir` mirrors the layout and the text; the provider tells the components which way arrow keys, swipes and sliders run. The same provider installs as `@kobra/direction`. Code, one-time codes, color values and media timelines stay left to right on their own. For a designed Arabic face, put one (IBM Plex Sans Arabic, Noto Sans Arabic) ahead of the system fallback in `--font-sans`.

In your own markup, write logical classes — `ms-*`, `pe-*`, `start-*`, `text-start`, `border-s`, `rounded-e` — instead of left and right ones, add `rtl:-scale-x-100` to arrows and chevrons, and leave Arabic text without letter-spacing: Safari pulls the letters apart.

## Components

Every one is at `https://kobra.systems/components/<name>`, and `https://kobra.systems/r/<name>.md` is this same detail for one component: what it exports, what it installs alongside, and the packages it needs.

### Free (no account needed)

- `@kobra/input-otp` — A segmented one-time-code input, built on input-otp.
- `@kobra/navigation-menu` — A collection of navigation links.
- `@kobra/video` — A video player built on Loomix, with liquid glass or blurred controls.
- `@kobra/carousel` — A horizontally navigable content collection, built on Embla.
- `@kobra/ai-editor` — A document an agent edits alongside you.
- `@kobra/command-menu` — A fast, nested command menu powered by kmenu.
- `@kobra/toast` — Stacked status notifications with progress, actions and descriptions.
- `@kobra/conversation` — Messages from both sides of a chat.
- `@kobra/halftone-dots` — An image rebuilt as a field of dots that morph between pictures.
- `@kobra/sound` — The cue every control answers a press with, built on Web Kits Audio.

### Agents

- `@kobra/reasoning-steps` — A model working before it answers.
- `@kobra/chat-history` — A chat whose button gathers everything you asked into one column over the blurred transcript.
- `@kobra/trace-waterfall` — A live trace of an agent run, its spans unfolding on one timeline.
- `@kobra/file-diff` — Changes an agent proposes to a file.
- `@kobra/image-generation` — A canvas forming while an image is generated.
- `@kobra/document-agent` — An agent’s draft beside its chat, each claim chipped with its source.
- `@kobra/streaming-text` — A reply arriving a token at a time.
- `@kobra/inline-citations` — Sources cited inside a reply.
- `@kobra/code-block` — Syntax-highlighted code with actions.
- `@kobra/task-list` — A task list an agent works through.
- `@kobra/chat-input` — A composer for prompting an agent, built on Voice Glow and ElevenLabs UI.
- `@kobra/plan-card` — A plan an agent is asking to run.
- `@kobra/question-card` — A question an agent needs answered before it continues.
- `@kobra/message` — A structured conversation message.
- `@kobra/message-scroller` — Conversation scrolling with edge controls.

### Content

- `@kobra/table` — Rows and columns of structured data.
- `@kobra/crm-table` — Accounts with owners, pipeline and win odds, in resizable columns.
- `@kobra/grouped-table` — Issues grouped by status, in a table whose columns glide into each row as you narrow it.
- `@kobra/chart` — Composable data visualizations, from Evil Charts.
- `@kobra/item` — A flexible row for lists and settings.
- `@kobra/avatar` — An image or fallback representing a person.
- `@kobra/badge` — A compact status or category label.
- `@kobra/marker` — A labeled point or status marker.
- `@kobra/kbd` — Keyboard input and shortcut hints.
- `@kobra/attachment` — A compact file attachment presentation.
- `@kobra/lightbox` — Photos in justified rows that open with a ripple zoom.
- `@kobra/qr-code` — A scannable code in dots that ripples each time what it encodes changes.
- `@kobra/advertisement` — A sponsor slot that turns through its ads on a line that fills.

### Feedback

- `@kobra/alert` — A callout for important contextual information.
- `@kobra/progress` — The completion state of a task.
- `@kobra/spinner` — An indeterminate loading indicator.
- `@kobra/skeleton` — A placeholder shown while content loads.
- `@kobra/empty` — An empty-state layout with guidance.

### Form controls

- `@kobra/form` — Validated form composition.
- `@kobra/input` — A text input with its label, description and attached controls.
- `@kobra/input-dissolve` — A field that carries its value away once it is spent.
- `@kobra/textarea` — A multiline text input.
- `@kobra/button` — A control that triggers an action.
- `@kobra/toggle-group` — A two-state control, alone or conjoined into a bar.
- `@kobra/filter-chips` — Filter chips that join into one track as neighbors are chosen, after Spotify’s library.
- `@kobra/checkbox` — A binary or indeterminate selection control.
- `@kobra/radio-group` — A single choice from several options.
- `@kobra/switch` — A control for toggling a setting.
- `@kobra/slider` — A value selected along a range, with a liquid handle from Gooey.
- `@kobra/select` — An option picker, as a styled menu or the native control.
- `@kobra/combobox` — A searchable option picker.
- `@kobra/multi-select` — Several values picked from one list, as chips.
- `@kobra/calendar` — A date selection calendar.
- `@kobra/color-palette` — A wheel of nineteen swatches, hue around and saturation inward.
- `@kobra/color-picker` — A gradient and solid picker, with draggable stops and a hex field.
- `@kobra/icon-picker` — An icon and its color, picked together.
- `@kobra/magnetic-dropzone` — A drop target that leans toward the file you are carrying.

### Layout

- `@kobra/card` — A surface grouping related content.
- `@kobra/accordion` — Vertically stacked disclosure sections.
- `@kobra/collapsible` — An expandable content region.
- `@kobra/aspect-ratio` — Keeps content within a fixed ratio.
- `@kobra/logo-carousel` — A wall of logos, shown a few at a time.
- `@kobra/separator` — A visual divider between content.
- `@kobra/scroll-area` — A custom cross-browser scroll container.
- `@kobra/resizable` — Panels separated by a draggable handle.
- `@kobra/direction` — Turns every component right to left, for Arabic and other RTL scripts.

### Navigation

- `@kobra/tabs` — Layered content selected by tab.
- `@kobra/breadcrumb` — A hierarchical navigation trail.
- `@kobra/pagination` — Controls for moving through pages.
- `@kobra/sidebar` — A composable application sidebar.
- `@kobra/menubar` — A persistent horizontal application menu.

### Overlays

- `@kobra/dialog` — A modal window over the current page, and the alert dialog that confirms.
- `@kobra/sheet` — A dialog that enters from an edge.
- `@kobra/drawer` — A panel that slides from an edge, built on Vaul.
- `@kobra/popover` — Floating content anchored to a trigger.
- `@kobra/hover-card` — Rich content revealed on hover.
- `@kobra/tooltip` — A concise label shown on hover or focus.
- `@kobra/dropdown-menu` — A menu opened from a trigger.
- `@kobra/context-menu` — Actions opened from a secondary click.

## Optional

An MCP server, which answers the same questions live rather than from this page:

```bash
claude mcp add --transport http kobra https://kobra.systems/api/mcp \
  --header "Authorization: Bearer ${KOBRA_TOKEN}"
```

Skills for motion, sound and migrating an existing design system:

```bash
npx skills add https://skills.sh/p/BCo1c0oBAtHom5It
```

Pricing and licensing: https://kobra.systems/pricing