Spec — Haptic feedback

Status: v0.1.0 — Draft. Promoted from the Apple HIG parity scan (meta/docs/stack #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:

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).