components / emptystate

EmptyState

Structured blank-slate surface for onboarding, first-use, and no-result moments.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • EmptyState turns zero-data moments into deliberate product surfaces instead of ad hoc illustration cards or lonely paragraphs.
  • It gives teams a consistent way to explain what is missing, why it matters, and what the user should do next.

Aliases

blank slate

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose EmptyState when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current EmptyState contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the EmptyState label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of EmptyState behind decorative copy or overloaded surface treatments.
  • Do not stretch EmptyState into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use EmptyState for first-use, zero-results, or post-filter no-match moments.
  • Use the icon and action areas to give the state more shape when the surrounding page is sparse.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use EmptyState when a simple inline line of text is enough.
  • Do not overload it with too many competing actions.

Anti-patterns

  • Using EmptyState as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy emptystate usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

blank-slate shell

root

Carries spacing, tone, and structural rhythm.

optional visual cue

icon

Optional symbol or lightweight illustration cue.

primary heading

title

Short statement of the missing or empty condition.

supporting guidance

description

Clarifies why the space is empty or what to do next.

optional call-to-action area

actions

Supports the primary next step.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
tone'neutral' | 'brand' | 'warning''neutral'Chooses the blank-slate tone.
size'sm' | 'md' | 'lg''md'Chooses the compiled size recipe for the component.
titlestring—Primary empty-state heading.
descriptionstring—Supporting explanation or guidance.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Slots

NameDescription
iconOptional icon or symbol.
defaultOptional richer body content.
actionsOptional actions area.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • neutral: Calm blank-slate treatment.
  • brand: More encouraging product-branded tone.
  • warning: Empty state with cautionary or corrective energy.

Sizes

  • sm: Compact inline empty state.
  • md: Default empty state.
  • lg: More spacious blank-slate surface for isolated pages.

States

  • rest: Static guidance surface.

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • EmptyState is a structural guidance surface and inherits semantics from its content.

Keyboard

  • Only embedded actions participate in keyboard flow.

Screen readers

  • The title and description should fully explain the empty condition without relying on the icon.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-empty-bg
#f2f5fb
--dk-empty-fg
#16181c
--dk-empty-border
#95989d
--dk-empty-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-empty-padding
clamp(2.37rem, 2.1728rem + 0.878vw, 2.963rem)
--dk-empty-gap
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

icon

--dk-empty-icon-size
2rem
--dk-empty-icon-color
#2072e4
--dk-empty-icon-shell-bg
#e5e8ed

title

--dk-empty-title-color
#16181c
--dk-empty-title-size
clamp(1.778rem, 1.6296rem + 0.658vw, 2.222rem)
--dk-empty-title-weight
680

description

--dk-empty-description-color
#16181c
--dk-empty-description-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

actions

--dk-empty-actions-gap
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

Implementation notes

  • EmptyState is most useful when the surrounding page does not collapse around it; let layout and composition do their part.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: first-use surface

A calm blank slate with one action.

Copy snippet

<EmptyState title="No items yet" description="Create your first item to get started."><svelte:fragment slot="icon">◎</svelte:fragment></EmptyState>

Common patterns

1 example

common

Common: encouraging onboarding

Brand tone adds product energy when the blank state should feel invitational.

Copy snippet

<EmptyState tone="brand" title="Start your workspace" description="Invite the first team members to begin." />

Edge cases

1 example

edge

Edge: no results after filtering

Warning tone works when the absence may be unexpected or corrective.

Copy snippet

<EmptyState tone="warning" title="No matching results" description="Adjust the filters and try again." />

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

neutral-md

pass

size=md|tone=neutral

  • Contrast: 98.5 Lc, 98.5 Lc
  • Layout: 0 / 280, 360, 480

brand-md

pass

size=md|tone=brand

  • Contrast: 98.5 Lc, 98.5 Lc
  • Layout: 0 / 280, 360, 480

danger-lg

pass

size=lg|tone=danger

  • Contrast: 98.5 Lc, 98.5 Lc
  • Layout: 0 / 280, 360, 480