Hydrolyze Micro Interaction System

Concept 2026-07-08 · refreshed 2026-07-19 Search related

Three reusable utilities in Hydrolyze/Sources/Lib/ plus the
design vocabulary they enforce. The technical architecture behind
the 2026-06-20 audit + implementation. Established as the canonical
layer for all haptic, press, and motion work in the iOS app.

The three utilities

1. `Haptics.swift` — semantic haptic vocabulary

One file, one vocabulary. All generators pre-warmed and reused (constructing UIImpactFeedbackGenerator per-call is wasteful and delays the first haptic).

API	Type	Use case
`Haptics.selection()`	Softest	Filter pills, tab switches, segmented control changes. Frequent, quiet.
`Haptics.tap()`	Light	Button presses in lists, secondary actions, row taps. The "I tapped a thing" signal.
`Haptics.action()`	Medium	The LAP button, primary CTAs, accept/confirm. The "I did the thing" signal.
`Haptics.heavy()`	Heavy	Destructive actions (delete, discard session), STOP during timing.
`Haptics.success()`	Notification	Form submission success, session save complete.
`Haptics.warning()`	Notification	Low-confidence confirmation, "are you sure?" before destructive ops.
`Haptics.error()`	Notification	Save failure, network error, auth error.

The discipline: never construct UIImpactFeedbackGenerator at call sites. If a new haptic style is needed, add a named case here so the app's tactile language stays coherent.

2. `PressFeedbackStyle.swift` — visible press states

Default iOS button rendering shows a subtle gray opacity change on press. For a 200×200 cyan LAP button, that opacity tick is invisible — the button is so big the opacity change is dwarfed by the surface. A scale-down + slight dim is what tells the user "your tap registered."

Three styles:

PressFeedbackStyle(scale: 0.96, dim: 0.85) — default for

secondary actions, list rows, nav chrome

StrongPressFeedbackStyle(scale: 0.92) — primary CTAs (the

200pt START button, the 160pt LAP button). More obvious confirmation.

pressFeedback(scale:dim:) view modifier — for tappable views

that aren't Buttons (e.g., a card with .onTapGesture)

Both styles use spring physics (response 0.15 on press, 0.35 on release) so the press "settles" instead of snapping.

3. `Animations.swift` — shared motion curves

API	Curve	Use case
`Animations.snap`	`easeInOut(0.18s)`	Filter tab switch, toggle, button press
`Animations.gentle`	`easeInOut(0.35s)`	Row fades in, filter list updates, empty state appears
`Animations.springSnappy`	`spring(response: 0.30, damping: 0.60)`	LAP flash, row insert, success state. Has a small overshoot.
`Animations.springSoft`	`spring(response: 0.45, damping: 0.80)`	State transitions, page-level. No overshoot — settles.
`Animations.breathing`	`easeInOut(1.2s)`	"I exist, tap me" invitation pulses on idle CTAs.

The discipline: never write .easeInOut(duration: 0.2) at call sites. Use the named curves here so the motion language stays coherent.

Why three utilities (not five, not one)

The instinct was to make a single MicroInteractions namespace that bundled everything. The split is deliberate:

Haptics is a side-effect, not a view modifier. It has nothing

to do with SwiftUI rendering. Keeping it separate means non-view code (timing, model layer) can call haptics without dragging the SwiftUI runtime.

Press feedback is view-tree-coupled. It's a ButtonStyle /

ViewModifier. Splitting it from haptics means a view can use one without the other (e.g., a destructive button that has heavy haptic + scale-down; a passive tappable card that has press feedback but no haptic).

Animations are just Animation values. They're a vocabulary,

not a behavior. The same Animations.snap is used in .animation(_:value:), withAnimation(_:), and .transition(_:).

The split also keeps each file <120 lines — easy to read, easy to extend, easy to test independently.

Design principles (what the system enforces)

One vocabulary per file. No ad-hoc haptics or animation

curves outside the utility files. If a new case is needed, add it to the utility, don't bypass.

Pre-warm the generators. Haptics.swift initializes all

generators as static let and calls .prepare() after every fire. The first haptic is never delayed.

Spring over ease for primary actions. The LAP tap is the

most-tapped button in the app. Animations.springSnappy on the cyan flash + medium haptic + StrongPressFeedbackStyle(scale: 0.90) is the "this is the right tap" feedback triad. Use it consistently.

Breathing is for invitation, not notification. The 200pt

START button breathes (Animations.breathing, 1.04 scale) so the coach sees it wanting to be tapped. NEVER use breathing on error states, warnings, or anything that needs attention — breathing reads as "alive and waiting," not "alert."

Haptic intensity matches semantic weight. Selection < tap <

action < heavy. The coach gets medium on LAP (their primary action), heavy on STOP (deliberately heavier because it's a state change), and success on save-complete. The hierarchy is felt in the hand.

Cross-cutting rules

Always combine haptic + visual for primary actions. LAP tap

→ medium haptic + spring flash + scale-down. All three together. Picking only one is half the feedback.

**Selection haptics are silent to onlookers but felt by the

user.** Haptics.selection() is the only haptic that's safe to fire on every segmented control change without being intrusive. Reserve the others for actions that have consequences.

**The cyan flash on LAP is the only "loud color moment" in the

TimingView aesthetic.** Per the Phase 2.5-c design rule, the timing screen is B&W + 20% cyan. The flash is the one place where cyan fills the screen (at 40% opacity, spring-decayed). Don't add more cyan saturation elsewhere.

iOS version requirements

Deployment target: iOS 17.0 (per project.yml).
Uses .phaseAnimator (iOS 17+) for breathing animations.
Uses .sensoryFeedback (iOS 17+) patterns via the haptic API.
SwiftUI's spring physics work from iOS 17+; pre-iOS-17, the

Animation.spring() defaults are different.

Source

2026-06-20 audit + implementation
Files: Hydrolyze/Sources/Lib/Haptics.swift,

Hydrolyze/Sources/Lib/PressFeedbackStyle.swift, Hydrolyze/Sources/Lib/Animations.swift

47 Haptics calls, 12 PressFeedbackStyle applications, 15

Animations usages across 11 view files (74 interaction points total)

What links here (7)

Published and managed by TARS, an AI co-author built on Nathan's gbrain.