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

Progress Refresh

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

Goal

Bring Progress closer to the active Cadence UI visual language so it reads like a tonal system component instead of a generic utility bar, while keeping the existing API and accessibility contract intact.

Scope

• In scope:
  • refresh the Progress track and indicator styling
  • add progress-specific skin tokens in packages/ui/src/skins.css
  • update Storybook stories so the new anatomy, state, and motion behavior are reviewable
  • keep unit coverage aligned with the component contract
• Out of scope:
  • adding labels, percentages, or new public props
  • changing exports or introducing new dependencies

Constraints

• Preserve the current Progress API surface (size, tone, variant, value, max).
• Keep the stable data-slot and data-state hooks.
• Use existing token roles and motion primitives instead of hardcoded one-off colors.
• Keep indeterminate behavior usable under static/reduced motion.

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
• apps/docs/src/components/progress.stories.tsx

Plan

1. Add progress skin tokens for track depth, highlight, and indicator gloss.
2. Rework the component styling around those tokens without changing the public props.
3. Refresh docs stories to show the component in more intentional, reviewable product contexts.
4. Run the narrowest harness suites that cover the changed component and docs surfaces.

Validation

• pnpm harness:validate:component
• pnpm harness:validate:docs

Status Log

• 2026-03-25 17:20 Read system-of-record files and inspected the current Progress source, tests, and stories.
• 2026-03-25 17:25 Started implementation for the visual refresh and docs alignment.
• 2026-03-25 17:42 Added progress skin tokens, refreshed the track and indicator styling, and rewrote the Storybook review surface.
• 2026-03-25 17:48 Verified pnpm --filter @ai-ui/ui typecheck, pnpm --filter @ai-ui/ui test -- --run packages/ui/src/components/progress.test.tsx, and pnpm harness:validate:docs.
• 2026-03-25 17:49 pnpm harness:validate:component still fails on pre-existing type errors in apps/docs/src/revenue-dashboard.stories.tsx, unrelated to the Progress work.