kortix-design-system
Use when building or editing any visual surface in apps/web — a page, screen, list, card, badge, avatar, modal, form, empty state, toast, tooltip, table, or panel — and you need to know WHICH componen
SKILL.md.agents/skills/kortix-design-system/SKILL.md
GitHubKortix Design System
Track this file: .agents/skills/kortix-design-system/SKILL.md
If you are touching a visual surface in apps/web, follow this. This file owns which component to compose. It does not own values — see below.
Read
kortix-brandfirst. It is the router for the Kortix look and voice. Its visual files (color.md,typography.md,layout.md,effects.md,motion.md) are the value law: the closed allowlist for every color, spacing step, type rung, radius, elevation, easing and duration, plus the rule on whether to animate at all. Itsdecisions.mdrecords why each rule is what it is. This file assumes you know those values and shows you what to build with them.
Companion skills — load all three
| Skill | Owns | Wins when they conflict |
|---|---|---|
| kortix-brand | The value allowlists, voice and claims. Color, spacing, type, radius, elevation, motion budget. Rejected defaults. scripts/audit.sh. Decision history. |
Values, copy and motion restraint |
| kortix-design-system (this file) | Components, layout shells, reference implementations, banned primitives | Which component |
| make-interfaces-feel-better | Polish: concentric radius, optical alignment, tabular nums, hit areas, font smoothing | Polish detail |
A polish skill will always propose more motion than Kortix wants. kortix-brand
is the ceiling all three operate under. Corrections to earlier versions of this
file (the shadow ladder that never existed, the press value) are recorded in
decisions.md, entries E1 and E2.
Start here: the rendered truth
Follow the Kortix design system. Every component, token and pattern below is
rendered at /design-system (apps/web/src/app/[locale]/(public)/(marketing)/design-system/).
The page paints each swatch with the real token and measures the value back, so
it cannot drift from globals.css. Open it before you build, copy what you see,
and when you add a component add it there too.
| Section | Anchor | What it shows |
|---|---|---|
| Colors | #colors |
the surface ladder, the core palette, the accents, the chart ramp, light beside dark |
| Token map | #tokens |
job → class → token → live value, by family |
| Typography, Spacing, Shadows, Motion | #typography #spacing #shadows #motion |
the rungs, steps, ladder and durations, measured |
| States | #states |
the four states of a list and of an action, side by side |
| Interaction | #interaction |
hover, press, focus, the glyph nudge, the icon swap, the info icon |
| Components | #components |
one Spec per primitive, one SpecRow per variant |
| Patterns, Anti-patterns, Usage | #patterns #anti-patterns #usage |
page patterns, the banned list, do and don't |
The prose behind the page is in references/:
patterns.md (structure, states, hover, translate, the info icon),
token-map.md (every job → class → token),
color-scheme.md (how the palette is built),
component-index.md (every primitive, its job, its anchor).
Spec grammar: how a surface explains itself
The rules in references/patterns.md, in short. They
apply to product UI, not only to the styleguide.
- Parallel structure. Things of one kind share one shape: the same slots in
the same order at the same size. A label sits in one fixed column and the
thing in the other, so a reader scans one edge (
SpecRow,sm:grid-cols-[7rem_minmax(0,1fr)]). Never a block that changes shape per item. - No title, description, title, description. A block has one name and, if it needs one, one explanation behind an info icon. A section heading never repeats as an intro paragraph under it. If the sentence is a rule, it belongs in a skill file, not on the screen.
- Explain with the info icon.
InfoIcon size-3.5in a<button aria-label>that opens aHoverCard(w-72 text-xs text-muted-foreground) on hover and on focus.Hintnames an icon-only control; the info icon explains a labelled thing. Reference:InfoHintin the route'sspec.tsx; rendered at#interaction-translate. - The four states, one primitive each. List:
Skeletonrows,EmptyStateEmptyArt,ErrorStatewith Try again, the rows. Action: idle, pending (Loadingreplaces the glyph,aria-busy, disabled, same label), done (a check swaps in place, onesuccessToast), disabled (opacity-50). Never an inline "Saved" line, never a green label, never a spinner for a list.
- Hover is color only.
hover:bg-hover transition-colors duration-fast. Pressactive:scale-[0.96]. Focusring-ring. Dense lists and anything an arrow key drives:transition-none.Buttondoes not ship the press scale; add it at the call site, behindmotion-safe:. - Translate is earned. A glyph may nudge
translate-x-0.5atduration-faston a marketing-profile link or a page's one primary link, with a reduced-motion branch. Never on a row, a menu item or a cell. A state swap is the icon-swap morph below. - Less text. State the fact once, name the object, cut the adjective.
Where components live: @kortix/ui
- One component source. Every primitive is in
packages/ui(@kortix/ui):packages/ui/src/primitives/<name>.tsx, helpers inpackages/ui/src/lib/, hooks inpackages/ui/src/hooks/, the session thread inpackages/ui/src/session/(@kortix/ui/session).apps/web, Kortix Apps, the white-label demo and SDK hosts render the same files (decision K9 indecisions.md). - Import the package path. apps/web imports
@kortix/ui/<name>for a primitive and@kortix/ui/<entry>(session,files,workspace, …) for a module. apps/web has no re-export shims:tests/unit/web-no-ui-shims.test.tsfails on a file that only re-exports@kortix/ui. Edit the component inpackages/ui. - Mock the file the import resolves to. bun mocks by resolved file:
mock.module('@kortix/ui/<name>')reaches the primitive for apps/web and for the package files that import it relatively. A barrel import (@kortix/ui,@kortix/ui/session) loads every module of the barrel, so a partial mock of one of them must keep the module's other exports:const real = await import('@kortix/ui/button'); mock.module('@kortix/ui/button', () => ({ ...real, Button: Stub })). - A new primitive goes in
packages/ui/src/primitives/with relative imports only (never@/, nevernext/*, never an app store), thenpnpm --filter @kortix/ui gen-exports. apps/web imports it as@kortix/ui/<name>. Copy for the user goes throughuseUiStrings(); a link goes throughuseUiLink().npx shadcn add <x>inapps/webwrites intoapps/web/src/components/ui/(apps/web/components.json): move the file topackages/ui/src/primitives/, rewrite its imports to relative paths, and import it from@kortix/ui/<name>. - Outside
apps/web(a Kortix App, an SDK host): follow the package skill,packages/ui/skills/kortix-ui/SKILL.md. A dashboard or App over Kortix sessions:references/custom-dashboard.md.kit.css(k-*classes) is only for plain HTML without React.
Philosophy
- Simplicity is the brand. Black & white + one accent. Calm, spacious, legible. No decoration that doesn't carry information. Show only important data.
- Reuse > Compose > Create. In that order. Never hand-roll something the system already provides.
- Tokens are law.
apps/web/src/app/globals.css(the:root/.darktokens) andpackages/ui/src/styles/theme.css(the@theme inlinekeys,@utilitydefinitions, keyframes and spinner classes that@kortix/uicomponents use) are the implementation source of truth for every visual property. If a value conflicts with anything else, these two files win. - Fast, or none. Kortix is a speed product. Motion exists to make the UI feel faster and to say where a thing came from — never to be admired. The more you animate, the less each animation is worth. The default answer to "should this animate?" is no.
- AI-native & self-documenting. The living styleguide at
/design-systemrenders every component. When you add a component, add it there too.
Strictly avoid — deprecated primitives
Do not use these in new work or when refactoring screens. They are legacy wrappers; match the hand-composed patterns in the customize section views instead.
| Banned | Use instead |
|---|---|
SectionCard (packages/ui/src/primitives/section-card.tsx) |
Card (card.tsx), Label + bg-popover rounded-md border panel, or Disclosure — see project-settings-page.tsx |
List / ListRow (packages/ui/src/primitives/list.tsx) |
<ul className="space-y-2"> + entity row classes — see access-row.tsx, review-detail.tsx |
Dialog / DialogContent in feature code |
Modal from packages/ui/src/primitives/modal.tsx — see secrets-view.tsx, channels-view.tsx |
Tooltip / TooltipTrigger / TooltipContent in feature code |
Hint from packages/ui/src/primitives/hint.tsx |
@/lib/toast (deleted; never recreate it), raw sonner, toast.success/error/info/warning(), toast.custom() |
Named helpers from packages/ui/src/primitives/toast.tsx. An action button is the button option (a Button), not sonner's action. tests/unit/toast-single-source.test.ts fails on any other sonner import |
Hand-rolled badge <span> chips |
Badge from packages/ui/src/primitives/badge.tsx |
A count beside a label (row, tab, menu item, button) as muted text or a Badge |
CountBadge from packages/ui/src/primitives/count-badge.tsx: the sidebar Review-count recipe (tabular pill, row text colour, 15% tint, 99+). Tone by meaning: waiting, reminder, conflict, neutral. Mobile: CountBadge in apps/mobile/components/kortix/count-badge.tsx |
Any icon as a spinner — CircleNotchIcon, SpinnerIcon, SpinnerGapIcon, or the same glyph aliased to Loader/Loader2/IconLoader |
Loading from packages/ui/src/primitives/loading.tsx — the spinner. The one other busy mark is SessionDotMatrix, for session-scoped work only (D4f in decisions.md) |
Hand-rolled <svg> spinners, animate-spin on non-Loading elements |
Loading — animation is built in |
When editing a file that already uses banned primitives, migrate to the reference pattern — do not add more usage.
Required primitives — use these, not alternatives
These are mandatory for their job. Import from the paths below; never reimplement or swap in a different library.
| Job | Import from | Notes |
|---|---|---|
| Tooltips on icon buttons | packages/ui/src/primitives/hint.tsx |
<Hint label="…">…</Hint> — wraps trigger, never Tooltip in features |
| Dialogs / sheets | packages/ui/src/primitives/modal.tsx |
Modal, ModalContent, ModalHeader, ModalTitle, ModalDescription, ModalBody, ModalFooter |
| Toasts | packages/ui/src/primitives/toast.tsx |
The only toast surface. successToast, errorToast, infoToast, warningToast, progressToast, loadingToast, dismissToast |
| Status chips | packages/ui/src/primitives/badge.tsx |
size="sm" or size="xs"; variants outline, kortix, success, destructive, beta, etc. |
| Expand/collapse panels | packages/ui/src/primitives/disclosure.tsx |
Disclosure, DisclosureTrigger, DisclosureContent — config lists, settings groups |
| Inline alerts | packages/ui/src/primitives/alert.tsx |
tone + optional icon + title |
| Search fields | packages/ui/src/primitives/input-group.tsx |
InputGroupSearch + InputGroupSearchInput. Every input is the one field surface: bg-popover, border, rounded-md. variant="popover" is deprecated and ignored (D4j) |
| Forms in panels | packages/ui/src/primitives/field.tsx |
Field, FieldLabel, FieldGroup, FieldDescription |
| Empty / error states | packages/ui/src/primitives/empty-state.tsx, empty-art.tsx, error-state.tsx |
The empty state of a tab, a folder or a list: EmptyState + media={<EmptyArt icon={…} />} (stacked cards, one Phosphor glyph), one title, one sentence, outline buttons with icons. No other decorative tile (D14, 2026-10-25) |
| Confirm destructive | packages/ui/src/primitives/confirm-dialog.tsx |
Mandatory before any destructive mutation — including DropdownMenuItem variant="destructive" items (see secrets-view.tsx delete, sections/view/gateway/gateway-keys.tsx revoke). Only accepted alternative: the inline Cancel/confirm button swap used for channel disconnects (channels-view.tsx). Never mutate from a single click |
| Loading / pending spinners | packages/ui/src/primitives/loading.tsx |
import Loading from '@kortix/ui/loading' — default size-4; use className="size-4 shrink-0" in dense buttons. Never CircleNotchIcon, SpinnerIcon, or other icons |
Also reach for: Button, ButtonGroup, Input, Select, Switch, Skeleton, Tabs / TabsList size="xs", Table, InlineMeta, UserAvatar, EntityAvatar.
Which component for which state
Paths are written in full. The values and the copy are in kortix-brand (layout.md sections Shells and States, voice-and-tone.md section 4).
| Situation | Compose | Never |
|---|---|---|
| The route has not mounted its shell (sign-in, project switch) | ProjectPendingScreen (apps/web/src/components/projects/project-pending-screen.tsx) |
A skeleton of a page you cannot draw |
| A list loads inside a mounted shell and the row shape is known | Skeleton rows |
A spinner for a list |
| A page or list failed to load | ErrorState size="sm" (packages/ui/src/primitives/error-state.tsx) inside the host panel, with a "Try again" action |
Alert for a load failure, or a wrapper box around it |
| An inline alert in a view that did load (a connection, a warning) | Alert with a variant |
A hand-colored banner |
| A tab, a folder or a list has no items | EmptyState with media={<EmptyArt icon={…} />} (packages/ui/src/primitives/empty-art.tsx): one title, one sentence, Button variant="outline" size="sm" actions with a leading icon. An empty folder passes no glyph. A search with no result uses MagnifyingGlassIcon (D14) |
Any other icon tile or illustration, a card, a forked or restyled EmptyArt / EmptyState, a new prop |
| People and agents with a role | AccessRow (packages/ui/src/access/access/access-row.tsx), grouped "People" then "Agents" under a Label |
A hand-built li, a kind badge, a [&>div]: selector |
Any form field, in a panel or in a Modal |
Field, FieldLabel, FieldGroup (packages/ui/src/primitives/field.tsx) |
A raw <label> beside an Input |
| A mutation finished | successToast or errorToast from packages/ui/src/primitives/toast.tsx |
An inline "Saved" line |
| Rows are selected for a bulk action | SelectionBar (packages/ui/src/internal/selection/selection-bar.tsx), pinned to the bottom of the list's column. See "Bulk selection" below |
Bulk buttons in a toolbar, a section heading or a table header |
| A new capability page | CapabilityPageShell |
CustomizeSectionWrapper (legacy, packages/ui/src/customize/sections/view/ only) |
Reference implementations — customize section views
Read the closest match before building any new screen. Paths are written in
full; the customize views live in packages/ui/src/customize/.
| File | Pattern to copy |
|---|---|
packages/ui/src/customize/sections/component/section-wrapper.tsx |
Section shell: title left, action right, max-w-2xl, responsive header |
packages/ui/src/customize/agents/agents-page.tsx |
Config entity list: search → rows → detail aside with Badge, ButtonGroup + Hint, toasts |
packages/ui/src/customize/skills/skills-page.tsx |
Capability page in CapabilityPageShell; EmptyState with a docs link |
packages/ui/src/customize/project-settings/project-settings-page.tsx |
Form sections: Label header → bg-popover rounded-md border px-4 py-5 panel; Disclosure for experimental; danger zone as neutral bordered row |
packages/ui/src/customize/sections/view/secrets-view.tsx |
Table + TabsList size="xs" filters + Modal forms + DropdownMenu row actions |
packages/ui/src/access/access/access-row.tsx |
Entity rows, UserAvatar, InlineMeta — the single row used by every access surface |
packages/ui/src/workspace/review/review-detail.tsx |
Tinted size-9 icon tile (bg-kortix-green/15 and bg-kortix-orange/15), Badge size="sm" verification chips |
packages/ui/src/workspace/sessions/project-sessions-view.tsx |
TabsList size="xs" filter tabs |
packages/ui/src/customize/sections/view/channels-view.tsx |
Table for integrations, Modal for connect flows, Alert for connected state |
packages/ui/src/internal/tunnel/computer-connect.tsx |
Split art modal (beams art beside the content), pinned lg actions, one copy button that swaps to a check in place (#8491) |
packages/ui/src/markdown/setup-links/connector-handshake.tsx |
Handshake tile: a catalogue logo fills its tile, a drawn mark takes one hairline (one boundary per tile, #8421) |
packages/ui/src/primitives/tabs.tsx |
Segmented TabsList (the default): recessed track, raised chip, concentric radii, p-[2px] pixel snap (D4b, D4c) |
packages/ui/src/primitives/menu-recipe.ts |
Menu row grid; MENU_PANEL_STATIC and FLOATING_PANEL_SURFACE are instant, MENU_PANEL and FLOATING_PANEL are for the hover card (D4a) |
apps/web/src/components/projects/project-pending-screen.tsx |
The page-level loading mark (D4h) |
packages/ui/src/primitives/dot-matrix/session-dot-matrix.tsx |
The session busy mark (D4f) |
packages/ui/src/primitives/empty-art.tsx |
The empty state art of a tab, a folder or a list, composed in packages/ui/src/workspace/spaces/space-links.tsx (D14) |
packages/ui/src/primitives/pixel-kortix-mark.tsx |
The pixel Kortix mark (D4g). Not an empty-state art for a tab, a folder or a list (D14) |
apps/web/src/features/workspace/command-palette.tsx |
Instant palette, PaletteEmpty one-line empty state |
apps/web/src/app/[locale]/(public)/(marketing)/design-system/spec.tsx |
The Spec grammar: Spec (name, info icon, source), SpecRow (label column + thing), SpecGrid / SpecCell (parallel states), InfoHint (the info icon with a hover card) |
…/design-system/states-section.tsx |
The four states of a list and of an action, each with its primitive |
…/design-system/interaction-section.tsx |
Hover (color only), press, focus, the glyph nudge, the icon swap, the info icon |
…/design-system/token-map-section.tsx |
Job → class → token → live value; the measured twin of references/token-map.md |
Shells: packages/ui/src/customize/shared/capability-page-shell.tsx (CapabilityPageShell)
is the current shell for capability pages. The older CustomizeSectionWrapper
(packages/ui/src/customize/sections/component/section-wrapper.tsx) still backs the
packages/ui/src/customize/sections/view/* screens.
Other references: tinted-icon tiles → packages/ui/src/customize/triggers/schedule-view.tsx; sidebar → packages/ui/src/workspace/sidebar/project-sidebar.tsx.
Layout & responsiveness
Always wrap a section in the shell its tree already uses — CapabilityPageShell
for a capability page, CustomizeSectionWrapper under packages/ui/src/customize/sections/view/.
Do not hand-roll the outer shell.
Canonical pattern (from section-wrapper.tsx):
<div className="flex h-full min-h-0 flex-col">
<div className="min-h-0 flex-1 overflow-y-auto">
<div className="mx-auto w-full max-w-2xl space-y-5 px-4 py-10 pb-20 lg:py-20">
<header className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
<div className="space-y-1">
<h2 className="text-foreground text-xl font-medium">{title}</h2>
<span className="flex items-center gap-1">
<p className="text-muted-foreground text-sm text-balance">
{description}
</p>
{/* optional docs link: Button variant="transparent" asChild */}
</span>
</div>
{action ? <div className="mt-2 shrink-0 sm:mt-0">{action}</div> : null}
</header>
{children}
</div>
</div>
</div>
Rules:
- Header: title + description left; primary action right. Stacks on mobile (
flex-col sm:flex-row). Content always below the header. - Container:
mx-auto w-full max-w-2xl. - Section padding:
py-10 pb-20 lg:py-20;space-y-5between header and body. - Major blocks inside body:
space-y-4(search + list),space-y-6(tab panels),space-y-8(settings sections). - Mobile-first: test narrow width.
Card & panel patterns (no SectionCard)
A panel inside another panel, a form panel in a settings section and a floating panel are bg-popover rounded-md border surfaces. A bordered list that sits directly on a page is bg-background plus border-border: the color rule wins over this recipe (color.md, in-flow section, Q11). Two sanctioned ways to build a panel — never SectionCard:
Card(packages/ui/src/primitives/card.tsx) — the codified panel. Use it when the surface has a title/description/action header, distinct content, or a footer. Slots carry the spacing (px-4,pt-5/pb-5,gap-5between slots — the panelpx-4 py-5rhythm); the bordered element itself has no padding, so flush children (tables, lists, images) sit edge-to-edge.- Hand-composed
div— for a one-off padded block inside a section, the one-div shorthandbg-popover rounded-md border px-4 py-5is fine (theproject-settings-page.tsxpattern). The moment the panel needs a flush child or an internal seam, move the padding onto inner sections.
Panels are flat: border, no shadow — elevation is for overlays (see Elevation under Tokens).
Card (component)
<Card>
<CardHeader>
<CardTitle>Repository</CardTitle>
<CardDescription>Where builds are pushed.</CardDescription>
<CardAction>
<Button size="sm" variant="secondary">
Edit
</Button>
</CardAction>
</CardHeader>
<CardContent>
{/* fields, rows — or a flush table as a direct Card child */}
</CardContent>
<CardFooter className="border-t">{/* meta or trailing actions */}</CardFooter>
</Card>
CardTitleistext-sm font-medium— panel-label scale, same asLabel. Don't scale it up; a Card is a panel, not a hero.- Divided header:
<CardHeader className="border-b">(it compacts topb-4); divided footer:className="border-t". variant="glass"(bg-card/40 border-border/40 shadow-sm) is the only elevated variant — translucent surfaces over wallpaper/media.
Settings / form panel
<section className="space-y-4">
<Label>Repository</Label>
<div className="bg-popover space-y-5 rounded-md border px-4 py-5">
<FieldGroup className="grid gap-3 sm:grid-cols-2">
{/* fields */}
</FieldGroup>
</div>
</section>
Entity row (list item)
<ul className="space-y-2">
<li className="group bg-popover flex items-center gap-3 rounded-md border px-4 py-2 transition-colors">
{/* leading: size-9 tinted icon tile */}
{/* body: min-w-0 flex-1 */}
{/* trailing: Button size="sm" */}
</li>
</ul>
Access rows use py-2.5 (packages/ui/src/access/access/access-row.tsx). Changes use py-2.
Config entity disclosure (agents, skills, commands)
<div className="space-y-2">
<Disclosure
variant="outline"
className="overflow-hidden"
open={open}
onOpenChange={setOpen}
>
<DisclosureTrigger variant="outline">
<Button
variant="popover"
className="flex w-full items-center justify-start rounded-none"
>
<span className="truncate text-sm font-medium">{name}</span>
</Button>
</DisclosureTrigger>
<DisclosureContent
variant="outline"
contentClassName="border-border border-t"
>
<div className="relative px-4 py-5">{/* detail */}</div>
</DisclosureContent>
</Disclosure>
</div>
Detail header: text-2xl font-semibold tracking-tight title; meta Badge variant="outline" size="sm"; toolbar absolute top-4 right-4 with ButtonGroup + Hint.
Dropdown item with icon + title + description
One recipe for every menu row that carries a glyph, a title and a one-line
explanation (the "New ▾" menu on Agents, Skills, Connectors, Triggers and
Secrets). Source: RichRowBody in
packages/ui/src/customize/shared/new-entity-menu.tsx;
Paper "New menu · icon + title + description", V03 (Jay, 2026-10-13).
<DropdownMenuContent align="end" className="w-76">
{" "}
{/* 280px */}
<DropdownMenuItem className="items-start gap-2.5 py-1.5">
{" "}
{/* px-2 rounded-sm from menuRow */}
<ChatCircleIcon className="text-muted-foreground mt-0.5 size-4 shrink-0" />
<span className="flex min-w-0 flex-1 flex-col">
<span className="text-foreground text-sm font-[550]">Create in chat</span>
<span className="text-muted-foreground mt-0.5 text-xs font-normal text-pretty">
An agent scaffolds it and opens a change request.
</span>
</span>
</DropdownMenuItem>
</DropdownMenuContent>
- First-line alignment, after
alert.tsx.items-startplusmt-0.5on the 16px glyph centres it on the title's first 20px line. Neveritems-center(the glyph drifts to the middle of a two-line block) and never a bareitems-start(the glyph sits on the cap height). - Two tiers. Title
text-sm font-[550] text-foreground, ink even before hover; the row's owntext-foreground/80andfont-mediumwould make it read lighter than the description's job. Descriptiontext-xs text-muted-foreground font-normal,mt-0.5under the title. - Width.
w-76(280px) lets a one-sentence description wrap at most once.w-64wrapped after about 30 characters. - Glyph. Muted,
size-4, no tile. Use the row's leading glyph, never a second one at the end.
Danger zone (settings)
Neutral bordered row — no red panel fill:
<div className="bg-popover rounded-md border px-4 py-3">
<div className="flex items-center justify-between gap-4">
<div className="min-w-0">
{/* title text-sm font-medium + description text-xs */}
</div>
<Button variant="destructive" size="sm" onClick={openConfirm}>
Archive
</Button>
</div>
</div>
destructive on the button is OK inside ConfirmDialog flow; panel itself stays neutral.
Bulk selection — always the sticky bottom bar
Every multi-select list puts its bulk actions in one floating bar, pinned to the bottom of the list's column. Never in the toolbar, the section heading or the table header. A bulk action in the header moves the controls away from the rows and shifts the layout when the selection starts.
- Component:
SelectionBar(packages/ui/src/internal/selection/selection-bar.tsx). It draws the "N selected" count, onesecondaryButtonGroup(Select all, then the actions) and the exitX. It enters with a short rise; it leaves at once. - Action tone:
tone: 'destructive'for a removing verb (Delete, Decline),tone: 'success'for an approving verb (Approve). Labels are words, no glyphs. - Placement: pinned to the bottom edge of the column, centred,
max-w-xl,bottom-4. Not plainstickyinside a scroller:stickystops under a short list.- In the account hub:
AccountHubSelectionBar(packages/ui/src/internal/account-hub/hub-sheet.tsx) renders the bar into a slot over the page column. - In a capability page: an
absolute inset-x-0 bottom-4wrapper in the non-scrolling column (customize/triggers/schedule-view.tsx).
- In the account hub:
- Selection: a checkbox gutter on each row and a select-all checkbox in the
table head (
MemberTableHead/MemberTableRow). The bar renders only while something is selected, and the exitXclears the selection. - Running: pass
progressfor a long batch, or disable the actions. Run the calls withPromise.allSettled, refresh the list once, and show one toast for the batch.
References: schedule/trigger-selection-bar.tsx (Triggers), drive-selection-bar.tsx
(Files), sessions-selection-bar.tsx (Sessions), access-projects-tab.tsx
(join requests).
Button conventions
Match the customize views — consistent sizes and variants:
| Context | Pattern |
|---|---|
| Section header primary action | Button size="sm" variant="secondary" + PlusIcon (size-4) + label; group with gap-1.5 |
| Empty state CTA | Button variant="outline" size="sm" className="gap-1.5" |
| Docs / secondary link | Button asChild variant="ghost" size="sm" className="gap-1.5" |
| Row secondary action | Button variant="ghost" size="sm" |
| Row primary action | Button size="sm" (default variant) |
| Icon-only with tooltip | Hint → Button variant="outline" size="icon" inside ButtonGroup |
| Inline text link | Button variant="transparent" size="sm" asChild |
| Modal cancel | Button variant="outline-ghost" |
| Pending / in-flight state | <Loading className="size-4 shrink-0" /> in buttons; <Loading /> or className="size-4 shrink-0" in headers — never CircleNotchIcon |
Icons in buttons: size-3.5 shrink-0 (dense) or size-4 (header). Always shrink-0 on icons. Exception: loading uses Loading, not an icon import.
Button groups — the default for buttons in a row
Two or more buttons side by side that serve one surface are a ButtonGroup (@kortix/ui/button-group). A toolbar cluster, a back/forward pair, a header's action set and a viewer's close cluster are all groups. Do not line buttons up with flex gap-1 and hand-tuned ml-*: the group owns the spacing (gap-px) and joins the corners of neighbours, so a row of controls reads as one object instead of loose icons.
| Rule | Why |
|---|---|
One variant for every member: all ghost, all secondary or all outline. |
Mixed weights break the group into a primary plus strays. A real primary action stands outside the group. |
The close X joins the group of the actions beside it. |
It is part of the toolbar, not a separate control. |
Every member is a direct child: Hint (it renders asChild) wrapping a Button is fine, and so are asChild links. |
The corner rounding targets direct children ([&>*]). A <span> or a PopoverAnchor wrapper between the group and the Button takes the rounding instead. |
No dividers, gap-*, ml-* or mx-* inside a group. |
The group sets the rhythm; one override drifts every row. |
| One group per job. Navigation (back/forward) and page actions (open, full screen, close) are two groups, with the address bar or title between them. | A group says "these act on the same thing". |
A hidden member ({cond && …}) is fine; a group of one is not: render the lone Button bare. |
A group of one adds nothing. |
Not a group: a modal or form footer (Cancel + Confirm stay a spaced pair, so the destructive or primary choice is not glued to Cancel), and a button beside a text input that is not part of it. Icon buttons inside an address or path pill are a group too: the pill holds the group at its trailing edge.
Reference implementations:
| File | Group |
|---|---|
app/[locale]/(public)/share/session/[token]/page.tsx |
Header actions, all secondary: open app, full screen, download or copy link, Open in Kortix |
packages/ui/src/browser/sandbox-browser-chrome.tsx |
Back / forward, ghost; Reload and the pill's trailing actions inside the address pill |
packages/ui/src/files/viewer/viewer-actions.tsx (ViewerPathPill) |
Refresh, copy, copy link inside the path pill, ghost |
packages/ui/src/session/panel/easy/app-preview.tsx |
Open in new tab, full screen, close, ghost |
packages/ui/src/files/viewer/file-viewer.tsx, file-preview.tsx |
Save as PDF or Present, Download, full screen, close, ghost |
packages/ui/src/changes/change-list.tsx |
Unified / split diff toggle, outline |
Cursor affordance
Every clickable element shows cursor: pointer. Disabled elements keep
cursor: default. Do not add cursor-default to an interactive element.
- A clickable element is a
<button>, a<Link>, or has arole. Never putonClickon a barediv. - The base rule in
apps/web/src/app/globals.cssgives the pointer to buttons, links,label[for], native checkbox/radio/file inputs, selects, summaries, and thebutton/checkbox/link/menuitem/menuitemcheckbox/menuitemradio/option/radio/switch/tab/treeitemroles. It excludes:disabled,aria-disabled, anddata-disabled. - A utility class beats
@layer base, so a straycursor-defaultsilently removes the pointer.tests/unit/cursor-affordance.test.tsfails on acursor-defaultinpackages/ui/src/primitiveswithout an inline reason.
Icons — Phosphor, plus the house glyph set
The only icon library in apps/web is @phosphor-icons/react. lucide-react,
react-icons, @mynaui/icons-react, and @icons-pack/react-simple-icons are
removed and blocked by ESLint (no-restricted-imports).
- House glyphs (D4i).
packages/ui/src/internal/icons(the glyphs the package renders) andapps/web/src/features/icon/icons(the ones only apps/web renders) hold the glyphs Phosphor lacks and the third-party marks. A house glyph usescurrentColorand takes its size fromclassName. When you add one, replace every Phosphor equivalent in the same change. - Always import the
*Icon-suffixed exports:PlusIcon,MagnifyingGlassIcon,CaretRightIcon— never the deprecated bare names (Plus). - Never pass a
weightprop. One constant governs the whole app:DEFAULT_ICON_WEIGHTinpackages/ui/src/lib/icon-config.ts(currentlybold). Change it, save, and every icon flips; commit it and production renders the same. There is no runtime toggle and no dev/prod branching — the constant is the single source of truth in every environment. Compare all six weights at /design-system → Icons. - Two delivery paths, same constant, both propless:
- Client components →
IconProvider(root layout) feeds it to Phosphor'sIconContext. Import from@phosphor-icons/react. - Server components (RSC) → React context does not exist in RSC, so import
from
@/lib/icons/ssr, where the weight is pre-bound. Importing@phosphor-icons/react/dist/ssrdirectly is ESLint-blocked (it silently defaults toregular); importing the main entry in a server component crashes the build (createContextat module scope). Adding an icon to a server component? Add its two lines tosrc/lib/icons/ssr.tsx.
- Client components →
- Exception — solid intent: status tiles, destructive
trash, and logo glyphs pass an explicit
weight="fill"so they stay solid regardless of the global weight. Completion checks useSolidCheckIcon, not a Phosphor weight variant. - Semantic layer:
packages/ui/src/primitives/kortix-icons.ts(IconAdd,IconDelete, …) re-exports Phosphor icons; prefer it where already adopted. It re-exports the client entry, so it is client-graph only. - Sizing stays Tailwind-first (
size-4,size-3.5 shrink-0in dense buttons); the provider'ssize: 24default only covers class-less usages. - Background on the RSC rule above: the main entry calls
createContextat module scope with no'use client'directive, so a server-only module graph reaching it crashes the build withTypeError: (0, d.createContext) is not a function. Phosphor's own SSR entry fixes the crash but hardcodesweight="regular", which would quietly ignoreDEFAULT_ICON_WEIGHT— that is why@/lib/icons/ssrexists and why the raw entry is ESLint-blocked outside it.
apps/mobile uses Phosphor too (phosphor-react-native, the community React
Native port with the same 1,512 glyphs and names). Its rules differ from web in
two places, both caused by Metro:
- Import icons only from
@/lib/icons. That registry is the only file that imports the package, one icon file at a time: Metro tree shaking is off, so the package barrel would ship every icon in all six weights. - The registry binds
DEFAULT_ICON_WEIGHT(apps/mobile/lib/icons/icon-config.ts,bold) onto each icon, becauseIconContextis exported only from that barrel.weight="fill"is still the only weight prop. apps/mobile/lib/icons/icon-imports.test.tsfails on a retired icon library, a direct package import, an unused registry entry, a non-fillweight, or a spinner glyph.
Motion in components
Budget and easings live in kortix-brand → motion.md.
Read the frequency ladder there before adding any animation. The short version:
Kortix is a speed product. Fast, or none. Count how many times a day a user sees the interaction; that number sets the budget. Constant-use surfaces — keyboard nav, dense-list hover, focus moves, table selection — get no animation at all.
What that means for the components in this file:
| Component | Motion |
|---|---|
| Row hover in a list, sidebar nav | transition-colors duration-fast. Color only — never position. |
| Keyboard-driven selection / arrow-key nav | None. transition-none. |
Disclosure, Tabs |
200ms, ease-out. Built in — do not add more. |
Modal, Dialog, sheets |
300ms max, ease-out, enter from scale-0.97. Built into modal.tsx. |
| Toast | Owned by toast.tsx. Do not restyle its motion. |
Loading |
Ships its own rotation. Never add animate-spin. |
| Buttons | active:scale-[0.96] + transition-colors. Nothing else. A full-width row presses with active:scale-[0.998] (D4k). |
| Skeleton → content | Cross-fade opacity, or nothing. Never a stagger. |
Do not add enter animations to list items. A staggered or animated list is measurably slower to read and to click than the same list appearing at once, and the cost is paid on every render.
Sanctioned exception — the icon-swap morph
Frequency gate: this pattern is for buttons whose state change is meaningful and occasional — copy → copied, connect → connected, follow → following. It is not for a control the user hits repeatedly in a working session. If in doubt, hard-swap the icon; a hard swap is never wrong, it is only plain.
When it does apply: never hard-swap {done ? <CheckIcon/> : <CopyIcon/>} with no
transition. Cross-fade the two icons in the same box with blur + scale +
opacity so it reads as one morph, not two objects blinking. The blur is what
bridges the two states — without it the eye sees two distinct objects.
Values: scale 0.25 → 1, opacity 0 → 1, blur 4px → 0, spring
{ type: 'spring', duration: 0.3, bounce: 0 }. bounce: 0 is the brand.
Always initial={false} so nothing animates on first paint.
import { AnimatePresence, motion } from "motion/react";
<button
onClick={handleCopy}
aria-label={copied ? "Copied" : "Copy"}
className={cn(
"inline-flex size-7 items-center justify-center rounded-md",
"text-muted-foreground hover:text-foreground hover:bg-muted-foreground/10",
"cursor-pointer transition-colors active:scale-[0.96]",
)}
>
<span className="relative inline-flex size-3.5 items-center justify-center">
<AnimatePresence initial={false} mode="popLayout">
<motion.span
key={copied ? "check" : "copy"}
initial={{ scale: 0.25, opacity: 0, filter: "blur(4px)" }}
animate={{ scale: 1, opacity: 1, filter: "blur(0px)" }}
exit={{ scale: 0.25, opacity: 0, filter: "blur(4px)" }}
transition={{ type: "spring", duration: 0.3, bounce: 0 }}
className="absolute inset-0 inline-flex items-center justify-center"
>
{copied ? (
<CheckIcon className="size-3.5 text-kortix-green" />
) : (
<CopyIcon className="size-3.5" />
)}
</motion.span>
</AnimatePresence>
</span>
</button>;
Rules: both icons share one fixed-size box (relative size-3.5 parent, each
child absolute inset-0) so they overlap and the blur bridges the crossfade.
Confirmed status colour stays a kortix-* token (text-kortix-green), never raw
palette. Ship a prefers-reduced-motion branch — drop the scale and blur, keep
the opacity. Reference: CopyButton in
packages/ui/src/markdown/copy-button.tsx.
Spacing cheat sheet (from reference views)
| Layer | Classes |
|---|---|
| Section wrapper → body | space-y-5 |
| Search + content block | space-y-4 |
| List of rows / disclosures | space-y-2 inside space-y-4 parent |
| Settings major sections | space-y-8 |
| Tab panel content | space-y-6 |
| Panel inner padding | px-4 py-5 (standard), px-4 py-3 (compact row) |
| Row internal gap | gap-3 (row), gap-1.5 (title/meta), gap-2 (button groups) |
| Detail content below title | mt-8 |
| No-match empty search | px-3 py-6 text-center text-xs |
Card slot rhythm |
px-4 all slots; pt-5 header / pb-5 last slot; gap-5 between slots |
Padding never sits on a bordered element that hosts flush children (tables, lists, seams) — put it on the slots/inner sections. A single padded block may use the one-div shorthand bg-popover rounded-md border px-4 py-5.
Tokens — see kortix-brand
Every value lives in kortix-brand (references/visual/visual-system.json, explained by the visual guidance files).
Colors, spacing steps, type rungs, radius ladder, elevation steps, easings and
durations are enumerated there as closed allowlists, with the reasons and the
audit.sh that enforces them. This file used to restate them; two copies drift,
so the copy is gone.
The five facts you will get wrong from stock Tailwind habit, restated here only because they bite immediately:
| Fact | Consequence |
|---|---|
--spacing: 0.23rem, not 0.25rem |
Every spacing utility is 8% tighter. A 16px mockup padding is p-4, never p-[16px]. |
--text-xs: 0.8125rem = 13px, not 12px |
text-xs is the workhorse (1999 uses). There is no rung below it. |
--radius: 0.625rem → rounded-md is 8px |
rounded-md is the default for every panel, row, table and card. |
Color is semantic tokens + the seven kortix-* accents |
No raw palette, no hex, and no dark: for color — tokens flip themselves. |
| In-flow surfaces are flat — border, no shadow | Shadows mean "floats above the page". |
Status pattern — tinted icon tile
<span className={cn(
'flex size-9 items-center justify-center rounded-sm',
merged && 'bg-kortix-green/15',
failed && 'bg-kortix-red/15',
open && 'bg-kortix-blue/15',
)}>
<Icon className={cn('size-5', merged && 'text-kortix-green', …)} />
</span>
Use weight="fill" icons at size-5 inside size-8/size-9 tiles. Pair with Badge for text labels when needed (review-detail.tsx, sandbox-provider-coverage.tsx).
Modal pattern (canonical — use modal.tsx)
From secrets-view.tsx / channels-view.tsx — not raw Dialog:
<Modal open={open} onOpenChange={setOpen}>
<ModalContent className="lg:max-w-lg">
<ModalHeader>
<ModalTitle>Title</ModalTitle>
<ModalDescription>Description</ModalDescription>
</ModalHeader>
<form onSubmit={handleSubmit}>
<ModalBody className="max-h-[60vh] overflow-y-auto">
{/* fields */}
</ModalBody>
<ModalFooter className="sm:justify-between">
<Button
type="button"
variant="outline-ghost"
onClick={() => setOpen(false)}
>
Cancel
</Button>
<Button type="submit" disabled={pending}>
{pending ? <Loading className="size-4 shrink-0" /> : null}
Save
</Button>
</ModalFooter>
</form>
</ModalContent>
</Modal>
Destructive confirms → ConfirmDialog, not a red-styled Modal trigger.
Tabs pattern
- Default
TabsList: the segmented control (recessed track, raisedshadow-xschip). A vertical list (a settings rail) is never segmented (packages/ui/src/primitives/tabs.tsx). - Primary section tabs:
TabsList type="underline"+TabsTrigger className="w-fit flex-none"(channels-view.tsx) - Filter / status tabs:
TabsList size="xs"+TabsTrigger(project-sessions-view.tsx,secrets-view.tsx) - Tab badge count:
<CountBadge count={n} />inside trigger
Loading pattern (canonical)
Every in-flight spinner is Loading from loading.tsx. There are no exceptions and no second spinner in this codebase. The component ships its own rotate/dash animation, so it never needs animate-spin.
No icon is ever a spinner. Not CircleNotchIcon, not SpinnerIcon, not SpinnerGapIcon, not any other Phosphor glyph, whatever it is aliased to (Loader, Loader2, IconLoader, …). If you catch yourself writing animate-spin on an icon, the answer is Loading. kortix-icons.ts deliberately exports no loader icon so the semantic layer can't offer you one.
import Loading from '@kortix/ui/loading';
// Button pending (replaces action icon)
<Button disabled={pending}>
{pending ? <Loading className="size-3.5 shrink-0" /> : <PlusIcon className="size-3.5 shrink-0" />}
Save
</Button>
// Section header action
<Button size="sm" variant="secondary" disabled={pending}>
{pending ? <Loading className="size-4 shrink-0" /> : <PlusIcon className="size-4" />}
New
</Button>
// Inline / modal submit
{pending ? <Loading className="size-4 shrink-0" /> : null}
Page-level loading is ProjectPendingScreen (the pulsing Kortix mark), not a skeleton (D4h). Use Skeleton only for a local element whose final shape is known (a field, a logo tile). Use Loading for active async operations (submit, fetch-in-button, mutation pending). For session-scoped work, such as an approve or deny button while a decision saves, use SessionDotMatrix (D4f). Never flash a fallback that the real content then replaces.
Search + loading + empty flow
Standard content block (agents-page.tsx pattern):
<div className="space-y-4">
<InputGroupSearch>…<InputGroupSearchInput />…</InputGroupSearch>
{isLoading ? (
<div className="space-y-1">{/* Skeleton h-7 rounded-md × 5 */}</div>
) : isError ? (
<ErrorState size="sm" action={<Button variant="outline" size="sm">Retry</Button>} />
) : items.length === 0 ? (
<EmptyState size="sm" action={…} />
) : (
/* list */
)}
</div>
Dos & Don'ts
- ✅ Page shell →
CapabilityPageShellfor a new page (CustomizeSectionWrapperonly underpackages/ui/src/customize/sections/view/). ❌ hand-rolled outer flex + header, ❌[&_header_h2]:overrides of the shell header. - ✅ Panels →
Card(card.tsx) orbg-popover rounded-md borderwithpx-4 py-5. ❌SectionCard, ❌ padding on a bordered element that hosts flush children. - ✅ Elevation → ladder step (
shadow-mdpopovers,shadow-lgmodals); in-flow panels stay flat with a border. ❌dark:shadow-*, ❌shadow-[…]when a step fits. - ✅ Lists →
<ul className="space-y-2">+ entity row classes. ❌List/ListRow, ❌divide-yCard lists. - ✅ Expandable config →
Disclosure+Button variant="popover". ❌ custom accordion, ❌ nested rounding unless concentric (inner radius = outer radius minus inset; otherwise the child is flush). See effects.md. - ✅ Modals →
Modalfrommodal.tsx. ❌Dialog/DialogContentin features. - ✅ Destructive actions →
ConfirmDialog(or the inline two-step Cancel/confirm swap,channels-view.tsx). ❌ firing a delete/revoke mutation directly from avariant="destructive"click. - ✅ Tooltips →
Hint. ❌Tooltipprimitives in features. - ✅ Two or more buttons in a row on one surface →
ButtonGroup, one variant, closeXincluded. ❌flex gap-1rows of loose buttons, ❌ml-*/ dividers between members, ❌ a group of one, ❌ grouping a modal's Cancel + Confirm. - ✅ Toasts →
@kortix/ui/toasthelpers. ❌@/lib/toast(deleted), raw sonner,toast.success(). - ✅ Badges →
<Badge size="sm" variant="…">. ❌ hand-rolled chip spans. - ✅ Status → tinted icon tile + optional
Badge. ❌ raw palette icon colors. - ✅ Color →
kortix-*+ semantic tokens. ❌text-emerald-600,bg-amber-500. - ✅ Clickable elements →
cursor: pointer; disabled keepdefault. ❌cursor-defaulton an interactive element. - ✅ Meta separators →
InlineMetaortext-muted-foreground/40bullet (•). ❌ inconsistent separators. - ✅ Empty tab, folder or list →
EmptyState+EmptyArt(one Phosphor glyph), one title, one sentence, outline buttons with icons (D14). ❌ centered<p>only, ❌ any other decorative tile or illustration, ❌ a forked or restyledEmptyState/EmptyArt(Q23). - ✅ Alerts →
Alert. ❌ hand-rolled colored banners. - ✅ Pending spinners →
Loadingfromloading.tsx. ❌CircleNotchIcon,SpinnerIcon, or anyanimate-spinicon. - ✅ Motion → count the frequency first;
transition-colors duration-faston hover,ease-outon enter/exit,active:scale-[0.96]on press. ❌transition-all, ❌ baretransition, ❌ease-in, ❌ anything over 300ms in product UI. - ✅ Keyboard-driven interactions →
transition-none. ❌ animating arrow-key nav or focus moves. - ✅ Every animation ships a
prefers-reduced-motionvariant. ❌ one variant only. - ✅ List items appear at once. ❌ stagger in product UI.
- ✅ Interactive elements show the pointer from the global rule. ❌
cursor-defaulton a clickable element. - ✅ Same kind, same shape: a fixed label column and the thing beside it. ❌ a block that changes layout per item.
- ✅ One name, one info icon with a hover card. ❌ title over description over sub-title over sub-description; ❌ an intro paragraph that repeats the heading.
- ✅ A list draws loading, empty, error and loaded with
Skeleton,EmptyState,ErrorStateand rows. ❌ a spinner for a list, ❌ a page skeleton the route cannot draw. - ✅ An action keeps its label through pending and done; the glyph swaps. ❌ an inline "Saved" line, ❌ a label that widens the button.
- ✅ Hover changes color only. ❌ a lift, a translate or a shadow on hover in app chrome.
- ✅ A glyph nudge on one primary or marketing link,
duration-fast, reduced-motion branch. ❌ translate on a row, a menu item or a cell.
Workflow checklist
- Load
kortix-brand— the value allowlists and the motion budget. Then this file, thenmake-interfaces-feel-better. - Read the closest reference view from the table above. Copy structure, spacing, and primitives — don't invent a new layout dialect.
- Open
/design-systemand skimreferences/component-index.mdfor anything not covered by the reference. Map every value throughreferences/token-map.md. - Structure: parallel slots, one name plus an info icon, the four states (
references/patterns.md). - Compose: the page shell (
CapabilityPageShell) → search/panel/row/disclosure/table →Badge+Hint+Modal+toast+Loading+EmptyState+EmptyArt. Buttons in a row →ButtonGroup. NeverSectionCard,List, orCircleNotchIcon. - Status → tinted icon tile. Color →
kortix-*. Radius →rounded-md(panel),rounded-none(flush trigger). Elevation → overlays only; flat border for in-flow panels. - Motion last. Count how often a user sees it. Constant → none. Otherwise ≤300ms,
ease-out, named property, token duration, reduced-motion variant. - New primitive? Tokens only, tiny API, add to
/design-system. - Verify:
.agents/skills/kortix-brand/scripts/audit.sh <your paths>clean, no banned imports, nested rounding only when concentric (see effects.md), light + dark,tscclean, polish checklist frommake-interfaces-feel-better. - Replay the interaction ten times. If you still notice the animation, it is too much.
Tabs: use <TabsList variant="secondary"> for transparent tabs with a bg-secondary active tab. Use size="xs" for small tabs. Compact tab components are removed.
Copy and completion icons
- Every copy action uses
CopyButtonfrom@kortix/ui/markdown/copy-button: text, links, code, tokens, and IDs. - It uses
Copyfrom@kortix/ui/icons(packages/ui/src/icons/copy.tsx) and swaps inSolidCheckIconfrom@kortix/ui/internal/icons/solid-check-iconafter clipboard success. Keep one fixed icon box. Reduced motion swaps immediately. - Within
packages/ui, custom copy controls reuseAnimatedCopyIconwith those same two icons. Hosts composeCopyButton. Preserve clipboard error handling and an accessible label. Never use Phosphor CopyIcon or a local copy timer. - Completion and success use
SolidCheckIcon. Never use a square filled CheckIcon as a completion symbol. A checkbox is for an editable selection only. - Avoid crowded cards. Use one heading, short facts, and one primary action. Put secondary explanation in an info hover card. Keep space between header, body, and actions. Do not stack a description under every fact.
Timestamp details use Hint from @kortix/ui/hint, never HoverCard. InlineMetaTime follows this rule. Reserve hover cards for richer previews such as related-item lists.