cadence-ui/docs/exec-plans/2026-03-25-sparkbar-primitive.md

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.