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