zeroclock/docs/plans/2026-02-18-motion-system-design.md

ZeroClock Motion System Design

Personality

Fluid & organic: spring-based easing with slight overshoot, 200-350ms durations for primary animations, 100-150ms for micro-interactions. The app should feel alive and responsive without being distracting.

Technology

@vueuse/motion for declarative spring-physics animations via v-motion directives and useMotion() composable. Vue's built-in <Transition> and <TransitionGroup> for enter/leave orchestration. CSS keyframes for ambient/looping animations (pulse, shimmer, float).

Spring Presets

Define reusable spring configs in a src/utils/motion.ts module:

• snappy: { damping: 20, stiffness: 300 } — buttons, toggles, small elements
• smooth: { damping: 15, stiffness: 200 } — page transitions, modals, cards
• popIn: { damping: 12, stiffness: 400 } — tag chips, badges, notifications

1. Page Transitions

Wrap <router-view> in App.vue with <router-view v-slot="{ Component }"> + <Transition>:

• Leave: opacity 1 -> 0, translateY 0 -> -8px, 150ms ease-out
• Enter: opacity 0 -> 1, translateY 8px -> 0, spring smooth preset
• Mode: out-in to prevent layout overlap in the flex container

CSS classes: .page-enter-active, .page-leave-active, .page-enter-from, .page-leave-to

2. List Animations

Entry rows, project cards, client cards

Use <TransitionGroup> with staggered enter:

• Enter: opacity 0 -> 1, translateY 12px -> 0, spring smooth, stagger 30ms per item (via transition-delay computed from index)
• Leave: opacity 1 -> 0, translateX 0 -> -20px, 150ms ease-in
• Move: transition: transform 300ms cubic-bezier(0.22, 1, 0.36, 1) for reorder

CSS classes: .list-enter-active, .list-leave-active, .list-move, .list-enter-from, .list-leave-to

Tag chips

• Enter: scale 0.8 -> 1, opacity 0 -> 1, spring popIn
• Leave: scale 1 -> 0.8, opacity 1 -> 0, 100ms

Favorites strip pills

• Enter: translateX -10px -> 0, opacity 0 -> 1, stagger 50ms
• Leave: scale 1 -> 0, opacity 0, 100ms

Recent entries in Timer

• Enter: opacity 0 -> 1, translateX -8px -> 0, stagger 40ms

3. Button & Interactive Feedback

Primary buttons (Start/Stop, Generate, Save, Import)

• :hover — scale(1.02), subtle shadow lift, spring snappy
• :active — scale(0.97), shadow compress, instant (no delay)
• Release — spring back to scale(1) via snappy preset

Icon buttons (edit, delete, copy, star, repeat)

• :active — scale(0.85), spring back
• Delete icons: rotate(-10deg) on active for a "shake" feel

Nav rail active indicator

Currently the left border appears instantly. Change to:

• Slide the 2px accent bar vertically to match the new active item position
• Use a dedicated <div> with v-motion and absolute positioning keyed to currentPath
• Spring smooth preset

Toggle switches

• Add cubic-bezier(0.34, 1.56, 0.64, 1) (overshoot) to the thumb's transition-transform
• Duration: 200ms (up from 150ms)

Project/client cards

• :hover — translateY(-1px), shadow elevation increase, 200ms
• :active — translateY(0), shadow compress

Accent color picker dots in Settings

• Selected dot: scale(1.15) with spring
• Hover: scale(1.1)

4. Loading & Empty States

Skeleton shimmer

New CSS keyframe shimmer: a gradient highlight sweeping left-to-right on placeholder blocks. Apply via .skeleton utility class.

@keyframes shimmer {
  0% { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}

Content fade-in

When data loads (entries, projects, reports), wrap the content area in a <Transition>:

• opacity: 0 -> 1, translateY: 4px -> 0, spring smooth
• Show skeleton while loading ref is true, transition to real content

Empty state icons

Add gentle vertical float animation to the empty state icons (Timer, BarChart3):

@keyframes float {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-4px); }
}

Duration: 3s, ease-in-out, infinite.

5. Modal & Dropdown Polish

Modals

Replace animate-modal-enter keyframe with spring-based:

• Backdrop enter: opacity 0 -> 1, 200ms ease-out
• Backdrop leave: opacity 1 -> 0, 150ms ease-in
• Panel enter: scale 0.95 -> 1, opacity 0 -> 1, spring smooth
• Panel leave: scale 1 -> 0.97, opacity 1 -> 0, 150ms ease-in

Use Vue <Transition> on the modal's v-if to get proper leave animations (currently missing — modals just vanish).

Dropdowns (AppSelect, AppTagInput, AppDatePicker)

Replace animate-dropdown-enter with spring:

• Enter: scale 0.95 -> 1, opacity 0 -> 1, translateY -4px -> 0, spring snappy
• Leave: opacity 1 -> 0, 100ms (fast close)

Toast notifications

Keep existing enter/exit keyframes but add slight horizontal slide:

• Enter: translateY -20px -> 0, translateX 10px -> 0 (slide from top-right)
• Exit: opacity fade + translateY -10px

6. Timer-Specific Animations

Timer start

When the timer transitions from STOPPED to RUNNING:

• The time display pulses once (scale 1 -> 1.03 -> 1) via spring
• The Start button morphs to Stop (color transition already exists, add scale pulse)

Timer stop

When the timer stops:

• Brief "completed" flash — the time display gets a subtle glow/highlight that fades

Progress bars (goals, budgets)

• Animate width from 0 to target value on mount, 600ms with spring smooth
• Use CSS transition: width 600ms cubic-bezier(0.22, 1, 0.36, 1)

Files to Modify

• package.json — add @vueuse/motion
• src/main.ts — register MotionPlugin
• src/utils/motion.ts — new, spring preset definitions
• src/styles/main.css — new keyframes (shimmer, float), update existing keyframes, add transition utility classes
• src/App.vue — page transition wrapper on <router-view>
• src/components/NavRail.vue — animated active indicator
• src/components/AppSelect.vue — dropdown leave animation
• src/components/AppTagInput.vue — tag chip enter/leave transitions
• src/components/ToastNotification.vue — enhanced enter/exit
• src/views/Timer.vue — timer start/stop animations, list transition on recent entries
• src/views/Entries.vue — TransitionGroup on entry rows
• src/views/Projects.vue — TransitionGroup on project cards, modal transitions
• src/views/Clients.vue — TransitionGroup on client cards, modal transitions
• src/views/Dashboard.vue — content fade-in, progress bar animation
• src/views/Reports.vue — content fade-in on tab switch
• src/views/Settings.vue — modal leave transition
• src/views/CalendarView.vue — entry block fade-in on week change
• src/views/TimesheetView.vue — row fade-in on data load

Verification

1. npm run build passes with no errors
2. Page transitions feel smooth, no layout flashing
3. List add/remove animations don't cause scroll jumps
4. Modals have proper enter AND leave animations
5. No animation on prefers-reduced-motion: reduce