Primitive contract

EmptyState

Explains why useful content is absent and provides an appropriate next action without an implicit alert.

Guided absence and next action · @sanchika/primitives

Purpose and semantics

Explains why useful content is absent and provides an appropriate next action without an implicit alert.

Recommended semantic: Use a section or aside with a labelled heading; actions remain native Link or Button semantics.

Anatomy

title

Names the absence.

explanation

Explains cause or boundary.

primary action

Clear next step.

detail

Optional secondary or source detail.

marker

Optional restrained visual cue.

Finite variants and important states

Variant · kind: empty, filtered, unavailable
Required states: empty, filtered, unavailable
Class hooks: .sk-empty-state · .sk-empty-state-filtered · .sk-empty-state-unavailable · .sk-empty-state__marker · .sk-empty-state__actions · .sk-empty-state__detail

Composed synthetic exemplar

Rendered state matrix

EmptyState: 3 required states

Each specimen starts from the package-owned example and contract state inventory. Simulated pointer and focus frames are labelled; consumers still verify real interaction in context.

emptyThe empty contract remains visible and inspectable.

No matching tools

Clear the search to restore all tools.

filteredThe filtered contract remains visible and inspectable.

No matching tools

Clear the search to restore all tools.

unavailableThe missing capability includes a safe alternative.

No matching tools

Clear the search to restore all tools.

Accessibility and consumer responsibility

Keyboard and screen reader

Actions keep native Link or Button behavior.
Use a labelled region where helpful
Do not add alert role by default

Consumer owns

Choose truthful kind
Wire actions
Use native action semantics

Mobile

Copy stays concise and actions wrap or stack

Reduced motion and forced colors

No override is required.

Text, marker, and action boundaries remain visible

Compact API reference

Package: @sanchika/primitives
CSS: @sanchika/primitives/styles.css
Contract: primitiveSpecs.find((contract) => contract.name === "EmptyState")
Primary class: .sk-empty-state