# 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`