# haptics.md

> An open, portable library of haptic feedback patterns with copy-ready code, built for humans and AI coding agents. Each pattern pairs an interaction (tapping a heart, holding a button, confirming a payment) with platform-correct code you can paste straight into an app.

## How to use this

1. Find the pattern that matches the interaction you are building in the index below.
2. Fetch its Markdown at https://haptics.md/haptics/<slug>.md - it has the feel description, the APIs, the minimum OS, and copy-ready code variants (SwiftUI, UIKit, Core Haptics, and more).
3. Paste the variant for your platform. Fire the haptic at the exact moment of the visual change - not before, not after.
4. Want the whole library as one document (every pattern with all its code)? Fetch https://haptics.md/llms-full.txt.

## Rules that keep haptics good

- Match intensity to importance: a light tap for a toggle, a heavier hit for a destructive or success moment. Do not make everything buzz hard.
- Never spam: no haptics per scroll pixel, per keystroke, or inside tight loops.
- Fire once, at the moment of the state change, and never gate app logic on haptic success.
- Respect the OS system-haptics setting. Haptics are a feedback and accessibility channel, delivered with consent.
- Degrade honestly: iOS gives the richest feel (Core Haptics); Android varies by device; the web Vibration API is duration-only and Android-Chrome-only, with nothing on iOS Safari. Never assume a device delivered what you asked for.

## The portable format (.hap.md) and the mission

haptics.md is moving to a portable descriptor: a Markdown file with one fenced `haptic` JSON block - an `intent` semantic token plus a `track` timeline - that compiles to each platform and degrades deterministically. The draft spec is at https://github.com/Bimbi-Digital/haptics.md/blob/main/SPEC.md. The north star is haptic braille for blind and low-vision users: see https://github.com/Bimbi-Digital/haptics.md/blob/main/docs/haptic-braille.md.

## Pattern index

### Foundations

- [Reusable HapticManager](https://haptics.md/haptics/haptic-manager.md): One shared object that prepares generators once and exposes every standard haptic as a single call.
- [Core Haptics engine setup](https://haptics.md/haptics/core-haptics-engine.md): Boilerplate for custom haptic patterns: capability check, engine creation, and auto-restart handlers.
- [SwiftUI .sensoryFeedback cheat sheet](https://haptics.md/haptics/sensoryfeedback-cheatsheet.md): Every built-in SwiftUI feedback value (iOS 17+) in one view, wired to trigger values.
- [UIKit feedback generator cheat sheet](https://haptics.md/haptics/uikit-cheatsheet.md): All three UIFeedbackGenerator families and every style, with the prepare → fire pattern.

### Taps & buttons

- [Tapping a heart / like button](https://haptics.md/haptics/like-heart-tap.md): User taps a heart to like a post; the icon pops and a soft tap confirms it.
- [Primary button press](https://haptics.md/haptics/primary-button.md): A standard call-to-action button ("Continue", "Add to cart") confirms the press.
- [Custom keyboard key press](https://haptics.md/haptics/keyboard-key.md): Each key on a custom keyboard, PIN pad, or calculator gives an instant tick on touch-down.
- [Toggle / switch flip](https://haptics.md/haptics/toggle-switch.md): A settings switch flips on or off with a mechanical click.
- [Tab bar / navigation selection](https://haptics.md/haptics/tab-bar-selection.md): Switching tabs in a custom tab bar gives a subtle tick per change.
- [Checkbox / task completion check](https://haptics.md/haptics/checkbox-check.md): Checking off a to-do item: a light tick on check, and nothing (or lighter) on uncheck.
- [Destructive action (delete)](https://haptics.md/haptics/destructive-delete.md): Confirming a delete: a heavy, unmistakable thud that says "this is significant".

### Press & hold

- [Long press activation (context menu feel)](https://haptics.md/haptics/long-press-activate.md): Holding an element until a context menu or secondary mode activates — the system "pop".
- [Hold-to-confirm with rising tension](https://haptics.md/haptics/hold-to-confirm.md): A "hold 1.5 s to confirm" button: vibration ramps up while holding, success fires at completion.
- [Hold to record (start / stop)](https://haptics.md/haptics/hold-to-record.md): Voice memo style: press starts recording, release stops it. Each boundary gets its own haptic.

### Drag, swipe & scroll

- [Pull-to-refresh threshold](https://haptics.md/haptics/pull-to-refresh.md): The moment a pull gesture crosses the "release to refresh" threshold, plus a success on completion.
- [Drag: pick up and drop](https://haptics.md/haptics/drag-pickup-drop.md): Dragging a card or icon: a soft lift when it detaches, a rigid thud when it lands.
- [Swipe action arming (swipe to archive)](https://haptics.md/haptics/swipe-action-threshold.md): Swiping a row until the action arms ("release to archive") — a tick when it arms and when it disarms.
- [List reorder ticks](https://haptics.md/haptics/list-reorder.md): Dragging a row through a list: one tick every time it displaces a neighbor, plus lift and settle haptics.
- [Textured drag (velocity-driven rumble)](https://haptics.md/haptics/drag-texture.md): Dragging across a surface that should feel textured — the faster the finger moves, the stronger the rumble.

### Pickers, sliders & steppers

- [Picker wheel ticks](https://haptics.md/haptics/picker-wheel-ticks.md): A custom wheel or scrubber that ticks once per row as it spins past values.
- [Slider with snapping detents](https://haptics.md/haptics/slider-detents.md): A slider that snaps to marked stops (0 / 25 / 50 / 75 / 100) and clicks at each detent.
- [Stepper increase / decrease](https://haptics.md/haptics/stepper-increase-decrease.md): Quantity steppers (+ / −): direction-aware feedback so up and down feel different.
- [Rotating dial / ratchet](https://haptics.md/haptics/dial-ratchet.md): A rotary knob (volume, timer) that clicks per step, with sharper clicks at faster spin — Digital-Crown style.
- [Canvas snap to alignment guide](https://haptics.md/haptics/canvas-snap-alignment.md): Dragging an object in an editor until it snaps to a guide, grid line, or another object.
- [Zoom / level change](https://haptics.md/haptics/zoom-level-change.md): Pinch-zoom that steps through discrete levels (1x, 2x, 3x) — a tick per level, camera-app style.

### Outcomes & notifications

- [Success (task completed)](https://haptics.md/haptics/success-feedback.md): A user-initiated task finishes: form submitted, file saved, order placed.
- [Error with shake animation](https://haptics.md/haptics/error-shake.md): Wrong password or invalid input: the field shakes while the error haptic buzzes — the lock-screen pattern.
- [Warning (needs attention)](https://haptics.md/haptics/warning-feedback.md): Something needs attention but is not fatal: low battery in a session, unsaved changes, weak signal.
- [Payment complete (custom double-pulse)](https://haptics.md/haptics/payment-complete.md): An Apple Pay-style confirmation: a soft pre-tap followed by a strong full-body pulse.
- [Connect / charging double thump](https://haptics.md/haptics/device-connect.md): A device pairs, a charger connects, a session links — the MagSafe-style double thump.
- [Countdown 3-2-1-Go](https://haptics.md/haptics/countdown-ticks.md): A workout or recording countdown: a tick per second, then a distinct stronger pattern on "go".

### Custom Core Haptics patterns

- [Heartbeat (lub-dub loop)](https://haptics.md/haptics/heartbeat.md): A health, meditation, or connection feature that plays a realistic looping heartbeat.
- [Drum roll / escalating anticipation](https://haptics.md/haptics/drum-roll-escalation.md): Building suspense before a reveal (prize wheel, match result): ticks accelerate and intensify, then release.
- [Game explosion / heavy collision](https://haptics.md/haptics/game-explosion.md): A game impact: sharp initial crack, then a rumble that decays over half a second.
- [AHAP files (designed patterns as assets)](https://haptics.md/haptics/ahap-file.md): Ship haptic patterns as JSON assets designers can iterate on without recompiling — the standard for game/media haptics.
- [Audio + haptic sync (CoreHaptics audio events)](https://haptics.md/haptics/system-audio-haptic-sync.md): A confirmation that is heard and felt as one event — haptic and sound scheduled on the same clock.