Empty state | Arcadia Design

No skills yet

import { Button, EmptyState } from "@arcadia/ui";

<EmptyState framed icon="file-text" title="No skills yet" actions={<Button size="sm" variant="secondary" icon="plus">New skill</Button>} />

TSX

import { Button, EmptyState } from "@arcadia/ui";

<EmptyState framed icon="provider" title="No MCP servers" actions={<Button size="sm" variant="secondary">Add server</Button>} />

One anatomy: an icon in a quiet fill-3 tile (what would be here), the title naming what is missing (text-2 at 500), and in actions the one button that fills the gap. Nothing explains: the title says what is missing, the action what to do.

It takes one of two forms. Inside a settings page or a list of cards it is framed and starts on the page's edge, where the list would sit. As a whole pane or region (a side pane's tab, a file preview, a closed browser) it is unframed and align="center".

Examples

Centered

align="center", unframed, for a pane of its own, such as a side panel with nothing to show.

No changes in this turn

import { EmptyState } from "@arcadia/ui";

<EmptyState align="center" icon="file-diff" title="No changes in this turn" />

Framed

framed draws the card the list would fill: a solid hairline a step above the page, at the large-surface corner, like a settings group. Never inside a card.

A cause

description carries only what the reader can't see otherwise: a failure's own words, one line in text-3.

Usage would not load

The server answered 503 Service Unavailable

import { Button, EmptyState } from "@arcadia/ui";

<EmptyState framed title="Usage would not load" description="The server answered 503 Service Unavailable"
  actions={<Button size="sm" variant="secondary">Try again</Button>} />

rootStyle takes where it sits and these knobs: the padding as a spacing token, the frame's line as a palette token.

--empty-pad: Ref<Space>Default var(--space-4); Padding (a framed start pads its sides as a card's rows).
--empty-frame: PaintDefault var(--stroke-3); The framed card's hairline.

Static text: no role, nothing focusable but its actions. When it replaces content after an action (a search with no results), give it role="status" so the change is announced.

A loading list shows a Skeleton, never an empty state: empty is an answer, not a wait.

EmptyState

icon: IconName; A glyph in a quiet tile: what would be here.
titlerequired: ReactNode; What is missing ("No skills yet"), text-2 at 500.
description: string; Only a cause the reader can't see otherwise (a failure's words), text-3. Never how to fill the gap.
actions: ReactNode; The one button that fills the gap.
align: "start" | "center"Default "start"; start with framed inside a settings page or a card list; center, unframed, for a whole pane or region.
framed: boolean; The card the list would fill: a hairline a step above the page, never inside a card.
rootStyle: RootStyle<EmptyStateKnobs>; Typed StyleX override: where it sits and its --empty-* knobs.

Rest props go to HTMLAttributes<HTMLDivElement>.

Usage

Examples

Centered

Framed

A cause

Customising

Accessibility

API reference

EmptyState