cadence-ui/docs/exec-plans/2026-03-25-foundation-and-pattern-motion-pass.md

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