# Foundation And Pattern Motion Pass

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

## Goal

Run a focused third-pass polish on four remaining motion gaps: overly busy `DataTable` chrome,
under-animated foundation surfaces, static-feeling workspace patterns, and missing docs/test
coverage for `StatCard` / `MetricCard` motion behavior.

## Scope

- In scope:
  - reduce excess hover lift around `DataTable` selection, search, and pagination chrome while
    preserving row hover and sort-state feedback
  - add restrained component-specific polish to `Alert`, `Avatar`, and `Badge`
  - bring `PageHeader`, `AppShell`, and `PageFooter` closer to the existing pattern motion quality
    bar set by `SidebarNav`
  - add dedicated motion stories and targeted regression tests for `StatCard` and `MetricCard`
- Out of scope:
  - adding new animation dependencies
  - broad visual redesign unrelated to motion and interaction feedback
  - touching unrelated in-progress component work

## Constraints

- Respect `DESIGN.md` and keep one calm, spatial motion language.
- Keep write scopes isolated so workers do not collide.
- Preserve existing public APIs unless a very small compatibility-safe addition is justified.
- Do not revert unrelated work already present in the dirty worktree.

## Ownership

- Main thread:
  - plan, review, integration, and validation
- Worker 1:
  - `packages/ui/src/components/data-table*`
  - `apps/docs/src/components/data-table.stories.tsx`
- Worker 2:
  - `packages/ui/src/components/alert*`
  - `packages/ui/src/components/avatar*`
  - `packages/ui/src/components/badge*`
  - nearest owned stories/tests if needed
- Worker 3:
  - `packages/ui/src/patterns/page-header*`
  - `packages/ui/src/patterns/app-shell*`
  - `packages/ui/src/patterns/page-footer*`
  - nearest owned stories/tests if needed
- Worker 4:
  - `packages/ui/src/components/stat-card*`
  - `packages/ui/src/components/metric-card*`
  - `apps/docs/src/components/stat-card.stories.tsx`
  - `apps/docs/src/components/metric-card.stories.tsx`

## Plan

1. Write the execution plan and confirm the four disjoint ownership slices.
2. Dispatch four workers with isolated write scopes and keep main-thread ownership limited to
   review, integration, and validation.
3. Review the returned slices, fix any integration gaps, and avoid broad shared-file churn.
4. Run focused tests and typechecks for the affected components and docs surfaces.

## Validation

- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/data-table.test.tsx`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/alert.test.tsx packages/ui/src/components/avatar.test.tsx packages/ui/src/components/badge.test.tsx`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/stat-card.test.tsx packages/ui/src/components/metric-card.test.tsx`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/patterns/page-header.test.tsx packages/ui/src/patterns/app-shell.test.tsx packages/ui/src/patterns/page-footer.test.tsx`
- `pnpm --filter @ai-ui/ui exec tsc --noEmit`
- `pnpm --dir apps/docs exec tsc --noEmit`

## Status Log

- `2026-03-25 17:27` started the pass after the previous motion review identified remaining polish
  gaps in `DataTable`, foundation surfaces, workspace patterns, and motion-story/test coverage
- `2026-03-25 17:28` wrote the execution plan and dispatched four isolated workers for
  `DataTable`, foundation components, workspace patterns, and KPI-card coverage
- `2026-03-25 17:33` reviewed and accepted all four returned slices, then validated the combined
  result set with focused Vitest coverage plus `pnpm --filter @ai-ui/ui exec tsc --noEmit` and
  `pnpm --dir apps/docs exec tsc --noEmit`