# Sparkbar Primitive

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

## Goal

Add a dedicated `Sparkbar` micro-visual primitive to `@ai-ui/ui` so compact KPI cards and
dashboard tiles can render tiny bar-based trend summaries without hand-written DOM.

## Scope

- In scope:
  - add a new `Sparkbar` component to `packages/ui`
  - keep the API narrow and card-focused: small size, low configuration, embedded usage
  - support simple bar highlighting for active ranges without turning the component into a full
    charting surface
  - add unit tests and Storybook docs for the public contract
  - replace the hand-written sparkbar markup in `apps/docs/src/revenue-dashboard.stories.tsx`
    and the related metric-card docs story
- Out of scope:
  - introducing a full `Sparkline` API in the same slice
  - adding axes, tooltips, interaction, or data transforms that belong to `Chart`
  - expanding `Chart` itself to absorb micro-visual responsibilities
  - broader dashboard contract cleanup outside the bar micro-vis use cases

## Constraints

- Follow `DESIGN.md` and keep the visual language tonal, rounded, and quiet enough for card media.
- Preserve a stable slot and `data-*` contract so docs and tests can target the primitive.
- Keep the public API additive and intentionally smaller than `Chart`.
- Avoid rewriting unrelated dirty-worktree changes while touching shared files like docs stories and
  package exports.

## Affected Surfaces

- `docs/exec-plans/2026-03-25-sparkbar-primitive.md`
- `packages/ui/src/components/sparkbar.tsx`
- `packages/ui/src/components/sparkbar.variants.ts`
- `packages/ui/src/components/sparkbar.test.tsx`
- `packages/ui/src/index.ts`
- `packages/ui/src/skins.css`
- `apps/docs/src/components/sparkbar.stories.tsx`
- `apps/docs/src/components/metric-card.stories.tsx`
- `apps/docs/src/revenue-dashboard.stories.tsx`
- `registry/index.json`

## Plan

1. Define a narrow `Sparkbar` API for embedded numeric bar trends and active-range emphasis.
2. Implement the component with stable slots, tone/variant styling, and decorative-by-default
   accessibility behavior.
3. Add Storybook stories that explain when to use `Sparkbar` instead of `Chart`.
4. Replace the existing hand-written bar maps in docs consumers with the new primitive.
5. Run focused package and docs validation, then record any remaining gaps.

## Validation

- `pnpm --filter @ai-ui/ui typecheck`
- `pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/sparkbar.test.tsx --config ../../vitest.config.ts`
- `pnpm exec eslint apps/docs/src/components/sparkbar.stories.tsx apps/docs/src/components/metric-card.stories.tsx apps/docs/src/revenue-dashboard.stories.tsx packages/ui/src/components/sparkbar.tsx packages/ui/src/components/sparkbar.variants.ts packages/ui/src/components/sparkbar.test.tsx packages/ui/src/index.ts`
- `pnpm harness:validate:docs`
- `pnpm registry:build`

## Status Log

- `2026-03-25 21:15` Read the system-of-record files and confirmed the repo currently has a full `Chart` pattern but no dedicated micro bar-trend primitive.
- `2026-03-25 21:22` Scoped the new component as `Sparkbar`: low-config, non-interactive, card-embedded, and explicitly separate from `Chart`.
- `2026-03-25 23:18` Implemented `Sparkbar`, tokenized its size/tone/variant styling, exported it from `@ai-ui/ui`, and added unit coverage for slots, emphasis, and accessibility behavior.
- `2026-03-25 23:28` Added dedicated Storybook docs and migrated the handwritten spark bars in the revenue dashboard and metric-card stories to the new primitive.
- `2026-03-25 23:34` Verified `pnpm --filter @ai-ui/ui typecheck`, targeted Sparkbar Vitest coverage, targeted ESLint, `pnpm harness:validate:docs`, and `pnpm registry:build`.