cadence-ui/docs/exec-plans/2026-03-25-motion-polish-pass.md

Motion Polish Pass

• Status: completed
• Owner: codex
• Date: 2026-03-25

Goal

Run a second polish pass focused on interaction motion across six existing component surfaces. The goal is to add the missing sense of staged, spatial feedback described in DESIGN.md without introducing a second motion language, widening public APIs unnecessarily, or making the system feel busy.

Scope

• In scope:
  • add polished active-guide, tooltip, and marker motion to Chart
  • add a one-time sweep and value count-up feel to Gauge
  • add shared active-pill motion to Tabs and SegmentedControl
  • add lighter interaction transitions to the newly polished DataTable
  • add subtle media float/breathe and CTA stagger to EmptyState
  • add active-row glide, list crossfade, and softer loading treatment to Command and Combobox
  • update the nearest stories and tests when behavior changes need review or coverage
• Out of scope:
  • introducing new animation dependencies
  • changing shared token files unless the main thread explicitly decides it is necessary
  • turning core surfaces into ambient animation showcases

Constraints

• Respect reduced motion and the repo's current Material-runtime design direction.
• Favor transform, opacity, box-shadow, and state-driven transitions over layout-heavy motion.
• Keep each worker on an isolated write scope.
• Preserve existing public component contracts unless a small compatibility-safe extension is justified.
• Do not revert or overwrite unrelated in-progress repo changes.

Affected Surfaces

• packages/ui/src/components/chart*
• packages/ui/src/components/gauge*
• packages/ui/src/components/tabs*
• packages/ui/src/components/segmented-control*
• packages/ui/src/components/data-table*
• packages/ui/src/components/empty-state*
• packages/ui/src/components/command*
• packages/ui/src/components/combobox*
• apps/docs/src/components/chart.stories.tsx
• apps/docs/src/components/gauge.stories.tsx
• apps/docs/src/components/tabs.stories.tsx
• apps/docs/src/components/segmented-control.stories.tsx
• apps/docs/src/components/data-table.stories.tsx
• apps/docs/src/components/empty-state.stories.tsx
• apps/docs/src/components/command.stories.tsx
• apps/docs/src/components/combobox.stories.tsx
• docs/exec-plans

Plan

1. Write a dedicated execution plan for the motion pass so the second round of work is resumable.
2. Dispatch six isolated workers, each owning one motion slice and its closest tests/docs.
3. Review the combined result set in the main thread and fix any compatibility or API-semantics issues before broader validation.
4. Run focused component, typecheck, and docs validation on the combined motion changes.
5. Record results, remaining risks, and any intentionally deferred motion refinements.

Validation

• pnpm --filter @ai-ui/ui exec vitest run <owned test files>
• pnpm --filter @ai-ui/ui exec tsc --noEmit
• pnpm --dir apps/docs exec tsc --noEmit
• pnpm build:docs

Orchestration Task Sketch

• T1: polish Chart motion
• T2: polish Gauge motion
• T3: polish Tabs and SegmentedControl motion
• T4: polish DataTable motion
• T5: polish EmptyState motion
• T6: polish Command and Combobox motion
• T7 -> T1,T2,T3,T4,T5,T6: integrate results and validate

Status Log

• 2026-03-25 16:45 started the motion-focused second pass after confirming the current component state from the first visual polish round
• 2026-03-25 16:47 wrote the motion pass plan and prepared six isolated worker slices with main-thread integration reserved for compatibility fixes and validation
• 2026-03-25 16:59 all six motion slices returned from delegated workers: Chart, Gauge, Tabs/SegmentedControl, DataTable, EmptyState, and Command/Combobox
• 2026-03-25 17:00 validated the combined result set with targeted Vitest coverage, pnpm --filter @ai-ui/ui exec tsc --noEmit, pnpm --dir apps/docs exec tsc --noEmit, and pnpm build:docs