# 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