# Loading

> Kwark keeps the page's frame steady while work arrives, says what it is opening in plain words, shows progress only when it is long enough to matter, and never lets a half-loaded screen save over real work.

Source: https://kwark.space/designSystem/patterns/loading

## The problem

A 1st AD opens the Breakdown on a phone in a basement location with one bar of signal. For several seconds there is nothing. If the screen is blank she wonders whether the scenes are gone; if it shows an empty state ("No scenes yet") she believes it, and may start re-entering them; if it shows a spinner that never resolves she cannot tell slow from broken.

There is a worse failure, and it happened. In September 2026 a phone opened a light project card that had not yet loaded the screenplay, and saved its placeholder over ten real pages. A loading state is not only a matter of patience; a screen that does not know it is loading can destroy work.

## Kwark's answer

### Know the difference between loading and empty

Every screen that fills from the cloud tracks whether it has its data yet. Until it does, it shows the loading state; only when the data has arrived and there is none does it show the empty state. The screenplay makes this explicit with a lifecycle: **Loading…**, then **Up to date**, **Edited**, **Saving…**, **Saved**, or **Not downloaded**.

### Never save from a screen that has not loaded

An unhydrated project (no screenplay on the device and the cloud unreachable) opens **read-only and never saves**. The banner says: "This screenplay has not downloaded to this device. Nothing will be saved until it does, so the copy elsewhere stays exactly as it is." with **Try again**. This is the rule that closed the placeholder-overwrite bug.

### Say what is opening, in the module's own words

Production screens say what they are waiting for, in a quiet line where the content will appear:

- "Opening the script…" (Breakdown, Shots & Boards)
- "Opening the desk…" (department desks, Camera & Light)
- "Opening the board…" (Research boards, character notes)
- "Loading projects" (Home's accessible label while the library arrives)

The line names the thing, not the machinery. It does not say "Fetching data" or "Please wait".

### Keep the frame steady

The header, the breadcrumb or one-line phone header, and the module's tools render at once. Only the content area waits. When content arrives it fills the space the loading state held, so nothing jumps. Where the shape is known and the wait is likely to be noticeable (a list of story cards, a page of script), a skeleton in that shape holds the place; it is never used for less than about half a second of waiting, or it flashes.

### Long work shows progress

Work that takes seconds and has a measurable end shows a progress toast that stays until done:

- Import: "Importing {project}: {n}%", then "Saved locally · cloud sync queued" or "Import needs attention".
- Export: the export dialog says **Exporting…** on its button and "Ready to export" before you start.
- A spinner with words, such as "Preparing print preview", for work with no measurable end.

### Settle, then step back

A status that is good news is worth a glance, not a permanent tenant. **Up to date** and **Saved** show, then step back after about 2.6 seconds. Anything the person must act on stays.

### Load less

Heavy parts load only when used: the three-dimensional storyboard figures are a separate chunk loaded when the Boards view opens, and the 2D fallback draws meanwhile. Every listener is shared across modules, and lists are not re-read to redraw (see [Review and quality](https://kwark.space/designSystem/method/review-and-quality.md)). The fastest loading state is the one that is never shown.

## Anatomy

| Part | Use | Never |
|---|---|---|
| Quiet line ("Opening the script…") | Most module content, short waits | As a permanent footer |
| Skeleton (`kw-skeleton`) | Known shapes, waits over about half a second | Under half a second; for things of unknown shape |
| Spinner with words (`kw-spinner`) | Work with no measurable end, inside a button or a small area | Alone, without words; full screen |
| Progress toast (`kw-toast--progress`) | Import, export, uploads: anything with a count or a percentage | For ordinary saving |
| Busy button (`aria-busy`) | The action the person just pressed | Changing its label to something unrelated |
| Not downloaded banner | The screen cannot load and will not save | As an error toast |

## Rules

- **Must** track loaded versus empty separately, and never show an empty state before the data has arrived.
- **Must** open a project read-only, and never save, when its screenplay has not reached the device.
- **Must** render the header and tools at once; only the content waits.
- **Must** name what is opening in the module's words.
- **Must** show progress, with a number, for imports, exports and uploads.
- **Never** show a full-screen spinner, a splash screen or an idle curtain. The idle curtain that blanked the screen after 60 seconds was removed (Decision 0012).
- **Never** show a spinner without words.
- **Never** animate a skeleton under `prefers-reduced-motion`; it stays still.
- **Always** let "Saved" and "Up to date" step back on their own.
- **Always** keep the person's place when content arrives: scroll position, selection, focus.

## Edge cases

- **Slow but working.** After about ten seconds, the quiet line may add the state: "Opening the script… This is taking longer than usual. Your work is safe."
- **Cloud unreachable, data on the device.** Open from the device at once; the sync word says "Saved on this device".
- **Cloud unreachable, nothing on the device.** The Not downloaded banner, read-only, **Try again**.
- **Part of a page loads.** A call sheet with its schedule but not its locations shows the sheet with the missing block marked, never blank fields that look like real blanks.
- **A sample project.** Ships inside the app, so looking needs no account and no network (Decision 0035, part 2).
- **Import interrupted.** "Import needs attention" with the reason; what was imported stays.

## Phone and desktop

The same states. On a phone the quiet line sits where the first card would be, under the one-line header, and the progress toast sits above the floating button. A long import on a phone keeps running if the screen locks, and says on return how far it got.

## Writing

- Name the thing: "Opening the script…", "Opening the desk…", "Opening the board…".
- Use the ellipsis character for work in progress: "Saving…", "Exporting…".
- Progress: "Importing Blank Pages: 64%", "48 of 112 pages".
- No "Please wait", "Hang tight", "Loading data", or jokes.

## Accessibility

- The loading area carries `aria-busy="true"`; skeleton shapes are `aria-hidden`.
- The quiet line is in a polite live region, so a screen reader hears what is opening once.
- Progress uses a native `progress` element with a label, or `role="progressbar"` with `aria-valuenow`.
- Focus is not moved by content arriving, unless the person asked for it (opening a scene).

**Do:** "Opening the script…" in the content area, with the header and tools already in place.

**Don't:** A blank white screen with a centred spinner, then "No scenes yet" for a second before the scenes arrive.

**Do:** A project that has not downloaded opens read-only with the banner and **Try again**.

**Don't:** A project that has not downloaded opens an empty editor that autosaves.

## Demo

```html
<div class="kw-card" aria-busy="true" style="width:100%;max-width:440px;display:grid;gap:8px"><span class="kw-meta" aria-live="polite">Opening the desk…</span><div class="kw-skeleton" style="height:40px" aria-hidden="true"></div><div class="kw-skeleton" style="height:40px" aria-hidden="true"></div><div class="kw-skeleton kw-skeleton--short" style="height:40px" aria-hidden="true"></div></div>
<span role="status" style="display:inline-flex;gap:8px;align-items:center"><span class="kw-spinner" aria-hidden="true"></span>Preparing print preview</span>
<button class="kw-button kw-button--primary" type="button" aria-busy="true"><span class="kw-spinner" aria-hidden="true"></span>Exporting…</button>
<div class="kw-toast kw-toast--info kw-toast--progress" role="status"><label>Exporting the screenplay <progress value="48" max="112"></progress></label><span class="kw-meta">48 of 112 pages</span></div>
```

## Related

[Skeleton](https://kwark.space/designSystem/components/skeleton.md), [Spinner](https://kwark.space/designSystem/components/spinner.md), [Progress](https://kwark.space/designSystem/components/progress.md), [Toast](https://kwark.space/designSystem/components/toast.md), [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md), [Empty states](https://kwark.space/designSystem/patterns/empty-states.md), [Motion](https://kwark.space/designSystem/foundations/motion.md).

## AI readiness test

**Task:** The Budget shows "No budget lines yet" for a second before lines appear.

**Give the agent:** This page, Empty states, Saving and sync.

**Constraint:** No new listeners.

**A reliable answer:**
- Adds a loaded flag so the empty state shows only after data has arrived
- Shows "Opening the budget…" or a skeleton of rows in the content area, with the header in place
- Ensures nothing saves until loaded
- Keeps the skeleton still under reduced motion
