{
  "title": "Empty states",
  "path": "/patterns/empty-states",
  "url": "https://design.werklist.com/patterns/empty-states",
  "text": "https://design.werklist.com/agent/patterns/empty-states",
  "summary": "One calm sentence and the next action, for a list or a board with nothing to show.",
  "version": "2.1.2",
  "kind": "pattern",
  "name": "Empty states",
  "purpose": "Tells the reader why a loaded surface has nothing to show and offers the action that fills it: one sentence, at most one action, no icon.",
  "use": [
    "A surface has loaded and has no items",
    "A search or a filter returned nothing",
    "The reader has dealt with everything and is all caught up",
    "A list that only the reader's own action fills is empty",
    "A reader who cannot add sees an empty surface"
  ],
  "avoid": [
    "Before the content has loaded: show the skeleton",
    "When the load failed: show the error in place",
    "Icons, illustrations, a second paragraph"
  ],
  "anatomy": [
    {
      "part": "Sentence on a page",
      "measure": "20 px, 26 px from 640 px wide, line height 1.25, weight 700, in balanced lines at most 34 rem wide",
      "token": "--text"
    },
    {
      "part": "Sentence in a panel or a card",
      "measure": "14 px on 20 px, weight 400",
      "token": "--text-muted"
    },
    {
      "part": "Action on a page",
      "measure": "Primary button, 44 px, 24 px under the sentence. It opens the same form as the Add button in the toolbar.",
      "token": "--space-6"
    },
    {
      "part": "Action in a panel or a card",
      "measure": "Quiet small button or a link, 8 px under the sentence, or none",
      "token": "--space-2"
    },
    {
      "part": "Space above and below",
      "measure": "On a page 48 px, 64 px from 640 px wide. In a panel or a card 48 px.",
      "token": "--space-12, --space-16"
    }
  ],
  "variants": [
    {
      "name": "Nothing yet",
      "use": "Says what goes here and offers the create action: 'Add the first candidate to this project.'"
    },
    {
      "name": "Nothing matches",
      "use": "Says the search or the filters hid everything and offers Clear filters or Clear search"
    },
    {
      "name": "All done",
      "use": "Says the reader is finished and offers nothing: 'You are all caught up.'"
    },
    {
      "name": "Filled by you",
      "use": "Says how the list fills and offers nothing: 'Candidates you save appear here.'"
    },
    {
      "name": "No access",
      "use": "Says who can add and offers nothing: 'Only the owners of this board can add items.'"
    },
    {
      "name": "Error in place",
      "use": "The failure sentence in full ink and Try again, as the Errors pattern sets it"
    }
  ],
  "rules": [
    "One sentence and at most one action. No icon, illustration or second paragraph.",
    "The toolbar, the search field and the filters stay above the empty state.",
    "In a table the header row stays, and the small sentence fills a body at least three rows high.",
    "A surface is empty only after it has loaded. While it loads it shows its skeleton, and a failed load shows the error.",
    "The action opens the same form as the Add button in the toolbar.",
    "A search that finds nothing is announced once: 'No candidates match.'"
  ],
  "accessibility": [
    "The sentence is plain text in reading order. It is a heading only when the surface has no other.",
    "The action follows the sentence in reading order."
  ],
  "content": [
    "Say what goes here or why nothing is here.",
    "No 'Oops', no exclamation mark, no 'No data'."
  ],
  "tokens": [
    "--text",
    "--text-muted",
    "--space-2",
    "--space-6",
    "--space-12",
    "--space-16"
  ]
}