symbolEffect-style icon micro-interactions for Mix

[leoafarias]

Summary

Should Mix add a SwiftUI-like symbolEffect API for icons (bounce/pulse/wiggle/rotate/breathe) using existing Mix animation infrastructure?

The goal is a tiny, ergonomic API for common icon micro-interactions with minimal new engine surface. Effects are transform/opacity only (Flutter icons are font glyphs).

Problem

Today, simple icon effects require custom animation boilerplate per screen. That makes design-system motion inconsistent and repetitive.

Proposed API (Swift-like entry point)

Assumes Dart 3.10+ with dot-shorthands enabled and a Duration extension like 250.ms.

final likeCount = ValueNotifier(0);
final isRecording = ValueNotifier(false);

final style = IconStyler()
  .symbolEffect(.bounce,
    trigger: likeCount,
    intensity: 0.15,
    duration: 250.ms,
  )
  .symbolEffect(.pulse,
    isActive: isRecording,
    minOpacity: 0.4,
    duration: 800.ms,
  );

// Trigger
likeCount.value++;

Proposed API (explicit helper methods, validated plan style)

final style = IconStyler()
  .bounceOnChange(trigger: likeCount, intensity: 0.15, duration: 250.ms)
  .pulseWhile(trigger: isRecording, minOpacity: 0.4, duration: 800.ms);

What users do today (current Mix API)

final likeCount = ValueNotifier(0);

final style = IconStyler().phaseAnimation<double>(
  trigger: likeCount,
  phases: [1.0, 0.85, 1.15, 1.0],
  styleBuilder: (scale, style) => style.wrap(.scale(x: scale, y: scale)),
  configBuilder: (_) => .easeOut(80.ms),
);

// Trigger
likeCount.value++;

Indefinite effects today require manual controllers or wrapper widgets (AnimatedBuilder, custom state), which is more boilerplate than a style-level API.

Constraints / Prerequisites

Before shipping effects, the current phase animation driver needs fixes:

• Fix trigger listener removal in PhaseAnimationDriver.updateDriver.
• Fix phase sequencing semantics (no implicit wrap, use current phase configs).

Downsides / Risks

• Adds motion primitives to Mix styles (not everyone wants animation in styles).
• Indefinite effects must avoid leaked listeners and runaway loops.
• Effects are limited to transform/opacity; no SF Symbols layered path animations.
• Potential overlap with existing animation property if both are used.

Alternatives (if we do not add symbolEffect)

• Document reusable phaseAnimation recipes (bounce/pulse/rotate).
• Add a small “motion presets” utility: IconStyler().motion(.bounce(...)).
• Add design-system motion tokens (durations/curves) without new API surface.

Open Questions

• Do we want one entry point (.symbolEffect) or explicit helpers (.bounceOnChange)?
• Should this be icon-only or reusable on any stylable widget?
• Which effects are truly needed in real apps? (bounce/pulse/rotate?)
• Should multiple effects be composable, or “last wins” for V1?

Scope

• V1: icon transforms/opacity, same style API, no new rendering engine.
• Out of scope: cross-route symbol transitions, path-morphing, SF Symbols layers.