raft-ui#

The package is raft-ui. Plain HTML can use foundation.css directly; the component guidance below applies to React. The React components are built on Base UI (@base-ui/react), Tailwind CSS v4, and tailwind-variants. Chat/workspace product domain: rails, sidebars, conversation panels, composers, task boards, activity inboxes, and search.

The rule files are also published at https://rui.botiverse.build/guides/overview. Do not register or install skills in a consumer project unless requested.

Working sequence#

1. Read only the rule files the current surface needs (table below); do not load every rule file by default.
2. Verify unrecognized props, parts, variants, and tokens with rules/lookup.md.
3. Implement the smallest composition that preserves native semantics and uses raft-ui where its behavior or visual contract is needed.
4. 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:

Never guess a prop or variant name. The tables below are orientation, not an API reference — see rules/lookup.md.

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.
• Raft is the only visual language, in light and dark modes; ThemeProvider switches the mode globally. Components adapt themselves.
• Yellow and pink split roles: primary (Source Yellow) is for hints and interactive expression (indicators, the active tab); accent is for core actions (a dialog's confirm, the composer's send). Never use yellow as decoration or background wash — see rules/styling.md. Focus rings are ink, not yellow: a 2px paper gap and a 2px ink ring (shadow-raft-focus).

Common mistakes#

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#

Read these when relevant#

Review checklist#

When reviewing or editing code that uses raft-ui, check:

• 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 tokens, raw oklch() only for one-offs
• 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
• No shadow written as shadow-[var(--…)] — named utility or fully literal

Stability#

raft-ui is the stable surface; raft-ui/wip is experimental. Import cn from raft-ui/cn.