feat(ui): add analytics primitives and layout patterns

2026-03-25 19:49:49 +08:00
parent cc1509d2f6
commit a5d75f42e9
63 changed files with 7751 additions and 2 deletions
@@ -0,0 +1,62 @@
+# 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`.