Interaction contract · prototype v1

A voice-first companion developers can inspect, replay, and implement.

One reference for the companion’s ten conversation states, independent capability conditions, action-safety rules, transitions, timing, native boundaries, and downloadable Lottie animations.

Open interactive prototype Download complete package

Deterministic product reference. No live microphone, speech model, navigation, or app-action API is included.

01 / 15 resting

Sleeping Closed-eye entry pose before activation.

Motion gallery

Every orb state, rendered from the handoff JSON

Select any animation to replay it at full size. The set covers ten conversation states, activity and surface variants, and independent microphone and completion conditions.

Implementation model

Conversation is only one axis

Do not encode permission, capture, keyboard, or surface visibility into the conversation enum. Those conditions change independently.

Conversation

Waking → ready → listening → acknowledged → thinking → result, clarification, or confirmation.

conversationState

Microphone

Permission and Mic on/off are distinct. Bot audio can remain available while capture is off.

permission + micEnabled

Surface

The orb persists across app pages, stays draggable in every state, and is clamped inside the visible screen. The first tap activates it; the next reveals independent circular actions around it. The orb shifts inward near an edge so every action remains reachable. No companion overlay exists.

resting | active | actions

Input

Voice leads. Keyboard and Dialogue are entry-point events whose native destinations remain intentionally deferred.

mic + keyboard + dialogue

Default sequence

From entry to resolution

Safe search path

1ReadyPrompt
2ListeningCapture
3Got itReceipt
4SearchingResolve
5SpeakingOutput

Consequential actions

Preview before committing

Purchases, bookings, cancellations, and account changes stop at awaiting-confirmation. Show the exact action and material consequence before proceeding.

Interruption

The screen never locks

District remains usable while the companion works. Speech output can be interrupted by voice or tap; app actions should only stop from an explicit tap.

Partial completion

Report committed work honestly

Never imply an external side effect was undone. Keep committed steps, cancel only future steps, then ask what the user wants to do next.

Developer package

Platform-neutral source files

The ZIP contains the same individual files below. Treat the Swift model as implementation guidance, then connect it to District’s production voice and action systems. Two Lottie sets ship side by side — V1 canonical and the V2 precision build — compare them live before choosing.

district-companion-handoff.zip Complete package · contract, Swift, SVG, motion notes, and both Lottie sets district-companion-lottie.zip V1 canonical set · 15 Lottie JSON files, manifest, and native integration guide district-companion-lottie-v2-dark.zip V2 precision set · dark mode, light-purple eyes · 15 Lottie JSON files and manifest district-companion-lottie-v2-light.zip V2 precision set · light mode, black eyes · 15 Lottie JSON files and manifest district-companion-lottie-v2.zip V2 precision set · both eye variants (30 files) and manifest

JSON Lottie manifest (V1)Files, state mapping, loop behavior, reduced-motion frames, and color keypaths. JSON Lottie manifest (V2)Per-theme file paths for both eye variants, palettes, baked opacities, and color keypaths. MD Lottie integration guideNative playback, precedence, theming, and regeneration guidance. JSON State contractStates, events, conditions, timing, and sample action steps. SWIFT Native reference typesCodable enums, state snapshot, action steps, and timing constants. SVG Vector state spriteReusable symbols for all ten pupil-free face poses. MD Motion specificationDurations, loops, reduced-motion behavior, and transition guidance. MD Integration guideBoundaries, recommended architecture, and implementation checklist.