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

One rule: **one tick per intention, felt once, never noisy.** Haptics confirm what the hand did; they never decorate, never announce, never repeat.

## 1. The map

| Intention | Kind | iOS native (UIKit) | Web fallback (`flakk-haptics.js`) | Where |
|---|---|---|---|---|
| tap on a control | `light` | `UIImpactFeedbackGenerator(.light)` | vibrate 8 ms / 1 switch tick | secondary buttons, rows that open something, text actions |
| selection change | `selection` | `UISelectionFeedbackGenerator.selectionChanged()` | vibrate 6 ms / 1 tick | dock tab switch, sidebar item, radio choice, switch, check toggled on |
| primary action started | `medium` | `UIImpactFeedbackGenerator(.medium)` | vibrate 14 ms / 1 tick | the amber button, Send, Save, Start, Check in |
| confirm / success | `success` | `UINotificationFeedbackGenerator(.success)` | 10-60-18 ms / 2 ticks | fired by the app's own success path only (payment link sent, room ready, unlocked, checked in) |
| warning | `warning` | `UINotificationFeedbackGenerator(.warning)` | 18-90-18 ms / 2 ticks | a destructive sheet opens; a field blocks Continue |
| error | `error` | `UINotificationFeedbackGenerator(.error)` | 24-50-24-50-24 ms / 3 ticks | the app's own error path (declined, failed to send, lock refused) |
| long-press / hold start | `medium` | `.medium` at hold recognition (450 ms) | 14 ms | orb hold → text chat, row hold → context sheet |
| hold complete | `heavy` then `success` | `UIImpactFeedbackGenerator(.heavy)` at 100 %, `.success` when the door reports open | 24 ms then success pattern | Flakk Key ring; hold-to-confirm ink button |
| drag pick-up | `medium` | `.medium` | 14 ms | orb drag (AI editor), row reorder |
| drag over a valid target | `selection` | selectionChanged, once per target | 6 ms | orb halo over a target |
| drag drop | `light` on cancel, `success` on a valid drop | `.light` / `.success` | 8 ms / success pattern | |
| orb activate (tap → voice) | `soft` | `UIImpactFeedbackGenerator(.soft)` | 8 ms | the one place `soft` is used |
| orb deactivate | none | | | |
| toast appears | none | | | the eye sees it; the hand did nothing |
| navigation back, scroll, pull-to-refresh pull, list reflow, skeleton → content | none | | | |
| pull-to-refresh release past threshold | `light` | `.light` | 8 ms | once |

Intensity: native generators at default intensity; `impactOccurred(intensity:)` 0.7 for `light` inside lists (a long list tapped many times must stay quiet).

## 2. Laws

1. One intention, one tick. A tap that is both a selection and a primary action fires only the stronger one (`medium`). The engine's 45 ms same-kind debounce stays.
2. Success and error come from the app's own result path, never from the press. If the result arrives in under 120 ms, the success tick waits until the tick animation starts (MOTION §10) so eye and hand agree.
3. Never more than one `error` per 2 s; never more than one `success` per 600 ms.
4. Nothing ticks while the orb is speaking except `selection` (so a user can still switch tabs) and `error`.
5. Nothing ticks on screens with no hand (desktop, EXEs, screen readers' synthetic clicks: `isTrusted === false`).
6. The "Vibration" switch (Setup) turns everything off, including native; the switch itself fires `success` once when turned on (already so in flakk-haptics.js).
7. Flakk Guest: the same map; plus the key ring is the only place with a ramp (hold start → heavy → success).

## 3. Flakk Key ring (the one choreography with three ticks)

hold start at 0 ms → `medium` · arc reaches 100 % at 600 ms → `heavy` · lock reports open (network, typically 200-900 ms later) → `success` and the row changes to "Unlocked 14:58". Release before 100 % → no tick (the arc rewinds). Lock refuses → `error` once and the sentence "The door did not open. Try again or ask the front desk."

## 4. Native bridge contract (m7zw, `window.flakkNative`)

m7zw's facade already exposes `haptics.success()` (CAPABILITY-MATRIX "haptics incl. success tick: yes"). The bible fixes the full surface so the web engine can route to it:

```ts
interface FlakkNativeHaptics {
  impact(style: 'light' | 'medium' | 'heavy' | 'soft' | 'rigid', intensity?: number): Promise<void>;
  notification(type: 'success' | 'warning' | 'error'): Promise<void>;
  selection(): Promise<void>;
  success(): Promise<void>;          // = notification('success'), kept for compatibility
  prepare?(): void;                  // calls generator.prepare() before a hold/drag starts
}
// window.flakkNative?.haptics
```

Mapping: `light/medium/heavy/soft → impact(style)`, `selection → selection()`, `success/warning/error → notification(type)`. The generators are created once per kind and `prepare()`d on pointerdown of the orb and the key ring so the first tick has no latency.

## 5. Web engine routing (`flakk-haptics.js` 1.1, owner: the lane that owns haptics; change list for the builder)

```js
function fire(kind) {
  if (!kind || kind === 'none' || !on()) return false;
  if (now - last < 45 && kind === lastKind) return false;
  var N = window.flakkNative && window.flakkNative.haptics;
  if (N) {                                        // native first
    try {
      if (kind === 'selection') N.selection();
      else if (kind === 'success' || kind === 'warning' || kind === 'error') N.notification(kind);
      else N.impact(kind);                        // light | medium | heavy | soft
      return true;
    } catch (e) { /* fall through */ }
  }
  if (VIB) return N_vibrate(PAT[kind] || PAT.light);  // Android / Chrome
  if (SW) { tick(TICKS[kind] || 1); return true; }    // iPhone Safari switch tick
  return false;
}
```

Add `soft: 8` to PAT and `soft: 1` to TICKS. Add `data-haptic="soft"` on the orb button, `data-haptic="none"` on every list row that only opens detail unless the row is a selection (then `selection`). The click-map stays calm by default: only mapped controls tick. Dock tabs move from `light` to `selection`.

Audit of today's state: `flakk-haptics.js` 1.0 maps tabs to `light` (change to `selection`), has no native route (add §5), no `soft` (add). 7jmp's staged confirm haptic in `fai-staff.js` / `bookings-core.js` must fire from the success callback, not from the press (gate checks the call site).

## 6. Gate deliverable: the haptic map per screen

Each builder screen comes with a table: control → kind → trigger (press | success path | error path | hold | drag) → file:line. The reviewer checks every row against §1 and §2; a screen with a tick on scroll, on back, on toast, or two ticks for one tap fails.
