/design

Haptic Design

Designing a haptic vocabulary — semantic, distinct, and centrally owned — rather than sprinkling generator calls through views.

API Decision Table

Rule of thumb: the moment you catch yourself choosing between .success and .impact(weight:) for game events, you've outgrown presets — build a Core Haptics vocabulary.

The Semantic-Vocabulary Architecture

One central service owns the engine; game code speaks in meanings, never in patterns:

enum HapticEvent {
    case start          // round/session begins
    case correct        // success tap
    case pass           // skip / failure tap
    case reveal         // content shown (card, letter, dare)
    case timerPulse     // gentle urgency (e.g. 10s left)
    case timerUrgent    // hard urgency (e.g. 5s left)
    case stop           // the signature interrupt (music stop, freeze, catch)
    case roundEnd       // round complete, score committed
    case winner         // the rarest, biggest pattern
}

@MainActor @Observable
final class HapticsService {
    private var engine: CHHapticEngine?
    private let supportsHaptics =
        CHHapticEngine.capabilitiesForHardware().supportsHaptics

    func fire(_ event: HapticEvent) {
        guard supportsHaptics else { return }          // silent no-op on Simulator/iPad
        startEngineIfNeeded()                          // lazy start on first use
        // build CHHapticPattern from events(for: event), play it
    }
}

Architecture rules (each prevents a real failure):

• Lazy engine start on first fire, not in init — engine start is not free and may race app launch.
• Capability-gate once (capabilitiesForHardware().supportsHaptics) so every call site can fire blindly; no availability checks leak into views.
• Handle stoppedHandler / resetHandler by nulling the engine so the next fire restarts it — the system stops engines freely (audio interruptions, thermal).
• Stop the engine on background (scenePhase change) and let lazy-start recover on foreground — a running engine in background wastes power and can be killed out from under you.
• Inject as an optional seam (haptics: HapticsService? = nil in stores/engines) — unit tests pass nil; previews pass a throwaway.
• Views get it via @Environment; only stores/engines fire game events (see single-owner rule in SKILL.md).

Vocabulary Design Rules

1. Name events by meaning, not by pattern — .correct, not .doubleTapLight. The pattern can be retuned later without touching call sites.
2. Signature moments get signature patterns. The freeze/stop moment of a music game, the spin of a wheel, the winner — each needs its own event. Reusing .roundEnd for the winner erases the climax (rarity gradient, SKILL.md).
3. Escalation tiers are pattern pairs — .timerPulse and .timerUrgent should be the same shape at different intensity/sharpness so they read as "the same thing, more urgent", and their thresholds must match the visual escalation exactly.
4. Continuous events for continuous moments. A spin deserves a .hapticContinuous with an intensity ramp (parameter curves), not repeated transients. Transients are for instants.
5. Cover every event in the domain, then stop. Draw up the event×channel matrix (feedback-audit.md) first; if an event isn't in the matrix, it doesn't get a haptic.

Pattern Sketches (starting points, tune on device)

Pitfalls

❌ Double-fire

Engine fires on "music stopped" and the store fires on the same state change → user feels a stutter-buzz. One owner per event.

❌ Preset semantics for game events

UINotificationFeedbackGenerator().notificationOccurred(.success) for a winner — it's the same buzz every form in iOS uses. Signature moments deserve custom patterns.

❌ No user toggle

Core Haptics ignores any system setting — there is no global "haptics off" that covers you. Ship a settings toggle; store it in the service, not in every call site.

❌ Testing feel in the Simulator

The Simulator plays no haptics at all. Pattern code can be unit-tested (event → pattern mapping), but intensity/sharpness tuning is device-only work — schedule it.

✅ Do

Centralize; speak semantics; gate once; tune the rarest events to be the biggest; give users an off switch.

References

• HIG — Playing haptics
• Core Haptics documentation
• CHHapticEngine