Layout & content

EmptyState

A calm, explanatory collection state with an optional next-step action.

EmptyStateEmptyStateProps

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

No projects yet

Create one to get started.

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

import { Button, EmptyState } from '@ai-created/ui';

export function Example() {
  return (
    <EmptyState
      title={"No projects yet"}
      description={"Create one to get started."}
    >
      <Button size="sm">Create project</Button>
    </EmptyState>
  );
}

Import

tsx

import { EmptyState, Button } from '@ai-created/ui';

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Surface

Required

Muted responsive container.

div

Icon

Optional

Optional decorative context cue.

Title

Required

Explains the empty condition.

Description

Optional

Optional reason or next-step guidance.

Action area

Optional

Optional children, usually one Button.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Content/Empty state

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish icon, title, description, and action properties with nested action support.

Auto layout

Direction: vertical
Gap: 8px copy gap; 16px icon gap; 24px action gap
Padding: 32px mobile; 48px desktop
Alignment: Center
Wrap: Content wraps

Resizing

Width: fill
Height: hug
Minimum width: 240px
Maximum width: Parent controlled
Minimum height: Content controlled
Maximum height: Content controlled
Overflow: visible

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
Icon	instance-swap	None	icon	No additional constraint
TitleRequired	text	No projects yet	title	No additional constraint
Description	text	None	description	No additional constraint
Action	slot	None	children	No additional constraint

Nested assets and slots

Surface

primitive / required

Muted responsive container.

Internal Surface

Icon

slot

Decorative 48px context icon.

icon

Action

slot

Usually one Button.

children

Content limits

Title

One line preferred, maximum two lines

Overflow: Wrap to two lines; then revise.

The state should remain quickly identifiable.

Description

Maximum three lines or about 180 characters

Overflow: Move longer onboarding guidance outside the component.

The empty state is an orientation point, not a help article.

Actions

One primary action, optional one secondary text link

Overflow: Remove lower-priority actions.

A single next step reduces decision cost.

Localization and RTL

Translatable: Title, Description, Action labels

Centered composition is direction-neutral.
Directional action icons mirror.
Test twice-length copy.
Test without an icon.
Test at 200% text size.

Responsive behavior

Fill the empty collection region.

md: padding increases from 32px to 48px

Copy remains centered.
Parent sets vertical placement and available height.

Authoring limits

Do not detach to fit extra actions or long instructional content.
Title is rendered as text, so the consumer must provide surrounding heading hierarchy when needed.

Accountable owner

Design systems content pattern owner

Canonical source: src/components/EmptyState.tsx

Copy templates and action hierarchy changes require content design review.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Padding

32px mobile / 48px md+

Icon

48 × 48px

Icon bottom margin

16px

Title/description gap

8px

Action top margin

24px

Copy width with icon

max-width 448px

Rules

Center all content.
Keep actions subordinate to the explanation.
Use muted Surface styling rather than error styling.

Token dependencies

--color-surface2

Muted Surface fill.

--color-border

Container border.

--color-text2

Title.

--color-text3

Icon and description.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

empty

Trigger: A successfully loaded collection has no items.
Visual response: Centered optional icon, copy, and action on a muted surface.
Behavior: Action follows its own component behavior.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Non-semantic Surface container; child action preserves its own semantics.
Accessible name: The visible title names the state in reading order.

Use a clear title that distinguishes empty from loading or failure.
Icons are decorative.
Supply a heading element through composition when the surrounding page hierarchy requires one.

Keyboard behavior

Tab: Moves to actions supplied as children.Only when an action is present.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { EmptyState, Button } from '@ai-created/ui';

Server Component compatible

Accepts all div attributes and forwards the container ref through Surface.
The icon prop accepts a Lucide icon component and marks it decorative.

tsx

<EmptyState title="No projects yet" description="Create one to get started."><Button>Create project</Button></EmptyState>

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
icon	LucideIcon	undefined	Optional decorative icon.
title	string	required	Short empty-state heading.
description	string	undefined	Supporting explanation.
children	ReactNode	undefined	Optional action content.
className	string	undefined	Additional classes.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Explain why the view is empty when it may be surprising.
Offer one concrete next step when the user can resolve it.

Do not

Do not show during loading.
Do not use upbeat copy for data loss or a failure.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Renders required title and optional icon, description, and children.
Forwards Surface div attributes.

Interaction

Optional action remains keyboard operable.

Accessibility

Reading order is icon-hidden, title, description, action.

Visual

Capture with/without icon and action at mobile and desktop padding.

Related specifications

skeleton notice button surface