cadence-ui/docs/exec-plans/2026-03-25-gauge-component.md

Gauge Component

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

Goal

Add a true radial Gauge component to packages/ui so the system supports meter-style KPI visuals in addition to linear Progress and segmented progress bars.

Scope

• In scope:
  • add a new Gauge component with radial SVG rendering
  • support dial and semi-circle shapes
  • cover the component with tests and Storybook docs
  • export the component from @ai-ui/ui
• Out of scope:
  • registry metadata refresh while the worktree already contains unrelated registry edits
  • retrofitting local draft dashboard stories to use the new component
  • animated needle / pointer gauges

Constraints

• Gauge should use role="meter" rather than overloading Progress.
• Keep variant semantic and reserve geometry differences for a dedicated shape dimension.
• Follow the current Cadence UI tonal and motion language.
• Preserve the existing dirty worktree and avoid rewriting unrelated draft files.

Affected Surfaces

• packages/ui/src/components/gauge.tsx
• packages/ui/src/components/gauge.variants.ts
• packages/ui/src/components/gauge.test.tsx
• packages/ui/src/skins.css
• packages/ui/src/index.ts
• apps/docs/src/components/gauge.stories.tsx

Plan

1. Define the Gauge API, rendering geometry, and stable slots.
2. Implement the component with skin tokens and SVG arc math.
3. Add tests and Storybook docs for geometry, states, and accessibility guidance.
4. Run targeted validation for the package surface and changed files.

Validation

• pnpm --filter @ai-ui/ui typecheck
• pnpm --filter @ai-ui/ui build
• pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/gauge.test.tsx --config ../../vitest.config.ts
• pnpm exec eslint apps/docs/src/components/gauge.stories.tsx packages/ui/src/components/gauge.tsx packages/ui/src/components/gauge.variants.ts packages/ui/src/components/gauge.test.tsx packages/ui/src/index.ts

Status Log

• 2026-03-25 18:30 Read the closest dashboard-oriented component and story patterns, and scoped Gauge as a separate meter primitive rather than an extension of Progress.
• 2026-03-25 18:42 Implemented the Gauge component with radial SVG geometry, dial and semi-circle shapes, meter semantics, and stable slots.
• 2026-03-25 18:47 Added package exports, skin tokens, unit coverage, and a dedicated Storybook docs page for Gauge.
• 2026-03-25 18:51 Verified pnpm --filter @ai-ui/ui typecheck, pnpm --filter @ai-ui/ui build, pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/gauge.test.tsx --config ../../vitest.config.ts, targeted eslint, and pnpm harness:validate:docs.