# 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.