id: error-state
kind: entry
name: Error State
description: Composition of components shown when content fails to load due to a system error.
purpose: Tells the user something went wrong and gives them a way to retry, instead of leaving a blank or broken surface.

metadata:
  status: {status: stable}
  since: 1.3.0
  tags: [feedback]

refs:
  - to: button
    rel: composes
  - to: empty-state
    rel: alternative-to

sections:
  - kind: guidelines
    for: all
    framing: when-to-use
    title: When to use
    items:
      - statement: A request fails due to a network or server error.
        level: should
      - statement: A list or search genuinely has zero results.
        level: should-not
        refs:
          - to: empty-state
            rel: alternative-to
            note: Zero results is a normal outcome, not a failure - it needs an empty-state message, not a retry action.

  - kind: guidelines
    for: human
    items:
      - statement: Always include a retry action, since the underlying condition is often transient.
        level: must
