Files
kandev/docs/specs/ui/requirements/persistent-status-motion.md
T
2026-08-28 17:05:03 +00:00

116 lines
5.2 KiB
Markdown

---
status: active
system: ui
created: 2026-08-23
updated: 2026-08-28
owners:
- kandev
---
# Persistent Status Motion Requirements
## Overview
Kandev uses rotating icons to show that tasks, sessions, runs, and agents are active.
These indicators can stay visible for a long time. Their motion must remain
clear without causing continuous main-thread rendering work.
## Terminology
- **Persistent status indicator:** A status icon whose lifetime follows a
task, session, agent, or run state instead of a short UI request.
- **Compositor-prepared motion:** A transform-only animation on an HTML element
that the browser can move to its compositor.
- **Persistent activity animation:** Motion whose lifetime follows ongoing
task, session, agent, or run activity instead of a bounded UI request.
## Requirements
### REQ-UI-PERSISTENT-STATUS-MOTION-001: Efficient persistent rotation
**Intent:** Keep visible working-state motion while avoiding unnecessary idle
CPU use.
**User story:** As a Kandev user, I want active status icons to keep rotating,
so that I can identify ongoing work without high idle CPU use.
#### Acceptance criteria
- **AC-UI-PERSISTENT-STATUS-MOTION-001.1:** When a task, session, agent, or run
has a long-lived active status, the matching indicator shall remain visibly
rotating on desktop and mobile.
- **AC-UI-PERSISTENT-STATUS-MOTION-001.2:** When the active status ends, the
indicator shall stop rotating and the existing next-state icon shall appear.
- **AC-UI-PERSISTENT-STATUS-MOTION-001.3:** While an indicator rotates, the UI
shall animate an HTML transform target and shall not animate the SVG element.
- **AC-UI-PERSISTENT-STATUS-MOTION-001.4:** The change shall preserve each
indicator's size, color, speed, status precedence, accessible meaning, and
test selector.
- **AC-UI-PERSISTENT-STATUS-MOTION-001.5:** The desktop and mobile surfaces
shall use the same status state and motion primitive without horizontal
overflow or a new interaction.
### REQ-UI-PERSISTENT-STATUS-MOTION-002: Efficient grid activity motion
**Intent:** Keep the recognizable grid activity animation while removing its
recurring main-thread rendering cost.
**User story:** As a Kandev user, I want the grid indicator to keep moving while
work is active, so that progress remains recognizable without unnecessary CPU
use.
#### Acceptance criteria
- **AC-UI-PERSISTENT-STATUS-MOTION-002.1:** When a long-lived active state uses
the grid activity indicator, all nine cells shall remain visibly animated in
their existing staggered pattern on desktop and mobile.
- **AC-UI-PERSISTENT-STATUS-MOTION-002.2:** When the active state ends or the
indicator unmounts, its animation shall stop and the existing next state shall
appear.
- **AC-UI-PERSISTENT-STATUS-MOTION-002.3:** In Chromium with Web Animations API
support, a settled grid indicator shall cause no recurring main-thread
`UpdateLayoutTree` or `Layerize` work attributable to its animation targets.
- **AC-UI-PERSISTENT-STATUS-MOTION-002.4:** The optimized indicator shall
preserve its nine-cell geometry, spacing, color, scale range, duration,
stagger, accessible status label, and existing selectors.
- **AC-UI-PERSISTENT-STATUS-MOTION-002.5:** When Web Animations API support is
unavailable, the grid indicator shall retain its current animated CSS
fallback.
### REQ-UI-PERSISTENT-STATUS-MOTION-003: Efficient persistent opacity motion
**Intent:** Keep long-lived glow and pulse feedback visible without sampling
their opacity animations on the main thread.
**User story:** As a Kandev user, I want busy composers and live status dots to
keep pulsing, so that active work remains obvious without high steady CPU use.
#### Acceptance criteria
- **AC-UI-PERSISTENT-STATUS-MOTION-003.1:** While their owning active states
remain true, the task composer glow and persistent status dots shall remain
visibly animated on desktop and mobile.
- **AC-UI-PERSISTENT-STATUS-MOTION-003.2:** When an owning active state ends or
its surface unmounts, the matching opacity animation shall stop and the
existing settled presentation shall appear.
- **AC-UI-PERSISTENT-STATUS-MOTION-003.3:** In Chromium with Web Animations API
support, a settled persistent opacity target shall cause no recurring
main-thread `UpdateLayoutTree` or `Layerize` work attributable to that target.
- **AC-UI-PERSISTENT-STATUS-MOTION-003.4:** The optimized motion shall preserve
the current opacity range, duration, easing, color, glow, geometry, status
precedence, accessible meaning, and test selectors of each migrated surface.
- **AC-UI-PERSISTENT-STATUS-MOTION-003.5:** Desktop and mobile shall use the
same active-state source and opacity-motion primitive without adding a touch
interaction, changing scroll ownership, or causing horizontal overflow.
- **AC-UI-PERSISTENT-STATUS-MOTION-003.6:** When Web Animations API support is
unavailable, each migrated surface shall retain its current animated CSS
fallback and reduced-motion behavior.
## Out of scope
- Removing status motion.
- Changing task, session, or run state rules.
- Changing reduced-motion behavior.
- Migrating one-shot entrance, selection, search, or confirmation cues.
- Changing plugin-owned animations, including Kandy celebration effects.