# Empty state

> What a screen says before there is anything on it: what goes here, and the one way to start.

Source: https://kwark.space/designSystem/components/empty-state

## Usage

### What it is
What a module shows before it has anything: what will be here, where it comes from, and one way forward. The specimen is the Breakdown with no scenes, as the app shows it.

### When to use
- A module, list or panel with nothing in it yet.

### When not to use
- For a filter with no results: say *No projects match*, with *Clear filters*.
- For errors: say what happened and what is safe ([Banner](https://kwark.space/designSystem/components/banner.md)).

### Writing
- The heading names what is missing: *No scenes to break down*, not *Nothing here!*.
- One or two sentences on where it will come from. No jokes, no teaching (Decision 0004).
- One action, named for its destination: *Open the screenplay*.

### Moving older code over
`EmptyState.tsx` draws a dashed gray-800 frame, a 32px icon and bold gray text. Kwark’s module pages use the centred, frameless version shown here; the library’s empty shelf is the same idea at a larger size.

## Style

### Anatomy

1. **Block**: centred, at most 420px, 32px 24px padding, no frame.
2. **Heading**: Raleway 400 at `--k-fs-head`, slight negative tracking.
3. **Text**: 14px, line height 1.7, `--k-text-2`.
4. **Action**: one story-surface primary button, 12px under the text.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-line-strong` | var(--k-text-2) | var(--k-text-2) |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-radius-card` | 10px |  |

## Code

### React

In the Kwark app: `import EmptyState from '@/components/ui/EmptyState'`.

```tsx
<EmptyState title="No locations yet"
  description="Locations you add here appear on every call sheet that uses them."
  action={{ label: 'Add location', onClick: add }} />
```

| Prop | Type | Notes |
|---|---|---|
| `title` | `string` |  |
| `description` | `string` |  |
| `action` | `{ label: string; onClick: () => void }` |  |
| `icon` | `LucideIcon` | optional; no illustrations |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-empty"><h3>No scenes to break down</h3><p>The breakdown reads the screenplay as it stands, scene by scene. Once it has scene headings, every one arrives here as a page to mark and a sheet to fill.</p><button class="kw-button kw-button--story kw-button--primary" type="button">Open the screenplay</button></div>
```

## Accessibility

- The title is a heading at the right level for the page.

## For agents

### Rules

- **Must** name what goes here and give exactly one action.
- **Never** use decorative illustrations or jokes in empty states.

### AI readiness test

**Task:** Write the empty Shot list for a project that has scenes but no shots.

**Give the agent:** Empty state, Content and voice.

**Constraint:** Shots can be added per scene.

**A reliable answer:**
- Title "No shots yet"
- Sentence says shots attach to scenes
- One action "Add first shot"
