cadence-ui/docs/exec-plans/2026-03-25-progress-patterns.md

Progress Patterns

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

Goal

Extend Progress beyond the default linear fill so the component can also render segmented dashboard-style progress bars like the operational cost reduction example, without splitting the API into separate one-off components.

Scope

• In scope:
  • add a structural pattern dimension to Progress
  • support a segmented dashboard meter mode
  • keep the existing linear pattern untouched as the default
  • update tests, exports, and Storybook docs
• Out of scope:
  • radial gauge visuals
  • introducing a separate Gauge component
  • modifying unrelated dashboard story drafts

Constraints

• Keep variant reserved for semantic color intent.
• Preserve the existing ARIA progressbar behavior.
• Expose stable slots and data-* hooks for the segmented structure.
• Stay within the current Cadence UI tonal and motion language.

Affected Surfaces

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

Plan

1. Add a pattern API for linear and segmented progress structures.
2. Implement segmented rendering with stable slots and deterministic filled-state logic.
3. Refresh docs so the segmented meter is shown in a realistic dashboard context.
4. Run targeted validation for the package and docs surfaces.

Validation

• pnpm --filter @ai-ui/ui typecheck
• pnpm --filter @ai-ui/ui test -- --run packages/ui/src/components/progress.test.tsx
• pnpm harness:validate:docs

Status Log

• 2026-03-25 17:58 Confirmed the existing Progress API is linear-only and inspected the local revenue dashboard draft for the target segmented visual language.
• 2026-03-25 18:10 Added a pattern dimension with segmented rendering, repeated segment slots, and progress-specific skin tokens for dashboard meters.
• 2026-03-25 18:14 Updated Storybook docs and package exports to document and expose the segmented mode.
• 2026-03-25 18:18 Verified pnpm --filter @ai-ui/ui typecheck, pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/components/progress.test.tsx --config ../../vitest.config.ts, and targeted eslint on the changed files.
• 2026-03-25 18:19 pnpm harness:validate:docs is currently blocked by an unrelated local Storybook draft: apps/docs/src/components/metric-card.stories.tsx imports MetricCard from @ai-ui/ui, but that export is not present in the built package yet.