feat(client): add Storybook with component stories (#256)

* feat(client): add Storybook with component stories

- Set up Storybook with Vite and dark theme support
- Add Chromatic CI workflow for visual regression testing
- Create stories for 37+ UI components
- Fix GameCard text color for cartridge preset compatibility
- Exclude stories from production TypeScript build

* feat(storybook): audit existing stories and add new component stories

- Fix AssetPreview stories: add required 'order' prop (set to null)
- Fix LeaderboardRow stories: migrate from react-router-dom MemoryRouter
  to @tanstack/react-router (matching the actual component)
- Add Tooltip stories (Default, LongContent, WithIcon)
- Add PositionCard stories (Default, NegativePnl, LargePosition, List)
- Add PredictCard stories (Default, TiedScore, HighStakes, CardGrid)

Skipped components with heavy provider dependencies:
- achievement-card (useAnalytics/PostHog)
- arcade-header (useDevice, useTheme, SidebarToggle)
- tabs/sub-tabs (useDevice, useAnalytics)
- price-footer (ListingWithUsd, erc20Metadata)
- summary (useAnalytics via game-header)
- CollectionHeader (useMarketplaceItemsViewModel, useShare)

* fix: lint and format fixes for storybook stories

* fix: format tooltip story

Author: MartianGreed

.claude-modified-files

@@ -0,0 +1,110 @@
+/Users/valentindosimont/.claude/plans/dreamy-drifting-hippo.md
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/main.ts
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/preview.ts
+/Users/valentindosimont/www/c7e/arcade/client/package.json
+/Users/valentindosimont/www/c7e/arcade/turbo.json
+/Users/valentindosimont/www/c7e/arcade/.gitignore
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/button.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/label.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/floating-loading-spinner.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/pagination.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/.github/workflows/ci-chromatic.yml
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/main.ts
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/storybook.css
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/preview.ts
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/storybook.css
+/Users/valentindosimont/www/c7e/arcade/client/biome.json
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/carousel.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/form.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/tab.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/sub-tab.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/menu-button.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/menu-item.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/leaderboard-row.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/leaderboard-username.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/copy-address.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/follow-tag.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/player-label.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/player-header.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/search-input.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-header.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/link-item.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/edition-item.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/index.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/header.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/footer.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/preview.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/filters/AttributeSearch.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/filters/PropertyItem.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/filters/OwnerFilterSection.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/token-detail/TokenProperties.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/token-detail/TokenTabs.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/token-detail/AssetPreview.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/icons/index.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-socials.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/controller-action.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-social.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/edition-actions.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-select.stories.tsx
+/Users/valentindosimont/.claude/plans/dreamy-drifting-hippo.md
+/Users/valentindosimont/.claude/plans/dreamy-drifting-hippo.md
+/Users/valentindosimont/.claude/plans/dreamy-drifting-hippo.md
+/Users/valentindosimont/.claude/plans/dreamy-drifting-hippo.md
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/preview.tsx
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/mocks/project.ts
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/main.ts
+/Users/valentindosimont/.claude/plans/dreamy-drifting-hippo.md
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/preview.tsx
+/Users/valentindosimont/.claude/plans/dreamy-drifting-hippo.md
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/preview.ts
+/Users/valentindosimont/www/c7e/arcade/client/.storybook/main.ts
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-select.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-select.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-select.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/.claude/plans/zazzy-percolating-wreath.md
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-select.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/index.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/token-detail/AssetPreview.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/token-detail/AssetPreview.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/header.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/preview.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/preview.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/footer.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-header.stories.tsx
+/Users/valentindosimont/.claude/plans/zazzy-percolating-wreath.md
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-select.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-header.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/index.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/preview.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/preview.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/header.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/collectible-card/footer.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/token-detail/AssetPreview.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/marketplace/token-detail/AssetPreview.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/game-select.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/.claude/plans/zazzy-percolating-wreath.md
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/edition-actions.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/edition-actions.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/edition-actions.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/modules/edition-actions.stories.tsx
+/Users/valentindosimont/.claude/plans/zazzy-percolating-wreath.md
+/Users/valentindosimont/www/c7e/arcade/.github/workflows/ci-chromatic.yml
+/Users/valentindosimont/www/c7e/arcade/.github/workflows/ci-chromatic.yml
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/src/components/ui/dashboard/GameCard.stories.tsx
+/Users/valentindosimont/www/c7e/arcade/client/tsconfig.app.json

.github/workflows/ci-chromatic.yml

@@ -0,0 +1,79 @@
+name: chromatic
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'client/**'
+      - '.github/workflows/ci-chromatic.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'client/**'
+      - '.github/workflows/ci-chromatic.yml'
+
+concurrency:
+  group: chromatic-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  chromatic:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for Chromatic token
+        id: check-token
+        run: |
+          if [ -z "${{ secrets.CHROMATIC_PROJECT_TOKEN }}" ]; then
+            echo "has_token=false" >> $GITHUB_OUTPUT
+            echo "⚠️ CHROMATIC_PROJECT_TOKEN not configured. Skipping Chromatic."
+          else
+            echo "has_token=true" >> $GITHUB_OUTPUT
+          fi
+
+      - uses: actions/checkout@v4
+        if: steps.check-token.outputs.has_token == 'true'
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+        if: steps.check-token.outputs.has_token == 'true'
+        with:
+          version: 10.5.2
+
+      - uses: actions/setup-node@v4
+        if: steps.check-token.outputs.has_token == 'true'
+        with:
+          node-version: 20
+          cache: "pnpm"
+
+      - name: Cache turbo
+        if: steps.check-token.outputs.has_token == 'true'
+        uses: actions/cache@v4
+        with:
+          path: .turbo
+          key: ${{ runner.os }}-turbo-chromatic-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-turbo-chromatic-
+            ${{ runner.os }}-turbo-
+
+      - name: Install dependencies
+        if: steps.check-token.outputs.has_token == 'true'
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Build dependencies
+        if: steps.check-token.outputs.has_token == 'true'
+        run: pnpm turbo run build:deps --filter=@cartridge/client
+
+      - name: Publish to Chromatic
+        if: steps.check-token.outputs.has_token == 'true'
+        uses: chromaui/action@latest
+        with:
+          workingDir: client
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          onlyChanged: true
+          autoAcceptChanges: ${{ github.ref == 'refs/heads/main' }}
+          exitZeroOnChanges: ${{ github.event_name == 'pull_request' }}
+          exitOnceUploaded: true
+          skip: ${{ contains(github.event.head_commit.message, '[skip ci]') }}

.gitignore

@@ -15,5 +15,9 @@ vite.config.ts.*
 .rules
 .DS_Store
 packages/*/tsup.config.bundled_*.mjs
+
+# Storybook
+storybook-static/
+*storybook.log
 client/storybook-static/
 .claude-modified-files

client/.storybook/main.ts

@@ -0,0 +1,68 @@
+// This file has been automatically migrated to valid ESM format by Storybook.
+import type { StorybookConfig } from "@storybook/react-vite";
+import { mergeConfig } from "vite";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+
+const config: StorybookConfig = {
+  stories: ["../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+
+  addons: [
+    getAbsolutePath("@storybook/addon-links"),
+    getAbsolutePath("@storybook/addon-themes"),
+    getAbsolutePath("@storybook/addon-docs")
+  ],
+
+  framework: {
+    name: getAbsolutePath("@storybook/react-vite"),
+    options: {},
+  },
+
+  staticDirs: ["../public"],
+
+  viteFinal: async (config) => {
+    const filteredPlugins = (config.plugins || []).filter((plugin) => {
+      if (!plugin) return false;
+      const pluginName = Array.isArray(plugin) ? undefined : (plugin as { name?: string }).name;
+      return pluginName !== "vite-plugin-pwa:build" && pluginName !== "vite-plugin-pwa:dev";
+    });
+
+    return mergeConfig(
+      { ...config, plugins: filteredPlugins },
+      {
+        resolve: {
+          alias: {
+            "@": resolve(__dirname, "../src"),
+          },
+        },
+        optimizeDeps: {
+          include: ["@cartridge/ui"],
+          exclude: ["@dojoengine/torii-wasm"],
+        },
+        define: {
+          __COMMIT_SHA__: JSON.stringify("storybook"),
+        },
+      }
+    );
+  },
+
+  typescript: {
+    check: false,
+    reactDocgen: "react-docgen-typescript",
+    reactDocgenTypescriptOptions: {
+      shouldExtractLiteralValuesFromEnum: true,
+      propFilter: (prop) =>
+        prop.parent ? !/node_modules/.test(prop.parent.fileName) : true,
+    },
+  }
+};
+
+export default config;
+
+function getAbsolutePath(value: string): any {
+  return dirname(fileURLToPath(import.meta.resolve(`${value}/package.json`)));
+}

client/.storybook/preview.ts

@@ -0,0 +1,42 @@
+import type { Preview } from "@storybook/react-vite";
+import { withThemeByClassName } from "@storybook/addon-themes";
+
+import "./storybook.css";
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    backgrounds: {
+      options: {
+        dark: { name: "dark", value: "#161A17" },
+        light: { name: "light", value: "#ffffff" }
+      }
+    },
+    layout: "centered",
+  },
+
+  decorators: [
+    withThemeByClassName({
+      themes: {
+        light: "",
+        dark: "dark",
+      },
+      defaultTheme: "dark",
+    }),
+  ],
+
+  tags: ["autodocs"],
+
+  initialGlobals: {
+    backgrounds: {
+      value: "dark"
+    }
+  }
+};
+
+export default preview;

client/.storybook/storybook.css

@@ -0,0 +1,29 @@
+@import "@cartridge/ui/themes/default.css";
+@import "@cartridge/ui/themes/dark.css";
+@import "@cartridge/ui/themes/fonts.css";
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --chart-1: 12 76% 61%;
+    --chart-2: 173 58% 39%;
+    --chart-3: 197 37% 24%;
+    --chart-4: 43 74% 66%;
+    --chart-5: 27 87% 67%;
+  }
+
+  .dark {
+    --chart-1: 220 70% 50%;
+    --chart-2: 160 60% 45%;
+    --chart-3: 30 80% 55%;
+    --chart-4: 280 65% 60%;
+    --chart-5: 340 75% 55%;
+  }
+}
+
+#storybook-root {
+  min-height: 100vh;
+}

client/biome.json

@@ -13,7 +13,8 @@
       ".vercel/**",
       "node_modules/**",
       "public/**",
-      "src/*.gen.ts"
+      "src/*.gen.ts",
+      "storybook-static/**"
     ]
   },
   "formatter": {