# Progress and loading

> Shows how much of a known job is done, in a bar and in figures: pages exported, folders imported. Kwark’s is the 2px bar of the import toast, with each folder on its own line.

Source: https://kwark.space/designSystem/components/progress

## Usage

### What it is
A bar and a sentence for work that can be measured: pages exported, folders imported, frames rendered. The figures matter more than the bar. *48 of 112 pages* tells a writer whether to wait or make tea; a bar alone does not.

### Which one
| Form | Status | Use |
|---|---|---|
| Bar with figures | In the app (`UploadProgressToast`) | One job with a known total: *Exporting the screenplay · 48 of 112 pages* |
| Import toast | In the app | A multi-part import: each folder on its line, its own percentage, a summary foot |
| Segmented bar | Ready for Kwark | A known number of parts that finish one by one: five folders, three reels |
| Working bar | Ready for Kwark | A step with no measurable amount inside a measured flow; prefer the [spinner](https://kwark.space/designSystem/components/spinner.md) on its own |
| Queued | In the app | Saved here, cloud part waiting: the bar fills in `--k-warn`, the words say so |

### Saved here, sent later
Kwark saves to the device first. An import that is complete here but waiting for the cloud is **not** an error: the bar is full, in the warn colour, and says *Saved on this device · Cloud sync queued* (Decision 0013). Green means it is in the cloud too.

### Timing
- Under a second: nothing. One to four: a [skeleton](https://kwark.space/designSystem/components/skeleton.md) or [spinner](https://kwark.space/designSystem/components/spinner.md). Longer with a total: this.
- Never block the screenplay. Exports and imports run in a toast while people keep writing.
- When it finishes, the toast says what happened and offers the next step: *Screenplay exported · Open*.

## Style

### Anatomy

1. **Bar**: 2px (`h-0.5`), 3px in a standalone block, `--k-line` track, fill in `--k-accent-soft`; `--k-ok` when done; `--k-warn` when queued or partly failed; width eases over `--k-dur-3`.
2. **Label row**: what is happening on the left (Poppins 500 12px), the figures on the right in tabular `--k-text-2` (*48 of 112 pages*).
3. **Segments**: 4px tall, 3px gaps, one per part; done parts in `--k-ok`, the active one filled to its percentage, queued at 55% `--k-warn`.
4. **Import toast**: up to 320px, `--k-surface`, 1px line, 10px corners, `--k-shadow-pop`; head with a 14px glyph, the title and a 26px minimise; the overall bar across its full width; folder rows (12px) with a tick, a tabular percentage, *Queued* in warn, or a dash; a 12px foot.
5. **Working bar**: a 32% fill that slides across in 1.4s; under reduced motion it holds full width at 45% opacity.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-ok` | #2c6e49 | #6cc08a |
| `--k-warn` | #8a5a00 | #d8a44a |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) |
| `--k-radius-card` | 10px |  |
| `--k-fs-meta` | 12px |  |
| `--k-ease-in-out` | cubic-bezier(.65, 0, .35, 1) |  |
| `--k-dur-3` | 320ms |  |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Exporting the screenplay</span><span>48 of 112 pages</span></div>
  <div class="kw-progress" role="progressbar" aria-valuenow="48" aria-valuemin="0" aria-valuemax="112" aria-valuetext="48 of 112 pages" aria-label="Exporting the screenplay"><span style="width:43%"></span></div>
</div>
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Importing Blank Pages</span><span>3 of 5 folders</span></div>
  <div class="kw-progress-segs" role="progressbar" aria-valuenow="3" aria-valuemin="0" aria-valuemax="5" aria-valuetext="3 of 5 folders, Screenplay at 60%, Schedule queued" aria-label="Importing Blank Pages"><span data-state="done"></span><span data-state="done"></span><span style="--kw-seg:60%"></span><span data-state="queued"></span><span></span></div>
</div>
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Checking the cloud copy</span><span>Usually a few seconds</span></div>
  <div class="kw-progress" data-state="working" role="progressbar" aria-label="Checking the cloud copy" aria-valuetext="Working"><span></span></div>
</div>
<div class="kw-upload" role="status">
  <div class="kw-upload__head"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3v12M17 8l-5-5-5 5M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/></svg><span>Importing project</span><button class="kw-icon-button" type="button" aria-label="Minimise import progress"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m18 15-6-6-6 6"/></svg></button></div>
  <div class="kw-progress" role="progressbar" aria-valuenow="64" aria-valuemin="0" aria-valuemax="100" aria-label="Importing Blank Pages: 64%"><span style="width:64%"></span></div>
  <ul class="kw-upload__list">
    <li data-state="done"><span>Characters</span><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.8 10A10 10 0 1 1 17 3.3"/><path d="m9 11 3 3L22 4"/></svg></li>
    <li data-state="done"><span>Outline</span><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.8 10A10 10 0 1 1 17 3.3"/><path d="m9 11 3 3L22 4"/></svg></li>
    <li data-state="uploading"><span>Screenplay</span><b>60%</b><div class="kw-progress"><span style="width:60%"></span></div></li>
    <li data-state="queued"><span>Breakdown</span><b>Queued</b></li>
    <li data-state="pending"><span>Schedule</span><b>–</b></li>
  </ul>
  <div class="kw-upload__foot">2/5 folders · syncing Screenplay</div>
</div>
<div class="kw-progress-block">
  <div class="kw-meter-row"><span>Saved on this device</span><span>Cloud sync queued</span></div>
  <div class="kw-progress" data-state="queued" role="progressbar" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100" aria-label="Import saved on this device, cloud sync queued"><span style="width:100%"></span></div>
</div>
```

The import toast in the app is `components/ui/UploadProgressToast.tsx`: a 2px overall bar (`h-0.5`), a folder list where each folder shows a dash while pending, a percentage while uploading (with its own 2px bar), *Queued* when the cloud part is waiting, and a tick when done; and a foot that reads *2/5 folders · syncing Screenplay*. The segmented bar and the indeterminate bar on this page are Ready for Kwark additions on the same 2px language.

## Accessibility

### ARIA
- `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` in the same words as the label: *48 of 112 pages*.
- The working bar has no value; its `aria-valuetext` is *Working*.
- The toast is `role="status"`. Announce the start and the end, and at most every 25%, never every percent.

### Keyboard
- The minimise button is reachable and named; the toast never takes focus on its own.
- When an import finishes with failures, the foot says how many and how to retry (*1 failed. Reopen import to retry.*), and that text is announced.

## For agents

### Rules

- **Must** give progress in figures as well as a bar: "48 of 112 pages", "2/5 folders".
- **Never** block the screenplay with progress; run it in a toast while people keep working.
- **Must** show "saved on this device, cloud sync queued" in the warn colour with words, never as an error.
- **Never** show progress for work under a second, and announce at most every quarter.
- **Always** end with what happened and the next step ("Screenplay exported · Open").

### AI readiness test

**Task:** Show progress while 112 pages export to PDF.

**Give the agent:** This page, Print and export, Toast.

**Constraint:** The writer keeps typing; the export may finish offline.

**A reliable answer:**
- Non-blocking toast with "Exporting the screenplay · 48 of 112 pages"
- aria-valuetext in the same words
- Announces at most every 25%
- Ends with "Screenplay exported" and Open
- Not a full-screen spinner
