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

Challenge Progress Pattern

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

Goal

Add a reusable ChallengeProgress pattern to packages/ui that recreates the stacked challenge target panel shown in the reference, while staying inside Cadence UI's own tonal, rounded, and component-first visual language.

Scope

• In scope:
  • add a new ChallengeProgress pattern for multi-row target progress panels
  • compose the pattern from existing Cadence UI primitives where practical, especially Badge, Progress, and Spinner
  • add tests and Storybook docs for the new pattern
  • export the pattern from @ai-ui/ui
• Out of scope:
  • changing the base Progress contract or segment-count limits
  • adding a new shared icon package or icon primitives
  • registry metadata refresh while the worktree already carries unrelated registry changes

Constraints

• Keep the pattern visually aligned with DESIGN.md, not the dark reference palette.
• Prefer stable slots and data attributes over story-local styling glue.
• Preserve the dirty worktree and avoid rewriting unrelated in-flight edits.
• Use the smallest new API surface that can still support multiple challenge rows.

Affected Surfaces

• packages/ui/src/patterns/challenge-progress.tsx
• packages/ui/src/patterns/challenge-progress.variants.ts
• packages/ui/src/patterns/challenge-progress.test.tsx
• packages/ui/src/index.ts
• apps/docs/src/patterns/challenge-progress.stories.tsx

Plan

1. Define the pattern API and slot structure around a title plus repeated challenge rows.
2. Implement the pattern styling with existing tokens and compose row status from existing primitives.
3. Add unit coverage and Storybook docs showing the reference-inspired layout in Cadence UI's own palette.
4. Run targeted validation for the new pattern, exports, and docs surface.

Validation

• pnpm --filter @ai-ui/ui typecheck
• pnpm --filter @ai-ui/ui exec vitest run packages/ui/src/patterns/challenge-progress.test.tsx --config ../../vitest.config.ts
• pnpm exec eslint apps/docs/src/patterns/challenge-progress.stories.tsx packages/ui/src/patterns/challenge-progress.tsx packages/ui/src/patterns/challenge-progress.variants.ts packages/ui/src/patterns/challenge-progress.test.tsx packages/ui/src/index.ts
• pnpm harness:validate:docs

Status Log

• 2026-03-25 19:44 Read the required system-of-record files, inspected the existing Progress, Badge, Spinner, and pattern authoring conventions, and scoped the work as a new reusable pattern instead of a one-off story.
• 2026-03-25 20:20 Implemented the ChallengeProgress pattern and variants around a title plus repeated challenge rows, composing row chips from Badge, row meters from segmented Progress, and loading affordances from Spinner.
• 2026-03-25 20:24 Added unit coverage, Storybook docs, and package exports for the new pattern.
• 2026-03-25 20:26 Verified pnpm --filter @ai-ui/ui typecheck, targeted vitest, targeted eslint, and pnpm harness:validate:docs.