# Motion

> Motion in Kwark answers something a person did, lasts 120 to 320 milliseconds, eases out, and stops when reduced motion is on. Nothing moves on its own.

Source: https://kwark.space/designSystem/foundations/motion

## Motion answers an action

In Kwark something moves because a person did something: pressed, opened, dragged, scrolled, typed. The movement shows where a thing came from and where it went. It is never there to be looked at.

- **Nothing moves on its own** in the app. No ambient animation, no idle animation, no particles, no parallax, no shimmer on a resting surface.
- **The words never move.** The script, a note, a character's page: text appears where the writer put it, and stays.
- **Motion is short.** A person who is writing should never wait for the interface to finish moving.

Two decisions set this. Decision 0012 removed the idle curtain, which blanked the screen after 60 seconds without input; it would have blanked a pitch or an animatic in a meeting, and it interrupted thinking. Decision 0041 removed the timeline's glow, brightness filter and six rising particles from the current scene, and replaced them with a 2px ring in the project's colour.

> **For agents:** Animate only in response to an input. Use `--k-dur-1` (120ms) for hover and press, `--k-dur-2` (200ms) for opening and toggling, `--k-dur-3` (320ms) for panels and sheets, with `--k-ease`. Never loop an animation in the app except a loader during a real wait. Always remove motion under `prefers-reduced-motion: reduce`.

## Durations and easing

| Token | Value | For | In the app today |
|---|---|---|---|
| `--k-dur-1` | 120ms | Hover, press, a colour or tone change | `IconButton` and `TextButton` hover: `120ms ease` (`system.css`); timeline scene hover |
| `--k-dur-2` | 200ms | Opening a menu, a switch, the dial tucking away and coming back | The dial: `transform 200ms ease, opacity 200ms ease` |
| `--k-dur-3` | 320ms | Panels, drawers, sheets, the scene list opening | The scene list: `width 0.3s cubic-bezier(0.16, 1, 0.3, 1)` |
| `--k-ease` | `cubic-bezier(.2, .7, .2, 1)` | Everything that enters or answers a press: fast at the start, settling at the end | — |
| `--k-ease-in-out` | `cubic-bezier(.65, 0, .35, 1)` | Something moving from one place to another on screen (a card dragged and dropped into place) | — |

These tokens are defined in `kwark.css` on this site. The app does not use them yet: its components write the same durations as literals (120ms, 200ms, 0.3s), and some older surfaces run longer, notably `Modal`, which fades in over 300ms and zooms in over 500ms on a desktop. New code uses the tokens; old code converges when it is touched.

**Why ease out.** Something that answers a press should start at once and slow as it arrives. An ease-in start feels like lag, which is the one thing motion in a writing tool must never feel like.

### Try it

```html
<style>
.kwm-row { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: var(--k-space-3); font: 500 var(--k-fs-meta)/1 var(--k-font-ui); color: var(--k-text-2); }
.kwm-track { position: relative; height: 32px; border-radius: var(--k-radius-control); background: var(--k-raise); }
.kwm-dot { position: absolute; top: 4px; left: 4px; width: 24px; height: 24px; border-radius: var(--k-radius-control); background: var(--k-accent); transition-property: left; }
.kwm-go:checked ~ .kwm-rows .kwm-dot { left: calc(100% - 28px); }
.kwm-1 { transition-duration: var(--k-dur-3); transition-timing-function: var(--k-ease); }
.kwm-2 { transition-duration: var(--k-dur-3); transition-timing-function: var(--k-ease-in-out); }
.kwm-3 { transition-duration: var(--k-dur-3); transition-timing-function: linear; }
.kwm-4 { transition-duration: 800ms; transition-timing-function: ease-in; }
@media (prefers-reduced-motion: reduce) { .kwm-dot { transition-duration: 1ms; } }
</style>
<input class="kwm-go kw-visually-hidden" type="checkbox" id="kwm-go">
<label for="kwm-go" class="kw-button kw-button--primary" style="justify-self:start">Open the panel</label>
<div class="kwm-rows" style="display:grid;gap:var(--k-space-2)">
  <div class="kwm-row"><span>--k-ease, 320ms</span><div class="kwm-track"><span class="kwm-dot kwm-1"></span></div></div>
  <div class="kwm-row"><span>--k-ease-in-out</span><div class="kwm-track"><span class="kwm-dot kwm-2"></span></div></div>
  <div class="kwm-row"><span>linear</span><div class="kwm-track"><span class="kwm-dot kwm-3"></span></div></div>
  <div class="kwm-row"><span>ease-in, 800ms</span><div class="kwm-track"><span class="kwm-dot kwm-4"></span></div></div>
</div>
```

Press the button, then press it again. The first row is Kwark: it leaves at once and settles. The last row is what not to do: it hesitates, then rushes, and takes long enough to notice.

## What moves, and what never does

| Moves | How |
|---|---|
| A hover or press | Tone only (`--k-raise`), `--k-dur-1`. No scale, no lift |
| A menu or popover opening | Appears at once, or fades in `--k-dur-2`. It never slides in from across the screen |
| A bottom sheet | Rises from the foot, `--k-dur-3` |
| A panel or the scene list | Slides open from its own edge, `--k-dur-3`, and the page makes room |
| The phone dial | Tucks off the corner while the writer types or reads down the page (`translateY` plus fade, 200ms) and comes back on the way up |
| A toast | Rises into place, stays, leaves |
| A loader | Only during a real wait, and only after 0.4s (below) |

| Never moves |
|---|
| The script, its line breaks and its page count |
| A resting card, row, cover or poster |
| Anything to attract attention: a pulsing button, a bouncing badge, a shaking field after an error |
| The interface after a period of no input (Decision 0012) |
| Decorative light: glows, particles, shimmer on a finished surface (Decision 0041) |

A skeleton's shimmer (`.kw-skeleton`) is a loader, and is allowed only while content is actually on its way.

## The phone timeline: strip, band and bay

On a phone the screenplay's timeline is three states of one thing (Decision 0007):

- **Strip.** At rest it is a 22px strip under the menu: talk and action in two colours, a 2px mark where you are, a dashed line at the target length. A thumb slid along it shows a loupe with the scene, its time against the target and its length; the page jumps there when the thumb lifts. The loupe follows the finger directly, with no easing: anything else would lag behind the thumb.
- **Band.** A tap on the strip, upright, opens the usual timeline band with a **Fold** button.
- **Bay.** A tap on a phone held sideways opens the timeline full screen, as an edit bay, above the menu bar. Tapping a scene jumps there and folds the bay back; **Back to page** or Escape folds it without moving.

The full band took a quarter of an upright phone and half a sideways one; a side reel was considered and rejected as too thin to tap. Desktops and tablets keep the band unchanged. Not yet tried on a real phone (memory note, 17 October 2026).

## Loading: no splash, no curtain

Kwark used to open with a `CinematicLoader`: a full-screen black curtain for two seconds and an 800ms fade, a floating logo with a blue glow, and a random film quote. The first-run audit measured it as a 2.8-second forced splash on every open, with quotes that joked or taunted, and called it a failure of calm and honesty.

It was removed in October 2026 and replaced by one loader, `SleekLoader` (`shared/SleekLoader.tsx`):

- **Full screen:** the page background at once, and a small 40px Kwark mark only if the wait lasts longer than 0.4s, fading in over 0.6s and then breathing slowly. A quick load shows nothing at all.
- **Small:** a 16px ring in the text colour, for a button that is working.
- **Reduced motion:** the mark appears without breathing; the ring turns at a quarter of the speed.

**When is a cinematic intro allowed?** Not in the app. A branded moment belongs on the marketing site or in a film the writer made, never between a writer and their script. The main checkout still mounts `CinematicLoader` in `App.tsx` as of 16 November 2026; it goes when the integration work merges.

## Reduced motion

When the system asks for reduced motion:

- Transitions and animations finish at once. This site's `kwark.css` sets them to 1ms under `.kw-root` and `[data-room]`; in the app about 50 files carry their own `prefers-reduced-motion` rules (the dial, the loader, the editor).
- Anything that moved to show a relationship (a card sliding into its new act) still ends in the right place; it just does not travel.
- Nothing that carries meaning is lost. If a state was shown only by motion, it was never shown properly; give it a word or a mark.

## Rules

- **Must** answer an input. **Never** start an animation on a timer or on idle.
- **Must** use `--k-dur-1`, `--k-dur-2` or `--k-dur-3`. **Never** exceed 320ms for interface motion.
- **Always** ease out with `--k-ease` for anything entering or answering a press.
- **Never** animate the script's text, its layout or its page count.
- **Never** use a splash screen, a curtain or a forced intro.
- **Always** honour `prefers-reduced-motion`, and test with it on.

**Do:** The scene list slides open from the left over 320ms with `--k-ease`, and the page moves to make room. Under reduced motion it is simply open.

**Don't:** A dialog that zooms in from 95% over 500ms, a card that bounces when dropped, a field that shakes on a wrong password.

## AI readiness test

**Task:** Animate a scene card moving from Act 1 to Act 2 in the outline when the writer drags and drops it.

**Give the agent:** This page, Elevation, the outline's card markup.

**Constraint:** It must feel immediate, and work for a person with reduced motion turned on.

**A reliable answer:**
- The card follows the pointer directly while dragging, with no easing
- On drop it settles into place with --k-ease-in-out over --k-dur-3 or less
- The lifted card uses --k-shadow-pop only while it floats
- Under prefers-reduced-motion it lands in place with no travel
- Nothing else on the page animates
