[Ryjen1]

fix(storybook): finalize widget showcase for #253 (closes #264)

Summary

Finalizes PR #253 (closing #264) by addressing theme override background no-ops, fixing environment switching in the CitizenClaim showcase, extracting shared Storybook options, updating integrator docs, and adding Playwright dynamic in-place tests with committed UI evidence.

Zero changes to packages/*. All updates are strictly scoped to examples/storybook and tests/widgets.

---

Acceptance Criteria Checklist

• Bug 1 — Background Controls Rewired:
  • GoodReserveWidget: swapShellBackground (backgroundSurface), amountCardBackground (backgroundInput), and submitButtonBackground (Button).
  • SuperfluidCampaignWidget: cardBackground (backgroundDark) and buttonBackground (Button).
  • AiCreditsWidget: heroBackground (backgroundSurface) and buttonBackground (Button).
  • Removed non-working dark_Card.background controls and added DocsCallout explaining that base theme tokens cascade to all internal surfaces across each widget.
  • Corrected misleading copy in GoodReserve header, Superfluid MDX, and AiCredits header.
• Bug 2 — CitizenClaim Environment Switch:
  • Added key={environment} to <CitizenClaimWidget> inside CitizenClaimWidgetStoryShell so it remounts on environment toggle and drops stale data.
• Shared Helper Refactor:
  • Extracted ENVIRONMENT_OPTIONS to examples/storybook/src/stories/helpers/environmentOptions.ts.
• Dynamic Tests & Visual Evidence:
  • Playwright specs asserting both initial styles and live in-place CSS updates via Storybook channel events (zero page reloads).
  • In-place environment remount test for CitizenClaim asserting DOM detachment and fresh contract calls to production UBI addresses.
  • Committed 11 screenshots under tests/widgets/*/test-results/.

---

Root Cause Analysis

Bug 1: Card background controls were no-ops in Theme Overrides

• AiCreditsWidget: AiCreditsHero.tsx sets backgroundColor="$backgroundSurface" directly in JSX. In Tamagui, explicit style props take precedence over component defaults (dark_Card.background). Wired the background control to base tokens themes.dark.backgroundSurface / themes.light.backgroundSurface.
• SuperfluidCampaignWidget: The outer container sets backgroundColor="$backgroundDark" directly on <Card>. Overrides on dark_Card.background have no effect. Wired the control to themes.dark.backgroundDark / themes.light.backgroundDark, restored the Button override control, and corrected misleading MDX copy.
• GoodReserveWidget: ReserveSwapShell sets backgroundColor: '$backgroundSurface' and ReserveAmountCard sets backgroundColor: '$backgroundInput'. Overriding dark_Card.background did nothing. Wired controls to backgroundSurface (shell) and backgroundInput (amount card), and corrected story header comments.

Bug 2: CitizenClaimWidget environment change did not refresh

• The widget adapter's auto-refresh effect listens to [isConnected, address, chainId], omitting environment.
• Adding key={environment} to <CitizenClaimWidget> inside CitizenClaimWidgetStoryShell forces React to remount when toggling between development and production in Storybook controls, dropping previous environment data and re-fetching cleanly.

---

Changes

• examples/storybook/src/stories/helpers/environmentOptions.ts
  • Extracted ENVIRONMENT_OPTIONS into a reusable helper typed as readonly CitizenClaimWidgetEnvironment[].
• examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetShowcase.stories.tsx
  • Replaced inline environment array with ENVIRONMENT_OPTIONS import.
• examples/storybook/src/stories/helpers/citizenClaimWidgetStories.tsx
  • Added key={environment} and wrapped in <div key={environment} data-testid={dataTestId}> to ensure clean React remounting on environment toggle; passed environment through CustodialLocalFixtureStory.
• examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetThemeOverrides.stories.tsx
  • Wired hero background control to themes.dark.backgroundSurface and themes.light.backgroundSurface; updated overridable paths copy, documenting how backgroundSurface cascades to other surfaces in the widget.
• examples/storybook/src/stories/helpers/aiCreditsWidgetStories.tsx
  • Added ThemedAiCreditsStory export with deterministic mock state and data-testid="AiCreditsWidget-themed".
• examples/storybook/src/stories/ai-credits-widget/AiCreditsWidget.mdx
  • Updated the Theme Overrides section description to accurately describe the supported overrides.
• examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidgetThemeOverrides.stories.tsx
  • Wired outer card background control to themes.dark.backgroundDark / themes.light.backgroundDark; restored dark_Button / light_Button background controls; documented cascading token behavior.
• examples/storybook/src/stories/helpers/superfluidCampaignWidgetStories.tsx
  • Added ThemedSuperfluidStory export mounting MockSuperfluidCampaignWidget directly inside its container div.
• examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidget.mdx
  • Corrected outer shell styling copy from dark_Card.background to backgroundDark.
• examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetThemeOverrides.stories.tsx
  • Rewired swapShellBackground to backgroundSurface and amountCardBackground to backgroundInput; documented that token badges and confirm highlights use $backgroundSurfaceAlt, which is not wired to a control and keeps the base theme color.
• examples/storybook/src/stories/goodreserve-widget/GoodReserveWidget.mdx
  • Updated the Theme Overrides section description to name the backgroundSurface / backgroundInput tokens the widget actually uses.
• tests/widgets/ai-credits-widget/theme-overrides.spec.ts
  • Asserts initial dark mode styles, updates heroBackground and buttonBackground in-place via the Storybook addon channel (no page reload), and asserts live computed CSS changes on the hero card (rgb(2, 132, 199)) and buy button (rgb(220, 38, 38)).
• tests/widgets/superfluid-campaign-widget/theme-overrides.spec.ts
  • Asserts initial styles, updates cardBackground and buttonBackground in-place via the Storybook addon channel, and asserts live computed CSS changes on the outer card (rgb(5, 150, 105)) and CTA button (rgb(220, 38, 38)).
• tests/widgets/goodreserve-widget/theme-overrides.spec.ts
  • Asserts initial styles, updates swapShellBackground, amountCardBackground, and submitButtonBackground in-place, and asserts live computed CSS changes on the outer shell (rgb(225, 29, 72)), amount card (rgb(5, 150, 105)), and submit button (rgb(37, 99, 235)).
• tests/widgets/citizen-claim-widget/showcase.spec.ts
  • Runs in a single page session without reloads: loads environment: 'development', updates the arg in-place to production, verifies the initial DOM node is detached (isConnected === false), and verifies intercepted outgoing RPC requests shift from development to production UBI contract addresses (0xd253a520..., 0x43d72ff1..., 0x22867567...).

---

Audit Findings (#253 Showcase)

• Fixed in scope:
  • Outdated story comments claiming dark_Card.background is not a no-op in AiCredits and GoodReserve.
  • Misleading MDX copy in Superfluid regarding outer container styling paths.
  • GoodReserve cascade copy that listed token badges under backgroundInput; token badges use $backgroundSurfaceAlt, and the story copy now documents that this token is not wired to a control.
• Reported findings (out of scope, separate follow-ups):
  • GoodReserveWidget does not expose an environment prop (tracked in [BountyPrep] Storybook: missing primitives and design system gaps #254).
  • useCitizenClaimAdapter effect dependencies should include environment directly so consumers outside Storybook do not need manual remount keys.
  • Packages hardcoding base tokens ($backgroundSurface, $backgroundSurfaceAlt, $backgroundDark, $backgroundInput) in JSX rather than referencing named Tamagui component theme targets.

---

Verification

Local Run Results (HEAD eed4ce4)

• Monorepo build (pnpm build): Passed across workspace packages (17/17 cached / built).
• Playwright suite: 7 / 7 passed (pnpm exec playwright test ... in 4.6s)
  • GoodReserveWidget: Shell updates rgb(30, 27, 75) → rgb(225, 29, 72), Amount card updates rgb(15, 23, 42) → rgb(5, 150, 105), Submit button updates rgb(124, 58, 237) → rgb(37, 99, 235).
  • SuperfluidCampaignWidget: Card updates rgb(30, 27, 75) → rgb(5, 150, 105), Action button updates rgb(124, 58, 237) → rgb(220, 38, 38).
  • AiCreditsWidget: Hero card updates rgb(30, 27, 75) → rgb(2, 132, 199), Buy button updates rgb(124, 58, 237) → rgb(220, 38, 38).
  • CitizenClaimWidget: In-place switch confirms old DOM node detachment (isConnected === false), clean remount, and fresh RPC queries dispatched to production UBI contracts (0xd253a520... Fuse, 0x43d72ff1... Celo, 0x22867567... XDC).
• Linting (pnpm exec eslint <modified files>): Passed with 0 errors and 0 warnings.
• Typecheck (tsc --noEmit): 0 errors on modified files.

Remote CI Status

• GitGuardian Security Checks: Passed (no secrets detected).
• Workflows (Deploy Storybook / Playwright Demo): Queued awaiting maintainer approval for external fork environment deployment (pull_request_target).

---

Evidence

• tests/widgets/ai-credits-widget/test-results/acw-theme-overrides-dark.png
• tests/widgets/ai-credits-widget/test-results/acw-theme-overrides-light.png
• tests/widgets/ai-credits-widget/test-results/acw-theme-overrides-custom.png
• tests/widgets/superfluid-campaign-widget/test-results/scw-theme-overrides-dark.png
• tests/widgets/superfluid-campaign-widget/test-results/scw-theme-overrides-light.png
• tests/widgets/superfluid-campaign-widget/test-results/scw-theme-overrides-custom.png
• tests/widgets/goodreserve-widget/test-results/grw-theme-overrides-dark.png
• tests/widgets/goodreserve-widget/test-results/grw-theme-overrides-light.png
• tests/widgets/goodreserve-widget/test-results/grw-theme-overrides-custom.png
• tests/widgets/citizen-claim-widget/test-results/ccw-showcase-development.png
• tests/widgets/citizen-claim-widget/test-results/ccw-showcase-production.png

---

Follow-ups

1. Update useCitizenClaimAdapter to add environment to the effect dependency array
2. Consider standardizing widget container components into named Tamagui primitives (e.g., ReserveSwapShell, SuperfluidCard) so integrators can use component sub-themes (dark_ReserveSwapShell) instead of overriding base palette tokens
3. Wire a backgroundSurfaceAlt control in the GoodReserve Theme Overrides playground (the limitation is currently documented in the story copy instead).