description	globs
AI Animation + Feedback UX. Standardize how our app visualizes agent thinking, progress, transitions, uncertainty, errors, and feedback loops. Ensure users remain in control, see what the AI is doing, and can steer, stop, or improve it.	app/**/* src/**/* packages/**/* components/**/* ui/**/*

AI Animation + Feedback UX — Project Rules

Goals

• Communicate agent state clearly at all times.
• Reduce perceived latency by streaming and staged reveals.
• Make uncertainty legible and reversible.
• Keep users in control with stop, confirm, and refine paths.
• Capture lightweight feedback to improve future results.

State Model (authoritative)

Implement and reference these canonical states in code, copy, and motion:

1. idle – agent ready, no work in flight.
2. intent_ack – we heard the user, show echo + quick affordances to refine.
3. planning – showing plan-of-action or tool selection preview.
4. executing – doing the thing; may call tools or sub-steps.
5. generating – streaming output visible to user.
6. needs_disambiguation – blocked on missing info; ask a crisp question.
7. success – result delivered; highlight what changed.
8. partial – useful but incomplete; show what’s missing and next step.
9. uncertain – low confidence; reveal caveats and alternatives.
10. error – explain what failed and offer recovery.
11. aborted – user canceled; preserve partials and suggest resume.

Use a small state machine or reducer per agent view. Log transitions.

Motion + Timing Defaults

• Micro-latency mask: If model round-trip < 300 ms, delay spinner to avoid flicker; otherwise show within 150–250 ms.
• Thinking indicator: Prefer animated dots, pulse, or avatar shimmer with status text:
  • planning: “Mapping steps…”
  • executing: “Running step 2 of 5…”
  • generating: stream tokens or chunks as they arrive.
• Streaming: Always stream when possible. Reveal by chunk, not char. Keep layout stable.
• Transitions: Fade/slide between states in 120–180 ms. Easing: standard in/out.
• Focus cues: On needs_disambiguation, pulse the input or card border once, then stop.
• Arrival emphasis: On success, brief 200–300 ms content highlight, then settle.

Justification: staged loading and streaming reduce perceived wait, improve comprehension.

Uncertainty + Confidence

• If you have a score, bucket to {low, medium, high}.
  • Low: soften emphasis, prepend “This might be off,” show 1–2 alternatives.
  • Medium: standard emphasis, include “Verify key details.”
  • High: full emphasis.
• It is acceptable to say “I don’t know.” Provide a next action: refine, search, or human handoff.
• Visually differentiate caveats from content. Do not bury them.

Users calibrate trust when UIs communicate limits and confidence.

Control + Safety

• Every long-running op shows Stop. Stopping transitions to aborted.
• High-impact ops require Confirm plan:
  • Show “Plan of action” as a checklist. Allow edit or deselect steps.
  • Only execute after positive confirmation.
• Provide Refine inline: opens parameters or prompt editor with previous inputs prefilled.
• Always support Undo / Revert for write actions. Show diff before apply, and after apply offer “Undo”.

Start, steer, stop patterns for agent management are familiar and reduce risk.