# Sync status

> One quiet word that says whether the work is safe: Saved, Saving…, Saved on this device, Changed elsewhere.

Source: https://kwark.space/designSystem/components/sync-status

## Usage

### What it is
The screenplay keeps one small pill at the corner of the window (`.script-sync-pill`, words from `lifecycleLabel`). It says the state, then steps back: *Up to date* and *Saved* fade out after 2.6 seconds, because a permanent tenant over the page is noise. Anything the writer has to act on stays.

| State | Word | Tone | Stays? |
|---|---|---|---|
| loading | Loading… | quiet | until loaded |
| hydrated | Up to date | quiet | fades after 2.6s |
| modified | Edited | text | yes |
| saving | Saving… | text | yes |
| saved | Saved | quiet | fades after 2.6s |
| offline | Saved on this device | warn | yes |
| unavailable | Not downloaded | warn | yes, with a banner |
| failed | Not saved | danger | yes, with Retry nearby |
| conflict | Changed elsewhere | danger | yes, with a banner |

Pressing Cmd+S always answers in this pill: *Saved* (Decision 0014).

### When to use
- Any screen where people type into the work: screenplay, outline cards, character pages.

### When not to use
- To explain a problem. When the writer must decide something (*Load the newer version* or *Keep mine*), a banner above the editor does that ([Banner](https://kwark.space/designSystem/components/banner.md)); the pill only names the state.
- On forms that save with an explicit button.

### Writing
State first, never blame (Decision 0013). *Saved on this device*, never *Offline* or *Sync failed*. *Not saved* is the only negative word, and only when it is true.

## Style

### Anatomy

1. **Pill**: 3px 9px, 999px corners, 1px `--k-line`, background `color-mix(--k-bg 85%, transparent)`.
2. **Word**: Poppins 500, `--k-text-2`. The app draws it at 10.5px, below the system’s 11px floor; the system sets it at `--k-fs-meta` (12px).
3. **Place**: fixed 16px from the bottom-left on a desktop; on a phone, under the header at the top-right (58px down, 10px in), clear of the dial.
4. **Tones**: warn states take `--k-warn` text and a warn-mixed border; danger states `--k-danger`.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-bg` | #f8fafc | #191919 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-warn` | #8a5a00 | #d8a44a |
| `--k-danger` | #b4382c | #e0685c |
| `--k-radius-pill` | 999px |  |
| `--k-fs-meta` | 12px |  |

## 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-sync-row">
  <span class="kw-sync" data-state="saved" role="status">Saved</span>
  <span class="kw-sync" data-state="saving">Saving…</span>
  <span class="kw-sync" data-state="offline">Saved on this device</span>
  <span class="kw-sync" data-state="conflict">Changed elsewhere</span>
</div>
```

## Accessibility

### Keyboard
Not focusable; it is a status, not a control. Actions for a state live in the banner or the account panel.

### ARIA
- `aria-live="polite"` on the pill so *Saved* is announced once. Do not announce every keystroke’s *Edited*: debounce to the transition into *Saving…* and out of it.
- The fade must not remove the text from the accessibility tree before it is announced; fade with opacity, not `display: none`.

## For agents

### Rules

- **Must** use the lifecycle words: Saved, Saving…, Edited, Saved on this device, Not downloaded, Not saved, Changed elsewhere.
- **Never** write "failed", "error" or "offline" in the pill (Decision 0013).
- **Must** fade only the calm states (Up to date, Saved); keep every state that needs attention.
- **Always** answer Cmd+S with *Saved* here (Decision 0014).
- **Never** put a button in the pill; decisions go in a banner.

### AI readiness test

**Task:** Add a save indicator to the outline card editor.

**Give the agent:** This page, Decisions 0013 and 0014, the Banner page.

**Constraint:** Cards save locally first and reach the cloud later.

**A reliable answer:**
- Shows Saving… then Saved, fading after 2.6s
- Shows Saved on this device when the cloud write is queued
- Never says failed
- Uses a banner, not the pill, for Changed elsewhere
