From 9032a631e7971abf50b8b4a240426f484aa96f6d Mon Sep 17 00:00:00 2001
From: "goodbounties-nanoclaw-agent[bot]"
 <307944451+goodbounties-nanoclaw-agent[bot]@users.noreply.github.com>
Date: Wed, 14 Oct 2026 10:25:19 +0000
Subject: [PATCH] [BountyCoder] feat(storybook): showcase all GoodWidget
 widgets with QA fixtures and theme overrides

Adds the Showcase/Theme-overrides/QA three-way story split to
CitizenClaimWidget, GoodReserveWidget, GovernanceWidget, AiCreditsWidget,
SuperfluidCampaignWidget, and GoodDataWidget per issue #252, including
MDX integrator docs and deterministic QA fixtures backing each widget's
Playwright states spec.

Co-Authored-By: Claude <noreply@anthropic.com>

On-Behalf-Of: BountyCoder[onecli] (yaskkeryodtdijpv)
---
 .../ai-credits-widget/AiCreditsWidget.mdx     |  36 ++-
 .../AiCreditsWidgetQA.stories.tsx             |   7 +
 .../AiCreditsWidgetShowcase.stories.tsx       |   6 -
 .../AiCreditsWidgetThemeOverrides.stories.tsx | 251 ++++++++++++++++++
 .../CitizenClaimWidget.mdx                    |  10 +-
 .../CitizenClaimWidgetShowcase.stories.tsx    |  22 +-
 ...tizenClaimWidgetThemeOverrides.stories.tsx | 206 ++++++++++++++
 .../gooddata-widget/GoodDataWidget.mdx        |  48 ++++
 .../GoodDataWidgetQA.stories.tsx              |   2 +-
 .../GoodDataWidgetShowcase.stories.tsx        |  19 ++
 .../GoodDataWidgetThemeOverrides.stories.tsx  | 198 ++++++++++++++
 .../goodreserve-widget/GoodReserveWidget.mdx  |  97 +++++++
 .../GoodReserveWidgetQA.stories.tsx           | 120 +++++++++
 ... => GoodReserveWidgetShowcase.stories.tsx} | 116 +-------
 ...oodReserveWidgetThemeOverrides.stories.tsx | 187 +++++++++++++
 .../GovernanceOnboarding.stories.tsx          |   4 +-
 .../governance-widget/GovernanceWidget.mdx    |   5 +
 .../helpers/citizenClaimWidgetStories.tsx     |  14 +-
 .../stories/helpers/goodDataWidgetStories.tsx |  20 +-
 .../SuperfluidCampaignWidget.mdx              |   8 +
 ...luidCampaignWidgetApiContracts.stories.tsx |   2 +-
 ...idCampaignWidgetThemeOverrides.stories.tsx | 183 +++++++++++++
 tests/widgets/gooddata-widget/states.spec.ts  |  10 +-
 .../widgets/goodreserve-widget/states.spec.ts |  38 +--
 .../governance-widget/onboarding.spec.ts      |  16 +-
 .../superfluid-campaign-widget/states.spec.ts |   4 +-
 26 files changed, 1455 insertions(+), 174 deletions(-)
 create mode 100644 examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetThemeOverrides.stories.tsx
 create mode 100644 examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetThemeOverrides.stories.tsx
 create mode 100644 examples/storybook/src/stories/gooddata-widget/GoodDataWidget.mdx
 create mode 100644 examples/storybook/src/stories/gooddata-widget/GoodDataWidgetShowcase.stories.tsx
 create mode 100644 examples/storybook/src/stories/gooddata-widget/GoodDataWidgetThemeOverrides.stories.tsx
 create mode 100644 examples/storybook/src/stories/goodreserve-widget/GoodReserveWidget.mdx
 create mode 100644 examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetQA.stories.tsx
 rename examples/storybook/src/stories/goodreserve-widget/{GoodReserveWidget.stories.tsx => GoodReserveWidgetShowcase.stories.tsx} (52%)
 create mode 100644 examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetThemeOverrides.stories.tsx
 create mode 100644 examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidgetThemeOverrides.stories.tsx

diff --git a/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidget.mdx b/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidget.mdx
index edcc07da..6bb89449 100644
--- a/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidget.mdx
+++ b/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidget.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Meta } from '@storybook/blocks';
 import * as ShowcaseStories from './AiCreditsWidgetShowcase.stories';
+import * as ThemeOverridesStories from './AiCreditsWidgetThemeOverrides.stories';
 import { DocsCallout, DocsCard, DocsGrid, DocsPage, DocsSection } from '../docs/DocsLayout';
 
 <Meta of={ShowcaseStories} />
@@ -10,29 +11,38 @@ import { DocsCallout, DocsCard, DocsGrid, DocsPage, DocsSection } from '../docs/
   lead="Buy AI coding credits with G$ on Celo. Credits settle on Base and are redeemable with AntSeed-compatible AI coding tools like Cursor and Cline."
 >
   <DocsSection
-    title="Interactive showcase (mock backend)"
-    description="Uses your browser wallet (`window.ethereum`, e.g. Rabby) with the in-memory mock backend — no local antseed worker required."
+    title="Injected wallet"
+    description="Uses your browser wallet (`window.ethereum`, e.g. Rabby), `VITE_AI_CREDITS_BACKEND_URL`, `VITE_AI_CREDITS_BASE_RPC_URL`, `VITE_AI_CREDITS_CELO_RPC_URL` (optional), `VITE_AI_CREDITS_FUNDING_VAULT_ADDRESS`, `VITE_AI_CREDITS_VAULT_ADDRESS`, and optional `VITE_AI_CREDITS_GOODID_ADDRESS` from `examples/storybook/.env.local`. GoodID verification uses on-chain `getWhitelistedRoot` via the Celo RPC (defaults to mainnet GoodID contract)."
   >
-    <Canvas of={ShowcaseStories.MockBackend} />
+    <Canvas of={ShowcaseStories.InjectedWallet} />
   </DocsSection>
 
   <DocsSection
-    title="Injected wallet"
-    description="Uses your browser wallet (`window.ethereum`, e.g. Rabby), `VITE_AI_CREDITS_BACKEND_URL`, `VITE_AI_CREDITS_BASE_RPC_URL`, `VITE_AI_CREDITS_CELO_RPC_URL` (optional), `VITE_AI_CREDITS_FUNDING_VAULT_ADDRESS`, `VITE_AI_CREDITS_VAULT_ADDRESS`, and optional `VITE_AI_CREDITS_GOODID_ADDRESS` from `examples/storybook/.env.local`. GoodID verification uses on-chain `getWhitelistedRoot` via the Celo RPC (defaults to mainnet GoodID contract)."
+    title="Theme overrides"
+    description="Play around with the primitive Card/Button theme overrides using the controls below. Both are demonstrated on the quote-ready fixture state, which renders the balance card and the primary Buy CTA button together in a single view."
   >
-    <Canvas of={ShowcaseStories.InjectedWallet} />
+    <Canvas of={ThemeOverridesStories.Playground} />
   </DocsSection>
 
   <DocsSection
     title="QA coverage"
-    description="Use the QA demo when you need reproducible fixture states, Playwright screenshots, or fixture-driven debugging."
+    description="Use the QA demo when you need reproducible fixture states, Playwright screenshots, or fixture-driven debugging. The in-memory mock-backend story (browser wallet, no local antseed worker required) now lives here too — it is a deterministic fixture, not a live product-facing showcase, so it belongs alongside the other QA states rather than in Showcase."
   >
-    <DocsCard
-      title="Open the QA fixture demo"
-      href="?path=/story/qa-aicreditswidget-runtime-fixtures--disconnected"
-    >
-      All QA fixture states as deterministic mock stories — ideal for automation and debugging.
-    </DocsCard>
+    <DocsGrid>
+      <DocsCard
+        title="Open the QA fixture demo"
+        href="?path=/story/qa-aicreditswidget-runtime-fixtures--disconnected"
+      >
+        All QA fixture states as deterministic mock stories — ideal for automation and debugging.
+      </DocsCard>
+      <DocsCard
+        title="Open the mock-backend story"
+        href="?path=/story/qa-aicreditswidget-runtime-fixtures--mock-backend"
+      >
+        Browser wallet (`window.ethereum`) with the in-memory mock backend — no local antseed worker
+        required.
+      </DocsCard>
+    </DocsGrid>
   </DocsSection>
 
   <DocsSection
diff --git a/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetQA.stories.tsx b/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetQA.stories.tsx
index 1ba61a3e..03f1a96e 100644
--- a/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetQA.stories.tsx
+++ b/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetQA.stories.tsx
@@ -17,6 +17,7 @@ import {
   PaymentFailedStory,
   BackendUnavailableStory,
   UnsupportedChainStory,
+  MockBackendStory,
   AppKitConnectWalletStory,
   MultiSignerManageStory,
   WalletControlsStory,
@@ -105,6 +106,12 @@ export const UnsupportedChain: Story = {
   render: () => <UnsupportedChainStory />,
 }
 
+/** Backend mocked, wallet is whatever EIP-1193 extension is injected in the browser. */
+export const MockBackend: Story = {
+  name: 'Mock Backend (browser wallet)',
+  render: () => <MockBackendStory />,
+}
+
 /** Multi-signer manage tab: signer selector and private-key reveal. */
 export const MultiSignerManage: Story = {
   render: () => <MultiSignerManageStory />,
diff --git a/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetShowcase.stories.tsx b/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetShowcase.stories.tsx
index 0fdff0bb..bfc19c10 100644
--- a/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetShowcase.stories.tsx
+++ b/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetShowcase.stories.tsx
@@ -2,7 +2,6 @@ import type { Meta, StoryObj } from '@storybook/react'
 import { AiCreditsWidget } from '@goodwidget/ai-credits-widget'
 import {
   InjectedWalletStory,
-  MockBackendStory,
   AppKitConnectWalletStory,
 } from '../helpers/aiCreditsWidgetStories'
 
@@ -22,11 +21,6 @@ const meta: Meta<typeof AiCreditsWidget> = {
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const MockBackend: Story = {
-  name: 'Mock Backend (browser wallet)',
-  render: () => <MockBackendStory />,
-}
-
 export const InjectedWallet: Story = {
   name: 'Injected Wallet',
   render: () => <InjectedWalletStory />,
diff --git a/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetThemeOverrides.stories.tsx b/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetThemeOverrides.stories.tsx
new file mode 100644
index 00000000..3e60bd17
--- /dev/null
+++ b/examples/storybook/src/stories/ai-credits-widget/AiCreditsWidgetThemeOverrides.stories.tsx
@@ -0,0 +1,251 @@
+/**
+ * AiCreditsWidget — Theme Overrides — demonstrates the widget's primitive
+ * theming surface (`Card`/`Button` from `packages/ui`) as live color-picker
+ * controls, following the StreamingWidget/GoodReserveWidget Theme overrides
+ * pattern for structure (CodeBlock + DocsCallout + live Canvas).
+ *
+ * This widget's own named sub-components — `AiCreditsStatusNotice`,
+ * `BonusBadgeFrame` (see packages/ai-credits-widget/src/components/theme/cards.ts)
+ * — have no dedicated `light_*`/`dark_*` presets in packages/ui/src/presets.ts
+ * (confirmed via grep), so they correctly cascade from the plain `Card`/`Button`
+ * theme instead of overriding it. A `dark_Card`/`dark_Button` override is NOT a
+ * no-op here.
+ *
+ * The quote-ready state is used because it renders the plain `Card` used by
+ * `AiCreditsHero` (packages/ai-credits-widget/src/components/buy/AiCreditsHero.tsx)
+ * alongside the plain primary `<Button>` inside `AmountPicker`, so a single pair
+ * of dark/light instances exercises both targets at once.
+ */
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  AiCreditsWidget,
+  type AiCreditsWidgetAdapterFactory,
+  type AiCreditsWidgetAdapterState,
+} from '@goodwidget/ai-credits-widget'
+import { createCustodialEip1193Provider } from '../../fixtures/custodialEip1193'
+import { DocsCallout, DocsList } from '../docs/DocsLayout'
+
+const provider = createCustodialEip1193Provider()
+
+// Mirrors the quote-ready fixture state used by AiCreditsWidgetQA.stories.tsx's
+// QuoteReady story, so this Playground renders the same Hero-card + Buy-button
+// surface as that reference fixture.
+function createQuoteReadyAdapterFactory(): AiCreditsWidgetAdapterFactory {
+  return () => {
+    const state: AiCreditsWidgetAdapterState = {
+      status: 'quote_ready',
+      address: '0x329377cbeeF39f01b0Ea04B80465c9eB47D3ED1',
+      chainId: 42220,
+      gBalance: '42.50',
+      gdUsdPerToken: 0.0015,
+      totalCreditUsd: null,
+      totalBonusUsd: null,
+      isGoodIdVerified: false,
+      signerPubKey: '0xabcdef1234567890abcdef1234567890abcdef12',
+      signerPrvKey: null,
+      operatorSignature: null,
+      operatorConsented: true,
+      operatorConsentPending: false,
+      operatorAddress: null,
+      currentOperator: null,
+      minDepositUsd: '1.00',
+      minStreamUsd: '1.00',
+      totalGdDepositedG: null,
+      monthlyStreamG: null,
+      withdrawableUsd: null,
+      depositBonusPercent: 10,
+      streamBonusPercent: 20,
+      error: null,
+      activeTab: 'buy',
+      signers: [],
+      derivedSignerAddress: null,
+    }
+    return {
+      state,
+      actions: {
+        connect: async () => {},
+        switchChain: async () => {},
+        generateSignerKey: async () => {},
+        selectSigner: async () => {},
+        discoverSigners: () => {},
+        importSignerFromPrivateKey: async () => state.signerPubKey,
+        applyDeepLinkSigner: async () => {},
+        signOperatorConsent: async () => {},
+        revokeOperatorConsent: async () => {},
+        syncOperatorConsentFromChain: async () => {},
+        buildQuote: async (depositG, streamG) => ({
+          depositAmountG: depositG,
+          streamAmountG: streamG,
+        }),
+        pay: async () => {},
+        refresh: async () => {},
+        verifyGoodId: async () => false,
+        startPurchase: () => {},
+        setActiveTab: () => {},
+        closeChannel: async () => {},
+        withdrawCredits: async () => {},
+        retry: async () => {},
+      },
+    }
+  }
+}
+
+function CodeBlock({ children }: { children: string }) {
+  return (
+    <pre
+      style={{
+        background: '#0f172a',
+        border: '1px solid rgba(59,130,246,0.28)',
+        borderRadius: 12,
+        color: '#e2e8f0',
+        fontFamily:
+          'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+        fontSize: 13,
+        lineHeight: 1.6,
+        margin: 0,
+        overflowX: 'auto',
+        padding: 18,
+        whiteSpace: 'pre',
+      }}
+    >
+      {children}
+    </pre>
+  )
+}
+
+interface OverridesArgs {
+  darkCardBackground: string
+  darkCardBorderColor: string
+  lightCardBackground: string
+  lightCardBorderColor: string
+  darkButtonBackground: string
+  darkButtonBackgroundHover: string
+  darkButtonColor: string
+  lightButtonBackground: string
+  lightButtonBackgroundHover: string
+  lightButtonColor: string
+}
+
+function buildThemeOverrides(args: OverridesArgs) {
+  return {
+    themes: {
+      dark_Card: {
+        background: args.darkCardBackground,
+        borderColor: args.darkCardBorderColor,
+      },
+      light_Card: {
+        background: args.lightCardBackground,
+        borderColor: args.lightCardBorderColor,
+      },
+      dark_Button: {
+        background: args.darkButtonBackground,
+        backgroundHover: args.darkButtonBackgroundHover,
+        color: args.darkButtonColor,
+      },
+      light_Button: {
+        background: args.lightButtonBackground,
+        backgroundHover: args.lightButtonBackgroundHover,
+        color: args.lightButtonColor,
+      },
+    },
+  }
+}
+
+const meta: Meta<OverridesArgs> = {
+  title: 'Widgets/AiCreditsWidget/Theme overrides',
+  tags: ['integrator', 'showcase'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    darkCardBackground: { control: 'color', description: 'themes.dark_Card.background' },
+    darkCardBorderColor: { control: 'color', description: 'themes.dark_Card.borderColor' },
+    lightCardBackground: { control: 'color', description: 'themes.light_Card.background' },
+    lightCardBorderColor: { control: 'color', description: 'themes.light_Card.borderColor' },
+    darkButtonBackground: { control: 'color', description: 'themes.dark_Button.background' },
+    darkButtonBackgroundHover: { control: 'color', description: 'themes.dark_Button.backgroundHover' },
+    darkButtonColor: { control: 'color', description: 'themes.dark_Button.color' },
+    lightButtonBackground: { control: 'color', description: 'themes.light_Button.background' },
+    lightButtonBackgroundHover: { control: 'color', description: 'themes.light_Button.backgroundHover' },
+    lightButtonColor: { control: 'color', description: 'themes.light_Button.color' },
+  },
+  args: {
+    darkCardBackground: '#1e1b4b',
+    darkCardBorderColor: '#7C3AED',
+    lightCardBackground: '#f5f3ff',
+    lightCardBorderColor: '#7C3AED',
+    darkButtonBackground: '#7C3AED',
+    darkButtonBackgroundHover: '#6D28D9',
+    darkButtonColor: '#FFFFFF',
+    lightButtonBackground: '#7C3AED',
+    lightButtonBackgroundHover: '#6D28D9',
+    lightButtonColor: '#FFFFFF',
+  },
+}
+export default meta
+type Story = StoryObj<OverridesArgs>
+
+export const Playground: Story = {
+  render: (args) => {
+    const themeOverrides = buildThemeOverrides(args)
+    const adapterFactory = createQuoteReadyAdapterFactory()
+    return (
+      <div style={{ display: 'grid', gap: 24, maxWidth: 960, margin: '0 auto' }}>
+        <CodeBlock>
+          {`<AiCreditsWidget\n  themeOverrides={${JSON.stringify(themeOverrides, null, 2)}}\n/>`}
+        </CodeBlock>
+
+        <DocsCallout title="All overridable paths on AiCreditsWidget" tone="info">
+          <DocsList>
+            <li>
+              <strong>dark_Card / light_Card</strong>: background, color, borderColor, shadowColor —
+              background and borderColor wired to the controls above; demonstrated below on the
+              `AiCreditsHero` balance card, which renders a plain Card with no dedicated preset of
+              its own
+            </li>
+            <li>
+              <strong>dark_Button / light_Button</strong>: background, backgroundHover,
+              backgroundPress, backgroundFocus, color, borderColor, borderColorFocus, shadowColor —
+              background, backgroundHover, and color wired to the controls above; demonstrated below
+              on the Buy tab's primary CTA button inside `AmountPicker`
+            </li>
+            <li>
+              <strong>dark_AiCreditsStatusNotice / dark_BonusBadgeFrame</strong>: no dedicated preset
+              exists for either named target (confirmed via packages/ui/src/presets.ts), so they
+              already cascade from Card/Button above — no separate named-target controls are needed
+              to reach them
+            </li>
+          </DocsList>
+        </DocsCallout>
+
+        <DocsCallout title="Why two columns" tone="info">
+          Each surface renders once in dark and once in light so every wired `light_*` control has a
+          visibly-exercised counterpart, not just a paired value that happens to exist.
+        </DocsCallout>
+
+        <div>
+          <p style={{ fontWeight: 600, marginBottom: 8 }}>
+            Quote-ready state — balance card and primary CTA button together
+          </p>
+          <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
+            <div data-testid="AiCreditsWidget-theme-overrides-dark" style={{ width: 380 }}>
+              <AiCreditsWidget
+                provider={provider}
+                adapterFactory={adapterFactory}
+                defaultTheme="dark"
+                themeOverrides={themeOverrides}
+              />
+            </div>
+            <div data-testid="AiCreditsWidget-theme-overrides-light" style={{ width: 380 }}>
+              <AiCreditsWidget
+                provider={provider}
+                adapterFactory={adapterFactory}
+                defaultTheme="light"
+                themeOverrides={themeOverrides}
+              />
+            </div>
+          </div>
+        </div>
+      </div>
+    )
+  },
+}
diff --git a/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidget.mdx b/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidget.mdx
index 4df267aa..4793d550 100644
--- a/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidget.mdx
+++ b/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidget.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Meta, Source } from '@storybook/blocks';
 import * as ShowcaseStories from './CitizenClaimWidgetShowcase.stories';
+import * as ThemeOverridesStories from './CitizenClaimWidgetThemeOverrides.stories';
 import { DocsCallout, DocsCard, DocsGrid, DocsPage, DocsSection } from '../docs/DocsLayout';
 
 <Meta of={ShowcaseStories} />
@@ -11,11 +12,18 @@ import { DocsCallout, DocsCard, DocsGrid, DocsPage, DocsSection } from '../docs/
 >
   <DocsSection
     title="Manual wallet showcase"
-    description="Use this story when reviewing the widget in a browser that has an injected wallet available. Use the Controls panel below the canvas to preview `defaultTheme` and a sample `themeOverrides` brand preset."
+    description="Use this story when reviewing the widget in a browser that has an injected wallet available. Use the Controls panel below the canvas to preview `defaultTheme`, a sample `themeOverrides` brand preset, and the deployed `environment` (development/production only — staging is never offered)."
   >
     <Canvas of={ShowcaseStories.InjectedWallet} />
   </DocsSection>
 
+  <DocsSection
+    title="Theme overrides"
+    description="Play around with the primitive Card/Button theme overrides using the controls below. Both are demonstrated on surfaces confirmed to actually render through the plain primitive, not the widget's own named ClaimCard/ClaimActionButton sub-themes — see the callout below the code for why those need a dedicated preset instead."
+  >
+    <Canvas of={ThemeOverridesStories.Playground} />
+  </DocsSection>
+
   <DocsSection
     title="How to mount it"
     description="Keep the host contract narrow. The widget expects a provider and optional theming inputs."
diff --git a/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetShowcase.stories.tsx b/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetShowcase.stories.tsx
index ea1475e0..9a46c4aa 100644
--- a/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetShowcase.stories.tsx
+++ b/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetShowcase.stories.tsx
@@ -1,13 +1,19 @@
 import type { Meta, StoryObj } from '@storybook/react'
-import { CitizenClaimWidget } from '@goodwidget/citizen-claim-widget'
+import { CitizenClaimWidget, type CitizenClaimWidgetEnvironment } from '@goodwidget/citizen-claim-widget'
 import { InjectedWalletStory } from '../helpers/citizenClaimWidgetStories'
 import { BRAND_PRESET_OPTIONS, brandPresetOverrides, type BrandPreset } from '../helpers/themeOverridePresets'
 
 interface CitizenClaimWidgetStoryArgs {
   defaultTheme: 'light' | 'dark'
   brandPreset: BrandPreset
+  environment: CitizenClaimWidgetEnvironment
 }
 
+// Identity/UBIScheme are deployed on development-celo and production-celo per
+// GoodProtocol's releases/deployment.json — staging is intentionally never
+// offered as a selectable option here, matching every other widget's control.
+const ENVIRONMENT_OPTIONS: CitizenClaimWidgetEnvironment[] = ['development', 'production']
+
 const meta: Meta<CitizenClaimWidgetStoryArgs> = {
   title: 'Widgets/CitizenClaimWidget/Showcase',
   component: CitizenClaimWidget,
@@ -24,10 +30,16 @@ const meta: Meta<CitizenClaimWidgetStoryArgs> = {
       options: BRAND_PRESET_OPTIONS,
       description: 'Sample host-branding themeOverrides preset.',
     },
+    environment: {
+      control: 'radio',
+      options: ENVIRONMENT_OPTIONS,
+      description: 'Deployed GoodProtocol environment passed to the widget’s environment prop.',
+    },
   },
   args: {
     defaultTheme: 'dark',
     brandPreset: 'None',
+    environment: 'development',
   },
 }
 
@@ -35,7 +47,11 @@ export default meta
 type Story = StoryObj<CitizenClaimWidgetStoryArgs>
 
 export const InjectedWallet: Story = {
-  render: ({ defaultTheme, brandPreset }) => (
-    <InjectedWalletStory defaultTheme={defaultTheme} themeOverrides={brandPresetOverrides(brandPreset)} />
+  render: ({ defaultTheme, brandPreset, environment }) => (
+    <InjectedWalletStory
+      defaultTheme={defaultTheme}
+      themeOverrides={brandPresetOverrides(brandPreset)}
+      environment={environment}
+    />
   ),
 }
diff --git a/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetThemeOverrides.stories.tsx b/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetThemeOverrides.stories.tsx
new file mode 100644
index 00000000..5e443d2b
--- /dev/null
+++ b/examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetThemeOverrides.stories.tsx
@@ -0,0 +1,206 @@
+/**
+ * CitizenClaimWidget — Theme Overrides — demonstrates the widget's primitive
+ * theming surface (`Card`/`Button` from `packages/ui`) as live color-picker
+ * controls, following the StreamingWidget/StakingMigrationWidget Theme
+ * overrides pattern for structure (CodeBlock + DocsCallout + live Canvas).
+ *
+ * This widget's own named sub-themes — `ClaimCard`, `ClaimActionButton`,
+ * `ClaimActionGlow` (see packages/citizen-claim-widget/src/CitizenClaimWidget.tsx)
+ * — already have dedicated `light_*`/`dark_*` presets in packages/ui/src/presets.ts,
+ * so overriding the plain `Card`/`Button` theme would be a no-op against the
+ * widget's default claim-tab surface, which renders through those named
+ * components instead. To avoid that no-op, this story targets the two
+ * surfaces confirmed to actually render the plain primitives:
+ *   - the plain `<Button>` on the identity-verification step (shown when the
+ *     connected wallet is not yet whitelisted)
+ *   - the plain `<Card>` placeholder on the Invite Rewards / News tabs
+ * Both are rendered in dark and light side by side so every wired `dark_*`
+ * control has a visibly-exercised `light_*` counterpart, not just a paired
+ * control that happens to exist.
+ *
+ * The identity-verification Button is reached via the custodial local-wallet
+ * fixture (same known, never-whitelisted test key already used in
+ * `QA/CitizenClaimWidget/Runtime Fixtures`), which resolves to the
+ * `not_whitelisted` status against live Celo RPC — the same deterministic
+ * live-RPC approach the Playwright spec for this widget relies on. The Card
+ * placeholder is reached via the widget's own `initialTab` prop, no mocking
+ * required.
+ */
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import type { CitizenClaimWidgetProps } from '@goodwidget/citizen-claim-widget'
+import { CustodialLocalFixtureStory } from '../helpers/citizenClaimWidgetStories'
+import { DocsCallout, DocsList } from '../docs/DocsLayout'
+
+type ThemeOverrides = NonNullable<CitizenClaimWidgetProps['themeOverrides']>
+
+const REFERENCE_ONLY_TARGETS: Array<{ name: string; fields: string[] }> = [
+  { name: 'ClaimCard', fields: ['background', 'borderColor', 'shadowColor'] },
+  { name: 'ClaimActionButton', fields: ['background', 'backgroundHover', 'color'] },
+  { name: 'ClaimActionGlow', fields: ['backgroundColor', 'glowOpacity'] },
+]
+
+function CodeBlock({ children }: { children: string }) {
+  return (
+    <pre
+      style={{
+        background: '#0f172a',
+        border: '1px solid rgba(59,130,246,0.28)',
+        borderRadius: 12,
+        color: '#e2e8f0',
+        fontFamily:
+          'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+        fontSize: 13,
+        lineHeight: 1.6,
+        margin: 0,
+        overflowX: 'auto',
+        padding: 18,
+        whiteSpace: 'pre',
+      }}
+    >
+      {children}
+    </pre>
+  )
+}
+
+interface OverridesArgs {
+  darkCardBackground: string
+  darkCardBorderColor: string
+  lightCardBackground: string
+  lightCardBorderColor: string
+  darkButtonBackground: string
+  darkButtonBackgroundHover: string
+  darkButtonColor: string
+  lightButtonBackground: string
+  lightButtonBackgroundHover: string
+  lightButtonColor: string
+}
+
+function buildThemeOverrides(args: OverridesArgs): ThemeOverrides {
+  return {
+    themes: {
+      dark_Card: {
+        background: args.darkCardBackground,
+        borderColor: args.darkCardBorderColor,
+      },
+      light_Card: {
+        background: args.lightCardBackground,
+        borderColor: args.lightCardBorderColor,
+      },
+      dark_Button: {
+        background: args.darkButtonBackground,
+        backgroundHover: args.darkButtonBackgroundHover,
+        color: args.darkButtonColor,
+      },
+      light_Button: {
+        background: args.lightButtonBackground,
+        backgroundHover: args.lightButtonBackgroundHover,
+        color: args.lightButtonColor,
+      },
+    },
+  }
+}
+
+const meta: Meta<OverridesArgs> = {
+  title: 'Widgets/CitizenClaimWidget/Theme overrides',
+  tags: ['integrator', 'showcase'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    darkCardBackground: { control: 'color', description: 'themes.dark_Card.background' },
+    darkCardBorderColor: { control: 'color', description: 'themes.dark_Card.borderColor' },
+    lightCardBackground: { control: 'color', description: 'themes.light_Card.background' },
+    lightCardBorderColor: { control: 'color', description: 'themes.light_Card.borderColor' },
+    darkButtonBackground: { control: 'color', description: 'themes.dark_Button.background' },
+    darkButtonBackgroundHover: { control: 'color', description: 'themes.dark_Button.backgroundHover' },
+    darkButtonColor: { control: 'color', description: 'themes.dark_Button.color' },
+    lightButtonBackground: { control: 'color', description: 'themes.light_Button.background' },
+    lightButtonBackgroundHover: { control: 'color', description: 'themes.light_Button.backgroundHover' },
+    lightButtonColor: { control: 'color', description: 'themes.light_Button.color' },
+  },
+  args: {
+    darkCardBackground: '#1e1b4b',
+    darkCardBorderColor: '#7C3AED',
+    lightCardBackground: '#f5f3ff',
+    lightCardBorderColor: '#7C3AED',
+    darkButtonBackground: '#7C3AED',
+    darkButtonBackgroundHover: '#6D28D9',
+    darkButtonColor: '#FFFFFF',
+    lightButtonBackground: '#7C3AED',
+    lightButtonBackgroundHover: '#6D28D9',
+    lightButtonColor: '#FFFFFF',
+  },
+}
+export default meta
+type Story = StoryObj<OverridesArgs>
+
+export const Playground: Story = {
+  render: (args) => {
+    const themeOverrides = buildThemeOverrides(args)
+    return (
+      <div style={{ display: 'grid', gap: 24, maxWidth: 960, margin: '0 auto' }}>
+        <CodeBlock>
+          {`<CitizenClaimWidget\n  themeOverrides={${JSON.stringify(themeOverrides, null, 2)}}\n/>`}
+        </CodeBlock>
+
+        <DocsCallout title="All overridable paths on CitizenClaimWidget" tone="info">
+          <DocsList>
+            <li>
+              <strong>dark_Card / light_Card</strong>: background, color, borderColor, shadowColor —
+              background and borderColor wired to the controls above; demonstrated on the Invite
+              Rewards/News placeholder below, the only plain-Card surface this widget renders
+            </li>
+            <li>
+              <strong>dark_Button / light_Button</strong>: background, backgroundHover,
+              backgroundPress, backgroundFocus, color, borderColor, borderColorFocus, shadowColor —
+              background, backgroundHover, and color wired to the controls above; demonstrated on the
+              identity-verification Verify button below, the only plain-Button surface this widget
+              renders
+            </li>
+            {REFERENCE_ONLY_TARGETS.map((target) => (
+              <li key={target.name}>
+                <strong>
+                  dark_{target.name} / light_{target.name}
+                </strong>
+                : {target.fields.join(', ')} — already has a dedicated preset in packages/ui, so a
+                plain Card/Button override does not reach it
+              </li>
+            ))}
+          </DocsList>
+        </DocsCallout>
+
+        <DocsCallout title="Why two columns" tone="info">
+          Each surface renders once in dark and once in light so every wired `light_*` control has a
+          visibly-exercised counterpart, not just a paired value that happens to exist.
+        </DocsCallout>
+
+        <div>
+          <p style={{ fontWeight: 600, marginBottom: 8 }}>
+            Button surface — identity verification step (not-whitelisted custodial fixture)
+          </p>
+          <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
+            <CustodialLocalFixtureStory defaultTheme="dark" themeOverrides={themeOverrides} />
+            <CustodialLocalFixtureStory defaultTheme="light" themeOverrides={themeOverrides} />
+          </div>
+        </div>
+
+        <div>
+          <p style={{ fontWeight: 600, marginBottom: 8 }}>
+            Card surface — Invite Rewards / News tab placeholder
+          </p>
+          <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
+            <CustodialLocalFixtureStory
+              defaultTheme="dark"
+              themeOverrides={themeOverrides}
+              initialTab="invite-rewards"
+            />
+            <CustodialLocalFixtureStory
+              defaultTheme="light"
+              themeOverrides={themeOverrides}
+              initialTab="invite-rewards"
+            />
+          </div>
+        </div>
+      </div>
+    )
+  },
+}
diff --git a/examples/storybook/src/stories/gooddata-widget/GoodDataWidget.mdx b/examples/storybook/src/stories/gooddata-widget/GoodDataWidget.mdx
new file mode 100644
index 00000000..782179f7
--- /dev/null
+++ b/examples/storybook/src/stories/gooddata-widget/GoodDataWidget.mdx
@@ -0,0 +1,48 @@
+import { Canvas, Meta } from '@storybook/blocks';
+import * as ShowcaseStories from './GoodDataWidgetShowcase.stories';
+import * as ThemeOverridesStories from './GoodDataWidgetThemeOverrides.stories';
+import { DocsCallout, DocsCard, DocsPage, DocsSection } from '../docs/DocsLayout';
+
+<Meta of={ShowcaseStories} />
+
+<DocsPage
+  eyebrow="Widget Guide"
+  title="GoodDataWidget"
+  lead="Hosts a registry of analytics dashboards and renders the single registered dashboard directly — today that is the AiCreditsDashboard, showing G$ deposit/stream volume and AI-credit usage sourced from the AntSeed Worker."
+>
+  <DocsSection
+    title="Live showcase"
+    description="Renders AiCreditsDashboard with no mockState, so it fetches real analytics from the live aiCredits connector (the AntSeed Worker) instead of a fixture. Use this story to validate the real integration end to end."
+  >
+    <Canvas of={ShowcaseStories.LiveConnector} />
+  </DocsSection>
+
+  <DocsSection
+    title="Theme overrides"
+    description="Play around with the primitive Button theme override using the controls below, demonstrated side by side in dark and light against a fixed demo dataset. GoodDataWidget has no themeOverrides prop of its own and no named theme-component module, so dark_Button/light_Button is its only override path; it also renders no Card anywhere in its source, so there is no Card control here."
+  >
+    <Canvas of={ThemeOverridesStories.Playground} />
+  </DocsSection>
+
+  <DocsSection
+    title="QA coverage"
+    description="Deterministic fixtures covering every data state the dashboard can be in: loading, a populated live response, the demo dataset, the live-connector-unavailable fallback, and an empty response."
+  >
+    <DocsCard
+      title="Open the QA fixture demo"
+      href="?path=/story/qa-gooddatawidget-runtime-fixtures--loading"
+    >
+      `Loading` / `Live` / `Demo` / `LiveUnavailable` / `Empty` cover the dashboard's full data-state
+      matrix against a fixed, non-random fixture so every render is reproducible across runs.
+    </DocsCard>
+  </DocsSection>
+
+  <DocsSection title="Workflow guidance" description="Choose the story type based on the job you are trying to do.">
+    <DocsCallout title="Rule of use" tone="info">
+      Use the showcase story to validate the real `aiCredits` connector end to end. Use the theme
+      overrides playground to check how host theming cascades into the dashboard's Button surface.
+      Use the QA fixtures to verify each individual data state renders correctly against a fixed
+      dataset.
+    </DocsCallout>
+  </DocsSection>
+</DocsPage>
diff --git a/examples/storybook/src/stories/gooddata-widget/GoodDataWidgetQA.stories.tsx b/examples/storybook/src/stories/gooddata-widget/GoodDataWidgetQA.stories.tsx
index cc24de3c..4d0f2dfc 100644
--- a/examples/storybook/src/stories/gooddata-widget/GoodDataWidgetQA.stories.tsx
+++ b/examples/storybook/src/stories/gooddata-widget/GoodDataWidgetQA.stories.tsx
@@ -9,7 +9,7 @@ import {
 } from '../helpers/goodDataWidgetStories'
 
 const meta: Meta<typeof AiCreditsDashboard> = {
-  title: 'QA/AiCreditsDashboard/Runtime Fixtures',
+  title: 'QA/GoodDataWidget/Runtime Fixtures',
   component: AiCreditsDashboard,
   tags: ['autodocs', 'qa'],
   args: {},
diff --git a/examples/storybook/src/stories/gooddata-widget/GoodDataWidgetShowcase.stories.tsx b/examples/storybook/src/stories/gooddata-widget/GoodDataWidgetShowcase.stories.tsx
new file mode 100644
index 00000000..02e3d487
--- /dev/null
+++ b/examples/storybook/src/stories/gooddata-widget/GoodDataWidgetShowcase.stories.tsx
@@ -0,0 +1,19 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { AiCreditsDashboard } from '@goodwidget/gooddata-widget'
+import { AiCreditsDashboardLiveConnectorStory } from '../helpers/goodDataWidgetStories'
+
+const meta: Meta<typeof AiCreditsDashboard> = {
+  title: 'Widgets/GoodDataWidget/Showcase',
+  component: AiCreditsDashboard,
+  tags: ['integrator', 'manual', 'showcase'],
+  args: {},
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof AiCreditsDashboard>
+
+/** Real `aiCredits` connector — fetches live analytics from the AntSeed Worker, not a fixture. */
+export const LiveConnector: Story = {
+  name: 'Live Connector',
+  render: () => <AiCreditsDashboardLiveConnectorStory />,
+}
diff --git a/examples/storybook/src/stories/gooddata-widget/GoodDataWidgetThemeOverrides.stories.tsx b/examples/storybook/src/stories/gooddata-widget/GoodDataWidgetThemeOverrides.stories.tsx
new file mode 100644
index 00000000..2f3f494e
--- /dev/null
+++ b/examples/storybook/src/stories/gooddata-widget/GoodDataWidgetThemeOverrides.stories.tsx
@@ -0,0 +1,198 @@
+/**
+ * GoodDataWidget — Theme Overrides — demonstrates the widget's primitive
+ * `Button` theme target as live color-picker controls, following the
+ * GoodReserveWidget/AiCreditsWidget Theme overrides pattern for structure
+ * (CodeBlock + DocsCallout + live Canvas).
+ *
+ * Button-only, no Card control: confirmed via `grep -rln "Card"
+ * packages/gooddata-widget/src` (zero matches) that this widget never
+ * renders a `Card` anywhere in its source — a dark_Card/light_Card control
+ * would be a no-op, so it is intentionally omitted rather than wired as a
+ * silent no-op.
+ *
+ * The demo fixture state uses the "demo" mockState (fixed, deterministic
+ * data) rather than the live connector, so the Theme overrides controls
+ * stay reproducible regardless of the AntSeed Worker's live availability.
+ * It renders the refresh button, the Live/Demo data-source toggle buttons,
+ * and the paginated table's First/Prev/Next/Last buttons together.
+ */
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { TamaguiProvider } from '@tamagui/core'
+import { createGoodWidgetConfig } from '@goodwidget/ui'
+import { AiCreditsDashboard, type AnalyticsResponse } from '@goodwidget/gooddata-widget'
+import { DocsCallout, DocsList } from '../docs/DocsLayout'
+
+// Fixed (non-random, non-"now") fixture so the Playground renders identically on every load.
+const DEMO_ANALYTICS_RESPONSE: AnalyticsResponse = {
+  days: 3,
+  daily: [
+    {
+      date: '2026-01-01',
+      gdOneTimeDepositsWei: '1000000000000000000000',
+      gdStreamedWei: '250000000000000000000',
+      gdTotalFlowRateWeiPerSecond: '2000000000000000',
+      aiCreditsUsedWei: '50000000',
+      uniqueGdSigners: 4,
+      uniqueCreditUsers: 2,
+      updatedAt: '2026-01-02T00:00:00.000Z',
+      missing: false,
+    },
+    {
+      date: '2026-01-02',
+      gdOneTimeDepositsWei: '1500000000000000000000',
+      gdStreamedWei: '280000000000000000000',
+      gdTotalFlowRateWeiPerSecond: '3000000000000000',
+      aiCreditsUsedWei: '75000000',
+      uniqueGdSigners: 6,
+      uniqueCreditUsers: 3,
+      updatedAt: '2026-01-03T00:00:00.000Z',
+      missing: false,
+    },
+    {
+      date: '2026-01-03',
+      gdOneTimeDepositsWei: '2000000000000000000000',
+      gdStreamedWei: '370000000000000000000',
+      gdTotalFlowRateWeiPerSecond: '4000000000000000',
+      aiCreditsUsedWei: '100000000',
+      uniqueGdSigners: 8,
+      uniqueCreditUsers: 5,
+      updatedAt: '2026-01-04T00:00:00.000Z',
+      missing: false,
+    },
+  ],
+  global: {
+    gdOneTimeDepositsWei: '4500000000000000000000',
+    gdStreamedWei: '900000000000000000000',
+    aiCreditsUsedWei: '225000000',
+    gdTotalFlowRateWeiPerSecond: '4000000000000000',
+    updatedAt: '2026-01-04T00:00:00.000Z',
+  },
+  lastRun: {
+    currentDate: '2026-01-04',
+    updatedAt: '2026-01-04T00:00:00.000Z',
+  },
+}
+
+function CodeBlock({ children }: { children: string }) {
+  return (
+    <pre
+      style={{
+        background: '#0f172a',
+        color: '#e2e8f0',
+        padding: 16,
+        borderRadius: 8,
+        overflowX: 'auto',
+        fontSize: 13,
+        lineHeight: 1.5,
+      }}
+    >
+      <code>{children}</code>
+    </pre>
+  )
+}
+
+interface OverridesArgs {
+  darkButtonBackground: string
+  darkButtonBackgroundHover: string
+  darkButtonColor: string
+  lightButtonBackground: string
+  lightButtonBackgroundHover: string
+  lightButtonColor: string
+}
+
+function buildThemeOverrides(args: OverridesArgs) {
+  return {
+    themes: {
+      dark_Button: {
+        background: args.darkButtonBackground,
+        backgroundHover: args.darkButtonBackgroundHover,
+        color: args.darkButtonColor,
+      },
+      light_Button: {
+        background: args.lightButtonBackground,
+        backgroundHover: args.lightButtonBackgroundHover,
+        color: args.lightButtonColor,
+      },
+    },
+  }
+}
+
+const meta: Meta<OverridesArgs> = {
+  title: 'Widgets/GoodDataWidget/Theme overrides',
+  tags: ['integrator', 'showcase'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    darkButtonBackground: { control: 'color', description: 'themes.dark_Button.background' },
+    darkButtonBackgroundHover: {
+      control: 'color',
+      description: 'themes.dark_Button.backgroundHover',
+    },
+    darkButtonColor: { control: 'color', description: 'themes.dark_Button.color' },
+    lightButtonBackground: { control: 'color', description: 'themes.light_Button.background' },
+    lightButtonBackgroundHover: {
+      control: 'color',
+      description: 'themes.light_Button.backgroundHover',
+    },
+    lightButtonColor: { control: 'color', description: 'themes.light_Button.color' },
+  },
+  args: {
+    darkButtonBackground: '#7C3AED',
+    darkButtonBackgroundHover: '#6D28D9',
+    darkButtonColor: '#FFFFFF',
+    lightButtonBackground: '#7C3AED',
+    lightButtonBackgroundHover: '#6D28D9',
+    lightButtonColor: '#FFFFFF',
+  },
+}
+export default meta
+type Story = StoryObj<OverridesArgs>
+
+export const Playground: Story = {
+  render: (args) => {
+    const themeOverrides = buildThemeOverrides(args)
+    // GoodDataWidget has no GoodWidgetProvider/themeOverrides prop of its own
+    // (it only ever receives a bare TamaguiProvider from its host), so this
+    // Playground builds the same merged Tamagui config createGoodWidgetConfig
+    // produces inside every other widget's provider, instead of relying on
+    // a themeOverrides prop that doesn't exist here.
+    const tamaguiConfig = createGoodWidgetConfig(themeOverrides)
+    return (
+      <div style={{ display: 'grid', gap: 24, maxWidth: 960, margin: '0 auto' }}>
+        <CodeBlock>
+          {`// GoodDataWidget has no themeOverrides prop — the host's own\n// TamaguiProvider owns theming, same as createGoodWidgetConfig()\n// does inside every other widget's GoodWidgetProvider:\nconst config = createGoodWidgetConfig(${JSON.stringify(themeOverrides, null, 2)})\n<TamaguiProvider config={config}>\n  <GoodDataWidget />\n</TamaguiProvider>`}
+        </CodeBlock>
+        <DocsCallout title="All overridable paths on GoodDataWidget" tone="info">
+          <DocsList>
+            <li>
+              <strong>dark_Button / light_Button</strong>: the refresh button, the Live/Demo
+              data-source toggle, and the paginated table&apos;s First/Prev/Next/Last buttons all
+              cascade from this theme — demonstrated below.
+            </li>
+          </DocsList>
+        </DocsCallout>
+        <DocsCallout title="No Card control" tone="warning">
+          GoodDataWidget renders no `Card` anywhere in its source (confirmed via grep), so a
+          dark_Card/light_Card control would be a no-op here and is intentionally omitted.
+        </DocsCallout>
+        <div>
+          <p style={{ fontWeight: 600, marginBottom: 8 }}>
+            Demo dataset — refresh button, data-source toggle, and pagination together
+          </p>
+          <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
+            <div data-testid="GoodDataWidget-theme-overrides-dark">
+              <TamaguiProvider config={tamaguiConfig} defaultTheme="dark">
+                <AiCreditsDashboard mockState={{ kind: 'demo', response: DEMO_ANALYTICS_RESPONSE }} />
+              </TamaguiProvider>
+            </div>
+            <div data-testid="GoodDataWidget-theme-overrides-light">
+              <TamaguiProvider config={tamaguiConfig} defaultTheme="light">
+                <AiCreditsDashboard mockState={{ kind: 'demo', response: DEMO_ANALYTICS_RESPONSE }} />
+              </TamaguiProvider>
+            </div>
+          </div>
+        </div>
+      </div>
+    )
+  },
+}
diff --git a/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidget.mdx b/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidget.mdx
new file mode 100644
index 00000000..f67d70ff
--- /dev/null
+++ b/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidget.mdx
@@ -0,0 +1,97 @@
+import { Canvas, Meta, Source } from '@storybook/blocks';
+import * as ShowcaseStories from './GoodReserveWidgetShowcase.stories';
+import * as ThemeOverridesStories from './GoodReserveWidgetThemeOverrides.stories';
+import { DocsCallout, DocsCard, DocsGrid, DocsPage, DocsSection } from '../docs/DocsLayout';
+
+<Meta of={ShowcaseStories} />
+
+<DocsPage
+  eyebrow="Widget Guide"
+  title="GoodReserveWidget"
+  lead="This widget combines a product-facing live-wallet showcase with deterministic swap-state fixtures for QA, screenshots, and state-flow validation."
+>
+  <DocsSection
+    title="Manual wallet showcase"
+    description="Use these stories when reviewing the live buy/sell swap flow against a real reserve quote. `Interactive` uses a known custodial test wallet so the amount-input and quote wiring run against the real adapter; `InjectedWallet` and `LiveWallet` connect to whatever EIP-1193 wallet extension is available in the browser."
+  >
+    <Canvas of={ShowcaseStories.Interactive} />
+  </DocsSection>
+
+  <DocsSection
+    title="Theme overrides"
+    description="Play around with the primitive Card/Button theme overrides using the controls below. Both are demonstrated on the idle-buy fixture state, which renders the outer swap card, the amount panels, and the primary CTA button together in a single view."
+  >
+    <Canvas of={ThemeOverridesStories.Playground} />
+  </DocsSection>
+
+  <DocsSection
+    title="How to mount it"
+    description="Keep the host contract narrow. The widget expects a provider and optional theming inputs."
+  >
+    <Source
+      dark
+      language="tsx"
+      code={`import { GoodReserveWidget } from '@goodwidget/goodreserve-widget'
+import { MiniAppShell } from '@goodwidget/ui'
+
+export function ReservePanel({ provider }: { provider?: unknown }) {
+  return (
+    <MiniAppShell title="GoodDollar">
+      <GoodReserveWidget
+        provider={provider}
+        defaultTheme="dark"
+        onSwapSuccess={(detail) => console.log('swap succeeded', detail)}
+        onSwapError={(detail) => console.log('swap failed', detail)}
+      />
+    </MiniAppShell>
+  )
+}`}
+    />
+  </DocsSection>
+
+  <DocsSection
+    title="QA coverage"
+    description="Deterministic swap states live in a dedicated QA story file so visual regression, fixture review, and debugging stay reproducible."
+  >
+    <DocsCard
+      title="Open the QA fixture demo"
+      href="?path=/story/qa-goodreservewidget-runtime-fixtures--no-provider"
+    >
+      No provider, SDK initializing, unsupported chain, idle/amount-editing, quote loading/ready/error,
+      slippage, confirm, approval, swap pending/success/error, and light theme fixture states live in
+      `QA / GoodReserveWidget / Runtime Fixtures`.
+    </DocsCard>
+  </DocsSection>
+
+  <DocsSection
+    title="Why this widget is split"
+    description="The runtime-connected swap path is useful for manual validation, while the quote/swap-state fixtures are better suited to automation and repeatable review."
+  >
+    <DocsGrid>
+      <DocsCard title="Showcase stories">
+        Manual review in a browser with a live reserve quote and either a custodial test wallet or an
+        injected wallet extension.
+      </DocsCard>
+      <DocsCard title="QA stories">
+        Controlled swap states for screenshots, automation, and debugging without live runtime
+        dependencies.
+      </DocsCard>
+    </DocsGrid>
+  </DocsSection>
+
+  <DocsSection
+    title="Workflow guidance"
+    description="Choose the story type based on whether you are reviewing integration behavior or validating deterministic widget states."
+  >
+    <DocsCallout title="Rule of use" tone="info">
+      Use the showcase story for product-facing swap checks. Use the QA fixtures when you need
+      repeatable screenshots, runtime-state coverage, or debugging.
+    </DocsCallout>
+    <DocsCallout title="No environment control" tone="info">
+      GoodReserveWidget has no `environment` prop anywhere in its current source, so this Showcase
+      page does not offer an environment switcher. Adding one would require a
+      `packages/goodreserve-widget` code change, which is out of scope here — tracked separately in
+      "[BountyPrep] Storybook: missing primitives and design system gaps".
+    </DocsCallout>
+  </DocsSection>
+</DocsPage>
diff --git a/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetQA.stories.tsx b/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetQA.stories.tsx
new file mode 100644
index 00000000..0fc4b2cd
--- /dev/null
+++ b/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetQA.stories.tsx
@@ -0,0 +1,120 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { GoodReserveWidget } from '@goodwidget/goodreserve-widget'
+import { createCustodialEip1193Provider } from '../../fixtures/custodialEip1193'
+import { reserveWidgetMockStates } from '../../fixtures/goodReserveWidgetMock'
+
+const provider = createCustodialEip1193Provider()
+
+const meta: Meta<typeof GoodReserveWidget> = {
+  title: 'QA/GoodReserveWidget/Runtime Fixtures',
+  component: GoodReserveWidget,
+  tags: ['autodocs', 'qa'],
+  parameters: { layout: 'padded' },
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+// Renders one deterministic reserve state per story for CI-safe widget coverage.
+const renderStory = (
+  mockState: Story['args']['mockState'],
+  dataTestId: string,
+  defaultTheme?: 'light' | 'dark',
+) => <GoodReserveWidget provider={provider} mockState={mockState} defaultTheme={defaultTheme} />
+
+export const NoProvider: Story = {
+  render: () => renderStory(reserveWidgetMockStates.noProvider, 'GoodReserveWidget-no-provider'),
+}
+
+export const SdkInitializing: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.sdkInitializing, 'GoodReserveWidget-sdk-initializing'),
+}
+
+export const UnsupportedChain: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.unsupportedChain, 'GoodReserveWidget-unsupported-chain'),
+}
+
+export const IdleBuy: Story = {
+  render: () => renderStory(reserveWidgetMockStates.idleBuy, 'GoodReserveWidget-idle-buy'),
+}
+
+export const AmountEditing: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.amountEditing, 'GoodReserveWidget-amount-editing'),
+}
+
+export const QuoteLoading: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.quoteLoading, 'GoodReserveWidget-quote-loading'),
+}
+
+export const QuoteReadyBuy: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.quoteReady, 'GoodReserveWidget-quote-ready-buy'),
+}
+
+export const QuoteReadyBuyLightTheme: Story = {
+  render: () =>
+    renderStory(
+      reserveWidgetMockStates.quoteReady,
+      'GoodReserveWidget-quote-ready-buy-light',
+      'light',
+    ),
+}
+
+export const QuoteReadySell: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.sellQuoteReady, 'GoodReserveWidget-quote-ready-sell'),
+}
+
+export const QuoteReadyXdc: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.xdcQuoteReady, 'GoodReserveWidget-quote-ready-xdc'),
+}
+
+export const QuoteError: Story = {
+  render: () => renderStory(reserveWidgetMockStates.quoteError, 'GoodReserveWidget-quote-error'),
+}
+
+// Stale-quote recovery: re-quoting automatically with the notice still visible.
+export const QuoteRefreshing: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.quoteRefreshing, 'GoodReserveWidget-quote-refreshing'),
+}
+
+export const InsufficientBalance: Story = {
+  render: () =>
+    renderStory(
+      reserveWidgetMockStates.insufficientBalance,
+      'GoodReserveWidget-insufficient-balance',
+    ),
+}
+
+export const SlippageSelection: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.slippageSelection, 'GoodReserveWidget-slippage-selection'),
+}
+
+export const ConfirmDialog: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.confirmDialog, 'GoodReserveWidget-confirm-dialog'),
+}
+
+export const ApprovalPending: Story = {
+  render: () =>
+    renderStory(reserveWidgetMockStates.approvalPending, 'GoodReserveWidget-approval-pending'),
+}
+
+export const SwapPending: Story = {
+  render: () => renderStory(reserveWidgetMockStates.swapPending, 'GoodReserveWidget-swap-pending'),
+}
+
+export const SwapSuccess: Story = {
+  render: () => renderStory(reserveWidgetMockStates.swapSuccess, 'GoodReserveWidget-swap-success'),
+}
+
+export const SwapError: Story = {
+  render: () => renderStory(reserveWidgetMockStates.swapError, 'GoodReserveWidget-swap-error'),
+}
diff --git a/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidget.stories.tsx b/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetShowcase.stories.tsx
similarity index 52%
rename from examples/storybook/src/stories/goodreserve-widget/GoodReserveWidget.stories.tsx
rename to examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetShowcase.stories.tsx
index 480bea63..a8e4ce3a 100644
--- a/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidget.stories.tsx
+++ b/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetShowcase.stories.tsx
@@ -6,128 +6,22 @@ import {
   getInjectedEip1193Provider,
   isInjectedProviderUsable,
 } from '../../fixtures/injectedEip1193'
-import { reserveWidgetMockStates } from '../../fixtures/goodReserveWidgetMock'
 
 const provider = createCustodialEip1193Provider()
 
+// GoodReserveWidget has no `environment` prop anywhere in its source (confirmed via
+// grep), so no environment control is offered here — see
+// "[BountyPrep] Storybook: missing primitives and design system gaps" for the logged gap.
 const meta: Meta<typeof GoodReserveWidget> = {
-  title: 'Widgets/GoodReserveWidget',
+  title: 'Widgets/GoodReserveWidget/Showcase',
   component: GoodReserveWidget,
-  tags: ['autodocs'],
+  tags: ['integrator', 'manual', 'showcase'],
   parameters: { layout: 'padded' },
 }
 
 export default meta
 type Story = StoryObj<typeof meta>
 
-// Renders one deterministic reserve state per story for CI-safe widget coverage.
-const renderStory = (
-  mockState: Story['args']['mockState'],
-  dataTestId: string,
-  defaultTheme?: 'light' | 'dark',
-) => (
-  // <div data-testid={dataTestId} style={{ width: 390 }}>
-  <GoodReserveWidget provider={provider} mockState={mockState} defaultTheme={defaultTheme} />
-  // </div>
-)
-
-export const NoProvider: Story = {
-  render: () => renderStory(reserveWidgetMockStates.noProvider, 'GoodReserveWidget-no-provider'),
-}
-
-export const SdkInitializing: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.sdkInitializing, 'GoodReserveWidget-sdk-initializing'),
-}
-
-export const UnsupportedChain: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.unsupportedChain, 'GoodReserveWidget-unsupported-chain'),
-}
-
-export const IdleBuy: Story = {
-  render: () => renderStory(reserveWidgetMockStates.idleBuy, 'GoodReserveWidget-idle-buy'),
-}
-
-export const AmountEditing: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.amountEditing, 'GoodReserveWidget-amount-editing'),
-}
-
-export const QuoteLoading: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.quoteLoading, 'GoodReserveWidget-quote-loading'),
-}
-
-export const QuoteReadyBuy: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.quoteReady, 'GoodReserveWidget-quote-ready-buy'),
-}
-
-export const QuoteReadyBuyLightTheme: Story = {
-  render: () =>
-    renderStory(
-      reserveWidgetMockStates.quoteReady,
-      'GoodReserveWidget-quote-ready-buy-light',
-      'light',
-    ),
-}
-
-export const QuoteReadySell: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.sellQuoteReady, 'GoodReserveWidget-quote-ready-sell'),
-}
-
-export const QuoteReadyXdc: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.xdcQuoteReady, 'GoodReserveWidget-quote-ready-xdc'),
-}
-
-export const QuoteError: Story = {
-  render: () => renderStory(reserveWidgetMockStates.quoteError, 'GoodReserveWidget-quote-error'),
-}
-
-// Stale-quote recovery: re-quoting automatically with the notice still visible.
-export const QuoteRefreshing: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.quoteRefreshing, 'GoodReserveWidget-quote-refreshing'),
-}
-
-export const InsufficientBalance: Story = {
-  render: () =>
-    renderStory(
-      reserveWidgetMockStates.insufficientBalance,
-      'GoodReserveWidget-insufficient-balance',
-    ),
-}
-
-export const SlippageSelection: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.slippageSelection, 'GoodReserveWidget-slippage-selection'),
-}
-
-export const ConfirmDialog: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.confirmDialog, 'GoodReserveWidget-confirm-dialog'),
-}
-
-export const ApprovalPending: Story = {
-  render: () =>
-    renderStory(reserveWidgetMockStates.approvalPending, 'GoodReserveWidget-approval-pending'),
-}
-
-export const SwapPending: Story = {
-  render: () => renderStory(reserveWidgetMockStates.swapPending, 'GoodReserveWidget-swap-pending'),
-}
-
-export const SwapSuccess: Story = {
-  render: () => renderStory(reserveWidgetMockStates.swapSuccess, 'GoodReserveWidget-swap-success'),
-}
-
-export const SwapError: Story = {
-  render: () => renderStory(reserveWidgetMockStates.swapError, 'GoodReserveWidget-swap-error'),
-}
-
 // Live adapter (no mockState) so the real amount-input wiring is exercised.
 // Used by the Playwright "types into the input" coverage. The SDK is now
 // statically imported and reaches the real getReserveStats/getBuyQuote path
diff --git a/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetThemeOverrides.stories.tsx b/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetThemeOverrides.stories.tsx
new file mode 100644
index 00000000..f694abdb
--- /dev/null
+++ b/examples/storybook/src/stories/goodreserve-widget/GoodReserveWidgetThemeOverrides.stories.tsx
@@ -0,0 +1,187 @@
+/**
+ * GoodReserveWidget — Theme Overrides — demonstrates the widget's primitive
+ * theming surface (`Card`/`Button` from `packages/ui`) as live color-picker
+ * controls, following the StreamingWidget/StakingMigrationWidget Theme
+ * overrides pattern for structure (CodeBlock + DocsCallout + live Canvas).
+ *
+ * This widget's own named sub-themes — `ReserveSwapShell`, `ReserveAmountCard`,
+ * `ReserveSurface`, `ReserveSurfaceInner`, `ReserveDetailsTable`,
+ * `ReserveTokenBadge`, `ReserveSwapDirectionButton`, `ReserveSettingsButton`,
+ * `ReserveSuccessIcon`, `ReserveConfirmToBadge` (see
+ * packages/goodreserve-widget/src/ReserveSwapView.tsx) — have no dedicated
+ * `light_*`/`dark_*` presets in packages/ui/src/presets.ts (confirmed via
+ * grep), so they correctly cascade from the plain `Card`/`Button` theme
+ * instead of overriding it, unlike CitizenClaimWidget's `ClaimCard` family.
+ * A `dark_Card`/`dark_Button` override is NOT a no-op here.
+ *
+ * The idle-buy fixture state is used because it renders the outer swap card
+ * (`ReserveSwapShell`, extends Card), the amount panels (`ReserveAmountCard`,
+ * extends Card), and the plain primary-CTA `<Button>` together in one state,
+ * so a single pair of dark/light instances exercises both targets at once.
+ */
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { GoodReserveWidget, type ReserveSwapWidgetProps } from '@goodwidget/goodreserve-widget'
+import { createCustodialEip1193Provider } from '../../fixtures/custodialEip1193'
+import { reserveWidgetMockStates } from '../../fixtures/goodReserveWidgetMock'
+import { DocsCallout, DocsList } from '../docs/DocsLayout'
+
+const provider = createCustodialEip1193Provider()
+
+type ThemeOverrides = NonNullable<ReserveSwapWidgetProps['themeOverrides']>
+
+function CodeBlock({ children }: { children: string }) {
+  return (
+    <pre
+      style={{
+        background: '#0f172a',
+        border: '1px solid rgba(59,130,246,0.28)',
+        borderRadius: 12,
+        color: '#e2e8f0',
+        fontFamily:
+          'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+        fontSize: 13,
+        lineHeight: 1.6,
+        margin: 0,
+        overflowX: 'auto',
+        padding: 18,
+        whiteSpace: 'pre',
+      }}
+    >
+      {children}
+    </pre>
+  )
+}
+
+interface OverridesArgs {
+  darkCardBackground: string
+  darkCardBorderColor: string
+  lightCardBackground: string
+  lightCardBorderColor: string
+  darkButtonBackground: string
+  darkButtonBackgroundHover: string
+  darkButtonColor: string
+  lightButtonBackground: string
+  lightButtonBackgroundHover: string
+  lightButtonColor: string
+}
+
+function buildThemeOverrides(args: OverridesArgs): ThemeOverrides {
+  return {
+    themes: {
+      dark_Card: {
+        background: args.darkCardBackground,
+        borderColor: args.darkCardBorderColor,
+      },
+      light_Card: {
+        background: args.lightCardBackground,
+        borderColor: args.lightCardBorderColor,
+      },
+      dark_Button: {
+        background: args.darkButtonBackground,
+        backgroundHover: args.darkButtonBackgroundHover,
+        color: args.darkButtonColor,
+      },
+      light_Button: {
+        background: args.lightButtonBackground,
+        backgroundHover: args.lightButtonBackgroundHover,
+        color: args.lightButtonColor,
+      },
+    },
+  }
+}
+
+const meta: Meta<OverridesArgs> = {
+  title: 'Widgets/GoodReserveWidget/Theme overrides',
+  tags: ['integrator', 'showcase'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    darkCardBackground: { control: 'color', description: 'themes.dark_Card.background' },
+    darkCardBorderColor: { control: 'color', description: 'themes.dark_Card.borderColor' },
+    lightCardBackground: { control: 'color', description: 'themes.light_Card.background' },
+    lightCardBorderColor: { control: 'color', description: 'themes.light_Card.borderColor' },
+    darkButtonBackground: { control: 'color', description: 'themes.dark_Button.background' },
+    darkButtonBackgroundHover: { control: 'color', description: 'themes.dark_Button.backgroundHover' },
+    darkButtonColor: { control: 'color', description: 'themes.dark_Button.color' },
+    lightButtonBackground: { control: 'color', description: 'themes.light_Button.background' },
+    lightButtonBackgroundHover: { control: 'color', description: 'themes.light_Button.backgroundHover' },
+    lightButtonColor: { control: 'color', description: 'themes.light_Button.color' },
+  },
+  args: {
+    darkCardBackground: '#1e1b4b',
+    darkCardBorderColor: '#7C3AED',
+    lightCardBackground: '#f5f3ff',
+    lightCardBorderColor: '#7C3AED',
+    darkButtonBackground: '#7C3AED',
+    darkButtonBackgroundHover: '#6D28D9',
+    darkButtonColor: '#FFFFFF',
+    lightButtonBackground: '#7C3AED',
+    lightButtonBackgroundHover: '#6D28D9',
+    lightButtonColor: '#FFFFFF',
+  },
+}
+export default meta
+type Story = StoryObj<OverridesArgs>
+
+export const Playground: Story = {
+  render: (args) => {
+    const themeOverrides = buildThemeOverrides(args)
+    return (
+      <div style={{ display: 'grid', gap: 24, maxWidth: 960, margin: '0 auto' }}>
+        <CodeBlock>
+          {`<GoodReserveWidget\n  themeOverrides={${JSON.stringify(themeOverrides, null, 2)}}\n/>`}
+        </CodeBlock>
+
+        <DocsCallout title="All overridable paths on GoodReserveWidget" tone="info">
+          <DocsList>
+            <li>
+              <strong>dark_Card / light_Card</strong>: background, color, borderColor, shadowColor —
+              background and borderColor wired to the controls above; demonstrated below on the
+              outer swap shell and the two amount panels, all of which extend the plain Card theme
+              with no dedicated preset of their own
+            </li>
+            <li>
+              <strong>dark_Button / light_Button</strong>: background, backgroundHover,
+              backgroundPress, backgroundFocus, color, borderColor, borderColorFocus, shadowColor —
+              background, backgroundHover, and color wired to the controls above; demonstrated below
+              on the primary CTA button
+            </li>
+            <li>
+              <strong>
+                dark_ReserveSwapShell / dark_ReserveAmountCard / dark_ReserveSurface / etc.
+              </strong>
+              : no dedicated preset exists for any named ReserveSwapView target (confirmed via
+              packages/ui/src/presets.ts), so they already cascade from Card/Button above — no
+              separate named-target controls are needed to reach them
+            </li>
+          </DocsList>
+        </DocsCallout>
+
+        <DocsCallout title="Why two columns" tone="info">
+          Each surface renders once in dark and once in light so every wired `light_*` control has a
+          visibly-exercised counterpart, not just a paired value that happens to exist.
+        </DocsCallout>
+
+        <div>
+          <p style={{ fontWeight: 600, marginBottom: 8 }}>
+            Idle-buy state — outer swap card, amount panels, and primary CTA button together
+          </p>
+          <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
+            <GoodReserveWidget
+              provider={provider}
+              mockState={reserveWidgetMockStates.idleBuy}
+              defaultTheme="dark"
+              themeOverrides={themeOverrides}
+            />
+            <GoodReserveWidget
+              provider={provider}
+              mockState={reserveWidgetMockStates.idleBuy}
+              defaultTheme="light"
+              themeOverrides={themeOverrides}
+            />
+          </div>
+        </div>
+      </div>
+    )
+  },
+}
diff --git a/examples/storybook/src/stories/governance-widget/GovernanceOnboarding.stories.tsx b/examples/storybook/src/stories/governance-widget/GovernanceOnboarding.stories.tsx
index 8d4e7875..e6dd3ed8 100644
--- a/examples/storybook/src/stories/governance-widget/GovernanceOnboarding.stories.tsx
+++ b/examples/storybook/src/stories/governance-widget/GovernanceOnboarding.stories.tsx
@@ -16,9 +16,9 @@ import {
 import { createCustodialEip1193Provider } from '../../fixtures/custodialEip1193'
 
 const meta: Meta<typeof GovernanceOnboardingWidget> = {
-  title: 'Widgets/GovernanceOnboarding',
+  title: 'QA/GovernanceWidget/Onboarding',
   component: GovernanceOnboardingWidget,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'qa'],
   parameters: {
     layout: 'padded',
     width: '100%',
diff --git a/examples/storybook/src/stories/governance-widget/GovernanceWidget.mdx b/examples/storybook/src/stories/governance-widget/GovernanceWidget.mdx
index f9ff004d..33034737 100644
--- a/examples/storybook/src/stories/governance-widget/GovernanceWidget.mdx
+++ b/examples/storybook/src/stories/governance-widget/GovernanceWidget.mdx
@@ -104,5 +104,10 @@ export function GovernancePanel({ provider }: { provider?: unknown }) {
       QA fixtures for repeatable screenshots and state coverage, and the live mocked-data flow when
       you need to manually exercise the real runtime without a live contract.
     </DocsCallout>
+    <DocsCallout title="Development only" tone="info">
+      `GoodDaoHouses` is currently deployed on `development-celo` only — it has no `staging-celo`
+      or `production-celo` entry in GoodProtocol's `releases/deployment.json`. Because there is
+      only one deployed value, this Showcase page offers no environment-switcher control.
+    </DocsCallout>
   </DocsSection>
 </DocsPage>
diff --git a/examples/storybook/src/stories/helpers/citizenClaimWidgetStories.tsx b/examples/storybook/src/stories/helpers/citizenClaimWidgetStories.tsx
index 171fe6e4..acd609bb 100644
--- a/examples/storybook/src/stories/helpers/citizenClaimWidgetStories.tsx
+++ b/examples/storybook/src/stories/helpers/citizenClaimWidgetStories.tsx
@@ -5,6 +5,7 @@ import {
   CitizenClaimWidget,
   createCitizenClaimWidgetCustodialExecution,
   useCitizenClaimAdapter,
+  type CitizenClaimWidgetEnvironment,
   type CitizenClaimWidgetProps,
 } from '@goodwidget/citizen-claim-widget'
 import {
@@ -70,11 +71,15 @@ function CitizenClaimWidgetStoryShell({
   dataTestId,
   defaultTheme,
   themeOverrides,
+  environment = 'development',
+  initialTab,
 }: {
   provider: unknown
   dataTestId: string
   defaultTheme?: 'light' | 'dark'
   themeOverrides?: CitizenClaimWidgetProps['themeOverrides']
+  environment?: CitizenClaimWidgetEnvironment
+  initialTab?: CitizenClaimWidgetProps['initialTab']
 }) {
   const [activeChainId, setActiveChainId] = useState<number | null>(null)
 
@@ -104,11 +109,12 @@ function CitizenClaimWidgetStoryShell({
   return (
     <CitizenClaimWidget
       provider={provider}
-      environment="development"
+      environment={environment}
       data-testid={dataTestId}
       chainId={activeChainId ?? 42220}
       defaultTheme={defaultTheme}
       themeOverrides={themeOverrides}
+      initialTab={initialTab}
     />
   )
 }
@@ -116,9 +122,11 @@ function CitizenClaimWidgetStoryShell({
 export function InjectedWalletStory({
   defaultTheme,
   themeOverrides,
+  environment,
 }: {
   defaultTheme?: 'light' | 'dark'
   themeOverrides?: CitizenClaimWidgetProps['themeOverrides']
+  environment?: CitizenClaimWidgetEnvironment
 } = {}) {
   const injectedProvider = getInjectedEip1193Provider()
   const usableProvider = isInjectedProviderUsable(injectedProvider)
@@ -141,6 +149,7 @@ export function InjectedWalletStory({
       dataTestId="CitizenClaimWidget-injected-wallet"
       defaultTheme={defaultTheme}
       themeOverrides={themeOverrides}
+      environment={environment}
     />
   )
 }
@@ -148,9 +157,11 @@ export function InjectedWalletStory({
 export function CustodialLocalFixtureStory({
   defaultTheme,
   themeOverrides,
+  initialTab,
 }: {
   defaultTheme?: 'light' | 'dark'
   themeOverrides?: CitizenClaimWidgetProps['themeOverrides']
+  initialTab?: CitizenClaimWidgetProps['initialTab']
 } = {}) {
   try {
     const provider = createCustodialEip1193Provider()
@@ -160,6 +171,7 @@ export function CustodialLocalFixtureStory({
         dataTestId="CitizenClaimWidget-custodial-wallet"
         defaultTheme={defaultTheme}
         themeOverrides={themeOverrides}
+        initialTab={initialTab}
       />
     )
   } catch (error: unknown) {
diff --git a/examples/storybook/src/stories/helpers/goodDataWidgetStories.tsx b/examples/storybook/src/stories/helpers/goodDataWidgetStories.tsx
index 2e94897e..791e93e3 100644
--- a/examples/storybook/src/stories/helpers/goodDataWidgetStories.tsx
+++ b/examples/storybook/src/stories/helpers/goodDataWidgetStories.tsx
@@ -1,7 +1,16 @@
 import React from 'react'
 import { TamaguiProvider } from '@tamagui/core'
 import { defaultConfig } from '@goodwidget/ui'
-import { AiCreditsDashboard, type AnalyticsResponse } from '@goodwidget/gooddata-widget'
+import {
+  AiCreditsDashboard,
+  registerAiCreditsDashboard,
+  type AnalyticsResponse,
+} from '@goodwidget/gooddata-widget'
+
+// Idempotent — registers the real `aiCredits` connector (hits the live
+// AntSeed Worker) against the default worker URL. Safe to call at module
+// scope since repeated calls are no-ops (see registerAiCreditsDashboard).
+registerAiCreditsDashboard()
 
 // Fixed (non-random, non-"now") fixture so every render and screenshot is byte-identical across runs.
 const FIXED_ANALYTICS_RESPONSE: AnalyticsResponse = {
@@ -109,3 +118,12 @@ export function AiCreditsDashboardEmptyStory() {
     </GoodDataWidgetStoryShell>
   )
 }
+
+/** No mockState — renders AiCreditsDashboardLive, which fetches from the real `aiCredits` connector (the live AntSeed Worker), not a fixture. */
+export function AiCreditsDashboardLiveConnectorStory() {
+  return (
+    <GoodDataWidgetStoryShell dataTestId="GoodDataWidget-live-connector">
+      <AiCreditsDashboard />
+    </GoodDataWidgetStoryShell>
+  )
+}
diff --git a/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidget.mdx b/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidget.mdx
index 3115ea54..17614a1d 100644
--- a/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidget.mdx
+++ b/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidget.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Meta } from '@storybook/blocks';
 import * as ShowcaseStories from './SuperfluidCampaignWidget.stories';
+import * as ThemeOverridesStories from './SuperfluidCampaignWidgetThemeOverrides.stories';
 import { DocsCallout, DocsCard, DocsGrid, DocsPage, DocsSection } from '../docs/DocsLayout';
 
 <Meta of={ShowcaseStories} />
@@ -16,6 +17,13 @@ import { DocsCallout, DocsCard, DocsGrid, DocsPage, DocsSection } from '../docs/
     <Canvas of={ShowcaseStories.InjectedWallet} />
   </DocsSection>
 
+  <DocsSection
+    title="Theme overrides"
+    description="Play around with the primitive Card/Button theme overrides using the controls below. Both are demonstrated on the content view with a populated leaderboard, which renders the outer shell card, an action card, and their CTA buttons together in a single view. This widget has no named theme-component module, so dark_Card/light_Card/dark_Button/light_Button are its only override paths."
+  >
+    <Canvas of={ThemeOverridesStories.Playground} />
+  </DocsSection>
+
   <DocsSection
     title="QA coverage"
     description="Deterministic fixtures for the disconnected (public) and connected views, and the leaderboard view, matching the two approved #127 mockups."
diff --git a/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidgetApiContracts.stories.tsx b/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidgetApiContracts.stories.tsx
index c8a0f5ca..ea1e16ed 100644
--- a/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidgetApiContracts.stories.tsx
+++ b/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidgetApiContracts.stories.tsx
@@ -3,7 +3,7 @@ import { SuperfluidCampaignWidget } from '@goodwidget/superfluid-campaign-widget
 import { LiveDataNoWalletStory } from '../helpers/superfluidCampaignWidgetStories'
 
 const meta: Meta<typeof SuperfluidCampaignWidget> = {
-  title: 'Widgets/SuperfluidCampaignWidget/API Contracts',
+  title: 'QA/SuperfluidCampaignWidget/API Contracts',
   component: SuperfluidCampaignWidget,
   tags: ['integration'],
   parameters: { layout: 'padded' },
diff --git a/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidgetThemeOverrides.stories.tsx b/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidgetThemeOverrides.stories.tsx
new file mode 100644
index 00000000..79305fe2
--- /dev/null
+++ b/examples/storybook/src/stories/superfluid-campaign-widget/SuperfluidCampaignWidgetThemeOverrides.stories.tsx
@@ -0,0 +1,183 @@
+/**
+ * SuperfluidCampaignWidget — Theme Overrides — demonstrates the widget's
+ * primitive theming surface (`Card`/`Button` from packages/ui) as live
+ * color-picker controls, following the GoodReserveWidget/AiCreditsWidget
+ * Theme overrides pattern for structure (CodeBlock + DocsCallout + live Canvas).
+ *
+ * Unlike GoodReserveWidget and AiCreditsWidget, this package defines no
+ * named theme-component module at all (confirmed: zero `createComponent`
+ * calls anywhere in packages/superfluid-campaign-widget/src) — every Card
+ * and Button in the widget (outer shell, ActionCard, LeaderboardSummary,
+ * LeaderboardRow, pagination/CTA buttons) is a plain primitive, so
+ * dark_Card/light_Card/dark_Button/light_Button are the only override
+ * paths this widget has. This is a design-system gap worth tracking
+ * separately, not something to fix by inventing a new named module here.
+ *
+ * The default "content" view with a populated leaderboard scenario is used
+ * because it renders the outer shell Card, an ActionCard, and the
+ * LeaderboardSummary card together with their CTA buttons in one view.
+ */
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { type SuperfluidCampaignWidgetProps } from '@goodwidget/superfluid-campaign-widget'
+import { MockSuperfluidCampaignWidget } from '@goodwidget/superfluid-campaign-widget/mocked'
+import { createCustodialEip1193Provider } from '../../fixtures/custodialEip1193'
+import { DocsCallout, DocsList } from '../docs/DocsLayout'
+
+const provider = createCustodialEip1193Provider()
+
+type ThemeOverrides = NonNullable<SuperfluidCampaignWidgetProps['themeOverrides']>
+
+function CodeBlock({ children }: { children: string }) {
+  return (
+    <pre
+      style={{
+        background: '#0f172a',
+        color: '#e2e8f0',
+        padding: 16,
+        borderRadius: 8,
+        overflowX: 'auto',
+        fontSize: 13,
+        lineHeight: 1.5,
+      }}
+    >
+      <code>{children}</code>
+    </pre>
+  )
+}
+
+interface OverridesArgs {
+  darkCardBackground: string
+  darkCardBorderColor: string
+  lightCardBackground: string
+  lightCardBorderColor: string
+  darkButtonBackground: string
+  darkButtonBackgroundHover: string
+  darkButtonColor: string
+  lightButtonBackground: string
+  lightButtonBackgroundHover: string
+  lightButtonColor: string
+}
+
+function buildThemeOverrides(args: OverridesArgs): ThemeOverrides {
+  return {
+    themes: {
+      dark_Card: {
+        background: args.darkCardBackground,
+        borderColor: args.darkCardBorderColor,
+      },
+      light_Card: {
+        background: args.lightCardBackground,
+        borderColor: args.lightCardBorderColor,
+      },
+      dark_Button: {
+        background: args.darkButtonBackground,
+        backgroundHover: args.darkButtonBackgroundHover,
+        color: args.darkButtonColor,
+      },
+      light_Button: {
+        background: args.lightButtonBackground,
+        backgroundHover: args.lightButtonBackgroundHover,
+        color: args.lightButtonColor,
+      },
+    },
+  }
+}
+
+const meta: Meta<OverridesArgs> = {
+  title: 'Widgets/SuperfluidCampaignWidget/Theme overrides',
+  tags: ['integrator', 'showcase'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    darkCardBackground: { control: 'color', description: 'themes.dark_Card.background' },
+    darkCardBorderColor: { control: 'color', description: 'themes.dark_Card.borderColor' },
+    lightCardBackground: { control: 'color', description: 'themes.light_Card.background' },
+    lightCardBorderColor: { control: 'color', description: 'themes.light_Card.borderColor' },
+    darkButtonBackground: { control: 'color', description: 'themes.dark_Button.background' },
+    darkButtonBackgroundHover: {
+      control: 'color',
+      description: 'themes.dark_Button.backgroundHover',
+    },
+    darkButtonColor: { control: 'color', description: 'themes.dark_Button.color' },
+    lightButtonBackground: { control: 'color', description: 'themes.light_Button.background' },
+    lightButtonBackgroundHover: {
+      control: 'color',
+      description: 'themes.light_Button.backgroundHover',
+    },
+    lightButtonColor: { control: 'color', description: 'themes.light_Button.color' },
+  },
+  args: {
+    darkCardBackground: '#1e1b4b',
+    darkCardBorderColor: '#7C3AED',
+    lightCardBackground: '#f5f3ff',
+    lightCardBorderColor: '#7C3AED',
+    darkButtonBackground: '#7C3AED',
+    darkButtonBackgroundHover: '#6D28D9',
+    darkButtonColor: '#FFFFFF',
+    lightButtonBackground: '#7C3AED',
+    lightButtonBackgroundHover: '#6D28D9',
+    lightButtonColor: '#FFFFFF',
+  },
+}
+export default meta
+type Story = StoryObj<OverridesArgs>
+
+export const Playground: Story = {
+  render: (args) => {
+    const themeOverrides = buildThemeOverrides(args)
+    return (
+      <div style={{ display: 'grid', gap: 24, maxWidth: 960, margin: '0 auto' }}>
+        <CodeBlock>
+          {`<SuperfluidCampaignWidget\n  themeOverrides={${JSON.stringify(themeOverrides, null, 2)}}\n/>`}
+        </CodeBlock>
+        <DocsCallout title="All overridable paths on SuperfluidCampaignWidget" tone="info">
+          <DocsList>
+            <li>
+              <strong>dark_Card / light_Card</strong>: outer widget shell, ActionCard, the
+              LeaderboardSummary card, and each LeaderboardRow all cascade from this theme —
+              demonstrated below on the outer shell and ActionCard.
+            </li>
+            <li>
+              <strong>dark_Button / light_Button</strong>: the "Claim SUP rewards" header CTA,
+              wallet connect button, action-card CTAs, "View Leaderboard" button, and leaderboard
+              pagination all cascade from this theme — demonstrated below on the action-card CTA
+              and the "View Leaderboard" button.
+            </li>
+          </DocsList>
+        </DocsCallout>
+        <DocsCallout title="No named theme-component module" tone="warning">
+          This widget has no `createComponent(Card, ...)`/`createComponent(Button, ...)` module
+          (unlike AiCreditsWidget or GoodReserveWidget), so there are no dedicated sub-theme
+          targets to override independently of the plain Card/Button theme shown here. Tracked as
+          a design-system gap rather than addressed in this change.
+        </DocsCallout>
+        <div>
+          <p style={{ fontWeight: 600, marginBottom: 8 }}>
+            Content view, populated leaderboard scenario — shell card, action card, and CTA
+            buttons together
+          </p>
+          <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
+            <div data-testid="SuperfluidCampaignWidget-theme-overrides-dark" style={{ width: 420 }}>
+              <MockSuperfluidCampaignWidget
+                provider={provider}
+                initialView="content"
+                leaderboardScenario="populated"
+                defaultTheme="dark"
+                themeOverrides={themeOverrides}
+              />
+            </div>
+            <div data-testid="SuperfluidCampaignWidget-theme-overrides-light" style={{ width: 420 }}>
+              <MockSuperfluidCampaignWidget
+                provider={provider}
+                initialView="content"
+                leaderboardScenario="populated"
+                defaultTheme="light"
+                themeOverrides={themeOverrides}
+              />
+            </div>
+          </div>
+        </div>
+      </div>
+    )
+  },
+}
diff --git a/tests/widgets/gooddata-widget/states.spec.ts b/tests/widgets/gooddata-widget/states.spec.ts
index b76cb329..8f25863d 100644
--- a/tests/widgets/gooddata-widget/states.spec.ts
+++ b/tests/widgets/gooddata-widget/states.spec.ts
@@ -1,12 +1,12 @@
 import { expect, test, type Page } from '@playwright/test'
 
 const STORY_IDS = {
-  loading: '/iframe.html?id=qa-aicreditsdashboard-runtime-fixtures--loading&viewMode=story',
-  live: '/iframe.html?id=qa-aicreditsdashboard-runtime-fixtures--live&viewMode=story',
-  demo: '/iframe.html?id=qa-aicreditsdashboard-runtime-fixtures--demo&viewMode=story',
+  loading: '/iframe.html?id=qa-gooddatawidget-runtime-fixtures--loading&viewMode=story',
+  live: '/iframe.html?id=qa-gooddatawidget-runtime-fixtures--live&viewMode=story',
+  demo: '/iframe.html?id=qa-gooddatawidget-runtime-fixtures--demo&viewMode=story',
   liveUnavailable:
-    '/iframe.html?id=qa-aicreditsdashboard-runtime-fixtures--live-unavailable&viewMode=story',
-  empty: '/iframe.html?id=qa-aicreditsdashboard-runtime-fixtures--empty&viewMode=story',
+    '/iframe.html?id=qa-gooddatawidget-runtime-fixtures--live-unavailable&viewMode=story',
+  empty: '/iframe.html?id=qa-gooddatawidget-runtime-fixtures--empty&viewMode=story',
 } as const
 
 async function gotoStory(page: Page, storyUrl: string): Promise<void> {
diff --git a/tests/widgets/goodreserve-widget/states.spec.ts b/tests/widgets/goodreserve-widget/states.spec.ts
index 577b393b..1320ea01 100644
--- a/tests/widgets/goodreserve-widget/states.spec.ts
+++ b/tests/widgets/goodreserve-widget/states.spec.ts
@@ -46,52 +46,52 @@ async function gotoStory(page: Page, storyId: string): Promise<void> {
 }
 
 test('no-provider state renders the connect CTA', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--no-provider')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--no-provider')
   await expect(page.getByText('Connect Wallet')).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-01-no-provider.png` })
 })
 
 test('unsupported-chain state renders the switch-network CTA', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--unsupported-chain')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--unsupported-chain')
   await expect(page.getByText('Switch Network')).toBeVisible()
   await expect(page.getByText('Unsupported').first()).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-02-unsupported-chain.png` })
 })
 
 test('sdk-initializing state shows a connecting loader', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--sdk-initializing')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--sdk-initializing')
   await expect(page.getByText('Connecting to the reserve…')).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-13-sdk-initializing.png` })
 })
 
 test('idle-buy state shows the Enter Amount CTA', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--idle-buy')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--idle-buy')
   await expect(page.getByText('Enter Amount')).toBeVisible()
   await expect(page.getByText('Swap on CELO').first()).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-03-idle-buy.png` })
 })
 
 test('amount-editing state reflects the typed amount', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--amount-editing')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--amount-editing')
   await expect(page.locator('input').first()).toHaveValue('25')
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-14-amount-editing.png` })
 })
 
 test('quote-loading state shows the fetching-quote CTA', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--quote-loading')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--quote-loading')
   await expect(page.getByText('Fetching Quote…')).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-15-quote-loading.png` })
 })
 
 test('quote-ready buy renders the quoted G$ output', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--quote-ready-buy')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--quote-ready-buy')
   await expect(page.getByText('108.25', { exact: true })).toBeVisible()
   await expect(page.getByText('Review Swap')).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-04-quote-ready-buy.png` })
 })
 
 test('quote-ready light theme resolves a different semantic palette from dark', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--quote-ready-buy')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--quote-ready-buy')
 
   const darkHeading = page.getByText('Swap on CELO').first()
   const darkShell = page.getByTestId('GoodReserveWidget-shell').first()
@@ -103,7 +103,7 @@ test('quote-ready light theme resolves a different semantic palette from dark',
 
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-17-quote-ready-buy-dark-theme.png` })
 
-  await gotoStory(page, 'widgets-goodreservewidget--quote-ready-buy-light-theme')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--quote-ready-buy-light-theme')
 
   const lightHeading = page.getByText('Swap on CELO').first()
   const lightShell = page.getByTestId('GoodReserveWidget-shell').first()
@@ -123,7 +123,7 @@ test('quote-ready light theme resolves a different semantic palette from dark',
 })
 
 test('quote-ready sell maps G$ into the from slot', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--quote-ready-sell')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--quote-ready-sell')
   await expect(page.getByText('8.9231', { exact: true })).toBeVisible()
   // Sell direction: the "from" balance is the G$ balance, not the stable balance.
   await expect(page.getByText('Balance: 300.123457', { exact: true })).toBeVisible()
@@ -131,28 +131,28 @@ test('quote-ready sell maps G$ into the from slot', async ({ page }) => {
 })
 
 test('quote-ready on XDC renders the dynamic network label', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--quote-ready-xdc')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--quote-ready-xdc')
   await expect(page.getByText('Swap on XDC').first()).toBeVisible()
   await expect(page.getByText('216.50', { exact: true })).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-06-quote-ready-xdc.png` })
 })
 
 test('insufficient-balance state warns and disables the CTA', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--insufficient-balance')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--insufficient-balance')
   await expect(page.getByText(/exceeds your available/i)).toBeVisible()
   await expect(page.getByText('Insufficient Balance')).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-07-insufficient-balance.png` })
 })
 
 test('slippage selection sheet exposes tolerance options', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--slippage-selection')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--slippage-selection')
   await expect(page.getByText('0.5%', { exact: true }).first()).toBeVisible()
   await expect(page.getByText('Done')).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-08-slippage-selection.png` })
 })
 
 test('confirm dialog renders as a bottom-sheet with a press-to-confirm button', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--confirm-dialog')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--confirm-dialog')
   await expect(page.getByText('Confirm Swap').first()).toBeVisible()
   await expect(page.getByText('Minimum Received', { exact: true })).toBeVisible()
   await expect(page.getByText('Max Slippage')).toBeVisible()
@@ -162,13 +162,13 @@ test('confirm dialog renders as a bottom-sheet with a press-to-confirm button',
 })
 
 test('swap-pending state shows the swapping CTA', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--swap-pending')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--swap-pending')
   await expect(page.getByText('Swapping…')).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-10-swap-pending.png` })
 })
 
 test('swap-success state shows the received amount, not the wallet balance', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--swap-success')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--swap-success')
   await expect(page.getByText('Swap Successful')).toBeVisible()
   await expect(page.getByText('Final amount received')).toBeVisible()
   // The fixture's lastSwapOutput is 10,230.46 while the wallet balance is 12,500;
@@ -179,7 +179,7 @@ test('swap-success state shows the received amount, not the wallet balance', asy
 })
 
 test('swap-error state surfaces the mapped reserve error', async ({ page }) => {
-  await gotoStory(page, 'widgets-goodreservewidget--swap-error')
+  await gotoStory(page, 'qa-goodreservewidget-runtime-fixtures--swap-error')
   await expect(page.getByText(/reverted/i)).toBeVisible()
   await page.screenshot({ path: `${SCREENSHOT_DIR}/grw-12-swap-error.png` })
 })
@@ -188,7 +188,7 @@ test('swap-error state surfaces the mapped reserve error', async ({ page }) => {
 // must accept typed characters. Tamagui's tag:'input' Stack does not forward
 // RN onChangeText on web, so the view wires a native onChange instead.
 test('amount input accepts typed characters (live adapter)', async ({ page }) => {
-  await page.goto('/iframe.html?id=widgets-goodreservewidget--interactive&viewMode=story')
+  await page.goto('/iframe.html?id=widgets-goodreservewidget-showcase--interactive&viewMode=story')
   await page.waitForLoadState('networkidle')
   await page.getByTestId('GoodReserveWidget-interactive').first().waitFor({ timeout: 30_000 })
 
@@ -219,7 +219,7 @@ test('amount input accepts typed characters (live adapter)', async ({ page }) =>
 test('live adapter completes a buy: quote → confirm → success with tx hash', async ({ page }) => {
   test.skip(process.env.GOODRESERVE_LIVE_TEST !== '1', 'Requires live RPC/wallet access')
 
-  await page.goto('/iframe.html?id=widgets-goodreservewidget--interactive&viewMode=story')
+  await page.goto('/iframe.html?id=widgets-goodreservewidget-showcase--interactive&viewMode=story')
   await page.waitForLoadState('networkidle')
   await page.getByTestId('GoodReserveWidget-interactive').first().waitFor({ timeout: 30_000 })
 
diff --git a/tests/widgets/governance-widget/onboarding.spec.ts b/tests/widgets/governance-widget/onboarding.spec.ts
index e6d306a7..7eab088e 100644
--- a/tests/widgets/governance-widget/onboarding.spec.ts
+++ b/tests/widgets/governance-widget/onboarding.spec.ts
@@ -2,21 +2,21 @@ import { expect, test, type Page } from '@playwright/test'
 
 const STORY_IDS = {
   injectedWelcomeUnverified:
-    '/iframe.html?id=widgets-governanceonboarding--injected-welcome-unverified&viewMode=story',
+    '/iframe.html?id=qa-governancewidget-onboarding--injected-welcome-unverified&viewMode=story',
   custodialWelcomeUnverified:
-    '/iframe.html?id=widgets-governanceonboarding--custodial-welcome-unverified&viewMode=story',
+    '/iframe.html?id=qa-governancewidget-onboarding--custodial-welcome-unverified&viewMode=story',
   custodialInteractiveFlow:
-    '/iframe.html?id=widgets-governanceonboarding--custodial-interactive-flow&viewMode=story',
+    '/iframe.html?id=qa-governancewidget-onboarding--custodial-interactive-flow&viewMode=story',
   custodialHouseSelection:
-    '/iframe.html?id=widgets-governanceonboarding--custodial-house-selection&viewMode=story',
+    '/iframe.html?id=qa-governancewidget-onboarding--custodial-house-selection&viewMode=story',
   custodialCitizenshipProfileReady:
-    '/iframe.html?id=widgets-governanceonboarding--custodial-citizenship-profile-ready&viewMode=story',
+    '/iframe.html?id=qa-governancewidget-onboarding--custodial-citizenship-profile-ready&viewMode=story',
   custodialAlignmentProfileError:
-    '/iframe.html?id=widgets-governanceonboarding--custodial-alignment-profile-error&viewMode=story',
+    '/iframe.html?id=qa-governancewidget-onboarding--custodial-alignment-profile-error&viewMode=story',
   custodialStakeProgress:
-    '/iframe.html?id=widgets-governanceonboarding--custodial-stake-progress&viewMode=story',
+    '/iframe.html?id=qa-governancewidget-onboarding--custodial-stake-progress&viewMode=story',
   custodialSuccess:
-    '/iframe.html?id=widgets-governanceonboarding--custodial-success&viewMode=story',
+    '/iframe.html?id=qa-governancewidget-onboarding--custodial-success&viewMode=story',
 } as const
 
 async function gotoStory(page: Page, storyUrl: string): Promise<void> {
diff --git a/tests/widgets/superfluid-campaign-widget/states.spec.ts b/tests/widgets/superfluid-campaign-widget/states.spec.ts
index 7d235b64..c707db0d 100644
--- a/tests/widgets/superfluid-campaign-widget/states.spec.ts
+++ b/tests/widgets/superfluid-campaign-widget/states.spec.ts
@@ -20,7 +20,7 @@ const STORY_IDS = {
   leaderboardEmpty:
     '/iframe.html?id=qa-superfluidcampaignwidget-runtime-fixtures--leaderboard-empty&viewMode=story',
   leaderboardApiContract:
-    '/iframe.html?id=widgets-superfluidcampaignwidget-api-contracts--leaderboard-api-contract&viewMode=story',
+    '/iframe.html?id=qa-superfluidcampaignwidget-api-contracts--leaderboard-api-contract&viewMode=story',
   supTotalsRequestFailed:
     '/iframe.html?id=qa-superfluidcampaignwidget-runtime-fixtures--sup-totals-request-failed&viewMode=story',
   supTotalsLoading:
@@ -30,7 +30,7 @@ const STORY_IDS = {
   supTotalsPopulated:
     '/iframe.html?id=qa-superfluidcampaignwidget-runtime-fixtures--sup-totals-populated&viewMode=story',
   supTotalsProgramsApiContract:
-    '/iframe.html?id=widgets-superfluidcampaignwidget-api-contracts--sup-totals-programs-api-contract&viewMode=story',
+    '/iframe.html?id=qa-superfluidcampaignwidget-api-contracts--sup-totals-programs-api-contract&viewMode=story',
 } as const
 
 // Top-ranked account address (truncated) for each campaign in LEADERBOARD_DATA_FIXTURES