# Motion kit: usage

Owner: Site role. Files: `resources/css/site/motion.css` (in `site.css`) and `resources/js/site/motion.js` (run from `site.js` on every page). Tokens: `resources/css/site/tokens.css`. Nothing depends on ids; any number of each hook per page works.

## States (read this first)

| `<html>` class | When | What CSS does |
|---|---|---|
| `motion` | JS on, motion allowed | Scenes pin (`.scrub` gets `--stage-h + --travel` height, `.stage` sticky); `[data-lit]` starts at `--v:0` and brightens. |
| none | JS off, or `prefers-reduced-motion` | Scenes are plain stacked sections; `--v` is `1` (everything lit); `--p/--a/--b/--k` stay `0`. **Write the scene so it reads at `--p:0`, or add a static fallback under `:root:not(.motion)`.** |
| `motion-forced` | URL hash `#rest`, `#mid`, `#end` | QA aid: every scene and statement frozen at p = 0 / .5 / 1, no pinning. |

Continuous animations (`.grad`, `.vis`, `.chip`, `.fword`) get `.kit-off` (paused) while off-screen, and stop under reduced motion. Only animate `transform`, `opacity`, `clip-path`, background/mask position.

Tokens most used: `--night`, `--night-2`, `--ink`, `--soft` (body text), `--dim` (large/decorative only), `--line`, `--mint`, `--teal`, `--gold`, `--red`, `--on-mint` (text on mint), `--shot-shadow`, `--stage-h`, `--section-y`, `--container`, `--text-statement`, `--text-lead`, `--text-eyebrow`. Shared UI classes (in `site/components.css`): `.btn .btn--primary` (mint), `.btn .btn--ghost` (white outline), `.eyebrow`, `.shot` (white frame + mint glow).

## Hooks

### Pinned scene `.scrub[data-scrub]`
```html
<section class="scrub my-scene" data-scrub style="--travel:1300px" aria-label="...">
  <div class="stage">
    <h2 class="my-title">...</h2>
    <img class="my-pic" ...>
  </div>
</section>
```
```css
.my-pic { transform: translateY(calc(40% - var(--a) * 40%)); }       /* --p 0..1, --a first 55%, --b last 45% */
.my-title { opacity: calc(1 - var(--b) * 3); }
:root:not(.motion) .my-scene .stage { padding-block: var(--section-y); } /* static fallback if absolutely positioned */
```
The stage has no height until `.motion`; set positioning for the pinned state under `.motion .my-scene ...` when the layout differs.

### Viewport progress `[data-lit]`
```html
<div class="my-thing" data-lit>...</div>   <!-- --v: 0..1 as it enters (1 without motion) -->
```

### Lighting statement `.lit[data-lit]`
```html
<h2 class="lit" data-lit>Your success is our <span class="hi">priority</span></h2>   <!-- .lit.wide = 26ch -->
```
Words become spans (`--i`, `--n`); `.hi` words are mint. Links inside are not split.

### Statement + moving picture `.duo`
```html
<div class="duo" data-lit>                 <!-- .duo.flip puts the picture first; one column at <=760px -->
  <div class="txt"><p class="lit" data-lit>...</p></div>
  <div class="vis tilt"><div class="shot"><x-media.img .../></div>
    <span class="chip" style="--x:-4%;--y:6%;--dx:-90px;--dy:-60px;--t:0s"><img src="icon.webp" alt=""></span>
  </div>
</div>
```
Picture motions (the `--v` comes from the parent `.duo[data-lit]`):
- `.vis.tilt > .shot > img` (+ optional `.chip` floating icons)
- `.vis.reveal > .win > img + i.sweep` (shutter open, slow zoom, light sweep)
- `.vis.slide > img` (devices glide in and float)
- `.vis.orbit` (icons orbit a hub):
```html
<div class="vis orbit" role="img" aria-label="...">
  <div class="ring r2"><span class="sat" style="--ang:20deg;--off:70deg"><span class="oc"><i><img src="a.webp" alt=""></i></span></span>...</div>
  <div class="ring r1"><span class="sat" style="--ang:75deg;--off:-60deg"><span class="oc"><i><img src="b.webp" alt=""></i></span></span>...</div>
  <div class="hub"><b></b><b></b><b></b><span><img src="hub.webp" alt=""></span></div>
</div>
```

### 3D turning screens `.deck` (inside a `.scrub`)
```html
<section class="scrub" data-scrub style="--travel:1300px"><div class="stage">
  <div class="deck-big"><h2 style="--i:0">Credit Leads</h2><h2 style="--i:1">Test Drive Calendar</h2></div>  <!-- any element: span or heading -->
  <div class="deck my-deck">
    <figure class="c" style="--i:0"><img ...></figure>
    <figure class="c" style="--i:1"><img ...></figure>
  </div>
  <div class="deck-desc"><div style="--i:0">Text... <a href="...">Read more</a></div><div style="--i:1">...</div></div>
</div></section>
```
JS sets `--k` (0 .. cards-1) on the section. Give the deck a height in the pinned state (`.motion .my-deck { height: 44%; }` or a fixed height); without motion the cards, titles and descriptions are plain stacked blocks (style that layout yourself, e.g. a grid). Links in descriptions are only focusable while their description is showing.

### Sliding lines `.row[data-lit]`
```html
<div class="rows"><div class="row" data-lit><h3>24/7 Support</h3><p>We are available 24/7...</p></div>...</div>
```
The h2/h3/h4 inside the row (directly or in a wrapper, e.g. with a small number label) is the oversized line (even rows mint, sliding the other way); the `p` is the description.

### Living light `.grad`
```html
<div class="grad" aria-hidden="true"><i class="g1"></i><i class="g2"></i><i class="g3"></i><i class="g4"></i>
  <span class="trail" style="top:22%;--c:#00d8c1;--d:3.8s;--w:-.4s"></span>...</div>
```
Absolutely fills its positioned parent. On phones `g4` and trails 4+ are hidden and blur is lighter.

### SVG-mask hero `.mask-hero` + `[data-zoom]`
```html
<svg class="mask-hero" aria-hidden="true" focusable="false"><defs>
  <mask id="mk-{{ $uid }}" maskUnits="userSpaceOnUse" x="0" y="0" width="100%" height="100%">
    <rect width="100%" height="100%" fill="#fff"/>
    <text data-zoom data-zoom-char="8" x="50%" y="46%" text-anchor="middle" dominant-baseline="central" fill="#000">DEALERSHIP</text>
  </mask></defs><rect width="100%" height="100%" fill="#050d0b" mask="url(#mk-{{ $uid }})"/></svg>
```
The mask id must be unique on the page (e.g. `Str::random(6)`). Inside a `.scrub`, `[data-zoom]` scales up to `1 + a³·95` (or `data-zoom="40"` for a different max) into letter `data-zoom-char` (0-based; default the middle). Font size: `--ws` on an ancestor. Keep the real heading text in the DOM (the SVG is decorative).

### Footer wordmark `.fword`
Used once in the footer (Site). `<div class="fword" data-lit aria-hidden="true"><span class="fo">iDealers</span><span class="fg">iDealers</span></div>`.

### Counter `[data-count]`
`<div data-count="500">+500</div>` counts 0 → 500 once in view, keeping "+". Static with reduced motion or no JS.
