# FLAKK MOTION SPEC 1.0 (part of the Design Bible, 19.11.2026)

Applies to: Flakk staff app (phone + desktop console), Flakk Guest, flakk.app, the EXEs. The CSS half lives in 92hg's `flakk-motion.css` / `flakk-motion.js` (web apps) and `flakk-motion-web.css/js` (site); this document is what they must implement. Nothing moves by browser default.

## 0. Laws

1. Only `transform` and `opacity` animate. Never width, height, top, left, margin, padding, box-shadow, filter, clip-path, background-position. Colour transitions (background-color, color, border-color) are allowed at 160 ms linear only.
2. No transform on a container that has `position: fixed` children (the dock and sheets are siblings of the content host, never inside a transformed parent).
3. Every motion has both directions proven (enter and exit, open and close, activate and deactivate) and is interruptible: a reversed gesture reverses from the current frame, never jumps.
4. Frame-time gate (iPhone 13 viewport, Chromium 4× CPU throttle): p50 ≤ 17 ms, < 5 % of frames > 34 ms for every choreography below. Recordings go to the review gate.
5. Reduced motion (`prefers-reduced-motion: reduce`): decorative loops stop (orb idle drift, skeleton shimmer, heartbeat pulse); state changes keep a 120 ms opacity fade; travel distances become 0; springs become linear. Tested both ways.
6. Nothing bounces more than once. Overshoot peaks ≤ 6 % (release ≤ 8 %) and settles within the duration.
7. Total choreography never exceeds 880 ms; a stagger never delays the last item more than 200 ms after the first.

## 1. Curves and durations (tokens)

| Token | Value | Feel | Use |
|---|---|---|---|
| `--fkm-spring-snappy` | linear() spring, response 0.40 s, damping 0.82, peak 1.014 | crisp | presses, tab icon, check tick, switch knob (0.34,1.56,.64,1 fallback) |
| `--fkm-spring-smooth` | response 0.55 s, damping 1.0 | settled | screen enter, sheet grow, list reflow |
| `--fkm-spring-gentle` | response 0.88 s, damping 0.72, peak 1.038 | soft | orb idle↔active morph, guest home orb appear |
| `--fkm-spring-release` | response 0.41 s, damping 0.62, peak 1.08 | elastic | drag drop, pull-to-refresh release, hold ring release |
| `--fkm-ease-out` | cubic-bezier(.22,1,.36,1) | | fades in |
| `--fkm-ease-in` | cubic-bezier(.55,0,.75,.2) | | fades out |
| `--fkm-fast-ms` 140 · `--fkm-snappy-ms` 400 · `--fkm-smooth-ms` 550 · `--fkm-gentle-ms` 880 · `--fkm-stagger-ms` 24 | | | |
| press scale `.96` (controls ≤ 56 px tall), `.94` (big objects: key card, orb hold, ledger stat tap) | | | |

92hg's current values (404/552/879/406, snappy peak 1.014, gentle 1.038, release 1.082) satisfy this; keep them.

## 2. Presses

- Buttons, rows, nav items, checks: on pointerdown scale to .96 (big objects .94) in 90 ms ease-out; on pointerup spring back with `snappy` (400 ms, peak 1.014). Cancelled press (pointer leaves) springs back the same way. No ripple, no colour flash, no shadow change.
- Dock tab: the icon scales .90 on press and springs back; the 44 px disc grows from scale .6 → 1 with `snappy` on selection and fades 160 ms out on deselection. The previously selected icon loses its amber in 160 ms linear.
- Text action (`.fk-action`): opacity .6 on press, back in 160 ms; no scale.

## 3. Tab switches (the content host)

- View Transition on `.fk-host` only; dock and page stay live. Forward (index increases): old host → opacity 0 + translateX(−24 px) + scale .985 in 140 ms ease-in; new host from opacity 0 + translateX(32 px) + scale .985 → identity in 550 ms `smooth`. Back = mirrored. Same-tab (reselect) = none.
- Direction "orb": when the agent changes the tab, the new host grows from the orb (transform-origin at the orb's centre relative to the host): scale .82 → 1, opacity 0 → 1, 550 ms `smooth`; old host fades 140 ms.
- Within the new host, the first 6 blocks (context, hero, lede, ledger, first two sections) stagger 24 ms each, each from opacity 0 + translateY(8 px). Items after the 6th appear with the 6th.
- Desktop sidebar switch: same host transition, travel 16 px instead of 24/32.
- Reduced motion: 120 ms cross-fade.

## 4. Sheets, panels, toasts: orb-origin present and dismiss

- Present: the scrim fades 0 → 1 in 220 ms ease-out. The sheet's transform-origin is the orb centre (CSS vars `--fk-orb-x/--fk-orb-y`, set by the motion layer from the orb's bounding box). The sheet goes scale .82 → 1 and opacity 0 → 1 over 550 ms `smooth`, and translateY(24 px) → 0 on phone. While the sheet is open the orb morphs to "active" (gentle, 880 ms) and the belt tucks (see §6).
- Dismiss (tap scrim, swipe down past 30 % height or 600 px/s, close action): the reverse at 400 ms with `--fkm-ease-in` on opacity; the sheet shrinks back toward the orb; the orb morphs back to idle; the belt returns.
- Drag to dismiss: the sheet follows the finger 1:1 (translateY only); below the threshold it springs back with `release`; above it continues the dismiss from the current frame.
- Desktop panel: slides from the right edge translateX(40 px) + opacity, 400 ms `smooth`; dismiss 260 ms. The orb in the sidebar still morphs.
- Toast: from the orb, scale .9 + opacity 0 → 1 in 400 ms `snappy`; holds 2.4 s; leaves by fading toward the orb in 260 ms. Never two toasts; the second replaces the first in place.

## 5. Lists

- Reflow (an item removed, a filter applied): remaining items FLIP with `smooth` 400 ms; the removed item fades + scale .96 in 180 ms. Never collapse height with a height animation; the FLIP of neighbours is the motion.
- New item (a message arrives): inserts at opacity 0 + translateY(−8 px) → identity, 400 ms `snappy`; the row below FLIPs down. A row that gets an unread dot: the dot scales 0 → 1 with `snappy`.
- Pull to refresh (phone): content follows 1:2 up to 72 px; release springs back with `release`; the orb's heartbeat quickens (see §8) while loading instead of a spinner.
- Skeleton: appears only after 180 ms, 200 ms fade in; content replaces it with a 160 ms fade and no height change.
- Scroll: native only. No scroll-linked animation, no parallax, no sticky headers that change size.

## 6. Dock: belt tuck and return (7jmp/92hg, confirmed)

- Activate: the two halves retract toward the orb with translate + scaleX(.1) + opacity, 480 ms, right half 30 ms behind the left; tab icons fade in the first third with a 40 ms stagger. The orb scales 1 → 1.3 with `gentle` and morphs idle → active.
- Deactivate: the mirror, from the current frame. Nothing fades in place; the belt always slides.
- Desktop (≥ 900): the sidebar has no belt; the orb morphs and the nav dims to .55 opacity in 160 ms.

## 7. Guest-specific choreographies

- Guest home first open: the orb appears scale .6 → 1 with `gentle` (880 ms), then the greeting line fades up 8 px at 300 ms, the faint sentence at 420 ms, the key card at 560 ms, the stay card at 640 ms. Total under 880 ms + 550.
- Check-in step: the question host slides as a forward tab switch; the selected choice row's amber disc grows with `snappy`; Continue is enabled with a 160 ms colour transition.
- Flakk Key hold ring: on hold start the arc draws from 0 to 100 % over 600 ms linear (dasharray/dashoffset is allowed here: it is a 160 px stroke, one element); the key icon scales .94; at 100 % the ring fills amber (opacity 0 → 1 in 120 ms), the icon springs 1.06 → 1 with `release`, the row status changes to "Unlocked 14:58". Release before 100 %: the arc rewinds at 2× speed. After unlock the ring fades back to its idle state over 1.2 s.
- Key ended (exact check-out): the navy card cross-fades to linen over 550 ms, the ring fades out, the text changes in place.

## 8. The orb (one particle system, amber + navy only)

- Idle (basic): slow drift, ≤ 1 % position noise, 6 s period; stops under reduced motion.
- Active (evolved): denser particle field, 1.3× scale in the dock buckle, morph from idle over 880 ms `gentle`; never a crossfade between two orbs.
- Heartbeat: scale 1 → 1 + 0.06 × loudness, driven by the real output audio envelope, 60 fps, attack 40 ms, release 180 ms; under reduced motion the pulse is replaced by a 2 % opacity breathing at 1 Hz while speaking.
- Gestures (one pointer state machine, owned by 7jmp): tap = voice; hold ≥ 450 ms = text chat (the orb squashes to .94 at 0 ms and the sheet grows at 450 ms); drag = the AI editor (the orb follows the finger with a 60 ms lag spring, halo appears under valid targets); double-tap never opens text. Each gesture's visual starts within one frame of the pointer event.
- Thinking: particle speed 1.6×, no spinner anywhere else in the app.

## 9. flakk.app site

- Above the fold: the orb only. Headline words fade up 8 px with 24 ms stagger on first paint; nothing else animates on load.
- Scroll reveals: sections fade up 12 px once, 550 ms `smooth`, threshold 20 % visible; never re-animate on scroll back.
- Hover (pointer: fine): rows amber-wash in 160 ms; buttons scale 1.02 with `snappy`; links no underline animation.

## 10. Success, warning and error motion

- Success in place: the pressed button's label cross-fades to the result ("Sent") in 160 ms; a 14 px tick draws over 260 ms (dashoffset) 60 ms later; the button turns navy in 160 ms; after 1.2 s the row updates (FLIP) and the button returns or disappears. Haptic: success, once, at the moment the tick starts.
- Warning (a field needs attention): the field's rule turns `--fk-warn` in 160 ms and the help line fades in; no shake.
- Error: the sentence replaces the content with a 160 ms fade. Nothing shakes, nothing flashes red. Haptic: error, once.

## 11. Numbers in motion

- A ledger number that changes counts from old to new over 400 ms with `--fkm-ease-out` (tabular during the count, proportional after). Bars scale their `transform: scaleX` from old to new with `smooth`.
- The hero date at midnight cross-fades (opacity) over 550 ms; it never slides.

## 12. Gate recordings

Each builder delivers, per screen: a 390 × 844 WebKit recording and a 1440 × 900 Chromium recording of every choreography on the screen (press, tab switch forward + back, sheet open + close, list change, success), plus the frame-time json from the gate script (`flakk_design_check` ≥ 1.6 adds `--motion`). See REVIEW-GATE.md.
