raft-ui

--- name: raft-ui-guide description: "Build UIs with raft-ui, the React component library for Raft using Base UI, Tailwind CSS v4, and tailwind-variants. Use when importing from raft-ui, selecting or composing components, checking variants and props, styling with semantic oklch tokens, or setting up styles.css, fonts.css, and ThemeProvider. Keywords include raft-ui, raft ui, RaftUI, Raft design system, brutal theme, and elegant theme." --- # raft-ui React component library for Raft. Built on **Base UI** (`@base-ui/react`), **Tailwind CSS v4**, and **tailwind-variants**. Chat/workspace product domain: rails, sidebars, conversation panels, composers, task boards. ## Working sequence 1. For a first install or an unstyled render, read [rules/setup.md](./rules/setup.md) and get the first Button rendering before composing a page. 2. Read only the domain rule needed for the current surface; do not load every rule file by default. 3. Verify unrecognized props, parts, variants, and tokens with [rules/lookup.md](./rules/lookup.md). 4. Implement the smallest composition that preserves native semantics and uses raft-ui where its behavior or visual contract is needed. 5. Apply the review checklist after implementation, not as a reason to add wrappers before they are needed. When this skill is loaded through TanStack Intent, run `intent load raft-ui#raft-ui-guide --path` before opening a linked rule file, then resolve the link relative to the returned `SKILL.md` directory. ## Override your priors first raft-ui is not shadcn/ui, not Radix, not MUI. These defaults are wrong here: | Your instinct | Reality in raft-ui | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `<Button variant="destructive">` | `variant="danger"`. Full set: `primary` `default` `information` `muted` `accent` `warning` `outline` `ghost` `link` `danger` `danger-secondary` `danger-outline` | | `<Button size="icon">` | `size="icon-xs\|icon-sm\|icon-md\|icon-lg"`. Text sizes are `xs` `sm` `md` `lg` | | Pass `theme="brutal"` to style a component | **`theme` is not a public prop.** It is stripped from every component's props and resolved from `ThemeProvider` via `useThemeFamily()` | | `className="text-gray-500 bg-slate-50"` | Tailwind's default palette is banned. Use oklch semantic tokens: `text-foreground-muted`, `bg-fill-muted` | | Flat props: `<Dialog title="x" description="y">` | Compound parts: `<Dialog><DialogContent><DialogHeader><DialogTitle>…` — `DialogContent` portals itself | | Radix API (`asChild`, `Portal.Root`) | Base UI API. Use the `render` prop, not `asChild` | | Add a `kind`/`state`/`emphasis` prop for a structural difference | Use the dedicated part or component instead | | `<Button loading>` doesn't exist, roll a spinner | `loading` and `loadingLabel` are real props on `Button` | **Never guess a prop or variant name.** The tables below are orientation, not an exhaustive API reference. Verify exact names against the installed version in `node_modules/raft-ui/dist/index.d.mts` — see [rules/lookup.md](./rules/lookup.md). Guessed props are the most common failure mode with this library, and they fail silently. ## Principles - Composition over configuration. Visible structure lives in `children` and named parts, never in a prop that switches layouts. - Prefer semantic tokens over raw color. Use inline `oklch()` only for a one-off precision value, then tokenize repeated values. - Base UI owns headless behavior (open state, focus, keyboard, collections). Product state (upload lifecycle, permissions, workflow) belongs in your app, not in a component prop. - Two theme families, `brutal` and `elegant`, are switched globally by `ThemeProvider`. Components adapt themselves. - Yellow and pink split roles. `primary` (Source Yellow) carries **hints and interactive expression** — new-message indicators, attention badges, the active tab, focus rings. `accent` carries **core and important actions** — a dialog's confirm, the composer's send. Never use yellow as decoration or background wash, and keep ghost/secondary variants semantically quiet. ## Common mistakes | Mistake | Fix | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `asChild` on a trigger or close part | Base UI: `render={<Button … />}` | | Actions menu built out of `Select` | `DropdownMenu` — see [rules/forms.md](./rules/forms.md) | | Persistent condition announced with `toast.info()` | `Banner` — toasts expire, conditions don't | | Buttons or links inside a `Tooltip` | `Popover` — tooltip content is unreachable | | Destructive confirm as a styled `Dialog` | `AlertDialog` with `AlertDialogAction` / `AlertDialogCancel` | | Variant value copied from another component | Look it up — negative is `danger` / `destructive` / `error` depending on the component | | Validation copy disconnected from its control | `Field` + `FieldError` | | `PanelHeader` where you meant the bare frame | `PanelHeaderRoot` — `PanelHeader` is the composed identity chrome, see [rules/layout.md](./rules/layout.md) | | Spinner hand-placed inside a `Button` | `loading` / `loadingLabel` props | | Re-created raft-ui divider, badge, or type styling | `Separator`, `Badge`, or `Text`; keep native semantics when intentional | ## Which control? Which feedback channel? ``` Choosing an option control: Is it an action, not a value? ──────────── DropdownMenu / ContextMenu └─ No: on/off? ├─ Applies immediately ──────────────── Switch ├─ Submitted with a form ────────────── Checkbox └─ No: one of several? ├─ 2–5, form answer ──────────────── RadioGroup ├─ 2–5, switches a view in place ─── SegmentedControl ├─ Swaps visible content panels ──── Tabs ├─ One of many ──────────────────── Select └─ Searchable or multi-select ────── Combobox (chips for multi) Delivering a message: Caused by the user's last action, safe to miss? ── toast.info() / toast.success() / toast.warning() / toast.error() Condition that is still true? ──────────────────── Banner Happened elsewhere, must persist until read? ───── NotificationCenter Loading? ── known layout → Skeleton · unknown duration → Spinner · known % → Progress ``` Intent names are **not** consistent across components — negative is `danger` on `Button`/`Badge`/`Status`/`Progress`, `destructive` on `Banner`, and `error` on toast objects and `NotificationCenterItemIcon`. Never carry a variant value from one component to another. ## Quick component map | Need | Use | | ------------------------------------------------ | -------------------------------------------------------------------------- | | Callout / inline status message | `Banner` | | Transient notification | `toast.info()` etc. + `ToastProvider` | | Confirm a destructive action | `AlertDialog` | | Generic modal | `Dialog` | | Edge-anchored panel | `Drawer` | | Rich hover preview | `PreviewCard` | | Plain hover hint | `Tooltip` | | Right-click menu | `ContextMenu` | | Button-triggered menu | `DropdownMenu` | | Single choice, few options | `RadioGroup` or `SegmentedControl` | | Single choice, many options | `Select` | | Searchable / multi choice | `Combobox` | | Label, help, or validation around a form control | `Field` + the applicable field parts | | Design-system divider | `Separator`; keep native semantics when styling is intentionally inherited | | Loading placeholder | `Skeleton` | | Inline busy indicator | `Spinner` | | Determinate progress | `Progress` | | Small count / tag | `Badge` | | Presence or state dot | `Status` | | Nothing-here state | `EmptyState` | | Keyboard shortcut | `Kbd` / `KbdGroup` | | raft-ui typography treatment | `Text.Sans` / `Text.Heading` / `Text.Mono` | Each domain file below opens with its own scenario table for the components it covers. ## Read these when relevant | File | Read it when | | ------------------------------------------------ | ---------------------------------------------------------------------------- | | [rules/lookup.md](./rules/lookup.md) | You need a prop, variant value, or token — read this before guessing | | [rules/composition.md](./rules/composition.md) | Assembling compound parts, overlay containers, business actions, or wrappers | | [rules/forms.md](./rules/forms.md) | Any input, option picker, or tabs — includes `Select` vs `DropdownMenu` | | [rules/overlays.md](./rules/overlays.md) | Dialogs, drawers, popovers, menus, tooltips | | [rules/feedback.md](./rules/feedback.md) | Banners, toasts, loading, empty states, badges | | [rules/display.md](./rules/display.md) | Typography, code, avatars, files, keyboard hints | | [rules/layout.md](./rules/layout.md) | Shell, panels, navigation, resizing, task surfaces | | [rules/conversation.md](./rules/conversation.md) | Chat sidebar, conversation panel, thread, composer | | [rules/styling.md](./rules/styling.md) | Writing any `className`, color, shadow, or `tv()` recipe | | [rules/setup.md](./rules/setup.md) | First-time install, Tailwind v4 wiring, fonts, theme provider | ## Review checklist When reviewing or editing code that uses raft-ui, check: - [ ] No `theme` prop passed to any component — family comes from `ThemeProvider` - [ ] No variant value carried across components — verify against the declarations - [ ] Controls with raft-ui label, description, or validation treatment use `Field`; simpler native associations remain explicit and accessible - [ ] No Tailwind default palette (`gray-*`, `slate-*`, …), hex, `rgb()`, or `hsl()` — semantic oklch tokens only - [ ] No `asChild` — element substitution uses `render` - [ ] Do not recreate a raft-ui component's visual or behavioral contract with ad hoc markup; native semantic elements remain valid when no library contract is needed - [ ] Every `Avatar` with an `AvatarImage` also has an `AvatarFallback`; every blocking overlay has a `Title` - [ ] Menu rows are `…Item` parts, not raw `<button>`s — raw buttons drop out of keyboard navigation - [ ] Product state (upload, permissions, read/unread) lives in the app; the component renders parts, not a `state` prop - [ ] Nothing imported from `raft-ui/wip` unless explicitly requested - [ ] No shadow written as `shadow-[var(--…)]` — named utility or fully literal ## Stability `raft-ui` is the stable surface. `raft-ui/wip` is unstable and may break in any release — do not reach for it unless the user explicitly asks. ```tsx import { Button, Dialog, Field } from "raft-ui"; import { cn } from "raft-ui/cn"; ```