@kortix/ui

@kortix/ui is the one React component library for every Kortix surface: apps/web, Kortix Apps, the white-label demo and SDK customer apps. Components are Tailwind v4 class strings that read CSS variables. Docs: https://kortix.com/docs/sdk/ui. Live catalog: https://kortix.com/design-system.

Availability: a workspace package of kortix-ai/suna ("@kortix/ui": "workspace:*"), not on npm yet. Outside it: tell the user, style with plain CSS over the section 6 variables, never copy component source.

1. Set up once

1. Styles. A Tailwind v4 host, in its main CSS:

   @import 'tailwindcss';
   @import '@kortix/ui/tailwind.css'; /* tokens, component layer, plugins; @source scans the package */
   

   Install its optional peers tw-animate-css, tailwind-scrollbar, tailwind-scrollbar-hide. A host without Tailwind (plain Vite, a CDN page) imports one file: import '@kortix/ui/styles.css'. It is prebuilt and has every class the package uses. It has no class you write yourself.
2. Fonts. @kortix/ui/fonts.css (Roobert) is for Kortix-owned surfaces only. A white-label host never imports it and renders the system stack.
3. Dark mode is the dark class on <html> (useIsDark() reads it). Mount once at the root: UiProvider (strings for translated copy, chat included; link for your router's link; useBrand for an organization's logo), IconProvider (@kortix/ui/icon-provider, the house icon weight; not the icon-set provider of lib/icon-context) and one <Toaster /> from @kortix/ui/toast for the toast helpers.
4. Import by subpath: import { Modal } from '@kortix/ui/modal'. The root @kortix/ui holds only the light core in section 7. Heavy parts (charts, maps, grids, mermaid, emoji data) load only from their own subpath.

2. Compose before you create

Reuse, then compose, then create. Find the job below before you write a new component.

Job	Compose	Subpath
Dialog or sheet	Modal, ModalContent, ModalHeader, ModalTitle, ModalBody, ModalFooter	modal
Destructive action	ConfirmDialog before the mutation, never a single click	confirm-dialog
Tooltip on an icon button	Hint label="…"	hint
Toast after a mutation	successToast, errorToast, infoToast, warningToast, loadingToast	toast
Status chip	Badge size="sm"	badge
Count beside a label	CountBadge (waiting, reminder, conflict, neutral)	count-badge
Inline alert	InfoBanner tone="…" title="…"	info-banner
Pending spinner	Loading (default export)	loading
Expand and collapse	Disclosure, DisclosureTrigger, DisclosureContent	disclosure
Form field	Field, FieldLabel, FieldGroup, FieldDescription with Input, Textarea, Select	field
Search field	InputGroupSearch, InputGroupSearchInput	input-group
Panel	Card and its slots, or bg-popover rounded-md border px-4 py-5	card
Buttons side by side	ButtonGroup	button-group
Tabs and filters	Tabs, TabsList, TabsListCompact	tabs
Menu, picker, palette	DropdownMenu, Popover, Command	dropdown-menu, popover, command
Table and empty list	Table; Empty with one muted line	table, empty

A new primitive is the last step: tokens only, a small API, and a section on /design-system.

3. Banned

Never	Use
Dialog / DialogContent in feature code	Modal
Tooltip primitives in feature code	Hint
toast() from sonner, toast.success()	the toast helpers and <Toaster />, all from @kortix/ui/toast; a host needs no sonner import
An icon with animate-spin, CircleNotchIcon, SpinnerIcon	Loading
A hand-rolled chip <span> or a colored banner	Badge, InfoBanner
SectionCard, List / ListRow	Card, <ul className="space-y-2"> rows
lucide-react or another icon set	@phosphor-icons/react, *Icon names, no weight prop (only weight="fill" for solid status glyphs)
A fork or a restyled copy of a component	the component as it ships; theme with tokens (section 6)

4. Tokens only

• Colors are semantic utilities: bg-background, bg-card, bg-popover, bg-muted, text-foreground, text-muted-foreground, border-border, bg-primary, text-destructive. Never a hex, rgb(), oklch() or a Tailwind palette class (text-emerald-600).
• --spacing is 0.23rem: the scale is 8% tighter than stock Tailwind. A 16px mockup gap is gap-4, never gap-[16px].
• Radius: rounded-md for panels and fields. Elevation is for overlays only; in-flow panels are flat.
• Motion: none by default. Hover is transition-colors duration-fast. Nothing over 300 ms in product UI.

5. Status tones

One meaning per hue. StatusTone (@kortix/ui/status) is success, warning, destructive, info, neutral. InfoBanner takes tone; StatusBadge and STATUS_DOT render it. Badge variants map the same meanings: success, warning, destructive, info, muted. Brand hues for a tinted icon tile: bg-kortix-green/15, bg-kortix-orange/15, bg-kortix-blue/15, with the icon in the full hue.

6. White-label

Override the CSS variables of tokens.css in your own :root and .dark. --kortix-blue is the accent (checked Switch / Checkbox / RadioGroup, brand Button, info Badge / InfoBanner); --ring the focus ring (--sidebar-ring and the --sidebar-primary selection follow it); --foreground / --background the page and the default Button; --primary (ink, not the accent) Progress, Slider, menu tint; plus --radius, --font-sans-system. Pass the organization's marks to UiProvider useBrand, so KortixLogo renders them. Never fork a component, never load fonts.css, never edit a generated file.

7. Components

Import from	Names
@kortix/ui (adapters)	cn, UiProvider, defaultUiStrings, defaultChatStrings, useUiStrings, useUiLink, useUiBrand, UiStrings, UiStringsInput, ChatStrings, UiLinkProps, UiLinkComponent, UiBrand, UseUiBrand, useIsDark
@kortix/ui (actions, display)	Button, buttonVariants, ButtonProps, Badge, badgeVariants, Card, CardAction, CardButton, CardContent, CardDescription, CardEyebrow, CardFeature, CardFooter, CardGroup, CardHeader, CardImage, CardMedia, CardTitle, CardButtonProps, CardButtonSize, CardButtonVariant, CardGroupProps, CardLogo, CardProps, Separator, Skeleton
@kortix/ui (forms)	Input, inputFocusClasses, inputInvalidClasses, inputSurfaceClasses, inputTransitionClasses, InputProps, useAutosizeTextArea, Textarea, AutosizeTextAreaRef, AutosizeTextAreaProps, Label, Checkbox, CheckboxProps, CheckboxVariant, Switch, SwitchProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, SelectTriggerProps
@kortix/ui (overlays)	Modal, ModalBody, ModalClose, ModalContent, ModalContentInner, ModalDescription, ModalFooter, ModalHeader, ModalOverlay, ModalPortal, ModalTitle, ModalTrigger, Hint, HintProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger
@kortix/ui (primitives, not for feature code: section 3)	Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger
@kortix/ui (navigation)	FilterBar, FilterBarItem, Tabs, TabsContent, TabsList, TabsListCompact, TabsTrigger, TabsTriggerCompact, tabsTriggerHeightVariants, tabsTriggerPaddingVariants, tabsTriggerTextVariants, TabsListType, TabsSize, TabsTriggerSize, TabsTriggerVariant, TabsUnderlineSize
@kortix/ui (conversation)	Bubble, BubbleContent, BubbleGroup, BubbleReactions, bubbleVariants, Message, MessageAvatar, MessageContent, MessageFooter, MessageGroup, MessageHeader, Marker, MarkerContent, MarkerIcon, markerVariants
@kortix/ui/chat (whole thread)	SessionThread, SessionThreadProps, SessionPickers, MessageList, DefaultEmptyState
@kortix/ui/chat (one message)	MessageView, MessageRenderers, RenderTool, ToolCall, Markdown, userMessageParts
@kortix/ui/chat (input)	Composer, ComposerCommand, parseCommand, slashQuery, ModelPicker, filterModels, AgentPicker
@kortix/ui/chat (prompts, errors)	PermissionPrompt, PermissionDecision, QuestionPrompt, ChatErrorHandler, sendFailureTitle
@kortix/ui/chat (streaming)	streamingMarkdown, holdBackFenceOpener, closeUnterminatedCodeFence, holdBackTableHeader

Every other component is one subpath per file: @kortix/ui/<file name> (@kortix/ui/dot-matrix/<name> for the dot matrices), plus @kortix/ui/lib/<name>, @kortix/ui/hooks/<name> and @kortix/ui/icons/<name>.

8. Chat recipe

import { useSession } from '@kortix/sdk/react';
import { SessionThread } from '@kortix/ui/chat';
import { errorToast } from '@kortix/ui/toast';

export function Chat({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const session = useSession(projectId, sessionId);
  return <div className="h-dvh"><SessionThread session={session} onError={(m) => errorToast(m)} /></div>;
}

• Needs @tanstack/react-query and one QueryClientProvider. The parent sets the height. Slots: composerToolbar, composerFooter, emptyState; renderTool (undefined keeps the default), renderers.
• A layout of your own composes MessageList, MessageView, Composer and the prompts from the same useSession result. Never write a second transport or a raw fetch.
• A fully custom transcript uses renderParts from @kortix/sdk/react (docs: /docs/sdk/react).

9. Verify

1. Types: tsc --noEmit in the host adds no error.
2. Run the page in a browser in light and dark, at 720 × 480 and at a phone width. Click every control.
3. Search your diff: no hex or rgb(, no -[ spacing bracket, no lucide-react, no toast(, no animate-spin. Kortix-internal: .agents/skills/kortix-brand/scripts/audit.sh <paths> is clean.
4. White-label: change --kortix-blue and --ring in :root; a checked Switch and focus rings follow.

10. Kortix-internal work

In kortix-ai/suna, these skills are the law and win over this file:

• kortix-brand (values, voice, decisions): https://github.com/kortix-ai/suna/blob/dev/.agents/skills/kortix-brand/SKILL.md
• kortix-design-system (which component, reference screens): https://github.com/kortix-ai/suna/blob/dev/.agents/skills/kortix-design-system/SKILL.md
• apps/web imports keep their old paths (@/components/ui/<name>): those files are one-line shims. Edit the component in packages/ui/src/components/ui/<name>.tsx, never the shim.