Haptic feedback

A semantic vocabulary for haptic feedback — impact, notification, and selection families mapped to UI events — so Koder apps trigger touch feedback consistently and sparingly across platforms, always paired with a visual/audible signal and respecting the OS haptics/reduce-motion setting. Apple HIG parity (Playing Haptics) with an Android mapping.

Status: v0.1.0 — Draft. Promoted from the Apple HIG parity scan (metadocsstack #080). Source: https://developer.apple.com/design/human-interface-guidelines/playing-haptics

R1 — Semantic vocabulary (closed families)

Haptics are chosen by meaning, not by raw waveform:

Family Token Fires when Platform mapping
Impact impact.light / .medium / .heavy / .soft / .rigid A UI element makes contact / a boundary is hit (snap, drag-end) iOS UIImpactFeedbackGenerator; Android VibrationEffect predefined
Notification notify.success / .warning / .error An async outcome resolves iOS UINotificationFeedbackGenerator; Android composed effect
Selection selection.change A discrete value changes during a continuous gesture (picker tick, segment change) iOS UISelectionFeedbackGenerator; Android tick

Components reference the token, never a device-specific pattern.

R2 — Pair with another modality (never sole signal)

Haptics augment — they are never the only feedback for an event. Every haptic accompanies a visual state change (specs/interaction/states.kmd) and/or sound, so users who cannot feel it (no haptics hardware, assistive context) still get the signal (parallels WCAG 1.4.1 for color).

R3 — Use sparingly

  • Reserve haptics for meaningful moments (success/error, snap, selection

    ticks). Do not buzz on every tap — over-use desensitizes and drains battery.

  • One haptic per event; never chain multiple generators for a single

    interaction.

R4 — Respect OS & user settings

  • Honor the OS "System Haptics"/vibration toggle and any in-app haptics

    preference; when off, silently skip (no visual fallback needed — R2 already provides the primary signal).

  • Treat haptics as motion-adjacent: when the platform's reduce-motion /

    reduce-haptics is set, suppress non-essential impacts.

  • Never use haptics to coerce attention (no "nag" buzzes).

R5 — Timing

  • Fire at the moment the event is perceivable (on success resolution,

    on the value tick), synchronized with the paired visual; a haptic that lags its visual reads as a glitch.

R6 — Accessibility

  • Haptics can aid accessibility (a non-visual success cue) but never

    replace an accessible-name/state change.

  • The presence of meaningful haptic feedback is disclosed in the feature's

    specs/accessibility/nutrition-labels.kmd entry.

Não-escopo

  • Custom waveform authoring / Core Haptics AHAP patterns (advanced, later).
  • Game-controller rumble.
  • Audio feedback design (separate).
  • Desktop/web surfaces without haptics hardware (the tokens are no-ops

    there).