cadence-ui/docs/exec-plans/2026-03-25-stat-and-metric-cards.md

Stat And Metric Cards

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

Goal

Add two dashboard-oriented composition components to @ai-ui/ui: a compact StatCard for the common label/value/delta/description KPI pattern, and a richer MetricCard that extends the same pattern with media, footer, and action regions for analytics panels.

Scope

• In scope:
  • add StatCard and MetricCard component source, variants, exports, tests, and docs
  • expose stable slot and state metadata consistent with the repo contract
  • refactor the new revenue dashboard scene to consume the components where they fit
• Out of scope:
  • introducing a full dashboard layout system
  • replacing all existing card-based compositions across the repo
  • expanding the chart system beyond what already exists

Constraints

• Follow the active Material-inspired design direction in DESIGN.md.
• Keep the API small and slot-oriented rather than introducing a single oversized props surface.
• Reuse existing card tokens and motion recipes instead of creating a parallel styling layer.
• Preserve enough flexibility that richer panels can still compose custom chart and footer content.

Affected Surfaces

• packages/ui/src/components
• packages/ui/src/index.ts
• apps/docs/src/components
• apps/docs/src/revenue-dashboard.stories.tsx
• docs/exec-plans

Plan

1. Implement StatCard as a compact KPI card with semantic slots for eyebrow, label, value, delta, and description.
2. Implement MetricCard on the same visual and slot contract, adding media, footer, and actions regions plus layout variants.
3. Add focused tests and Storybook stories that document the standard usage, anatomy, and review guidance.
4. Refactor the revenue dashboard scene to consume the new components for representative panels.
5. Run focused validation and record any unrelated repository issues that remain.

Validation

• pnpm --filter @ai-ui/ui typecheck
• pnpm --filter @ai-ui/ui test
• pnpm build:docs

Orchestration Task Sketch

• T1: implement StatCard and MetricCard source plus exports
• T2 -> T1: add stories/tests and refactor the revenue dashboard scene
• T3 -> T2: run focused validation and document residual issues

Status Log

• 2026-03-25 16:16 started the stat/metric card slice after confirming the current dashboard scene still relies on repeated KPI glue code
• 2026-03-25 16:27 implemented StatCard and MetricCard, exported them from @ai-ui/ui, added tests and Storybook stories, and refactored representative revenue-dashboard panels onto the new components
• 2026-03-25 16:31 validated pnpm --filter @ai-ui/ui typecheck, pnpm --filter @ai-ui/ui test, pnpm build, and pnpm build:docs
• 2026-03-25 16:33 noted that the running Storybook dev session still carries unrelated development noise from other in-flight docs slices (progress.stories.tsx index warnings and an InputGroup runtime export mismatch on the dashboard iframe), but the package build and Storybook production build both pass