Storybook polish: interactive theming controls for widgets (#64)

examples/storybook/.storybook/preview.tsx

@@ -6,6 +6,7 @@ const preview: Preview = {
     layout: 'centered',
     controls: {
       expanded: true,
+      disableSaveFromUI: true,
     },
     options: {
       storySort: {

examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidget.mdx

@@ -1,4 +1,4 @@
-import { Canvas, Meta } from '@storybook/blocks';
+import { Canvas, Meta, Source } from '@storybook/blocks';
 import * as ShowcaseStories from './CitizenClaimWidgetShowcase.stories';
 import { DocsCallout, DocsCard, DocsGrid, DocsPage, DocsSection } from '../docs/DocsLayout';
 
@@ -11,11 +11,35 @@ 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."
+    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."
   >
     <Canvas of={ShowcaseStories.InjectedWallet} />
   </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 { CitizenClaimWidget } from '@goodwidget/citizen-claim-widget'
+import { MiniAppShell } from '@goodwidget/ui'
+
+export function ClaimPanel({ provider }: { provider?: unknown }) {
+  return (
+    <MiniAppShell title="GoodDollar">
+      <CitizenClaimWidget
+        provider={provider}
+        environment="production"
+        defaultTheme="dark"
+      />
+    </MiniAppShell>
+  )
+}`}
+    />
+  </DocsSection>
+
   <DocsSection
     title="QA coverage"
     description="Use the QA demo when you need reproducible custodial state, Playwright screenshots, or fixture-driven debugging. Keep this page focused on the product-facing integration flow."

examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetQA.stories.tsx

@@ -1,17 +1,41 @@
 import type { Meta, StoryObj } from '@storybook/react'
 import { CitizenClaimWidget } from '@goodwidget/citizen-claim-widget'
 import { CustodialLocalFixtureStory } from '../helpers/citizenClaimWidgetStories'
+import { BRAND_PRESET_OPTIONS, brandPresetOverrides, type BrandPreset } from '../helpers/themeOverridePresets'
 
-const meta: Meta<typeof CitizenClaimWidget> = {
+interface CitizenClaimWidgetQAArgs {
+  defaultTheme: 'light' | 'dark'
+  brandPreset: BrandPreset
+}
+
+const meta: Meta<CitizenClaimWidgetQAArgs> = {
   title: 'QA/CitizenClaimWidget/Runtime Fixtures',
   component: CitizenClaimWidget,
   tags: ['autodocs', 'qa'],
   parameters: { layout: 'padded' },
+  argTypes: {
+    defaultTheme: {
+      control: 'radio',
+      options: ['dark', 'light'],
+      description: 'Base theme applied via the widget’s own defaultTheme prop.',
+    },
+    brandPreset: {
+      control: 'select',
+      options: BRAND_PRESET_OPTIONS,
+      description: 'Sample host-branding themeOverrides preset.',
+    },
+  },
+  args: {
+    defaultTheme: 'dark',
+    brandPreset: 'None',
+  },
 }
 
 export default meta
-type Story = StoryObj<typeof meta>
+type Story = StoryObj<CitizenClaimWidgetQAArgs>
 
 export const CustodialLocalFixture: Story = {
-  render: () => <CustodialLocalFixtureStory />,
+  render: ({ defaultTheme, brandPreset }) => (
+    <CustodialLocalFixtureStory defaultTheme={defaultTheme} themeOverrides={brandPresetOverrides(brandPreset)} />
+  ),
 }

examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidgetShowcase.stories.tsx

@@ -1,17 +1,41 @@
 import type { Meta, StoryObj } from '@storybook/react'
 import { CitizenClaimWidget } from '@goodwidget/citizen-claim-widget'
 import { InjectedWalletStory } from '../helpers/citizenClaimWidgetStories'
+import { BRAND_PRESET_OPTIONS, brandPresetOverrides, type BrandPreset } from '../helpers/themeOverridePresets'
 
-const meta: Meta<typeof CitizenClaimWidget> = {
+interface CitizenClaimWidgetStoryArgs {
+  defaultTheme: 'light' | 'dark'
+  brandPreset: BrandPreset
+}
+
+const meta: Meta<CitizenClaimWidgetStoryArgs> = {
   title: 'Widgets/CitizenClaimWidget/Showcase',
   component: CitizenClaimWidget,
   tags: ['integrator', 'manual', 'showcase'],
   parameters: { layout: 'padded' },
+  argTypes: {
+    defaultTheme: {
+      control: 'radio',
+      options: ['dark', 'light'],
+      description: 'Base theme applied via the widget’s own defaultTheme prop.',
+    },
+    brandPreset: {
+      control: 'select',
+      options: BRAND_PRESET_OPTIONS,
+      description: 'Sample host-branding themeOverrides preset.',
+    },
+  },
+  args: {
+    defaultTheme: 'dark',
+    brandPreset: 'None',
+  },
 }
 
 export default meta
-type Story = StoryObj<typeof meta>
+type Story = StoryObj<CitizenClaimWidgetStoryArgs>
 
 export const InjectedWallet: Story = {
-  render: () => <InjectedWalletStory />,
+  render: ({ defaultTheme, brandPreset }) => (
+    <InjectedWalletStory defaultTheme={defaultTheme} themeOverrides={brandPresetOverrides(brandPreset)} />
+  ),
 }

examples/storybook/src/stories/claim-widget/ClaimWidget.mdx

@@ -1,5 +1,6 @@
 import { Canvas, Meta, Source } from '@storybook/blocks';
 import * as ClaimWidgetStories from './ClaimWidget.stories';
+import * as ThemeOverridesStories from './ClaimWidgetThemeOverrides.stories';
 import { DocsCallout, DocsCard, DocsGrid, DocsList, DocsPage, DocsSection } from '../docs/DocsLayout';
 
 <Meta of={ClaimWidgetStories} />
@@ -36,6 +37,13 @@ import { DocsCallout, DocsCard, DocsGrid, DocsList, DocsPage, DocsSection } from
     </DocsCallout>
   </DocsSection>
 
+  <DocsSection
+    title="Theme overrides"
+    description="Play around with some of the theme overrides using the controls below (you may have to activate Controls in the addons panel, top-right). The code here can be copied and used directly in your own dapp — it always matches what's rendered. See the callout below the code for additional overridable styles not wired to a control."
+  >
+    <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."

examples/storybook/src/stories/claim-widget/ClaimWidget.stories.tsx

@@ -7,48 +7,76 @@
  */
 import type { Meta, StoryObj } from '@storybook/react'
 import { ClaimWidget } from '@goodwidget/claim-widget-theme-demo'
-import {
-  ClaimWidgetStoryCanvas,
-  cobaltOverrides,
-  tealOverrides,
-} from '../helpers/claimWidgetStories'
+import { ClaimWidgetStoryCanvas } from '../helpers/claimWidgetStories'
+import { BRAND_PRESET_OPTIONS, brandPresetOverrides, type BrandPreset } from '../helpers/themeOverridePresets'
 
-const meta: Meta<typeof ClaimWidget> = {
+interface ClaimWidgetStoryArgs {
+  defaultTheme: 'light' | 'dark'
+  brandPreset: BrandPreset
+}
+
+const meta: Meta<ClaimWidgetStoryArgs> = {
   title: 'Widgets/ClaimWidget Theme Demo/Showcase',
   component: ClaimWidget,
   tags: ['integrator', 'showcase'],
   parameters: { layout: 'padded' },
-  goodWidgetProvider: {
-    disableProvider: true,
-    useShell: false,
+  argTypes: {
+    defaultTheme: {
+      control: 'radio',
+      options: ['dark', 'light'],
+      description: 'Base theme applied via the widget’s own defaultTheme prop.',
+    },
+    brandPreset: {
+      control: 'select',
+      options: BRAND_PRESET_OPTIONS,
+      description: 'Sample host-branding themeOverrides preset.',
+    },
   },
 }
 export default meta
 
-type Story = StoryObj<typeof ClaimWidget>
+type Story = StoryObj<ClaimWidgetStoryArgs>
 
 export const Default: Story = {
-  render: () => <ClaimWidgetStoryCanvas dataTestId="ClaimWidget-default" />,
+  args: { defaultTheme: 'dark', brandPreset: 'None' },
+  render: ({ defaultTheme, brandPreset }) => (
+    <ClaimWidgetStoryCanvas
+      dataTestId="ClaimWidget-default"
+      defaultTheme={defaultTheme}
+      themeOverrides={brandPresetOverrides(brandPreset)}
+    />
+  ),
 }
 
 export const LightTheme: Story = {
-  render: () => <ClaimWidgetStoryCanvas dataTestId="ClaimWidget-light" defaultTheme="light" />,
+  args: { defaultTheme: 'light', brandPreset: 'None' },
+  render: ({ defaultTheme, brandPreset }) => (
+    <ClaimWidgetStoryCanvas
+      dataTestId="ClaimWidget-light"
+      defaultTheme={defaultTheme}
+      themeOverrides={brandPresetOverrides(brandPreset)}
+    />
+  ),
 }
 
 export const CobaltBrand: Story = {
-  render: () => (
+  args: { defaultTheme: 'dark', brandPreset: 'Cobalt' },
+  render: ({ defaultTheme, brandPreset }) => (
     <ClaimWidgetStoryCanvas
       dataTestId="ClaimWidget-cobalt"
-      themeOverrides={cobaltOverrides}
+      defaultTheme={defaultTheme}
+      themeOverrides={brandPresetOverrides(brandPreset)}
     />
   ),
 }
 
 export const TealBrand: Story = {
-  render: () => (
+  args: { defaultTheme: 'dark', brandPreset: 'Teal' },
+  render: ({ defaultTheme, brandPreset }) => (
     <ClaimWidgetStoryCanvas
       dataTestId="ClaimWidget-teal"
-      themeOverrides={tealOverrides}
+      defaultTheme={defaultTheme}
+      themeOverrides={brandPresetOverrides(brandPreset)}
     />
   ),
 }