# Page loader

> Kwark’s one loader: the page’s own background at once, and a small Kwark mark only if the wait passes 0.4 seconds.

Source: https://kwark.space/designSystem/components/cinematic-loader

## Usage

### What it is
There is no cinematic loader in Kwark, and that is a decision. `SleekLoader` paints the page background at once and shows a 40px Kwark mark only after 0.4 seconds, fading to 55% and breathing slowly. A quick load therefore shows nothing at all. Decision 0012 (no idle curtain) rules out any curtain, title card or animation that stands between a writer and their page.

### When it is allowed
- **Full screen**: opening the app, opening a project before its first data arrives.
- **Small ring**: inside a button while it works (`Button loading`), and in a toast’s progress line.

### When it is not allowed
- Never as a splash with a film leader, countdown, light leak or logo animation.
- Never on a return to a page that is already cached; paint the cached page.
- Never in place of content that can be shown partially: draw what has arrived.

### Writing
The screen-reader text says what is opening: *Opening Blank Pages*, not *Loading…*.

## Style

### Anatomy

1. **Full**: fixed, inset 0, `--k-bg`, the mark centred.
2. **Mark**: 40 × 40px, opacity 0 → 0.55 over 0.6s after a 0.4s delay, then breathing between 0.55 and 0.3 over 2.4s.
3. **Ring**: 16px (`--k-icon-md`), 2px border in `currentColor` with the right side transparent, 70% opacity, one turn in 0.9s.
4. **Reduced motion**: the mark appears without breathing; the ring turns at 2.4s.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-bg` | #f8fafc | #191919 |
| `--k-icon-md` | 16px |  |
| `--k-radius-pill` | 999px |  |

## Code

### React

In the Kwark app: `import { SleekLoader } from '@/shared/SleekLoader'`.

```tsx
<SleekLoader fullScreen text="Opening Blank Pages" />
<Button loading>Save scene</Button>   // uses <SleekLoader small /> inside
```

| Prop | Type | Notes |
|---|---|---|
| `fullScreen` | `boolean` | covers the window in --k-bg |
| `small` | `boolean` | 16px ring for buttons |
| `text` | `string` | read to screen readers only; default "Opening Kwark" |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-pageloader" role="status"><img class="kw-pageloader__mark" src="/img/kwark_logo.svg" alt=""><span class="kw-visually-hidden">Opening Kwark</span></div>
<span class="kw-ring" role="status" aria-label="Saving"></span>
```

## Accessibility

### Keyboard
Not interactive.

### ARIA
- `role="status"` with hidden text naming what is opening. The ring is `role="status"` with an `aria-label`.
- A button that is loading keeps its label and sets `aria-busy="true"`.

## For agents

### Rules

- **Never** add a cinematic splash, film leader or animated title card (Decision 0012).
- **Must** show nothing for the first 0.4 seconds.
- **Always** name what is opening in the screen-reader text.
- **Must** stop breathing under prefers-reduced-motion.

### AI readiness test

**Task:** Design an opening animation for Kwark with a film-leader countdown.

**Give the agent:** This page, Decision 0012.

**Constraint:** The founder asked for something cinematic.

**A reliable answer:**
- Explains that Decision 0012 rules out an idle curtain
- Proposes the existing delayed mark
- Suggests the cinematic feeling belongs in the work (covers, posters) not the wait
