# District Companion motion specification

This document describes the prototype motion language. Advance production state from real service events; only perceptual transitions and finite expression timing should remain time-based.

## Principles

- Shape and motion communicate state before colour.
- The companion is a flat 190-unit circular face on a 240 × 240 canvas, with pupil-free capsule eyes.
- Open-eye states share an uneven 7.3-second blink cycle. Suppress it during deliberate closed-eye expressions.
- Light purple is reserved for attention, output, progress, and success.
- The character has no mouth, ears, pupils, eyebrows, gradients, metallic treatment, or head indentation.
- The underlying District screen remains usable while the companion is expanded or working.

## State motion

| State | Motion | Prototype timing |
|---|---|---:|
| Waking | Eyes open from compact rest | 850 ms, finite |
| Ready | Gentle body breath and eye drift | 4.8 s / 5.4 s loops |
| Listening | Body pulse and inward signals | 1.1 s loop |
| Acknowledged | Synchronous perk and wink | 650 ms, finite |
| Thinking / Searching | Thinking beats, eye scan, or search orbit | 1.35 s / 2.2 s / 3.2 s loops |
| Clarification | Attentive hold and question ring | 2.4 s / 1.7 s loops |
| Awaiting confirmation | Steady, low-motion attention | 2.5 s loop |
| Taking action | Directional progress trace | 1.45 s loop |
| Speaking | Alternating output waves, glow, and body beat | 1.8 s loop |
| Completed | Short success lift and ring | 900 ms / 1.2 s, finite |
| Completion residue | Subtle orbit after returning to ready | 8 s loop |

## Reduced motion

When the platform’s reduce-motion preference is enabled:

- Remove looping breath, drift, pulse, orbit, scan, wave, and blink.
- Render the readable end pose for the current state.
- Preserve state labels, progress copy, and non-colour signals.
- Cross-fades may remain only when allowed by the platform accessibility guidance.

## Transition guidance

- Morph body and eye geometry over roughly 300–400 ms with an ease-out curve.
- Use finite receipt expressions for Waking, Acknowledged, and Completed; never leave them looping.
- Keep the completion pose for about 1.5 seconds, then return to Ready with a subtle residual marker.
- Do not use prototype search, speech, or action timers as production completion signals.