rebreak-monorepo/docs/RIVE_ANIMATOR_BRIEF.md

Rive Animator Brief — Lyra Avatar Emotion States

Ready-to-publish — copy section between the dividers below into your job-post on Dribbble / Fiverr / Twitter / Rive Discord.

---

🎯 Project: Rebreak — Lyra Avatar Animation

I'm hiring a Rive-animator to extend Lyra, the AI-companion of Rebreak — a recovery app for people working through gambling addiction (German market, planned DiGA-listing in healthcare).

Critical context: This is a sensitive recovery-app, NOT a playful game. Lyra is a warm, present companion — never cute-mascot, never childish, never dramatic. Subtle > exaggerated.

Budget: $100 USD, ~1 week target. Self-qualify before applying.

What I have (current .riv)

• File: lyra-avatar.riv (264 KB) — will be shared after engagement-confirmation
• Artboard name: Artboard
• State machine name: State Machine 1, default state idle
• Existing animation timelines (extracted via strings):
  • Idle Loop — wired as idle
  • idle to Pose 1 + Pose 1 loop — wired as happy (2-phase: app manually switches via 900ms JS-timer)
  • 01 Wave 1 — wired as empathy
  • 01 Wave 2 — exists, NOT wired (orphan)
  • WALK — placeholder, currently aliased as thinking (please replace with proper thinking-pose animation)
  • Kedip (Indonesian "blink") — orphan from template
• Runtime: rive-react-native ^9.0.1 (export against this compatible Rive editor version)
• Avatar usage: appears at 40px (small list), 112px (chat-header), 160px (onboarding hero) — must read clearly even at 40px

⚠️ Critical naming contract — do NOT rename existing names

The React code calls timelines directly by name (not via state-machine inputs). If you rename a timeline, the app silently breaks (no animation plays, no error). This means:

• Keep: Artboard artboard, State Machine 1 SM-name, idle default-state, Idle Loop timeline name
• New emotion-states must use exactly these timeline names (snake_case): sad, joy, confusion, calm, surprise, listening, thinking (replacing WALK)
• For multi-phase emotions (e.g. dramatic intro → loop): use <state> intro + <state> loop pattern, just like existing idle to Pose 1 + Pose 1 loop
• Bonus (+$X if you propose): expose state-machine inputs (SetEmotion enum-trigger) so we can transition imperatively. Optional — named-timelines remain the primary contract.

Deliverables — emotion states

You'll add these to the existing state-machine. Total: 6 new states + 1 placeholder-replacement (thinking).

Tier 1 — must-have (4 states, baseline budget)

Internal name (timeline)	Trigger in app	Eyes	Brow	Mouth	Body
thinking (REPLACE WALK)	LLM is generating response	look up-and-to-side, slow blink	one slightly raised	gently closed, slight pursed	finger-near-temple pose if possible, head tilt ~5°
listening	User mid-typing OR voice-recording	open, attentive, natural blink	neutral relaxed	gently closed, micro-Mona-Lisa upturn	subtle head nod every ~3s
calm	Breathing exercise / meditation active	half-closed	neutral relaxed	slight serene smile	very slow up/down breathing loop (~4s cycle to match 4-7-8 breathing pace)
sad	User describes loss/relapse/shame	softened, slight downcast, lower lid raised	inner-up, slight angle	closed, neutral or micro-downturn	tiny head tilt down (~5°), slow breathing

Tier 2 — nice-to-have (2-3 more states, push budget if you can)

Internal name (timeline)	Trigger in app	Visual direction
joy	Streak milestone, big celebration	bigger smile than happy (warmer not goofy), small head bounce on intro then settle
confusion	Lyra needs clarification	one brow raised, slight squint, head tilt ~10° to one side
surprise	Unexpected user input	wide-open eyes (brief), both brows raised, small "o" mouth, quick head pull-back micro on intro then settle

Skip these (anti-patterns for recovery use-case)

• ❌ angry / frustrated — never from coach
• ❌ shocked / horror — too dramatic for trauma-context
• ❌ Cute-mascot expressions (winks, tongue-out, hearts in eyes)
• ❌ Heavy bone-rigs / particles — runtime cost too high

Visual style guidelines

• Match existing Lyra-look (extract palette + line-weight from the .riv you'll receive)
• Subtle is better — these animations play during emotional moments, they should support not demand attention
• Loop-friendly — idle, calm, listening should breathe naturally, no pop on loop boundary
• Smooth transitions — prefer 200-400ms crossfades over hard cuts. Especially: empathy → idle → happy should never feel jarring (route through idle, never direct jump from negative to positive)
• Readability at 40px — exaggerate eye/brow shapes slightly, avoid mouth-only emotion (mouth is too small at 40px to carry expression)

Technical Requirements

• Output: ONE .riv file named exactly lyra-avatar.riv (replaces current file)
• Single artboard, single state-machine — preserve existing structure
• Rive editor version: 2024.x (compatible with rive-react-native ^9.0.1)
• Performance: 60 fps target on mid-range Android (Pixel 5-class)
• File-size: ≤500KB (current 264KB, want headroom for new states)
• Loop-cycle precision: calm should be ~4 seconds (we sync app-side to user's 4-7-8 breathing exercise)

Bonus task (optional, +scope)

Existing happy uses a 2-phase manual switch via 900ms JS-timeout — clunky. If you can fix this so it loops cleanly inside the .riv itself (intro auto-blends into loop without app-side coordination), that's worth +$X.

Timeline + Budget

• $100 USD flat, paid: 50% on first-draft approval, 50% on final delivery
• 1 week from brief-confirmation
• Milestones:
  1. Day 0: brief-confirm + you receive .riv file + answers to your questions
  2. Day 2-3: first draft of 1-2 states for visual-direction approval (style-confirm)
  3. Day 4-6: remaining states + 1 round of revisions
  4. Day 7: final delivery

Deliverables you provide

1. lyra-avatar.riv — replaces existing file
2. Short README (1 page max):
   • List of all timeline-names + when each plays
   • Any limitations or known issues
   • State-machine diagram (simple)
3. Source-file (Rive editor .rev or equivalent) for future edits
4. Optional bonus: short demo-video (15-30 sec) showing all states cycling — earns trust

Questions to ask BEFORE starting (please answer in your application)

1. Can I use the current .riv as a base and add states, or do you want a clean rebuild?
2. Confirm Rive runtime version (rive-react-native ^9.0.1) — compatible with your export?
3. Should I also fix the existing happy 2-phase JS-timer (auto-blend in .riv instead)?
4. For the German market: any culture-specific gestures to avoid?
5. Any brand-colors / hex-codes I must match?
6. Audio cues or visual-only?
7. Do you have Figma / brand-guide I should reference?

What I value in your work

• Restraint over flashiness
• Clean state-machine architecture (other devs may extend later)
• Honest communication if scope is too tight for budget — happy to scope down to 4 states (Tier 1 only)
• Async-first (Slack-like / email / Discord-DM)

How to apply

Send me:

1. Link to Rive portfolio (not Lottie, not After-Effects — actual .riv work)
2. Confirmation you've read this brief (so I know it's not auto-applied)
3. Your suggested approach: extend existing state-machine OR rebuild?
4. Your answers to the 7 questions above

Looking forward to working together.

---

End of brief — copy everything above into your job-post.

How to use this brief (internal — not for animator)

1. Vor dem Senden alle [Platzhalter]-Stellen (insbesondere Communication-Channel falls du das spezifizieren willst) ausfüllen
2. Aktuelle .riv mitschicken — Animator braucht sie als Style-Referenz + State-Machine-Setup
3. Klarstellen: Emotion-Namen in der Tabelle sind Code-Contracts und müssen exakt so im Rive-File heißen — sonst muss React-Code refactored werden
4. Vor Vergabe 2-3 Animator-Portfolios checken — suche „warm/subtle character"-style, NICHT nur knallige Logo-Animationen
5. Nach Erhalt der ersten Draft auf echtem Android-Mid-Range-Gerät testen (Pixel 5 oder älter), nicht nur iOS-Simulator
6. Wo publishen (in Reihenfolge der Wahrscheinlichkeit):
   • Rive Discord (https://rive.app/community → Discord) — Rive-spezialisierte Animatoren, keine LottieFiles-Refugees
   • Twitter #RiveAnimation hashtag + DMs an Animator-Portfolios die du gut findest
   • Fiverr „Rive animator" custom-offers ($30-150 typische Gigs)
   • Dribbble „Hiring" section — gemischte Quality, mehr Style-fokus
7. Wenn .riv ankommt: drag in apps/rebreak-native/assets/lyra-avatar.riv (overwrite), commit, fertig. Code ist schon flexibel (RiveAvatar accepts any state-name nach Task #39 component-flex).

Sources / Internal-Files

• Brief-Audit: apps/rebreak-native/components/RiveAvatar.tsx (lines 42-51 — Emotion-API contract)
• Existing .riv: apps/rebreak-native/assets/lyra-avatar.riv (264 KB)
• Plugin: apps/rebreak-native/plugins/with-rive-asset-android.js (Android raw-resource auto-mirror)
• Trigger-context: apps/rebreak-native/app/lyra.tsx (lines 37-44, 306-323), apps/rebreak-native/app/urge.tsx, apps/rebreak-native/lib/lyraResponse.ts:57-61 (existing detectEmotion())