docs: add storybook for components and embed live previews

- Initialize Storybook with Vite in @appshell/react.
- Add Header and Footer stories.
- Embed Storybook iframes into Fumadocs documentation for Header and Footer.
- Update GitHub Pages deployment workflow to build and publish Storybook.

Author: fyalavuz

.github/workflows/docs.yml

@@ -41,12 +41,17 @@ jobs:
         env:
           NEXT_PUBLIC_BASE_PATH: /${{ env.REPO_NAME }}/examples
 
+      - name: Build Storybook
+        run: cd packages/react && pnpm build-storybook
+
       - name: Merge outputs
         run: |
           mkdir -p _site
           cp -r apps/docs/out/* _site/
           mkdir -p _site/examples
           cp -r apps/examples/out/* _site/examples/
+          mkdir -p _site/storybook
+          cp -r packages/react/storybook-static/* _site/storybook/
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

apps/docs/content/docs/components/footer.mdx

@@ -5,6 +5,19 @@ description: Fixed footer with three variants -- tab-bar, floating, and mini --
 
 The `Footer` component renders a fixed-position bar at the bottom of the viewport. It supports three visual variants and an auto-hide behavior.
 
+<div className="my-6">
+  <iframe 
+    src="/react-appshell/storybook/iframe.html?id=components-footer--tab-bar&viewMode=story" 
+    className="w-full h-[300px] border rounded-lg bg-background shadow-sm"
+    title="Footer Storybook Preview"
+  />
+  <div className="mt-2 text-sm text-right">
+    <a href="/react-appshell/storybook/index.html?path=/story/components-footer--tab-bar" target="_blank" rel="noopener noreferrer" className="underline text-muted-foreground hover:text-foreground transition-colors">
+      Open full Storybook
+    </a>
+  </div>
+</div>
+
 ## Footer props
 
 | Prop | Type | Default | Description |

apps/docs/content/docs/components/header.mdx

@@ -5,6 +5,19 @@ description: A flexible, scroll-aware header with 6 behaviors, 3 themes, and mob
 
 The `Header` component renders up to three rows -- navigation, context (title/subtitle), and search -- and controls how they respond to scrolling.
 
+<div className="my-6">
+  <iframe 
+    src="/react-appshell/storybook/iframe.html?id=components-header--default&viewMode=story" 
+    className="w-full h-[400px] border rounded-lg bg-background shadow-sm"
+    title="Header Storybook Preview"
+  />
+  <div className="mt-2 text-sm text-right">
+    <a href="/react-appshell/storybook/index.html?path=/story/components-header--default" target="_blank" rel="noopener noreferrer" className="underline text-muted-foreground hover:text-foreground transition-colors">
+      Open full Storybook
+    </a>
+  </div>
+</div>
+
 ## Props
 
 | Prop | Type | Default | Description |

packages/react/.storybook/globals.css

@@ -0,0 +1,86 @@
+@import 'tailwindcss';
+@source "../src";
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --radius: 0.625rem;
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.145 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.145 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.985 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.396 0.141 25.723);
+  --destructive-foreground: oklch(0.637 0.237 25.331);
+  --border: oklch(0.269 0 0);
+  --input: oklch(0.269 0 0);
+  --ring: oklch(0.439 0 0);
+}
+
+@theme inline {
+  --font-sans: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}

packages/react/.storybook/main.ts

@@ -0,0 +1,27 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+import { dirname } from "path"
+
+import { fileURLToPath } from "url"
+
+/**
+* This function is used to resolve the absolute path of a package.
+* It is needed in projects that use Yarn PnP or are set up within a monorepo.
+*/
+function getAbsolutePath(value: string) {
+  return dirname(fileURLToPath(import.meta.resolve(`${value}/package.json`)))
+}
+const config: StorybookConfig = {
+  "stories": [
+    "../src/**/*.mdx",
+    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"
+  ],
+  "addons": [
+    getAbsolutePath('@chromatic-com/storybook'),
+    getAbsolutePath('@storybook/addon-vitest'),
+    getAbsolutePath('@storybook/addon-a11y'),
+    getAbsolutePath('@storybook/addon-docs')
+  ],
+  "framework": getAbsolutePath('@storybook/react-vite')
+};
+export default config;

packages/react/.storybook/preview.ts

@@ -0,0 +1,22 @@
+import type { Preview } from '@storybook/react-vite'
+import './globals.css';
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+       color: /(background|color)$/i,
+       date: /Date$/i,
+      },
+    },
+
+    a11y: {
+      // 'todo' - show a11y violations in the test UI only
+      // 'error' - fail CI on a11y violations
+      // 'off' - skip a11y checks entirely
+      test: 'todo'
+    }
+  },
+};
+
+export default preview;

packages/react/.storybook/vitest.setup.ts

@@ -0,0 +1,7 @@
+import * as a11yAddonAnnotations from "@storybook/addon-a11y/preview";
+import { setProjectAnnotations } from '@storybook/react-vite';
+import * as projectAnnotations from './preview';
+
+// This is an important step to apply the right configuration when testing your stories.
+// More info at: https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest#setprojectannotations
+setProjectAnnotations([a11yAddonAnnotations, projectAnnotations]);

packages/react/package.json

@@ -44,7 +44,9 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
     "clean": "rm -rf dist",
-    "size": "node scripts/size-report.mjs"
+    "size": "node scripts/size-report.mjs",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
@@ -57,22 +59,35 @@
     }
   },
   "devDependencies": {
+    "@chromatic-com/storybook": "^5.0.1",
     "@eslint/js": "^9.0.0",
+    "@storybook/addon-a11y": "^10.2.13",
+    "@storybook/addon-docs": "^10.2.13",
+    "@storybook/addon-vitest": "^10.2.13",
+    "@storybook/react-vite": "^10.2.13",
+    "@tailwindcss/vite": "^4.2.1",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
+    "@vitest/browser": "3.2.4",
+    "@vitest/coverage-v8": "3.2.4",
     "clsx": "^2.1.0",
     "eslint": "^9.0.0",
     "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-storybook": "^10.2.13",
     "framer-motion": "^12.6.0",
     "jsdom": "^26.1.0",
+    "playwright": "^1.58.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "storybook": "^10.2.13",
     "tailwind-merge": "^3.3.0",
+    "tailwindcss": "^4.1.0",
     "tsup": "^8.4.0",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.56.1",
+    "vite": "^7.3.1",
     "vitest": "^3.2.0"
   }
 }

packages/react/src/Footer.stories.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Footer, FooterItem } from './Footer';
+import { AppShellProvider } from './context';
+import { Home, Search, PlusCircle, Bell, User } from 'lucide-react';
+
+const meta = {
+  title: 'Components/Footer',
+  component: Footer,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [
+    (Story) => (
+      <AppShellProvider>
+        <div className="h-screen bg-muted/20 pb-20">
+          <Story />
+        </div>
+      </AppShellProvider>
+    ),
+  ],
+  tags: ['autodocs'],
+} satisfies Meta<typeof Footer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const TabBar: Story = {
+  args: {
+    variant: 'tab-bar',
+    behavior: 'static',
+    children: (
+      <>
+        <FooterItem icon={<Home className="size-5" />} label="Home" active />
+        <FooterItem icon={<Search className="size-5" />} label="Search" />
+        <FooterItem icon={<PlusCircle className="size-5" />} label="Add" />
+        <FooterItem icon={<Bell className="size-5" />} label="Alerts" badge={3} />
+        <FooterItem icon={<User className="size-5" />} label="Profile" />
+      </>
+    ),
+  },
+};
+
+export const Floating: Story = {
+  args: {
+    variant: 'floating',
+    position: 'right',
+    children: (
+      <button className="flex items-center gap-2 rounded-full bg-primary px-4 py-3 font-semibold text-primary-foreground shadow-lg hover:shadow-xl transition-all hover:-translate-y-1">
+        <PlusCircle className="size-5" /> Create
+      </button>
+    ),
+  },
+};
+
+export const Mini: Story = {
+  args: {
+    variant: 'mini',
+    children: (
+      <div className="flex w-full items-center justify-between">
+        <span className="text-sm font-medium">1 item selected</span>
+        <div className="flex gap-2">
+          <button className="text-sm font-medium text-primary hover:underline">Edit</button>
+          <button className="text-sm font-medium text-destructive hover:underline">Delete</button>
+        </div>
+      </div>
+    ),
+  },
+};

packages/react/src/Header.stories.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Header } from './Header';
+import { AppShellProvider } from './context';
+import { HeaderNav, HeaderNavItem } from './HeaderNav';
+
+const meta = {
+  title: 'Components/Header',
+  component: Header,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [
+    (Story) => (
+      <AppShellProvider>
+        <Story />
+      </AppShellProvider>
+    ),
+  ],
+  tags: ['autodocs'],
+} satisfies Meta<typeof Header>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    title: 'Dashboard',
+    subtitle: 'Welcome back, user',
+    theme: 'light',
+    behavior: 'static',
+    logo: <span className="font-bold text-xl ml-4">AppShell</span>,
+    nav: (
+      <HeaderNav>
+        <HeaderNavItem label="Home" active />
+        <HeaderNavItem label="Analytics" />
+        <HeaderNavItem label="Settings" />
+      </HeaderNav>
+    ),
+  },
+};
+
+export const PrimaryTheme: Story = {
+  args: {
+    ...Default.args,
+    theme: 'primary',
+  },
+};
+
+export const DarkTheme: Story = {
+  args: {
+    ...Default.args,
+    theme: 'dark',
+  },
+};