# 7. Motion

DSSL separates *defining* a motion from *running* it. `motion` defines keyframes. `animate:`
runs one on an element. `seen` and states decide when.

## 7.1 Defining a motion

```dssl
motion rise-in {
  from { opacity: 0; translate: 0 18 }
  to   { opacity: 1; translate: 0 0 }
}

motion pulse {
  essential
  0%   { opacity: 1 }
  50%  { opacity: 0.6 }
  100% { opacity: 1 }
}
```

- **MOT-1.** `motion <name> { ... }` is allowed only at the top level. A motion block holds
  keyframe blocks and the word `essential`. Any other declaration is the error `"<prop>" is
  not allowed inside motion`, with the hint `motions take from/to/at blocks and essential`.
- **MOT-2.** A keyframe block header is one of `from` (0), `to` (100), `at N%` or `N%` or
  `N`, or a comma list of these (`0%, 100%`). Every offset MUST be between 0 and 100. A bad
  header is the error `bad keyframe selector "<h>"`.
- **MOT-3.** `essential` (alone, or as `essential: true`) marks the motion as one that keeps
  playing under `prefers-reduced-motion`.
- **MOT-4.** Declarations inside a keyframe are resolved like any other declaration
  (chapter 6) with `prop` set to the source property. Custom properties are dropped. Each
  output property is named in camelCase (`background-color` becomes `backgroundColor`).
- **MOT-5.** In a keyframe, the deform words (`bend`, `bend-y`, `bend-up`, `fold`, `stretch`)
  are not kept as properties. They are composed into one `transform` (8.5), with an extra
  `transformOrigin` for the edge-pinned ones, because there is no box yet when keyframes are
  built. A deform value of 0 is a real reset.
- **MOT-6.** A list header makes one frame per offset with the same properties. The frames of a
  motion are sorted by offset (a stable sort).
- **MOT-7.** The result is `{ essential: bool, frames: [{ offset, props }] }`. A motion block
  is parsed once, the first time it is needed.

## 7.2 Running a motion

`animate: part, part, ...` or `none`. Each part is `name [words]`.

- **MOT-8.** The spec record starts as
  `{ motion: name, duration: 400, easing: smooth, fill: 'both', delay: 0 }`. `smooth` is the
  `cubic-bezier(0.4, 0, 0.2, 1)` easing from appendix A.
- **MOT-9.** Words after the name are read in order:
  - `delay N`, `jitter N`, `iterations N`: the next word is a number with an optional `ms` or
    `s` unit (for `iterations` a plain count). Missing: error `<word> needs a number`.
  - `essential`: sets `essentialHere`.
  - a number with optional unit: the first word after the name is the duration (`s` means
    seconds, otherwise ms); a later one is the delay.
  - an easing name: sets the easing.
  - `both`, `forwards`, `backwards`, `none`, `auto`: the fill mode.
  - `infinite`: iterations is infinity.
  - `alternate`, `alternate-reverse`, `reverse`, `normal`: the direction.
  - anything else: error `unknown animate part "<w>"`, hint = did-you-mean over the easing
    names and the words above.
- **MOT-10.** One part gives one `@animate` declaration. Several parts (a top-level comma)
  give several, in order. `animate: none` gives `@animate: null`.
- **MOT-11.** After the whole file is walked, every `@animate` with a motion name is linked:
  the motion is looked up in this file, then in the motions the host passed in (7.3). If
  found, the spec gets `frames`, and `essential` is true when the motion or the spec says so.
  If not found, the error is `unknown motion "<n>"`, with a did-you-mean over the file's
  motions, or a hint showing how to define one, and the spec is marked `broken`.
- **MOT-12.** Several `@animate` declarations matched by one element all run, in cascade
  order. `@animate: null` from a later rule cancels the ones before it.

## 7.3 Motions across files

- **MOT-13.** The host passes the already-built motions of earlier files to the resolver (the
  motion registry). A motion defined in an earlier file can be used by a later one, like a
  token. A motion in the current file shadows one in the registry.
- **MOT-14.** After resolving, every motion in the file is built (not only the referenced
  ones) and returned as `motionFrames`, for any consumer that wants all of them (the static
  emitter, 11.4).

## 7.4 The animation shorthand

- **MOT-15.** The plain CSS properties `animation` and `animation-name` pass through (PRP-1,
  item 4), with a bare number meaning ms. If a rule has one whose words do not include the
  name of any motion in this file or the registry, the warning is
  `animation "<v>" references no motion defined in this sheet - it will not run`.
- **MOT-16.** `animation-delay`, `-duration`, `-iteration-count`, `-direction`, `-fill-mode`,
  `-timing-function` and `-play-state` do nothing in a rule that has no `animation` or
  `animation-name`. The warning is `<prop> does nothing here: this rule has no CSS animation
  to tune`, with a hint to put the setting in the `animate:` line.

## 7.5 stagger

`stagger: N` on a parent offsets the delay of each element child's animations by
`index * N` ms, where `index` is the child's position among the parent's element children.

- **MOT-17.** The value is a number with optional `ms` or `s`, or `none`. Anything else is the
  error `stagger needs a duration like "60" or "120ms", or "none"`. It writes `@stagger` with
  milliseconds, or `@stagger: null`.

## 7.6 Reduced motion

- **MOT-18.** When the user prefers reduced motion, a motion plays only if it is `essential`
  (by its own flag or by `essential` on the `animate:` line). Others do not run. Textures,
  auras and tilt follow their own rules in chapter 8.