cadence-ui/docs/exec-plans/2026-03-25-dashboard-contract-hardening.md

Dashboard Contract Hardening

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

Goal

Harden the new dashboard-oriented component contracts so the Revenue Dashboard scene no longer needs to bypass them for high-emphasis KPI cards or for custom chart header layouts.

Scope

• In scope:
  • extend MetricCard with high-emphasis tones suitable for dark or hero KPI panels
  • add structured MetricCard header slots for leading and aside content
  • make the Chart header composable without breaking the current convenience props
  • refresh docs stories, tests, and the revenue dashboard consumer to use the stronger contracts
• Out of scope:
  • introducing a full dashboard layout or navigation system
  • expanding the chart surface beyond the existing cartesian trend pattern
  • extracting new sparkline or sparkbar primitives in this slice

Constraints

• Preserve the current Material-inspired design direction in DESIGN.md.
• Keep the API additive and source-owned instead of replacing existing stories with one-off markup.
• Preserve the stable slot and data-* review surface so tests and docs stay predictable.
• Keep the current title / description / value / valueChange chart props working while adding the more composable header path.

Affected Surfaces

• docs/exec-plans
• packages/ui/src/components/metric-card.tsx
• packages/ui/src/components/metric-card.variants.ts
• packages/ui/src/components/chart.tsx
• packages/ui/src/components/chart.variants.ts
• packages/ui/src/index.ts
• packages/ui/src/components/*.test.tsx
• apps/docs/src/components/*.stories.tsx
• apps/docs/src/revenue-dashboard.stories.tsx

Plan

1. Extend MetricCard with inverse and hero visual tones plus stable leading and aside header slots.
2. Refactor Chart to accept a composed header while keeping the current prop-based header API as a convenience fallback.
3. Update stories and the revenue dashboard scene so the new contracts are exercised by real compositions instead of only isolated tests.
4. Run focused component and docs validation, then record any residual issues.

Validation

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

Orchestration Task Sketch

• T1: harden MetricCard tone and header composition contract
• T2 -> T1: harden Chart header composition contract
• T3 -> T2: refresh stories, revenue dashboard usage, and focused validation

Status Log

• 2026-03-25 20:36 started the contract-hardening slice after reviewing the revenue dashboard and confirming that Sales Growth and Sales Impact still rely on API workarounds rather than first-class component affordances
• 2026-03-25 20:49 extended MetricCard with inverse and hero tones plus leading and aside header slots, then refactored the docs story and revenue dashboard consumer to use them
• 2026-03-25 20:56 refactored Chart to support a composed header path while preserving the legacy prop-driven header contract, and updated stories and tests to cover both paths
• 2026-03-25 20:59 validated focused MetricCard and Chart tests plus build:docs; pnpm --filter @ai-ui/ui typecheck is still blocked by unrelated pre-existing packages/ui/src/components/sparkbar.tsx type errors outside this slice